refactor(usb_host): Removed parent_dev_hdl from the External Port Driver (part3/4)

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,19 @@ 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 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,67 @@ 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_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_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_disable(usb_device_handle_t parent_dev_hdl, uint8_t parent_port_num);
+esp_err_t hub_node_disable(unsigned int node_uid);
 
 /**
  * @brief Notify Hub driver that new device has been attached