refactor(usb/usbh): Update USBH device creation and enumeration handling

This commit updates how the USBH handles device creation and enumeration so that
upper layers (such as the Hub driver) can use the USBH API for enumeration instead
of calling the HCD.

USBH Updates:

USBH now creates unenumerated devices set to address 0 with no device/config
descriptor. A newly created device can be opened and communicated with immediately
(using control transfers). This allows the Hub driver to call the USBH instead of
the HCD. Summary of USBH changes:

- Added new APIs to add/remove a device. Devices are now created as unenumerated
and can be immediately opened and communicated with.
- Added new APIs to enumerate a device (see 'usbh_dev_set_...()' functions). Device
must be locked (see 'usbh_dev_enum_lock()') before enumeration functions can be called.
- Added UID for each device. This allows the particular USBH without needing to
use the device's handle (which implies opening the device).

Hub Driver Updates:

Hub driver now calls the USBH for enumeration. Summary of USBH changes:

- Replace all 'hcd_pipe_...()' calls with 'usbh_dev_...()' calls
- Refactored port event handling to fit with new USBH API
- Updated to use UID to uniquely identify devices without opening them

USB Host Updates:

- Reroute USBH control transfers to clients and hub driver

Author: Dazza0

components/usb/hcd_dwc.c

@@ -1983,20 +1983,6 @@ esp_err_t hcd_pipe_update_dev_addr(hcd_pipe_handle_t pipe_hdl, uint8_t dev_addr)
     return ESP_OK;
 }
 
-esp_err_t hcd_pipe_update_callback(hcd_pipe_handle_t pipe_hdl, hcd_pipe_callback_t callback, void *user_arg)
-{
-    pipe_t *pipe = (pipe_t *)pipe_hdl;
-    HCD_ENTER_CRITICAL();
-    // Check if pipe is in the correct state to be updated
-    HCD_CHECK_FROM_CRIT(!pipe->cs_flags.pipe_cmd_processing &&
-                        !pipe->cs_flags.has_urb,
-                        ESP_ERR_INVALID_STATE);
-    pipe->callback = callback;
-    pipe->callback_arg = user_arg;
-    HCD_EXIT_CRITICAL();
-    return ESP_OK;
-}
-
 void *hcd_pipe_get_context(hcd_pipe_handle_t pipe_hdl)
 {
     pipe_t *pipe = (pipe_t *)pipe_hdl;

components/usb/hub.c

@@ -418,22 +418,6 @@ esp_err_t hcd_pipe_update_mps(hcd_pipe_handle_t pipe_hdl, int mps);
  */
 esp_err_t hcd_pipe_update_dev_addr(hcd_pipe_handle_t pipe_hdl, uint8_t dev_addr);
 
-/**
- * @brief Update a pipe's callback
- *
- * This function is intended to be called on default pipes at the end of enumeration to switch to a callback that
- * handles the completion of regular control transfer.
- * - Pipe is not current processing a command
- * - Pipe does not have any enqueued URBs
- * - Port cannot be resetting
- *
- * @param pipe_hdl Pipe handle
- * @param callback Callback
- * @param user_arg Callback argument
- * @return esp_err_t
- */
-esp_err_t hcd_pipe_update_callback(hcd_pipe_handle_t pipe_hdl, hcd_pipe_callback_t callback, void *user_arg);
-
 /**
  * @brief Get the context variable of a pipe from its handle
  *

components/usb/private_include/hcd.h

@@ -42,9 +42,10 @@ typedef struct {
  * - Initializes the HCD root port
  *
  * @param[in] hub_config Hub driver configuration
+ * @param[out] client_ret Unique pointer to identify the Hub as a USB Host client
  * @return esp_err_t
  */
-esp_err_t hub_install(hub_config_t *hub_config);
+esp_err_t hub_install(hub_config_t *hub_config, void **client_ret);
 
 /**
  * @brief Uninstall Hub driver
@@ -78,15 +79,16 @@ esp_err_t hub_root_start(void);
 esp_err_t hub_root_stop(void);
 
 /**
- * @brief Indicate to the Hub driver that a device has been freed
+ * @brief Indicate to the Hub driver that a device's port can be recycled
  *
- * Hub driver can now recover the port that the device was connected to
+ * The device connected to the port has been freed. The Hub driver can now
+ * recycled the port.
  *
- * @param dev_addr Device address
+ * @param dev_uid Device's unique ID
  * @return
  *     - ESP_OK: Success
  */
-esp_err_t hub_dev_is_free(uint8_t dev_addr);
+esp_err_t hub_port_recycle(unsigned int dev_uid);
 
 /**
  * @brief Hub driver's processing function

components/usb/private_include/hub.h

@@ -58,7 +58,7 @@ typedef struct {
             usb_device_handle_t dev_hdl;
         } dev_gone_data;
         struct {
-            uint8_t dev_addr;
+            unsigned int dev_uid;
         } dev_free_data;
     };
 } usbh_event_data_t;
@@ -195,6 +195,32 @@ esp_err_t usbh_devs_num(int *num_devs_ret);
  */
 esp_err_t usbh_devs_addr_list_fill(int list_len, uint8_t *dev_addr_list, int *num_dev_ret);
 
+/**
+ * @brief Create a device and add it to the device pool
+ *
+ * The created device will not be enumerated where the device's address is 0,
+ * device and config descriptor are NULL. The device will still have a default
+ * pipe, thus allowing control transfers to be submitted.
+ *
+ * - Call usbh_devs_open() before communicating with the device
+ * - Call usbh_dev_enum_lock() before enumerating the device via the various
+ * usbh_dev_set_...() functions.
+ *
+ * @param[in] uid Unique ID assigned to the device
+ * @param[in] dev_speed Device's speed
+ * @param[in] port_hdl Handle of the port that the device is connected to
+ * @return esp_err_t
+ */
+esp_err_t usbh_devs_add(unsigned int uid, usb_speed_t dev_speed, hcd_port_handle_t port_hdl);
+
+/**
+ * @brief Indicates to the USBH that a device is gone
+ *
+ * @param[in] uid Unique ID assigned to the device on creation (see 'usbh_devs_add()')
+ * @return esp_err_t
+ */
+esp_err_t usbh_devs_remove(unsigned int uid);
+
 /**
  * @brief Mark that all devices should be freed at the next possible opportunity
  *
@@ -227,6 +253,16 @@ esp_err_t usbh_devs_open(uint8_t dev_addr, usb_device_handle_t *dev_hdl);
  */
 esp_err_t usbh_devs_close(usb_device_handle_t dev_hdl);
 
+/**
+ * @brief Trigger a USBH_EVENT_NEW_DEV event for the device
+ *
+ * This is typically called after a device has been fully enumerated.
+ *
+ * @param[in] dev_hdl Device handle
+ * @return esp_err_t
+ */
+esp_err_t usbh_devs_new_dev_event(usb_device_handle_t dev_hdl);
+
 // ------------------------------------------------ Device Functions ---------------------------------------------------
 
 // ----------------------- Getters -------------------------
@@ -245,7 +281,8 @@ esp_err_t usbh_dev_get_addr(usb_device_handle_t dev_hdl, uint8_t *dev_addr);
 /**
  * @brief Get a device's information
  *
- * @note This function can block
+ * @note It is possible that the device has not been enumerated yet, thus some
+ * fields may be NULL.
  * @param[in] dev_hdl Device handle
  * @param[out] dev_info Device information
  * @return esp_err_t
@@ -257,6 +294,8 @@ esp_err_t usbh_dev_get_info(usb_device_handle_t dev_hdl, usb_device_info_t *dev_
  *
  * - The device descriptor is cached when the device is created by the Hub driver
  *
+ * @note It is possible that the device has not been enumerated yet, thus the
+ * device descriptor could be NULL.
  * @param[in] dev_hdl Device handle
  * @param[out] dev_desc_ret Device descriptor
  * @return esp_err_t
@@ -268,13 +307,109 @@ esp_err_t usbh_dev_get_desc(usb_device_handle_t dev_hdl, const usb_device_desc_t
  *
  * Simply returns a reference to the internally cached configuration descriptor
  *
- * @note This function can block
+ * @note It is possible that the device has not been enumerated yet, thus the
+ * configuration descriptor could be NULL.
  * @param[in] dev_hdl Device handle
  * @param config_desc_ret
  * @return esp_err_t
  */
 esp_err_t usbh_dev_get_config_desc(usb_device_handle_t dev_hdl, const usb_config_desc_t **config_desc_ret);
 
+// ----------------------- Setters -------------------------
+
+/**
+ * @brief Lock a device for enumeration
+ *
+ * - A device's enumeration lock must be set before any of its enumeration fields
+ * (e.g., address, device/config descriptors) can be set/updated.
+ * - The caller must be the sole opener of the device (see 'usbh_devs_open()')
+ * when locking the device for enumeration.
+ *
+ * @param[in] dev_hdl Device handle
+ * @return esp_err_t
+ */
+esp_err_t usbh_dev_enum_lock(usb_device_handle_t dev_hdl);
+
+/**
+ * @brief Release a device's enumeration lock
+ *
+ * @param[in] dev_hdl Device handle
+ * @return esp_err_t
+ */
+esp_err_t usbh_dev_enum_unlock(usb_device_handle_t dev_hdl);
+
+/**
+ * @brief Set the maximum packet size of EP0 for a device
+ *
+ * Typically called during enumeration after obtaining the first 8 bytes of the
+ * device's descriptor.
+ *
+ * @note The device's enumeration lock must be set before calling this function
+ * (see 'usbh_dev_enum_lock()')
+ * @param[in] dev_hdl Device handle
+ * @param[in] wMaxPacketSize Maximum packet size
+ * @return esp_err_t
+ */
+esp_err_t usbh_dev_set_ep0_mps(usb_device_handle_t dev_hdl, uint16_t wMaxPacketSize);
+
+/**
+ * @brief Set a device's address
+ *
+ * Typically called during enumeration after a SET_ADDRESSS request has be
+ * sent to the device.
+ *
+ * @note The device's enumeration lock must be set before calling this function
+ * (see 'usbh_dev_enum_lock()')
+ * @param[in] dev_hdl Device handle
+ * @param[in] dev_addr
+ * @return esp_err_t
+ */
+esp_err_t usbh_dev_set_addr(usb_device_handle_t dev_hdl, uint8_t dev_addr);
+
+/**
+ * @brief Set a device's descriptor
+ *
+ * Typically called during enumeration after obtaining the device's descriptor
+ * via a GET_DESCRIPTOR request.
+ *
+ * @note The device's enumeration lock must be set before calling this function
+ * (see 'usbh_dev_enum_lock()')
+ * @param[in] dev_hdl Device handle
+ * @param[in] device_desc Device descriptor to copy
+ * @return esp_err_t
+ */
+esp_err_t usbh_dev_set_desc(usb_device_handle_t dev_hdl, const usb_device_desc_t *device_desc);
+
+/**
+ * @brief Set a device's configuration descriptor
+ *
+ * Typically called during enumeration after obtaining the device's configuration
+ * descriptor via a GET_DESCRIPTOR request.
+ *
+ * @note The device's enumeration lock must be set before calling this function
+ * (see 'usbh_dev_enum_lock()')
+ * @param[in] dev_hdl Device handle
+ * @param[in] config_desc_full Configuration descriptor to copy
+ * @return esp_err_t
+ */
+esp_err_t usbh_dev_set_config_desc(usb_device_handle_t dev_hdl, const usb_config_desc_t *config_desc_full);
+
+/**
+ * @brief Set a device's string descriptor
+ *
+ * Typically called during enumeration after obtaining one of the device's string
+ * descriptor via a GET_DESCRIPTOR request.
+ *
+ * @note The device's enumeration lock must be set before calling this function
+ * (see 'usbh_dev_enum_lock()')
+ * @param[in] dev_hdl Device handle
+ * @param[in] str_desc String descriptor to copy
+ * @param[in] select Select string descriptor. 0/1/2 for Manufacturer/Product/Serial
+ * Number string descriptors respectively
+ * @return esp_err_t
+ */
+esp_err_t usbh_dev_set_str_desc(usb_device_handle_t dev_hdl, const usb_str_desc_t *str_desc, int select);
+
 // ----------------------------------------------- Endpoint Functions -------------------------------------------------
 
 /**
@@ -381,110 +516,6 @@ esp_err_t usbh_ep_enqueue_urb(usbh_ep_handle_t ep_hdl, urb_t *urb);
  */
 esp_err_t usbh_ep_dequeue_urb(usbh_ep_handle_t ep_hdl, urb_t **urb_ret);
 
-// -------------------------------------------------- Hub Functions ----------------------------------------------------
-
-// ------------------- Device Related ----------------------
-
-/**
- * @brief Indicates to USBH the start of enumeration for a device
- *
- * - The Hub driver calls this function before it starts enumerating a new device.
- * - The USBH will allocate a new device that will be initialized by the Hub driver using the remaining hub enumeration
- *   functions.
- * - The new device's default pipe handle is returned to all the Hub driver to be used during enumeration.
- *
- * @note Hub Driver only
- * @param[in] port_hdl Handle of the port that the device is connected to
- * @param[in] dev_speed Device's speed
- * @param[out] new_dev_hdl Device's handle
- * @param[out] default_pipe_hdl Device's default pipe handle
- * @return esp_err_t
- */
-esp_err_t usbh_hub_add_dev(hcd_port_handle_t port_hdl, usb_speed_t dev_speed, usb_device_handle_t *new_dev_hdl, hcd_pipe_handle_t *default_pipe_hdl);
-
-/**
- * @brief Indicates to the USBH that a device is gone
- *
- * @param dev_hdl Device handle
- * @return esp_err_t
- */
-esp_err_t usbh_hub_dev_gone(usb_device_handle_t dev_hdl);
-
-// ----------------- Enumeration Related -------------------
-
-/**
- * @brief Assign the enumerating device's address
- *
- * @note Hub Driver only
- * @note Must call in sequence
- * @param[in] dev_hdl Device handle
- * @param dev_addr
- * @return esp_err_t
- */
-esp_err_t usbh_hub_enum_fill_dev_addr(usb_device_handle_t dev_hdl, uint8_t dev_addr);
-
-/**
- * @brief Fill the enumerating device's descriptor
- *
- * @note Hub Driver only
- * @note Must call in sequence
- * @param[in] dev_hdl Device handle
- * @param device_desc
- * @return esp_err_t
- */
-esp_err_t usbh_hub_enum_fill_dev_desc(usb_device_handle_t dev_hdl, const usb_device_desc_t *device_desc);
-
-/**
- * @brief Fill the enumerating device's active configuration descriptor
- *
- * @note Hub Driver only
- * @note Must call in sequence
- * @note This function can block
- * @param[in] dev_hdl Device handle
- * @param config_desc_full
- * @return esp_err_t
- */
-esp_err_t usbh_hub_enum_fill_config_desc(usb_device_handle_t dev_hdl, const usb_config_desc_t *config_desc_full);
-
-/**
- * @brief Fill one of the string descriptors of the enumerating device
- *
- * @note Hub Driver only
- * @note Must call in sequence
- * @param dev_hdl Device handle
- * @param str_desc Pointer to string descriptor
- * @param select Select which string descriptor. 0/1/2 for Manufacturer/Product/Serial Number string descriptors respectively
- * @return esp_err_t
- */
-esp_err_t usbh_hub_enum_fill_str_desc(usb_device_handle_t dev_hdl, const usb_str_desc_t *str_desc, int select);
-
-/**
- * @brief Indicate the device enumeration is completed
- *
- * This will allow the device to be opened by clients, and also trigger a USBH_EVENT_NEW_DEV event.
- *
- * @note Hub Driver only
- * @note Must call in sequence
- * @note This function can block
- * @param[in] dev_hdl Device handle
- * @return esp_err_t
- */
-esp_err_t usbh_hub_enum_done(usb_device_handle_t dev_hdl);
-
-/**
- * @brief Indicate that device enumeration has failed
- *
- * This will cause the enumerating device's resources to be cleaned up
- * The Hub Driver must guarantee that the enumerating device's default pipe is already halted, flushed, and dequeued.
- *
- * @note Hub Driver only
- * @note Must call in sequence
- * @note This function can block
- * @param[in] dev_hdl Device handle
- * @return esp_err_t
- */
-esp_err_t usbh_hub_enum_failed(usb_device_handle_t dev_hdl);
-
 #ifdef __cplusplus
 }
 #endif