Merge pull request #389 from espressif/feat/hub_multi_root_port

feat(hub): Added support for multiple root ports

Author: tore-espressif

host/class/cdc/usb_host_cdc_acm/test_app/main/test_app_main.c

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2024-2025 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2024-2026 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -38,6 +38,6 @@ void app_main(void)
     printf("                 \\/         \\/             \\/     \\/        \r\n");
 
     unity_utils_setup_heap_record(80);
-    unity_utils_set_leak_level(30);
+    unity_utils_set_leak_level(40);
     unity_run_menu();
 }

host/usb/private_include/enum.h

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2024-2025 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2024-2026 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -109,6 +109,7 @@ esp_err_t enum_uninstall(void);
  * @return
  *    - ESP_OK: Enumeration process started
  *    - ESP_ERR_NOT_FOUND: No device at address 0
+ *    - ESP_ERR_NO_MEM: Pending enumeration queue is full
  */
 esp_err_t enum_start(unsigned int uid);
 

host/usb/private_include/ext_hub.h

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2024-2025 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2024-2026 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -97,6 +97,15 @@ void *ext_hub_get_client(void);
  */
 esp_err_t ext_hub_get_speed(ext_hub_handle_t ext_hub_hdl, usb_speed_t *speed);
 
+/**
+ * @brief Get the root port handle of an External Hub device
+ *
+ * @param[in] ext_hub_hdl External Hub device handle
+ *
+ * @return Root port handle on success, NULL on error
+ */
+hcd_port_handle_t ext_hub_get_root_port(ext_hub_handle_t ext_hub_hdl);
+
 /**
  * @brief Add new device
  *

host/usb/private_include/hcd.h

@@ -14,12 +14,17 @@ extern "C" {
 #include <stdbool.h>
 #include <sys/queue.h>
 #include "esp_err.h"
+#include "soc/soc_caps.h"
 #include "esp_idf_version.h"
 #include "usb_private.h"
 #include "usb/usb_types_ch9.h"
 
 // ------------------------------------------------- Macros & Types ----------------------------------------------------
 
+// ----------------------- Configs -------------------------
+
+#define HCD_NUM_PORTS                           SOC_USB_OTG_PERIPH_NUM   // Each peripheral is a root port
+
 // ----------------------- States --------------------------
 
 /**

host/usb/private_include/hub.h

@@ -77,7 +77,7 @@ typedef struct {
  * - USBH must already be installed
  * Exit:
  * - Install Hub driver memory resources
- * - Initializes the HCD root port
+ * - Initializes the HCD root ports selected by hub_config->port_map
  *
  * @param[in] hub_config Hub driver configuration
  * @param[out] client_ret Unique pointer to identify the Hub as a USB Host client
@@ -95,44 +95,43 @@ esp_err_t hub_install(hub_config_t *hub_config, void **client_ret);
  *
  * This must be called before uninstalling the USBH
  * Entry:
- * - Must have stopped the root port
+ * - Must have stopped all enabled root ports
  * Exit:
- * - HCD root port deinitialized
+ * - HCD root ports deinitialized
  *
  * @return
  *    - ESP_OK: Hub driver uninstalled successfully
- *    - ESP_ERR_INVALID_STATE: Hub driver is not installed, or root port is in other state than not powered
+ *    - ESP_ERR_INVALID_STATE: Hub driver is not installed, or any enabled root port is in other state than not powered
  */
 esp_err_t hub_uninstall(void);
 
 /**
- * @brief Start the Hub driver's root port
+ * @brief Start the Hub driver's root ports
  *
- * This will power the root port ON
- *
- * @note This function should only be called from the Host Library task
+ * This will power ON all enabled root ports.
  *
  * @return
- *    - ESP_OK: Root port has been powered on
- *    - ESP_ERR_INVALID_STATE: Hub driver is not installed, or root port is in other state than not powered
+ *    - ESP_OK: All enabled root ports have been powered on
+ *    - ESP_ERR_INVALID_STATE: Hub driver is not installed, or any enabled root port is in other state than not powered
  */
 esp_err_t hub_root_start(void);
 
 /**
- * @brief Stops the Hub driver's root port
+ * @brief Stops the Hub driver's root ports
  *
- * This will power OFF the root port
+ * This will power OFF all enabled root ports.
  *
  * @return
- *    - ESP_OK: Root port has been powered off
- *    - ESP_ERR_INVALID_STATE: Hub driver is not installed, or root port is in not powered state
+ *    - ESP_OK: All enabled root ports have been powered off
+ *    - ESP_ERR_INVALID_STATE: Hub driver is not installed, or all enabled root ports are already not powered
  */
 esp_err_t hub_root_stop(void);
 
 /**
- * @brief Check if root port is in suspended state
+ * @brief Check if a root port is in suspended state
  *
- * This will check root port state
+ * This will check root port state. In multi-port configurations, this currently
+ * checks the first enabled root port only.
  *
  * @return
  *    - true: Root port is in suspended state
@@ -143,7 +142,8 @@ bool hub_root_is_suspended(void);
 /**
  * @brief Check if the Hub driver's root port can be suspended
  *
- * This will check if all HCD pipes are idle and which state the root port is in
+ * This will check if all HCD pipes are idle and which state the root port is in.
+ * In multi-port configurations, this currently checks the first enabled root port only.
  *
  * @return
  *    - ESP_OK: Hub driver's root port can be suspended
@@ -157,6 +157,8 @@ esp_err_t hub_root_can_suspend(void);
 /**
  * @brief Check if the Hub driver's root port can be resumed
  *
+ * In multi-port configurations, this currently checks the first enabled root port only.
+ *
  * @return
  *    - ESP_OK: Hub driver's root port can be resumed
  *    - ESP_ERR_INVALID_STATE: Hub driver is not installed
@@ -169,7 +171,8 @@ esp_err_t hub_root_can_resume(void);
 /**
  * @brief Mark the Hub driver's root port as ready for suspend
  *
- * This will mark the root port, as ready to be suspended and and will be processed by the hub processing loop
+ * This will mark the root port as ready to be suspended and will be processed by the hub processing loop.
+ * In multi-port configurations, this currently targets the first enabled root port only.
  *
  * @return
  *    - ESP_OK: Hub driver suspended successfully
@@ -181,7 +184,8 @@ esp_err_t hub_root_mark_suspend(void);
 /**
  * @brief Mark the Hub driver's root port as ready for resume
  *
- * This will mark the root port, as ready to be resumed and and will be processed by the hub processing loop
+ * This will mark the root port as ready to be resumed and will be processed by the hub processing loop.
+ * In multi-port configurations, this currently targets the first enabled root port only.
  *
  * @return
  *    - ESP_OK: Hub driver resumed successfully

host/usb/private_include/usbh.h

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2015-2025 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2015-2026 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -336,6 +336,23 @@ void usbh_devs_set_pm_actions_all(usbh_dev_ctrl_t device_ctrl);
  */
 esp_err_t usbh_devs_open(uint8_t dev_addr, usb_device_handle_t *dev_hdl);
 
+/**
+ * @brief Open a device by UID
+ *
+ * A device must be opened before it can be used
+ *
+ * @param[in]  uid     Unique ID assigned to the device
+ * @param[out] dev_hdl Device handle
+ *
+ * @return
+ *    - ESP_OK: Device opened successfully
+ *    - ESP_ERR_INVALID_ARG: Invalid argument
+ *    - ESP_ERR_INVALID_STATE: Device is in invalid state, either already gone (disconnected), or waiting to be freed
+ *    - ESP_ERR_NOT_ALLOWED: It is not allowed to open the device, it is locked for the enumeration
+ *    - ESP_ERR_NOT_FOUND: Device with provided UID not found
+ */
+esp_err_t usbh_devs_open_uid(unsigned int uid, usb_device_handle_t *dev_hdl);
+
 /**
  * @brief Trigger a USBH_EVENT_NEW_DEV event for the device
  *
@@ -395,6 +412,18 @@ esp_err_t usbh_dev_get_addr(usb_device_handle_t dev_hdl, uint8_t *dev_addr);
  */
 esp_err_t usbh_dev_get_info(usb_device_handle_t dev_hdl, usb_device_info_t *dev_info);
 
+/**
+ * @brief Get the root port handle of a device
+ *
+ * @param[in] dev_hdl Device handle
+ * @param[out] root_port_hdl Root port handle
+ *
+ * @return
+ *    - ESP_OK: Root port handle obtained successfully
+ *    - ESP_ERR_INVALID_ARG: Invalid argument
+ */
+esp_err_t usbh_dev_get_root_port_hdl(usb_device_handle_t dev_hdl, hcd_port_handle_t *root_port_hdl);
+
 /**
  * @brief Get a device's device descriptor
  *

host/usb/src/enum.c

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2023-2025 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2023-2026 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -26,6 +26,7 @@
 #define ENUM_WORST_CASE_MPS_FS_HS                   64      // The worst case MPS of EP0 for a FS/HS device
 #define ENUM_LANGID                                 0x409   // Current enumeration only supports English (United States) string descriptors
 #define ENUM_MAX_ADDRESS                            (127)   // Maximal device address value
+#define ENUM_PENDING_QUEUE_LEN                      (5)
 
 /**
  * @brief Stages of device enumeration listed in their order of execution
@@ -139,6 +140,11 @@ typedef struct {
         enum_device_params_t dev_params;            /**< Parameters of device under enumeration */
         int expect_num_bytes;                       /**< Expected number of bytes for IN transfers stages. Set to 0 for OUT transfer */
         uint8_t next_dev_addr;                      /**< Device address for device under enumeration */
+        // Pending enumeration queue
+        unsigned int pending_uids[ENUM_PENDING_QUEUE_LEN];
+        uint16_t pending_head;
+        uint16_t pending_tail;
+        uint16_t pending_count;
     } single_thread;                                /**< Single thread members don't require a critical section so long as they are never accessed from multiple threads */
 
     struct {
@@ -203,6 +209,30 @@ static uint8_t get_next_free_dev_addr(void)
     return new_dev_addr;
 }
 
+static bool pending_uid_enqueue(unsigned int uid)
+{
+    if (p_enum_driver->single_thread.pending_count >= ENUM_PENDING_QUEUE_LEN) {
+        return false;
+    }
+    p_enum_driver->single_thread.pending_uids[p_enum_driver->single_thread.pending_tail] = uid;
+    p_enum_driver->single_thread.pending_tail =
+        (p_enum_driver->single_thread.pending_tail + 1) % ENUM_PENDING_QUEUE_LEN;
+    p_enum_driver->single_thread.pending_count++;
+    return true;
+}
+
+static bool pending_uid_dequeue(unsigned int *uid)
+{
+    if (p_enum_driver->single_thread.pending_count == 0) {
+        return false;
+    }
+    *uid = p_enum_driver->single_thread.pending_uids[p_enum_driver->single_thread.pending_head];
+    p_enum_driver->single_thread.pending_head =
+        (p_enum_driver->single_thread.pending_head + 1) % ENUM_PENDING_QUEUE_LEN;
+    p_enum_driver->single_thread.pending_count--;
+    return true;
+}
+
 /**
  * @brief Get Configuration descriptor index
  *
@@ -1161,11 +1191,19 @@ esp_err_t enum_start(unsigned int uid)
 {
     ENUM_CHECK(p_enum_driver != NULL, ESP_ERR_INVALID_STATE);
 
+    if (p_enum_driver->single_thread.stage != ENUM_STAGE_IDLE) {
+
+        // We are already enumerating a device, add the new device to the pending queue
+        if (!pending_uid_enqueue(uid)) {
+            return ESP_ERR_NO_MEM;
+        }
+        return ESP_OK;
+    }
     esp_err_t ret = ESP_FAIL;
 
     // Open device and lock it for enumeration process
     usb_device_handle_t dev_hdl;
-    ret = usbh_devs_open(0, &dev_hdl);
+    ret = usbh_devs_open_uid(uid, &dev_hdl);
     if (ret != ESP_OK) {
         return ret;
     }
@@ -1176,7 +1214,7 @@ esp_err_t enum_start(unsigned int uid)
     ESP_ERROR_CHECK(usbh_dev_get_info(dev_hdl, &dev_info));
 
     // Stage ENUM_STAGE_GET_SHORT_DEV_DESC
-    ESP_LOGD(ENUM_TAG, "Start processing device with address %d", 0);
+    ESP_LOGD(ENUM_TAG, "Start processing device with uid %d", uid);
 
     p_enum_driver->single_thread.stage = ENUM_STAGE_GET_SHORT_DEV_DESC;
     p_enum_driver->single_thread.node_uid = uid;
@@ -1322,5 +1360,17 @@ esp_err_t enum_process(void)
         p_enum_driver->constant.proc_req_cb(USB_PROC_REQ_SOURCE_ENUM, false, p_enum_driver->constant.proc_req_cb_arg);
     }
 
+    // If we are idle and there are pending devices, start the next one
+    while (p_enum_driver->single_thread.pending_count > 0 &&
+            p_enum_driver->single_thread.stage == ENUM_STAGE_IDLE) {
+        unsigned int next_uid = 0;
+        if (!pending_uid_dequeue(&next_uid)) {
+            break;
+        }
+        if (enum_start(next_uid) == ESP_OK) {
+            break;
+        }
+    }
+
     return ESP_OK;
 }

host/usb/src/ext_hub.c

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2024-2025 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2024-2026 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -1298,6 +1298,18 @@ esp_err_t ext_hub_get_speed(ext_hub_handle_t ext_hub_hdl, usb_speed_t *speed)
     return ESP_OK;
 }
 
+hcd_port_handle_t ext_hub_get_root_port(ext_hub_handle_t ext_hub_hdl)
+{
+    EXT_HUB_CHECK(ext_hub_hdl != NULL, NULL);
+    EXT_HUB_CHECK(dev_is_in_list(ext_hub_hdl), NULL);
+    ext_hub_dev_t *ext_hub_dev = (ext_hub_dev_t *)ext_hub_hdl;
+    hcd_port_handle_t root_port_hdl = NULL;
+    if (usbh_dev_get_root_port_hdl(ext_hub_dev->constant.dev_hdl, &root_port_hdl) != ESP_OK) {
+        return NULL;
+    }
+    return root_port_hdl;
+}
+
 esp_err_t ext_hub_new_dev(uint8_t dev_addr)
 {
     EXT_HUB_ENTER_CRITICAL();

host/usb/src/hcd_dwc.c

@@ -17,7 +17,6 @@
 #include "esp_err.h"
 #include "esp_log.h"
 
-#include "soc/soc_caps.h"
 #include "hal/usb_dwc_hal.h"
 #include "hcd.h"
 #include "usb_private.h"
@@ -51,8 +50,6 @@
 #define CTRL_EP_MAX_MPS_LS                      8   // Largest Maximum Packet Size for Low Speed control endpoints
 #define CTRL_EP_MAX_MPS_HSFS                    64  // Largest Maximum Packet Size for High & Full Speed control endpoints
 
-#define NUM_PORTS                               SOC_USB_OTG_PERIPH_NUM   // Each peripheral is a root port
-
 // ----------------------- Configs -------------------------
 
 #ifdef CONFIG_USB_HOST_DWC_DMA_CAP_MEMORY_IN_PSRAM      // In esp32p4, the USB-DWC internal DMA can access external RAM
@@ -269,7 +266,7 @@ struct port_obj {
 
 // With s_port_inited[] we can check if a port has been initialized -> to provide singleton handle for each root port
 // Each peripheral is a root port
-static bool s_port_inited[NUM_PORTS] = {0};
+static bool s_port_inited[HCD_NUM_PORTS] = {0};
 
 // ------------------------------------------------- Forward Declare ---------------------------------------------------
 
@@ -1454,7 +1451,7 @@ static esp_err_t _port_cmd_disable(port_t *port)
 esp_err_t hcd_port_init(int port_number, const hcd_port_config_t *port_config, hcd_port_handle_t *port_hdl)
 {
     HCD_CHECK(port_number >= 0 && port_config != NULL && port_hdl != NULL, ESP_ERR_INVALID_ARG);
-    HCD_CHECK(port_number < NUM_PORTS, ESP_ERR_NOT_FOUND);
+    HCD_CHECK(port_number < HCD_NUM_PORTS, ESP_ERR_NOT_FOUND);
 
     HCD_ENTER_CRITICAL();
     HCD_CHECK_FROM_CRIT(!s_port_inited[port_number], ESP_ERR_INVALID_STATE);