feature(usb_host): Support multiple DWC OTG peripheral ports in Host mode

host/usb/include/usb/usb_types_stack.h

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2015-2024 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2015-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -74,8 +74,10 @@ typedef bool (*usb_host_enum_filter_cb_t)(const usb_device_desc_t *dev_desc, uin
  * @brief Parent device information
 */
 typedef struct {
-    usb_device_handle_t dev_hdl;                    /**< Device's parent handle */
-    uint8_t port_num;                               /**< Device's parent port number */
+    // IDF-12502: Remove the parent dev_hdl from parent_info structure (breaking change)
+    usb_device_handle_t dev_hdl __attribute__((deprecated)); /**< Device's parent handle: Deprecated, as dev_hdl only valid when device was opened via usbh_devs_open() */
+    uint8_t dev_addr;                                        /**< Device's parent bus address */
+    uint8_t port_num;                                        /**< Device's parent port number */
 } usb_parent_dev_info_t;
 
 /**

host/usb/private_include/enum.h

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2024 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2024-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -44,31 +44,9 @@ typedef enum {
 } enum_event_t;
 
 typedef struct {
-    enum_event_t event;                         /**< Enumerator driver event */
-    union {
-        struct {
-            unsigned int uid;                   /**< Device unique ID */
-            usb_device_handle_t parent_dev_hdl; /**< Parent of the enumerating device */
-            uint8_t parent_port_num;            /**< Parent port number of the enumerating device */
-        } started;                              /**< ENUM_EVENT_STARTED specific data */
-
-        struct {
-            usb_device_handle_t parent_dev_hdl; /**< Parent of the enumerating device */
-            uint8_t parent_port_num;            /**< Parent port number of the enumerating device */
-        } reset_req;                            /**< ENUM_EVENT_RESET_REQUIRED specific data */
-
-        struct {
-            usb_device_handle_t parent_dev_hdl; /**< Parent of the enumerating device */
-            uint8_t parent_port_num;            /**< Parent port number of the enumerating device */
-            usb_device_handle_t dev_hdl;        /**< Handle of the enumerating device */
-            uint8_t dev_addr;                   /**< Address of the enumerating device */
-        } complete;                             /**< ENUM_EVENT_COMPLETED specific data */
-
-        struct {
-            usb_device_handle_t parent_dev_hdl; /**< Parent of the enumerating device */
-            uint8_t parent_port_num;            /**< Parent port number of the enumerating device */
-        } canceled;                             /**< ENUM_EVENT_CANCELED specific data */
-    };
+    enum_event_t event;             /**< Enumerator driver event */
+    unsigned int node_uid;          /**< Unique node ID */
+    usb_device_handle_t dev_hdl;    /**< Handle of the enumerating device */
 } enum_event_data_t;
 
 // ---------------------------- Callbacks --------------------------------------

host/usb/private_include/ext_hub.h

@@ -83,17 +83,34 @@ void *ext_hub_get_client(void);
 // -------------------------- External Hub API ---------------------------------
 
 /**
- * @brief Get External Hub device handle by USBH device handle
+ * @brief Get the External Hub device USB speed
  *
- * @param[in] dev_hdl       USBH device handle
- * @param[out] ext_hub_hdl  External Hub device handle
+ * @note Device should be in list of devices
  *
+ * @paramp[in] ext_hub_hdl   External Hub device handle
+ * @param[out] speed         USB speed
  * @return
- *    - ESP_OK: External Hub device handle successfully obtained
- *    - ESP_ERR_INVALID_STATE: External Hub driver is not installed
- *    - ESP_ERR_NOT_FOUND: Device not found
+ *    - ESP_ERR_NOT_ALLOWED if the External Hub driver is not installed
+ *    - ESP_ERR_INVALID_ARG if the handle or speed is NULL
+ *    - ESP_ERR_NOT_FOUND if the device is not found
+ *    - ESP_OK if the speed was obtained
  */
-esp_err_t ext_hub_get_handle(usb_device_handle_t dev_hdl, ext_hub_handle_t *ext_hub_hdl);
+esp_err_t ext_hub_get_speed(ext_hub_handle_t ext_hub_hdl, usb_speed_t *speed);
+
+/**
+ * @brief Get the External Hub device USB address
+ *
+ * @note Device should be in list of devices
+ *
+ * @paramp[in] ext_hub_hdl   External Hub device handle
+ * @param[out] addr          USB address
+ * @return
+ *    - ESP_ERR_NOT_ALLOWED if the External Hub driver is not installed
+ *    - ESP_ERR_INVALID_ARG if the handle or addr is NULL
+ *    - ESP_ERR_NOT_FOUND if the device is not found
+ *    - ESP_OK if the address was obtained
+ */
+esp_err_t ext_hub_get_dev_addr(ext_hub_handle_t ext_hub_hdl, uint8_t *addr);
 
 /**
  * @brief Add new device
@@ -245,6 +262,17 @@ esp_err_t ext_hub_port_disable(ext_hub_handle_t ext_hub_hdl, uint8_t port_num);
  */
 esp_err_t ext_hub_port_get_speed(ext_hub_handle_t ext_hub_hdl, uint8_t port_num, usb_speed_t *speed);
 
+/**
+ * @brief Returns root port handle of the External Hub
+ *
+ * @param[in] ext_hub_hdl   External Hub handle
+ *
+ * @return
+ *   - Root port handle of the External Hub if the External Hub is installed
+ *   - NULL if External Hub is not installed
+ */
+hcd_port_handle_t ext_hub_get_root_port_handle(ext_hub_handle_t ext_hub_hdl);
+
 // --------------------------- USB Chapter 11 ----------------------------------
 
 /**

host/usb/private_include/ext_port.h

@@ -47,29 +47,6 @@ typedef enum {
     EXT_PORT_DISCONNECTED,          /**< Port has a device disconnection event */
 } ext_port_event_t;
 
-/**
- * @brief Event data object for External Port driver events
- */
-typedef struct {
-    ext_port_event_t event;
-    union {
-        struct {
-            usb_device_handle_t parent_dev_hdl; /**< Ports' parent device handle */
-            uint8_t parent_port_num;            /**< Ports' parent port number */
-        } connected;                            /**< EXT_PORT_CONNECTED event specific data */
-
-        struct {
-            usb_device_handle_t parent_dev_hdl; /**< Ports' parent device handle */
-            uint8_t parent_port_num;            /**< Ports' parent port number */
-        } reset_completed;                      /**< EXT_PORT_RESET_COMPLETED event specific data */
-
-        struct {
-            usb_device_handle_t parent_dev_hdl; /**< Ports' parent device handle */
-            uint8_t parent_port_num;            /**< Ports' parent port number */
-        } disconnected;                         /**< EXT_PORT_DISCONNECTED event specific data */
-    };
-} ext_port_event_data_t;
-
 typedef enum {
     EXT_PORT_PARENT_REQ_CONTROL = 0x01,     /** Port requires action from the parent Hub */
     EXT_PORT_PARENT_REQ_PROC_COMPLETED      /** All ports were handled */
@@ -101,7 +78,7 @@ typedef void (*ext_port_cb_t)(void *user_arg);
  *
  * @note For the Hub Driver only
  */
-typedef void (*ext_port_event_cb_t)(ext_port_hdl_t port_hdl, ext_port_event_data_t *event_data, void *arg);
+typedef void (*ext_port_event_cb_t)(ext_port_hdl_t port_hdl, ext_port_event_t event, void *arg);
 
 /**
  * @brief Callback used to indicate that the External Port driver requires a Hub class specific request
@@ -129,8 +106,7 @@ typedef struct {
  */
 typedef struct {
     void *context;                              /**< Ports' parent external Hub handle */
-    usb_device_handle_t parent_dev_hdl;         /**< Ports' parent device handle */
-    uint8_t parent_port_num;                    /**< Ports' parent port number */
+    uint8_t port_num;                    /**< Ports' parent port number */
     uint16_t port_power_delay_ms;               /**< Ports' Power on time to Power Good, ms */
 } ext_port_config_t;
 

host/usb/private_include/hcd.h

@@ -303,6 +303,15 @@ hcd_port_state_t hcd_port_get_state(hcd_port_handle_t port_hdl);
  */
 esp_err_t hcd_port_get_speed(hcd_port_handle_t port_hdl, usb_speed_t *speed);
 
+/**
+ * @brief Get the port number
+ *
+ * @param[in] port_hdl Port handle
+ *
+ * @return uint8_t Port number
+ */
+uint8_t hcd_port_get_number(hcd_port_handle_t port_hdl);
+
 /**
  * @brief Handle a ports event
  *

host/usb/private_include/hub.h

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2015-2024 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2015-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -111,86 +111,107 @@ esp_err_t hub_uninstall(void);
  *
  * @note This function should only be called from the Host Library task
  *
+ * @param[in] port_idx  Root port index
+ *
  * @return
  *    - ESP_OK: Hub driver started successfully
  *    - ESP_ERR_INVALID_STATE: Hub driver is not installed, or root port is in other state than not powered
  */
-esp_err_t hub_root_start(void);
+esp_err_t hub_root_start(uint8_t port_idx);
 
 /**
  * @brief Stops the Hub driver's root port
  *
  * This will power OFF the root port
  *
+ * @param[in] port_idx  Root port index
+ *
  * @return
  *    - ESP_OK: Hub driver started successfully
  *    - ESP_ERR_INVALID_STATE: Hub driver is not installed, or root port is in not powered state
  */
-esp_err_t hub_root_stop(void);
+esp_err_t hub_root_stop(uint8_t port_idx);
 
 /**
  * @brief Indicate to the Hub driver that a device's port can be recycled
  *
- * The device connected to the port has been freed. The Hub driver can now recycled the port
+ * The device connected to the port has been freed.
+ * The Hub driver can now recycled the node and re-enable the port while it it still present.
  *
  * @note This function should only be called from the Host Library task
  *
- * @param[in] parent_dev_hdl    Parent device handle (is used to get the External Hub handle)
- * @param[in] parent_port_num   Parent number (is used to specify the External Port)
- * @param[in] dev_uid Device's unique ID
+ * @param[in] node_uid  Device's node unique ID
  *
  * @return
  *    - ESP_OK: device's port can be recycled
  *    - ESP_ERR_INVALID_STATE: Hub driver is not installed
  *    - ESP_ERR_NOT_SUPPORTED: Recycling External Port is not available (External Hub support disabled),
  *      or ext hub port error
+ *    - ESP_ERR_NOT_FOUND: Device's node is not found
  */
-esp_err_t hub_port_recycle(usb_device_handle_t parent_dev_hdl, uint8_t parent_port_num, unsigned int dev_uid);
+esp_err_t hub_node_recycle(unsigned int node_uid);
 
 /**
- * @brief Reset the port
+ * @brief Reset the device in the port, related to the specific Device Tree node
  *
  * @note This function should only be called from the Host Library task
  *
- * @param[in] parent_dev_hdl    Parent device handle (is used to get the External Hub handle)
- * @param[in] parent_port_num   Parent number (is used to specify the External Port)
+ * @param[in] node_uid  Device's node unique ID
+ *
  * @return
- *    - ESP_OK: Port reset successful
+ *    - ESP_OK if device in port reset successful
  *    - ESP_ERR_INVALID_STATE: Hub driver is not installed
  *    - ESP_ERR_NOT_SUPPORTED: Resetting External Port is not available (External Hub support disabled),
  *      or ext hub port error
+ *    - ESP_ERR_NOT_FOUND: Device's node is not found
  */
-esp_err_t hub_port_reset(usb_device_handle_t parent_dev_hdl, uint8_t parent_port_num);
+esp_err_t hub_node_reset(unsigned int node_uid);
 
 /**
- * @brief Activate the port
+ * @brief Port, related to the specific Device Tree node, has an active device
  *
  * @note This function should only be called from the Host Library task
  *
- * @param[in] parent_dev_hdl    Parent device handle (is used to get the External Hub handle)
- * @param[in] parent_port_num   Parent number (is used to specify the External Port)
+ * @param[in] node_uid  Device's node unique ID
  *
  * @return
- *    - ESP_OK: Port activated successfully
- *    - ESP_ERR_NOT_SUPPORTED: Activating External Port is not available (External Hub support disabled),
+ *    - ESP_OK if Port, related to the Device Tree node was activated successfully
+ *    - ESP_ERR_NOT_SUPPORTED if activating Port is not available (External Hub support disabled),
  *      or ext hub port error
+ *    - ESP_ERR_NOT_FOUND if Device's node is not found
  */
-esp_err_t hub_port_active(usb_device_handle_t parent_dev_hdl, uint8_t parent_port_num);
+esp_err_t hub_node_active(unsigned int node_uid);
 
 /**
- * @brief Disable the port
+ * @brief Disable the port, related to the specific Device Tree node
  *
  * @note This function should only be called from the Host Library task
  *
- * @param[in] parent_dev_hdl    Parent device handle (is used to get the External Hub handle)
- * @param[in] parent_port_num   Parent number (is used to specify the External Port)
+ * @param[in] node_uid  Device's node unique ID
  *
  * @return
  *    - ESP_OK:                  Port has been disabled without error
  *    - ESP_ERR_INVALID_STATE:   Port can't be disabled in current state
  *    - ESP_ERR_NOT_SUPPORTED:   This function is not support by the selected port
+ *    - ESP_ERR_NOT_FOUND:       Device's node is not found
+ */
+esp_err_t hub_node_disable(unsigned int node_uid);
+
+/**
+ * @brief Get the node information of the device
+ *
+ * @note This function should only be called from the Host Library task
+ *
+ * @param[in] node_uid  Device's node unique ID
+ * @param[out] info     Device information
+ *
+ * @return
+ *    - ESP_ERR_NOT_ALLOWED if the Hub driver is not installed
+ *    - ESP_ERR_INVALID_ARG if the info pointer is NULL
+ *    - ESP_ERR_NOT_FOUND if the device node is not found
+ *    - ESP_OK if Device's information obtained successfully
  */
-esp_err_t hub_port_disable(usb_device_handle_t parent_dev_hdl, uint8_t parent_port_num);
+esp_err_t hub_node_get_info(unsigned int node_uid, usb_parent_dev_info_t *info);
 
 /**
  * @brief Notify Hub driver that new device has been attached