refactor(usb_host): Move parent-child tree management to Hub Driver

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

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/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
  */
@@ -131,66 +131,83 @@ esp_err_t hub_root_stop(void);
 /**
  * @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_node_active(unsigned int node_uid);
+
+/**
+ * @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] node_uid  Device's node unique ID
+ *
+ * @return
+ *    - ESP_ERR_INVALID_STATE if Hub driver is not installed
+ *    - ESP_ERR_NOT_SUPPORTED if the function is not support by the selected port
+ *    - ESP_ERR_NOT_FOUND if device's tree node is not found by uid
+ *    - ESP_OK if Port has been disabled without error
  */
-esp_err_t hub_port_active(usb_device_handle_t parent_dev_hdl, uint8_t parent_port_num);
+esp_err_t hub_node_disable(unsigned int node_uid);
 
 /**
- * @brief Disable the port
+ * @brief Get the node information of the 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
+ * @param[out] info     Device information
  *
  * @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_INVALID_STATE 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

host/usb/private_include/usbh.h

@@ -59,8 +59,6 @@ typedef struct {
         } dev_gone_data;
         struct {
             unsigned int dev_uid;
-            usb_device_handle_t parent_dev_hdl;
-            uint8_t port_num;
         } dev_free_data;
     };
 } usbh_event_data_t;
@@ -139,8 +137,6 @@ typedef struct {
     unsigned int uid;                       /**< Unique ID assigned to the device */
     usb_speed_t speed;                      /**< Device's speed */
     hcd_port_handle_t root_port_hdl;        /**< Handle of the port that the device is connected to */
-    usb_device_handle_t parent_dev_hdl;     /**< Parent's device handle */
-    uint8_t parent_port_num;                /**< Parent's port number */
 } usbh_dev_params_t;
 
 // ---------------------- USBH Processing Functions ----------------------------
@@ -269,21 +265,6 @@ esp_err_t usbh_devs_add(usbh_dev_params_t *params);
  */
 esp_err_t usbh_devs_remove(unsigned int uid);
 
-/**
- * @brief Get a device's connection information
- *
- * @note Can be called without opening the device
- *
- * @param[in] uid               Unique ID assigned to the device
- * @param[out] parent_info      Parent device handle
- *
- * @return
- *    - ESP_OK: Device parent info obtained successfully
- *    - ESP_ERR_INVALID_ARG: Invalid argument
- *    - ESP_ERR_NOT_FOUND: Device with provided uid not found
- */
-esp_err_t usbh_devs_get_parent_info(unsigned int uid, usb_parent_dev_info_t *parent_info);
-
 /**
  * @brief Mark that all devices should be freed at the next possible opportunity
  *
@@ -342,6 +323,20 @@ esp_err_t usbh_devs_new_dev_event(usb_device_handle_t dev_hdl);
 esp_err_t usbh_dev_close(usb_device_handle_t dev_hdl);
 
 // ------------------------------ Getters --------------------------------------
+/**
+ * @brief Get a device's UID
+ *
+ * @note Callers of this function must have opened the device via usbh_devs_open()
+ *
+ * @param[in] dev_hdl Device handle
+ * @param[out] uid Device's UID
+ *
+ * @return
+ *    - ESP_ERR_INVALID_ARG if invalid argument
+ *    - ESP_OK if Device's UID obtained successfully
+ */
+esp_err_t usbh_dev_get_uid(usb_device_handle_t dev_hdl, unsigned int *uid);
+
 /**
  * @brief Get a device's address
  *