refactor(usb_phy): Move USB PHY implementation to esp_hw_support

Moved USB PHY source and headers from `usb/` to `esp_hw_support/`
to better reflect their hardware-specific nature.
Replaced use of public GPIO driver APIs with internal LL (Low-Level) APIs
for more precise hardware control and alignment with ESP-IDF HAL best practices.
Deleted deprecated PHY helper functions.
Consolidated all SoC-specific declarations under `usb_periph.h`.

BREAKING CHANGE: deprecated USB PHY APIs have been removed; update
callers to use the new interfaces in esp_hw_support/usb_phy.h

.gitlab/CODEOWNERS

@@ -99,6 +99,7 @@
 /components/esp_https_server/         @esp-idf-codeowners/app-utilities
 /components/esp_hw_support/           @esp-idf-codeowners/system @esp-idf-codeowners/peripherals
 /components/esp_hw_support/lowpower/  @esp-idf-codeowners/power-management
+/components/esp_hw_support/usb_phy/   @esp-idf-codeowners/peripherals/usb
 /components/esp_lcd/                  @esp-idf-codeowners/peripherals
 /components/esp_local_ctrl/           @esp-idf-codeowners/app-utilities
 /components/esp_mm/                   @esp-idf-codeowners/peripherals

components/esp_hw_support/CMakeLists.txt

@@ -37,6 +37,9 @@ if(NOT non_os_build)
                      "dma/gdma_link.c"
                      "spi_bus_lock.c"
                      "clk_utils.c")
+    if(CONFIG_SOC_USB_OTG_SUPPORTED)
+        list(APPEND srcs "usb_phy/usb_phy.c")
+    endif()
     if(CONFIG_SOC_CLK_TREE_SUPPORTED)
         list(APPEND srcs "port/esp_clk_tree_common.c")
     endif()

components/esp_hw_support/include/esp_private/usb_phy.h

@@ -43,15 +43,6 @@ typedef enum {
     USB_PHY_STATUS_IN_USE,           /**< PHY is in use */
 } usb_phy_status_t;
 
-/**
- * @brief USB PHY available actions
- */
-typedef enum {
-    USB_PHY_ACTION_HOST_ALLOW_CONN,             /**< Enable physical connection when operating as an OTG Host */
-    USB_PHY_ACTION_HOST_FORCE_DISCONN,          /**< Disable physical connection when operating as an OTG Host */
-    USB_PHY_ACTION_MAX,
-} usb_phy_action_t;
-
 /**
  * @brief USB external PHY IO pins configuration structure
  */
@@ -132,32 +123,6 @@ esp_err_t usb_new_phy(const usb_phy_config_t *config, usb_phy_handle_t *handle_r
  */
 esp_err_t usb_phy_otg_set_mode(usb_phy_handle_t handle, usb_otg_mode_t mode);
 
-/**
- * @brief Configure USB speed for a USB PHY that is operating as an OTG Device
- *
- * @param handle Pointer of USB PHY context handle
- * @param mode USB speed
- *
- * @return
- *     - ESP_OK Success
- *     - ESP_ERR_INVALID_ARG Parameter error.
- *     - ESP_FAIL OTG set speed fail.
- */
-esp_err_t __attribute__((deprecated)) usb_phy_otg_dev_set_speed(usb_phy_handle_t handle, usb_phy_speed_t speed);
-
-/**
- * @brief Take a action for a USB PHY
- *
- * @param handle Pointer of USB PHY context handle
- * @param action USB PHY action
- *
- * @return
- *     - ESP_OK Success
- *     - ESP_ERR_INVALID_ARG Parameter error.
- *     - ESP_FAIL Action cannot be performed.
- */
-esp_err_t __attribute__((deprecated)) usb_phy_action(usb_phy_handle_t handle, usb_phy_action_t action);
-
 /**
  * @brief Delete a USB PHY
  *

components/esp_hw_support/test_apps/.build-test-rules.yml

@@ -45,6 +45,21 @@ components/esp_hw_support/test_apps/sleep_retention:
     - if: SOC_PAU_SUPPORTED == 1 and SOC_LIGHT_SLEEP_SUPPORTED == 1 and SOC_PM_CPU_RETENTION_BY_SW == 1 and CONFIG_NAME != "xip_psram"
     - if: SOC_PAU_SUPPORTED == 1 and SOC_LIGHT_SLEEP_SUPPORTED == 1 and SOC_PM_CPU_RETENTION_BY_SW == 1 and (SOC_SPIRAM_XIP_SUPPORTED == 1 and CONFIG_NAME == "xip_psram")
 
+components/esp_hw_support/test_apps/usb_phy:
+  enable:
+    - if: SOC_USB_OTG_SUPPORTED == 1
+  depends_components:
+    - usb
+  depends_filepatterns:
+    - components/hal/usb*.c
+    - components/hal/include/hal/usb*.h
+    - components/hal/esp32*/include/hal/usb*.h
+    - components/soc/esp32*/usb*.c
+    - components/soc/include/soc/usb*.h
+    - components/soc/esp32*/include/soc/usb_dwc_*.h
+    - components/soc/esp32*/include/soc/usb_wrap_*.h
+    - components/esp_hw_support/**/usb_phy.*
+
 components/esp_hw_support/test_apps/vad_wakeup:
   disable:
     - if: SOC_LP_VAD_SUPPORTED != 1

components/esp_hw_support/usb_phy/usb_phy.c

@@ -12,14 +12,21 @@
 #include "esp_private/periph_ctrl.h"
 #include "esp_private/usb_phy.h"
 #include "esp_private/critical_section.h"
-#include "soc/usb_dwc_periph.h"
+#include "soc/usb_periph.h"
+#include "hal/gpio_types.h"
 #include "hal/usb_serial_jtag_hal.h"
 #include "hal/usb_wrap_hal.h"
 #include "hal/usb_utmi_hal.h"
-#include "esp_rom_gpio.h"
+#include "hal/gpio_ll.h"
-#include "driver/gpio.h"
 #include "soc/soc_caps.h"
 
+/// Check whether it is a valid GPIO number
+#define GPIO_IS_VALID_GPIO(gpio_num)        ((gpio_num >= 0) && \
+                                              (((1ULL << (gpio_num)) & SOC_GPIO_VALID_GPIO_MASK) != 0))
+/// Check whether it can be a valid GPIO number of output mode
+#define GPIO_IS_VALID_OUTPUT_GPIO(gpio_num) ((gpio_num >= 0) && \
+                                              (((1ULL << (gpio_num)) & SOC_GPIO_VALID_OUTPUT_GPIO_MASK) != 0))
+
 #if SOC_USB_UTMI_PHY_NO_POWER_OFF_ISO
 #include "esp_private/sleep_usb.h"
 #include "esp_sleep.h"
@@ -65,27 +72,27 @@ DEFINE_CRIT_SECTION_LOCK_STATIC(phy_spinlock);
 #define PHY_ENTER_CRITICAL()           esp_os_enter_critical(&phy_spinlock)
 #define PHY_EXIT_CRITICAL()            esp_os_exit_critical(&phy_spinlock)
 
-static esp_err_t phy_configure_pin_input(int gpio_pin, int signal_idx)
+static esp_err_t phy_configure_pin_input(const int gpio_pin, const int signal_idx)
 {
     if (gpio_pin != GPIO_NUM_NC) {
         ESP_RETURN_ON_FALSE(GPIO_IS_VALID_GPIO(gpio_pin),
                             ESP_ERR_INVALID_ARG, USBPHY_TAG, "io_num argument is invalid");
-        esp_rom_gpio_pad_select_gpio(gpio_pin);
+        gpio_ll_func_sel(GPIO_LL_GET_HW(0), gpio_pin, PIN_FUNC_GPIO);
-        esp_rom_gpio_connect_in_signal(gpio_pin, signal_idx, false);
+        gpio_ll_set_input_signal_matrix_source(GPIO_LL_GET_HW(0), signal_idx, gpio_pin, false);
-        gpio_input_enable(gpio_pin);
+        gpio_ll_input_enable(GPIO_LL_GET_HW(0), gpio_pin);
-        esp_rom_gpio_pad_unhold(gpio_pin);
+        gpio_ll_hold_dis(GPIO_LL_GET_HW(0), gpio_pin);
     }
     return ESP_OK;
 }
 
-static esp_err_t phy_configure_pin_output(int gpio_pin, int signal_idx)
+static esp_err_t phy_configure_pin_output(const int gpio_pin, const int signal_idx)
 {
     if (gpio_pin != GPIO_NUM_NC) {
         ESP_RETURN_ON_FALSE(GPIO_IS_VALID_OUTPUT_GPIO(gpio_pin),
                             ESP_ERR_INVALID_ARG, USBPHY_TAG, "io_num argument is invalid");
-        esp_rom_gpio_pad_select_gpio(gpio_pin);
+        gpio_ll_func_sel(GPIO_LL_GET_HW(0), gpio_pin, PIN_FUNC_GPIO);
-        esp_rom_gpio_connect_out_signal(gpio_pin, signal_idx, false, false);
+        gpio_ll_set_output_signal_matrix_source(GPIO_LL_GET_HW(0), gpio_pin, signal_idx, false);
-        esp_rom_gpio_pad_unhold(gpio_pin);
+        gpio_ll_hold_dis(GPIO_LL_GET_HW(0), gpio_pin);
     }
     return ESP_OK;
 }
@@ -151,10 +158,10 @@ esp_err_t usb_phy_otg_set_mode(usb_phy_handle_t handle, usb_otg_mode_t mode)
     const usb_otg_signal_conn_t *otg_sig = usb_dwc_info.controllers[otg11_index].otg_signals;
     assert(otg_sig);
     if (mode == USB_OTG_MODE_HOST) {
-        esp_rom_gpio_connect_in_signal(GPIO_MATRIX_CONST_ZERO_INPUT, otg_sig->iddig, false);     // connected connector is A side
+        gpio_ll_set_input_signal_matrix_source(GPIO_LL_GET_HW(0), otg_sig->iddig, GPIO_MATRIX_CONST_ZERO_INPUT, false);     // connected connector is A side
-        esp_rom_gpio_connect_in_signal(GPIO_MATRIX_CONST_ZERO_INPUT, otg_sig->bvalid, false);
+        gpio_ll_set_input_signal_matrix_source(GPIO_LL_GET_HW(0), otg_sig->bvalid, GPIO_MATRIX_CONST_ZERO_INPUT, false);
-        esp_rom_gpio_connect_in_signal(GPIO_MATRIX_CONST_ONE_INPUT,  otg_sig->vbusvalid, false);  // receiving a valid Vbus from host
+        gpio_ll_set_input_signal_matrix_source(GPIO_LL_GET_HW(0), otg_sig->vbusvalid, GPIO_MATRIX_CONST_ONE_INPUT, false);  // receiving a valid Vbus from host
-        esp_rom_gpio_connect_in_signal(GPIO_MATRIX_CONST_ONE_INPUT,  otg_sig->avalid, false);     // HIGH to force USB host mode
+        gpio_ll_set_input_signal_matrix_source(GPIO_LL_GET_HW(0), otg_sig->avalid, GPIO_MATRIX_CONST_ONE_INPUT, false);     // HIGH to force USB host mode
         if (handle->target == USB_PHY_TARGET_INT) {
             // Configure pull resistors for host
             usb_wrap_pull_override_vals_t vals = {
@@ -166,90 +173,15 @@ esp_err_t usb_phy_otg_set_mode(usb_phy_handle_t handle, usb_otg_mode_t mode)
             usb_wrap_hal_phy_enable_pull_override(&handle->wrap_hal, &vals);
         }
     } else if (mode == USB_OTG_MODE_DEVICE) {
-        esp_rom_gpio_connect_in_signal(GPIO_MATRIX_CONST_ONE_INPUT,  otg_sig->iddig, false);      // connected connector is mini-B side
+        gpio_ll_set_input_signal_matrix_source(GPIO_LL_GET_HW(0), otg_sig->iddig, GPIO_MATRIX_CONST_ONE_INPUT, false);      // connected connector is mini-B side
-        esp_rom_gpio_connect_in_signal(GPIO_MATRIX_CONST_ONE_INPUT,  otg_sig->bvalid, false);     // HIGH to force USB device mode
+        gpio_ll_set_input_signal_matrix_source(GPIO_LL_GET_HW(0), otg_sig->bvalid, GPIO_MATRIX_CONST_ONE_INPUT, false);     // HIGH to force USB device mode
-        esp_rom_gpio_connect_in_signal(GPIO_MATRIX_CONST_ONE_INPUT,  otg_sig->vbusvalid, false);  // receiving a valid Vbus from device
+        gpio_ll_set_input_signal_matrix_source(GPIO_LL_GET_HW(0), otg_sig->vbusvalid, GPIO_MATRIX_CONST_ONE_INPUT, false);  // receiving a valid Vbus from device
-        esp_rom_gpio_connect_in_signal(GPIO_MATRIX_CONST_ZERO_INPUT, otg_sig->avalid, false);
+        gpio_ll_set_input_signal_matrix_source(GPIO_LL_GET_HW(0), otg_sig->avalid, GPIO_MATRIX_CONST_ZERO_INPUT, false);
     }
 
     return ESP_OK;
 }
 
-esp_err_t usb_phy_otg_dev_set_speed(usb_phy_handle_t handle, usb_phy_speed_t speed)
-{
-    ESP_RETURN_ON_FALSE(handle, ESP_ERR_INVALID_ARG, USBPHY_TAG, "handle argument is invalid");
-    ESP_RETURN_ON_FALSE(speed < USB_PHY_SPEED_MAX, ESP_ERR_INVALID_ARG, USBPHY_TAG, "speed argument is invalid");
-    ESP_RETURN_ON_FALSE((handle->target == USB_PHY_TARGET_UTMI) == (speed == USB_PHY_SPEED_HIGH), ESP_ERR_NOT_SUPPORTED, USBPHY_TAG, "UTMI can be HighSpeed only"); // This is our software limitation
-
-    // Keeping this here for backward compatibility
-    // No need to configure anything neither for UTMI PHY nor for USB FSLS PHY
-    return ESP_OK;
-}
-
-esp_err_t usb_phy_action(usb_phy_handle_t handle, usb_phy_action_t action)
-{
-    ESP_RETURN_ON_FALSE(handle, ESP_ERR_INVALID_ARG, USBPHY_TAG, "handle argument is invalid");
-    ESP_RETURN_ON_FALSE(handle->target != USB_PHY_TARGET_UTMI, ESP_ERR_NOT_SUPPORTED, USBPHY_TAG, "Operation not supported on UTMI PHY");
-    ESP_RETURN_ON_FALSE(action < USB_PHY_ACTION_MAX, ESP_ERR_INVALID_ARG, USBPHY_TAG, "action argument is invalid");
-    ESP_RETURN_ON_FALSE((action == USB_PHY_ACTION_HOST_ALLOW_CONN && handle->controller == USB_PHY_CTRL_OTG) ||
-                        (action == USB_PHY_ACTION_HOST_FORCE_DISCONN && handle->controller == USB_PHY_CTRL_OTG),
-                        ESP_ERR_INVALID_ARG, USBPHY_TAG, "wrong target for the action");
-
-    esp_err_t ret = ESP_OK;
-    const usb_fsls_serial_signal_conn_t *fsls_sig = usb_dwc_info.controllers[otg11_index].fsls_signals;
-    assert(fsls_sig);
-
-    switch (action) {
-    case USB_PHY_ACTION_HOST_ALLOW_CONN:
-        if (handle->target == USB_PHY_TARGET_INT) {
-            usb_wrap_hal_phy_enable_test_mode(&handle->wrap_hal, false);
-        } else {
-            if (!handle->iopins) {
-                ret = ESP_FAIL;
-                ESP_LOGE(USBPHY_TAG, "no I/O pins provided for connection");
-                break;
-            }
-            /*
-            Allow for connections on the external PHY by connecting the VP and VM signals to the external PHY.
-            */
-            esp_rom_gpio_connect_in_signal(handle->iopins->vp_io_num, fsls_sig->rx_dp, false);
-            esp_rom_gpio_connect_in_signal(handle->iopins->vm_io_num, fsls_sig->rx_dm, false);
-        }
-        break;
-
-    case USB_PHY_ACTION_HOST_FORCE_DISCONN:
-        if (handle->target == USB_PHY_TARGET_INT) {
-            /*
-            We mimic a disconnect by enabling the internal PHY's test mode,
-            then forcing the output_enable to HIGH. This will cause the received
-            VP and VM to be zero, thus mimicking a disconnection.
-            */
-            const usb_wrap_test_mode_vals_t vals = {
-                .tx_enable_n = true,
-                .tx_dp = false,
-                .tx_dm = false,
-                .rx_dp = false,
-                .rx_dm = false,
-                .rx_rcv = false,
-            };
-            usb_wrap_hal_phy_test_mode_set_signals(&handle->wrap_hal, &vals);
-            usb_wrap_hal_phy_enable_test_mode(&handle->wrap_hal, true);
-        } else {
-            /*
-            Disable connections on the external PHY by connecting the VP and VM signals to the constant LOW signal.
-            */
-            esp_rom_gpio_connect_in_signal(GPIO_MATRIX_CONST_ZERO_INPUT, fsls_sig->rx_dp, false);
-            esp_rom_gpio_connect_in_signal(GPIO_MATRIX_CONST_ZERO_INPUT, fsls_sig->rx_dm, false);
-        }
-        break;
-
-    default:
-        break;
-    }
-
-    return ret;
-}
-
 static esp_err_t usb_phy_install(void)
 {
     PHY_ENTER_CRITICAL();
@@ -369,8 +301,8 @@ esp_err_t usb_new_phy(const usb_phy_config_t *config, usb_phy_handle_t *handle_r
     // For FSLS PHY that shares pads with GPIO peripheral, we must set drive capability to 3 (40mA)
     if (phy_target == USB_PHY_TARGET_INT) {
         assert(usb_dwc_info.controllers[otg11_index].internal_phy_io);
-        gpio_set_drive_capability(usb_dwc_info.controllers[otg11_index].internal_phy_io->dm, GPIO_DRIVE_CAP_3);
+        gpio_ll_set_drive_capability(GPIO_LL_GET_HW(0), usb_dwc_info.controllers[otg11_index].internal_phy_io->dm, GPIO_DRIVE_CAP_3);
-        gpio_set_drive_capability(usb_dwc_info.controllers[otg11_index].internal_phy_io->dp, GPIO_DRIVE_CAP_3);
+        gpio_ll_set_drive_capability(GPIO_LL_GET_HW(0), usb_dwc_info.controllers[otg11_index].internal_phy_io->dp, GPIO_DRIVE_CAP_3);
     }
 
     *handle_ret = (usb_phy_handle_t) phy_context;

components/hal/usb_dwc_hal.c

@@ -10,7 +10,7 @@
 #include <stdlib.h> // For abort()
 #include "sdkconfig.h"
 #include "soc/chip_revision.h"
-#include "soc/usb_dwc_periph.h"
+#include "soc/usb_periph.h"
 #include "hal/usb_dwc_hal.h"
 #include "hal/usb_dwc_ll.h"
 #include "hal/efuse_hal.h"

components/soc/esp32p4/usb_dwc_periph.c

@@ -7,7 +7,7 @@
 #include <stddef.h>
 #include "soc/interrupts.h"
 #include "soc/gpio_sig_map.h"
-#include "soc/usb_dwc_periph.h"
+#include "soc/usb_periph.h"
 #include "soc/usb_dwc_struct.h"
 
 /* -------------------------------- Private --------------------------------- */

components/soc/esp32s2/usb_dwc_periph.c

@@ -6,7 +6,7 @@
 
 #include "soc/gpio_sig_map.h"
 #include "soc/interrupts.h"
-#include "soc/usb_dwc_periph.h"
+#include "soc/usb_periph.h"
 
 /* -------------------------------- Private --------------------------------- */
 

components/soc/esp32s3/usb_dwc_periph.c

@@ -6,7 +6,7 @@
 
 #include "soc/gpio_sig_map.h"
 #include "soc/interrupts.h"
-#include "soc/usb_dwc_periph.h"
+#include "soc/usb_periph.h"
 
 /* -------------------------------- Private --------------------------------- */
 

components/soc/include/soc/usb_dwc_periph.h

@@ -1,108 +0,0 @@
-/*
- * SPDX-FileCopyrightText: 2020-2025 Espressif Systems (Shanghai) CO LTD
- *
- * SPDX-License-Identifier: Apache-2.0
- */
-
-#pragma once
-
-#include "soc/soc_caps.h"
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-#if SOC_USB_OTG_SUPPORTED
-
-/* ---------------------------------- Types --------------------------------- */
-
-/**
- * @brief USB PHY Instance Type
- */
-typedef enum {
-    USB_PHY_INST_FSLS_INTERN_0 = (1 << 0),
-    USB_PHY_INST_FSLS_INTERN_1 = (1 << 1),
-    USB_PHY_INST_UTMI_0        = (1 << 2),
-    USB_PHY_INST_EXTERN        = (1 << 3),
-} usb_phy_inst_t;
-
-/**
- * @brief USB PHY FSLS Serial Interface Signals
- *
- * Structure to store the GPIO matrix signal indexes for a USB PHY FSLS Serial
- * interface's signals.
- *
- * @note Refer to section "2.2.1.13 FsLsSerialMode" of the UTMI+ for more
- *       details regarding the FSLS Serial Interface.
- */
-typedef struct {
-    // Inputs
-    int rx_dp;
-    int rx_dm;
-    int rx_rcv;
-    // Outputs
-    int suspend_n;
-    int tx_enable_n;
-    int tx_dp;
-    int tx_dm;
-    int fs_edge_sel;
-} usb_fsls_serial_signal_conn_t;
-
-/**
- * @brief USB PHY UTMI OTG Interface Signal Index Type
- *
- * Structure to store the GPIO matrix signal indexes for a UTMI PHY interface's
- * OTG signals.
- */
-typedef struct {
-    // Inputs
-    int iddig;
-    int avalid;
-    int bvalid;
-    int vbusvalid;
-    int sessend;
-    // Outputs
-    int idpullup;
-    int dppulldown;
-    int dmpulldown;
-    int drvvbus;
-    int chrgvbus;
-    int dischrgvbus;
-} usb_otg_signal_conn_t;
-
-/**
- * @brief Internal USB PHY IO
- *
- * Structure to store the IO numbers for a particular internal USB PHY
- */
-typedef struct {
-    int dp;
-    int dm;
-} usb_internal_phy_io_t;
-
-/**
- * @brief USB Controller Information
- *
- * Structure to store information for all USB-DWC instances
- *
- * For targets with multiple USB controllers, we support only fixed mapping of the PHYs.
- * This is a software limitation; the hardware supports swapping Controllers and PHYs.
- */
-typedef struct {
-    struct {
-        const usb_fsls_serial_signal_conn_t * const fsls_signals;   // Must be set if external PHY is supported by controller
-        const usb_otg_signal_conn_t * const otg_signals;
-        const usb_internal_phy_io_t * const internal_phy_io;        // Must be set for internal FSLS PHY(s)
-        const usb_phy_inst_t supported_phys;                        // Bitmap of supported PHYs by this controller
-        const int irq;
-        const int irq_2nd_cpu;  // The USB-DWC can provide 2nd interrupt so each CPU can have its own interrupt line. Set to -1 if not supported
-    } controllers [SOC_USB_OTG_PERIPH_NUM];
-} usb_dwc_info_t;
-
-extern const usb_dwc_info_t usb_dwc_info;
-
-#endif // SOC_USB_OTG_SUPPORTED
-
-#ifdef __cplusplus
-}
-#endif

components/soc/include/soc/usb_periph.h

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2020-2024 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2020-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -18,23 +18,92 @@ extern "C" {
 
 #if SOC_USB_OTG_SUPPORTED
 
+/* ---------------------------------- Types --------------------------------- */
+
 /**
- * @brief A pin descriptor for init (DEPRECATED)
+ * @brief USB PHY Instance Type
+ */
+typedef enum {
+    USB_PHY_INST_FSLS_INTERN_0 = (1 << 0),
+    USB_PHY_INST_FSLS_INTERN_1 = (1 << 1),
+    USB_PHY_INST_UTMI_0        = (1 << 2),
+    USB_PHY_INST_EXTERN        = (1 << 3),
+} usb_phy_inst_t;
+
+/**
+ * @brief USB PHY FSLS Serial Interface Signals
  *
- * Todo: Remove in IDF v6.0 (IDF-9029)
+ * Structure to store the GPIO matrix signal indexes for a USB PHY FSLS Serial
+ * interface's signals.
  *
- * @note These IO pins are deprecated. When connecting USB OTG to an external
+ * @note Refer to section "2.2.1.13 FsLsSerialMode" of the UTMI+ for more
- * FSLS PHY, the FSLS Serial Interface signals can be routed to any GPIO via the
+ *       details regarding the FSLS Serial Interface.
- * GPI0 matrix. Thus, this mapping of signals to IO pins is meaningless.
  */
 typedef struct {
-    const int pin;
+    // Inputs
-    const int func;
+    int rx_dp;
-    const bool is_output;
+    int rx_dm;
-    const int ext_phy_only;
+    int rx_rcv;
-} usb_iopin_dsc_t;
+    // Outputs
+    int suspend_n;
+    int tx_enable_n;
+    int tx_dp;
+    int tx_dm;
+    int fs_edge_sel;
+} usb_fsls_serial_signal_conn_t;
 
-extern const usb_iopin_dsc_t usb_periph_iopins[];
+/**
+ * @brief USB PHY UTMI OTG Interface Signal Index Type
+ *
+ * Structure to store the GPIO matrix signal indexes for a UTMI PHY interface's
+ * OTG signals.
+ */
+typedef struct {
+    // Inputs
+    int iddig;
+    int avalid;
+    int bvalid;
+    int vbusvalid;
+    int sessend;
+    // Outputs
+    int idpullup;
+    int dppulldown;
+    int dmpulldown;
+    int drvvbus;
+    int chrgvbus;
+    int dischrgvbus;
+} usb_otg_signal_conn_t;
+
+/**
+ * @brief Internal USB PHY IO
+ *
+ * Structure to store the IO numbers for a particular internal USB PHY
+ */
+typedef struct {
+    int dp;
+    int dm;
+} usb_internal_phy_io_t;
+
+/**
+ * @brief USB Controller Information
+ *
+ * Structure to store information for all USB-DWC instances
+ *
+ * For targets with multiple USB controllers, we support only fixed mapping of the PHYs.
+ * This is a software limitation; the hardware supports swapping Controllers and PHYs.
+ */
+typedef struct {
+    struct {
+        const usb_fsls_serial_signal_conn_t * const fsls_signals;   // Must be set if external PHY is supported by controller
+        const usb_otg_signal_conn_t * const otg_signals;
+        const usb_internal_phy_io_t * const internal_phy_io;        // Must be set for internal FSLS PHY(s)
+        const usb_phy_inst_t supported_phys;                        // Bitmap of supported PHYs by this controller
+        const int irq;
+        const int irq_2nd_cpu;  // The USB-DWC can provide 2nd interrupt so each CPU can have its own interrupt line. Set to -1 if not supported
+    } controllers [SOC_USB_OTG_PERIPH_NUM];
+} usb_dwc_info_t;
+
+extern const usb_dwc_info_t usb_dwc_info;
 
 #endif // SOC_USB_OTG_SUPPORTED
 

components/soc/linux/include/soc/gpio_sig_map.h

@@ -0,0 +1,7 @@
+/**
+ * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+ *
+ *  SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once

components/soc/linux/include/soc/soc_pins.h

@@ -0,0 +1,7 @@
+/**
+ * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+ *
+ *  SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once

components/usb/CMakeLists.txt

@@ -10,7 +10,7 @@ set(priv_includes)
 # As CONFIG_SOC_USB_OTG_SUPPORTED comes from Kconfig, it is not evaluated yet
 # when components are being registered.
 # Thus, always add the (private) requirements, regardless of Kconfig
-set(priv_requires esp_driver_gpio esp_mm)  # usb_phy driver relies on gpio driver API
+set(priv_requires esp_mm)
 
 # Explicitly add psram component for esp32p4, as the USB-DWC internal DMA can access PSRAM on esp32p4
 if(${target} STREQUAL "esp32p4")
@@ -25,7 +25,6 @@ if(CONFIG_SOC_USB_OTG_SUPPORTED)
                      "usb_host.c"
                      "usb_private.c"
                      "usbh.c"
-                     "usb_phy.c"
                      )
     list(APPEND include "include")
     list(APPEND priv_includes "private_include")

components/usb/hcd_dwc.c

@@ -18,7 +18,7 @@
 #include "esp_log.h"
 
 #include "soc/soc_caps.h"
-#include "soc/usb_dwc_periph.h"
+#include "soc/usb_periph.h"
 #include "hal/usb_dwc_hal.h"
 #include "hcd.h"
 #include "usb_private.h"

components/usb/test_apps/.build-test-rules.yml

@@ -17,17 +17,3 @@ components/usb/test_apps:
     - components/soc/include/soc/usb*.h
     - components/soc/esp32*/include/soc/usb_dwc_*.h
     - components/soc/esp32*/include/soc/usb_wrap_*.h
-
-components/usb/test_apps/phy:
-  enable:
-    - if: SOC_USB_OTG_SUPPORTED == 1
-  depends_components:
-    - usb
-  depends_filepatterns:
-    - components/hal/usb*.c
-    - components/hal/include/hal/usb*.h
-    - components/hal/esp32*/include/hal/usb*.h
-    - components/soc/esp32*/usb*.c
-    - components/soc/include/soc/usb*.h
-    - components/soc/esp32*/include/soc/usb_dwc_*.h
-    - components/soc/esp32*/include/soc/usb_wrap_*.h

components/usb/usb_host.c

@@ -17,7 +17,7 @@ Warning: The USB Host Library API is still a beta version and may be subject to
 #include "freertos/queue.h"
 #include "freertos/semphr.h"
 #include "esp_private/critical_section.h"
-#include "soc/usb_dwc_periph.h"
+#include "soc/usb_periph.h"
 #include "esp_err.h"
 #include "esp_log.h"
 #include "esp_heap_caps.h"

examples/peripherals/.build-test-rules.yml

@@ -594,6 +594,8 @@ examples/peripherals/usb/host:
     - components/soc/include/soc/usb*.h
     - components/soc/esp32*/include/soc/usb_dwc_*.h
     - components/soc/esp32*/include/soc/usb_wrap_*.h
+    - components/esp_hw_support/usb_phy/usb_phy.c
+    - components/esp_hw_support/include/esp_private/usb_phy.h
     - examples/peripherals/usb/host/**/*
 
 examples/peripherals/usb_serial_jtag/usb_serial_jtag_echo:

tools/ci/check_public_headers_exceptions.txt

@@ -98,7 +98,6 @@ components/protocomm/include/transports/protocomm_httpd.h
 components/fatfs/src/diskio.h
 components/fatfs/diskio/diskio_sdmmc.h
 components/mbedtls/esp_crt_bundle/include/esp_crt_bundle.h
-components/usb/include/esp_private/usb_phy.h
 components/usb/include/usb/usb_types_stack.h
 
 ### Headers that don't compile with C++

tools/mocks/esp_hw_support/CMakeLists.txt

@@ -3,6 +3,9 @@
 message(STATUS "building ESP HW SUPPORT MOCKS")
 
 idf_component_get_property(original_esp_hw_support_dir esp_hw_support COMPONENT_OVERRIDEN_DIR)
+if(NOT original_esp_hw_support_dir)
+    idf_component_get_property(original_esp_hw_support_dir esp_hw_support COMPONENT_DIR)
+endif()
 
 idf_component_mock(INCLUDE_DIRS "${original_esp_hw_support_dir}/include"
                    MOCK_HEADER_FILES ${original_esp_hw_support_dir}/include/esp_mac.h

tools/mocks/usb/usb_host_full_mock/usb/CMakeLists.txt

@@ -5,14 +5,18 @@
 message(STATUS "building full USB HOST MOCKS")
 
 idf_component_get_property(original_usb_dir usb COMPONENT_OVERRIDEN_DIR)
+idf_component_get_property(original_esp_hw_support_dir esp_hw_support COMPONENT_OVERRIDEN_DIR)
+if(NOT original_esp_hw_support_dir)
+    idf_component_get_property(original_esp_hw_support_dir esp_hw_support COMPONENT_SRCDIR)
+endif()
 
 idf_component_mock(INCLUDE_DIRS "${original_usb_dir}/include"
-                                "${original_usb_dir}/include/esp_private"
                                 "${original_usb_dir}/include/usb"
                                 "${original_usb_dir}/private_include"
+                                "${original_esp_hw_support_dir}/include/esp_private"     # for USB PHY
                                 "include"
                    MOCK_HEADER_FILES ${original_usb_dir}/include/usb/usb_host.h
-                                     ${original_usb_dir}/include/esp_private/usb_phy.h
+                                     ${original_esp_hw_support_dir}/include/esp_private/usb_phy.h
                    REQUIRES freertos)
 
 

tools/mocks/usb/usb_host_layer_mock/usb/CMakeLists.txt

@@ -5,16 +5,21 @@
 message(STATUS "building USB HOST Layer MOCKS")
 
 idf_component_get_property(original_usb_dir usb COMPONENT_OVERRIDEN_DIR)
+idf_component_get_property(original_esp_hw_support_dir esp_hw_support COMPONENT_OVERRIDEN_DIR)
+if(NOT original_esp_hw_support_dir)
+    idf_component_get_property(original_esp_hw_support_dir esp_hw_support COMPONENT_DIR)
+endif()
+
 
 idf_component_mock(INCLUDE_DIRS "${original_usb_dir}/include"
-                                "${original_usb_dir}/include/esp_private"
                                 "${original_usb_dir}/include/usb"
                                 "${original_usb_dir}/private_include"
+                                "${original_esp_hw_support_dir}/include/esp_private"     # for USB PHY
                    MOCK_HEADER_FILES ${original_usb_dir}/private_include/enum.h
                                      ${original_usb_dir}/private_include/hcd.h
                                      ${original_usb_dir}/private_include/hub.h
                                      ${original_usb_dir}/private_include/usbh.h
-                                     ${original_usb_dir}/include/esp_private/usb_phy.h
+                                     ${original_esp_hw_support_dir}/include/esp_private/usb_phy.h
                    REQUIRES freertos)
 
 # We do not mock usb_host.c, we use the original implementation of it

tools/mocks/usb/usbh_layer_mock/usb/CMakeLists.txt

@@ -7,7 +7,6 @@ message(STATUS "building USBH Layer MOCKS")
 idf_component_get_property(original_usb_dir usb COMPONENT_OVERRIDEN_DIR)
 
 idf_component_mock(INCLUDE_DIRS "${original_usb_dir}/include"
-                                "${original_usb_dir}/include/esp_private"
                                 "${original_usb_dir}/include/usb"
                                 "${original_usb_dir}/private_include"
                    MOCK_HEADER_FILES ${original_usb_dir}/private_include/hcd.h