refactor(host/enum): Serialize device enumeration

Author: tore-espressif

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/usbh.h

@@ -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
  *

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/usbh.c

@@ -940,8 +940,9 @@ esp_err_t usbh_devs_add(usbh_dev_params_t *params)
         ret = ESP_ERR_INVALID_ARG;
         goto exit;
     }
-    // Check that there is not already a device currently with address 0
-    if (_find_dev_from_addr(0) != NULL) {
+    // Check that there is not already a device currently with address 0 (not enumerated) on the same port
+    device_t *dev_with_addr_0 = _find_dev_from_addr(0);
+    if (dev_with_addr_0 != NULL && dev_with_addr_0->constant.port_hdl == params->root_port_hdl) {
         ret = ESP_ERR_NOT_FINISHED;
         goto exit;
     }
@@ -1131,14 +1132,9 @@ 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)
+esp_err_t _dev_open(device_t *dev_obj)
 {
-    USBH_CHECK(dev_hdl != NULL, ESP_ERR_INVALID_ARG);
     esp_err_t ret;
-
-    USBH_ENTER_CRITICAL();
-    // Go through the device lists to find the device with the specified address
-    device_t *dev_obj = _find_dev_from_addr(dev_addr);
     if (dev_obj != NULL) {
         // Check if the device is in a state to be opened
         if (dev_obj->dynamic.flags.is_gone ||           // Device is already gone (disconnected)
@@ -1148,14 +1144,45 @@ esp_err_t usbh_devs_open(uint8_t dev_addr, usb_device_handle_t *dev_hdl)
             ret = ESP_ERR_NOT_ALLOWED;
         } else {
             dev_obj->dynamic.open_count++;
-            *dev_hdl = (usb_device_handle_t)dev_obj;
             ret = ESP_OK;
         }
     } else {
         ret = ESP_ERR_NOT_FOUND;
     }
+    return ret;
+}
+
+esp_err_t usbh_devs_open(uint8_t dev_addr, usb_device_handle_t *dev_hdl)
+{
+    USBH_CHECK(dev_hdl != NULL, ESP_ERR_INVALID_ARG);
+    esp_err_t ret;
+
+    USBH_ENTER_CRITICAL();
+    // Go through the device lists to find the device with the specified address
+    device_t *dev_obj = _find_dev_from_addr(dev_addr);
+    ret = _dev_open(dev_obj);
+    USBH_EXIT_CRITICAL();
+
+    if (ret == ESP_OK) {
+        *dev_hdl = (usb_device_handle_t)dev_obj;
+    }
+    return ret;
+}
+
+esp_err_t usbh_devs_open_uid(unsigned int uid, usb_device_handle_t *dev_hdl)
+{
+    USBH_CHECK(dev_hdl != NULL, ESP_ERR_INVALID_ARG);
+    esp_err_t ret;
+
+    USBH_ENTER_CRITICAL();
+    // Go through the device lists to find the device with the specified address
+    device_t *dev_obj = _find_dev_from_uid(uid);
+    ret = _dev_open(dev_obj);
     USBH_EXIT_CRITICAL();
 
+    if (ret == ESP_OK) {
+        *dev_hdl = (usb_device_handle_t)dev_obj;
+    }
     return ret;
 }