refactor(soc): Deprecate usb pin mappings

usb_pins.h and usb_periph.h/c lists mappings of USB DWC signals to GPIOs used
to connect to external FSLS PHYs. However, those signals can be routed to any
GPIOs via the GPIO matrix. Thus, these mapping are meaningless and have been
deprecated.

components/soc/esp32s2/include/soc/usb_pins.h

@@ -1,12 +1,18 @@
 /*
- * SPDX-FileCopyrightText: 2020-2022 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2020-2024 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
 
 #pragma once
 
-/* GPIOs used to connect an external USB PHY */
+/*
+Note: These macros are deprecated. When connecting USB OTG to an external FSLS
+PHY, the FSLS Serial Interface signals can be routed to any GPIO via the GPIO
+matrix. Thus, these macros are meaningless.
+
+Todo: Remove in IDF v6.0 (IDF-9029)
+*/
 #define USBPHY_VP_NUM 33
 #define USBPHY_VM_NUM 34
 #define USBPHY_RCV_NUM 35

components/soc/esp32s2/usb_periph.c

@@ -1,20 +1,19 @@
-// Copyright 2020 Espressif Systems (Shanghai) PTE LTD
+/*
-//
+ * SPDX-FileCopyrightText: 2024 Espressif Systems (Shanghai) CO LTD
-// Licensed under the Apache License, Version 2.0 (the "License");
+ *
-// you may not use this file except in compliance with the License.
+ * SPDX-License-Identifier: Apache-2.0
-// You may obtain a copy of the License at
+ */
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
 
 #include "soc/soc_caps.h"
 #include "soc/usb_periph.h"
 
+/*
+Note: These IO pins are deprecated. When connecting USB OTG to an external FSLS
+PHY, the FSLS Serial Interface signals can be routed to any GPIO via the GPIO
+matrix. Thus, this mapping of signals to IO pins is meaningless.
+
+Todo: Remove in IDF v6.0 (IDF-9029)
+*/
 const usb_iopin_dsc_t usb_periph_iopins[] = {
     {USBPHY_VP_NUM, USB_EXTPHY_VP_IDX, 0, 1},
     {USBPHY_VM_NUM, USB_EXTPHY_VM_IDX, 0, 1},

components/soc/esp32s3/include/soc/usb_pins.h

@@ -1,12 +1,18 @@
 /*
- * SPDX-FileCopyrightText: 2020-2022 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2020-2024 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
 
 #pragma once
 
-/* GPIOs used to connect an external USB PHY */
+/*
+Note: These macros are deprecated. When connecting USB OTG to an external FSLS
+PHY, the FSLS Serial Interface signals can be routed to any GPIO via the GPIO
+matrix. Thus, these macros are meaningless.
+
+Todo: Remove in IDF v6.0 (IDF-9029)
+*/
 #define USBPHY_VP_NUM 42
 #define USBPHY_VM_NUM 41
 #define USBPHY_RCV_NUM 21

components/soc/esp32s3/usb_periph.c

@@ -1,20 +1,19 @@
-// Copyright 2020 Espressif Systems (Shanghai) PTE LTD
+/*
-//
+ * SPDX-FileCopyrightText: 2024 Espressif Systems (Shanghai) CO LTD
-// Licensed under the Apache License, Version 2.0 (the "License");
+ *
-// you may not use this file except in compliance with the License.
+ * SPDX-License-Identifier: Apache-2.0
-// You may obtain a copy of the License at
+ */
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
 
 #include "soc/soc_caps.h"
 #include "soc/usb_periph.h"
 
+/*
+Note: These IO pins are deprecated. When connecting USB OTG to an external FSLS
+PHY, the FSLS Serial Interface signals can be routed to any GPIO via the GPIO
+matrix. Thus, this mapping of signals to IO pins is meaningless.
+
+Todo: Remove in IDF v6.0 (IDF-9029)
+*/
 const usb_iopin_dsc_t usb_periph_iopins[] = {
     {USBPHY_VP_NUM, USB_EXTPHY_VP_IDX, 0, 1},
     {USBPHY_VM_NUM, USB_EXTPHY_VM_IDX, 0, 1},

components/soc/include/soc/usb_periph.h

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2020-2022 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2020-2024 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -10,18 +10,21 @@
 #include <stdbool.h>
 #include "soc/soc_pins.h"
 #include "soc/gpio_sig_map.h"
-#include "soc/usb_reg.h"
-#include "soc/usb_types.h"
-#include "soc/usb_struct.h"
-#include "soc/usb_wrap_reg.h"
-#include "soc/usb_wrap_struct.h"
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
+#if SOC_USB_OTG_SUPPORTED
+
 /**
- * @brief A pin descriptor for init
+ * @brief A pin descriptor for init (DEPRECATED)
+ *
+ * Todo: Remove in IDF v6.0 (IDF-9029)
+ *
+ * @note These IO pins are deprecated. When connecting USB OTG to an external
+ * FSLS PHY, the FSLS Serial Interface signals can be routed to any GPIO via the
+ * GPI0 matrix. Thus, this mapping of signals to IO pins is meaningless.
  */
 typedef struct {
     const int pin;
@@ -32,6 +35,8 @@ typedef struct {
 
 extern const usb_iopin_dsc_t usb_periph_iopins[];
 
+#endif // SOC_USB_OTG_SUPPORTED
+
 #ifdef __cplusplus
 }
 #endif

tools/ci/check_copyright_ignore.txt

@@ -886,7 +886,6 @@ components/soc/esp32s2/include/soc/usbh_struct.h
 components/soc/esp32s2/include/soc/wdev_reg.h
 components/soc/esp32s2/ledc_periph.c
 components/soc/esp32s2/uart_periph.c
-components/soc/esp32s2/usb_periph.c
 components/soc/esp32s3/dedic_gpio_periph.c
 components/soc/esp32s3/i2c_periph.c
 components/soc/esp32s3/include/soc/apb_ctrl_reg.h
@@ -960,7 +959,6 @@ components/soc/esp32s3/ledc_periph.c
 components/soc/esp32s3/sdio_slave_periph.c
 components/soc/esp32s3/sdmmc_periph.c
 components/soc/esp32s3/uart_periph.c
-components/soc/esp32s3/usb_periph.c
 components/soc/include/soc/dedic_gpio_periph.h
 components/soc/include/soc/emac_periph.h
 components/soc/include/soc/gpio_periph.h