Merge branch 'refactor/usb_host_add_func_ret_values_description' into 'master'

Refactor: USB Host add function return values description

Closes IDF-10455

See merge request espressif/esp-idf!32106

components/usb/enum.c

@@ -1141,7 +1141,7 @@ esp_err_t enum_install(enum_config_t *config, void **client_ret)
     // Initialize ENUM objects
     urb_t *urb = urb_alloc(sizeof(usb_setup_packet_t) + ENUM_CTRL_TRANSFER_MAX_DATA_LEN, 0);
     if (urb == NULL) {
-        ret = ESP_ERR_NOT_FINISHED;
+        ret = ESP_ERR_NO_MEM;
         goto alloc_err;
     }
 
@@ -1164,7 +1164,7 @@ esp_err_t enum_install(enum_config_t *config, void **client_ret)
 
     // Enumeration driver is single_threaded
     if (p_enum_driver != NULL) {
-        ret = ESP_ERR_NOT_FINISHED;
+        ret = ESP_ERR_INVALID_STATE;
         goto err;
     }
     p_enum_driver = enum_drv;

components/usb/ext_hub.c

@@ -1288,12 +1288,14 @@ esp_err_t ext_hub_new_dev(uint8_t dev_addr)
     // Open device
     ret = usbh_devs_open(dev_addr, &dev_hdl);
     if (ret != ESP_OK) {
+        ESP_LOGE(EXT_HUB_TAG, "USBH device opening error: %s", esp_err_to_name(ret));
         return ret;
     }
 
     // Get Configuration Descriptor
     ret = usbh_dev_get_config_desc(dev_hdl, &config_desc);
     if (ret != ESP_OK) {
+        ESP_LOGE(EXT_HUB_TAG, "Getting config desc error %s", esp_err_to_name(ret));
         goto exit;
     }
 
@@ -1307,12 +1309,14 @@ esp_err_t ext_hub_new_dev(uint8_t dev_addr)
 
     ret = find_first_intf_desc(config_desc, &hub_config);
     if (ret != ESP_OK) {
+        ESP_LOGE(EXT_HUB_TAG, "Finding HUB interface error %s", esp_err_to_name(ret));
         goto exit;
     }
 
     // Create External Hub device
     ret = device_alloc(&hub_config, &hub_dev);
     if (ret != ESP_OK) {
+        ESP_LOGE(EXT_HUB_TAG, "External HUB device alloc error %s", esp_err_to_name(ret));
         goto exit;
     }
 

components/usb/hcd_dwc.c

@@ -1011,6 +1011,7 @@ esp_err_t hcd_install(const hcd_config_t *config)
                              (void *)p_hcd_obj_dmy->port_obj,
                              &p_hcd_obj_dmy->isr_hdl);
     if (err_ret != ESP_OK) {
+        ESP_LOGE(HCD_DWC_TAG, "Interrupt alloc error: %s", esp_err_to_name(err_ret));
         goto intr_alloc_err;
     }
     HCD_ENTER_CRITICAL();

components/usb/hub.c

@@ -479,6 +479,7 @@ esp_err_t hub_install(hub_config_t *hub_config, void **client_ret)
     };
     ret = ext_hub_install(&ext_hub_config);
     if (ret != ESP_OK) {
+        ESP_LOGE(HUB_DRIVER_TAG, "Ext hub install error: %s", esp_err_to_name(ret));
         goto err_ext_hub;
     }
     *client_ret = ext_hub_get_client();
@@ -496,6 +497,7 @@ esp_err_t hub_install(hub_config_t *hub_config, void **client_ret)
     hcd_port_handle_t root_port_hdl;
     ret = hcd_port_init(HUB_ROOT_PORT_NUM, &port_config, &root_port_hdl);
     if (ret != ESP_OK) {
+        ESP_LOGE(HUB_DRIVER_TAG, "HCD Port init error: %s", esp_err_to_name(ret));
         goto err;
     }
 
@@ -598,6 +600,9 @@ esp_err_t hub_port_recycle(usb_device_handle_t parent_dev_hdl, uint8_t parent_po
         ext_hub_handle_t ext_hub_hdl = NULL;
         ext_hub_get_handle(parent_dev_hdl, &ext_hub_hdl);
         ret = ext_hub_port_recycle(ext_hub_hdl, parent_port_num);
+        if (ret != ESP_OK) {
+            ESP_LOGE(HUB_DRIVER_TAG, "Ext hub port recycle error: %s", esp_err_to_name(ret));
+        }
 #else
         ESP_LOGW(HUB_DRIVER_TAG, "Recycling External Port is not available (External Hub support disabled)");
         ret = ESP_ERR_NOT_SUPPORTED;
@@ -626,6 +631,9 @@ esp_err_t hub_port_reset(usb_device_handle_t parent_dev_hdl, uint8_t parent_port
         ext_hub_handle_t ext_hub_hdl = NULL;
         ext_hub_get_handle(parent_dev_hdl, &ext_hub_hdl);
         ret = ext_hub_port_reset(ext_hub_hdl, parent_port_num);
+        if (ret != ESP_OK) {
+            ESP_LOGE(HUB_DRIVER_TAG, "Ext hub port reset error: %s", esp_err_to_name(ret));
+        }
 #else
         ESP_LOGW(HUB_DRIVER_TAG, "Resetting External Port is not available (External Hub support disabled)");
         ret = ESP_ERR_NOT_SUPPORTED;
@@ -647,6 +655,9 @@ esp_err_t hub_port_active(usb_device_handle_t parent_dev_hdl, uint8_t parent_por
         ext_hub_handle_t ext_hub_hdl = NULL;
         ext_hub_get_handle(parent_dev_hdl, &ext_hub_hdl);
         ret = ext_hub_port_active(ext_hub_hdl, parent_port_num);
+        if (ret != ESP_OK) {
+            ESP_LOGE(HUB_DRIVER_TAG, "Ext hub port activation error: %s", esp_err_to_name(ret));
+        }
 #else
         ESP_LOGW(HUB_DRIVER_TAG, "Activating External Port is not available (External Hub support disabled)");
         ret = ESP_ERR_NOT_SUPPORTED;

components/usb/include/usb/usb_helpers.h

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2015-2022 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2015-2024 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -129,7 +129,7 @@ typedef void (*print_class_descriptor_cb)(const usb_standard_desc_t *);
 /**
  * @brief Print device descriptor
  *
- * @param devc_desc Device descriptor
+ * @param[in] devc_desc Device descriptor
  */
 void usb_print_device_descriptor(const usb_device_desc_t *devc_desc);
 
@@ -139,17 +139,17 @@ void usb_print_device_descriptor(const usb_device_desc_t *devc_desc);
  * - This function prints the full contents of a configuration descriptor (including interface and endpoint descriptors)
  * - When a non-standard descriptor is encountered, this function will call the class_specific_cb if it is provided
  *
- * @param cfg_desc Configuration descriptor
+ * @param[in] cfg_desc Configuration descriptor
- * @param class_specific_cb Class specific descriptor callback. Can be NULL
+ * @param[in] class_specific_cb Class specific descriptor callback. Can be NULL
  */
 void usb_print_config_descriptor(const usb_config_desc_t *cfg_desc, print_class_descriptor_cb class_specific_cb);
 
 /**
  * @brief Print a string descriptor
  *
- * This funciton will only print ASCII characters of the UTF-16 encoded string
+ * This function will only print ASCII characters of the UTF-16 encoded string
  *
- * @param str_desc String descriptor
+ * @param[in] str_desc String descriptor
  */
 void usb_print_string_descriptor(const usb_str_desc_t *str_desc);
 

components/usb/include/usb/usb_host.h

@@ -131,14 +131,20 @@ typedef struct {
 /**
  * @brief Install the USB Host Library
  *
- * - This function should only once to install the USB Host Library
+ * - This function should be called only once to install the USB Host Library
  * - This function should be called before any other USB Host Library functions are called
  *
  * @note If skip_phy_setup is set in the install configuration, the user is responsible for ensuring that the underlying
  *       Host Controller is enabled and the USB PHY (internal or external) is already setup before this function is
  *       called.
  * @param[in] config USB Host Library configuration
- * @return esp_err_t
+ *
+ * @return
+ *    - ESP_OK: USB Host installed successfully
+ *    - ESP_ERR_INVALID_ARG: Invalid argument
+ *    - ESP_ERR_INVALID_STATE: USB Host Library is not in correct state to be installed
+ *      (eg. the library itself of one of it's drivers is already installed)
+ *    - ESP_ERR_NO_MEM: Insufficient memory
  */
 esp_err_t usb_host_install(const usb_host_config_t *config);
 
@@ -152,7 +158,10 @@ esp_err_t usb_host_install(const usb_host_config_t *config);
  *
  * @note If skip_phy_setup was set when the Host Library was installed, the user is responsible for disabling the
  *       underlying Host Controller and USB PHY (internal or external).
- * @return esp_err_t
+ *
+ * @return
+ *    - ESP_OK: USB Host uninstalled successfully
+ *    - ESP_ERR_INVALID_STATE: USB Host Library is not installed, or has unfinished actions
  */
 esp_err_t usb_host_uninstall(void);
 
@@ -166,7 +175,11 @@ esp_err_t usb_host_uninstall(void);
  * @note This function can block
  * @param[in] timeout_ticks Timeout in ticks to wait for an event to occur
  * @param[out] event_flags_ret Event flags that indicate what USB Host Library event occurred.
- * @return esp_err_t
+ *
+ * @return
+ *    - ESP_OK: No events to be handled
+ *    - ESP_ERR_INVALID_STATE: USB Host Library is not installed
+ *    - ESP_ERR_TIMEOUT: Semaphore waiting for events has timed out
  */
 esp_err_t usb_host_lib_handle_events(TickType_t timeout_ticks, uint32_t *event_flags_ret);
 
@@ -175,7 +188,9 @@ esp_err_t usb_host_lib_handle_events(TickType_t timeout_ticks, uint32_t *event_f
  *
  * - This function simply unblocks the USB Host Library event handling function (usb_host_lib_handle_events())
  *
- * @return esp_err_t
+ * @return
+ *    - ESP_OK: USB Host library unblocked successfully
+ *    - ESP_ERR_INVALID_STATE: USB Host Library is not installed
  */
 esp_err_t usb_host_lib_unblock(void);
 
@@ -183,7 +198,11 @@ esp_err_t usb_host_lib_unblock(void);
  * @brief Get current information about the USB Host Library
  *
  * @param[out] info_ret USB Host Library Information
- * @return esp_err_t
+ *
+ * @return
+ *    - ESP_OK: USB Host Library info obtained successfully
+ *    - ESP_ERR_INVALID_STATE: USB Host Library is not installed
+ *    - ESP_ERR_INVALID_ARG: Invalid argument
  */
 esp_err_t usb_host_lib_info(usb_host_lib_info_t *info_ret);
 
@@ -197,7 +216,12 @@ esp_err_t usb_host_lib_info(usb_host_lib_info_t *info_ret);
  *
  * @param[in] client_config Client configuration
  * @param[out] client_hdl_ret Client handle
- * @return esp_err_t
+ *
+ * @return
+ *    - ESP_OK: USB Host Library client registered successfully
+ *    - ESP_ERR_INVALID_STATE: USB Host Library is not installed
+ *    - ESP_ERR_INVALID_ARG: Invalid argument
+ *    - ESP_ERR_NO_MEM: Insufficient memory
  */
 esp_err_t usb_host_client_register(const usb_host_client_config_t *client_config, usb_host_client_handle_t *client_hdl_ret);
 
@@ -208,7 +232,10 @@ esp_err_t usb_host_client_register(const usb_host_client_config_t *client_config
  * - The client must have closed all previously opened devices before attempting to deregister
  *
  * @param[in] client_hdl Client handle
- * @return esp_err_t
+ *
+ * @return
+ *    - ESP_OK: USB Host Library client deregistered successfully
+ *    - ESP_ERR_INVALID_ARG: Invalid argument
  */
 esp_err_t usb_host_client_deregister(usb_host_client_handle_t client_hdl);
 
@@ -221,7 +248,12 @@ esp_err_t usb_host_client_deregister(usb_host_client_handle_t client_hdl);
  * @note This function can block
  * @param[in] client_hdl Client handle
  * @param[in] timeout_ticks Timeout in ticks to wait for an event to occur
- * @return esp_err_t
+ *
+ * @return
+ *    - ESP_OK: No event to be handled
+ *    - ESP_ERR_INVALID_STATE: USB Host Library is not installed
+ *    - ESP_ERR_INVALID_ARG: Invalid argument
+ *    - ESP_ERR_TIMEOUT: Semaphore waiting for events has timed out
  */
 esp_err_t usb_host_client_handle_events(usb_host_client_handle_t client_hdl, TickType_t timeout_ticks);
 
@@ -232,7 +264,10 @@ esp_err_t usb_host_client_handle_events(usb_host_client_handle_t client_hdl, Tic
  * - This function is useful when need to unblock a client in order to deregister it.
  *
  * @param[in] client_hdl Client handle
- * @return esp_err_t
+ *
+ * @return
+ *    - ESP_OK: Client unblocked successfully
+ *    - ESP_ERR_INVALID_ARG: Invalid argument
  */
 esp_err_t usb_host_client_unblock(usb_host_client_handle_t client_hdl);
 
@@ -247,7 +282,10 @@ esp_err_t usb_host_client_unblock(usb_host_client_handle_t client_hdl);
  * @param[in] client_hdl Client handle
  * @param[in] dev_addr Device's address
  * @param[out] dev_hdl_ret Device's handle
- * @return esp_err_t
+ *
+ * @return
+ *    - ESP_OK: Device opened successfully
+ *    - ESP_ERR_INVALID_ARG: Invalid argument
  */
 esp_err_t usb_host_device_open(usb_host_client_handle_t client_hdl, uint8_t dev_addr, usb_device_handle_t *dev_hdl_ret);
 
@@ -256,12 +294,18 @@ esp_err_t usb_host_device_open(usb_host_client_handle_t client_hdl, uint8_t dev_
  *
  * - This function allows a client to close a device
  * - A client must close a device after it has finished using the device (claimed interfaces must also be released)
- * - A client must close all devices it has opened before deregistering
+ * - A client must close all devices it has opened before de-registering
  *
  * @note This function can block
  * @param[in] client_hdl Client handle
  * @param[in] dev_hdl Device handle
- * @return esp_err_t
+ *
+ * @return
+ *    - ESP_OK: Device closed successfully
+ *    - ESP_ERR_INVALID_ARG: Invalid argument
+ *    - ESP_ERR_NOT_FOUND: Device address not found among opened devices
+ *    - ESP_ERR_INVALID_STATE: The client never opened the device, or the client has not released
+ *      all the interfaces from the device
  */
 esp_err_t usb_host_device_close(usb_host_client_handle_t client_hdl, usb_device_handle_t dev_hdl);
 
@@ -276,9 +320,10 @@ esp_err_t usb_host_device_close(usb_host_client_handle_t client_hdl, usb_device_
  * - This function is useful when cleaning up devices before uninstalling the USB Host Library
  *
  * @return
- *  - ESP_ERR_NOT_FINISHED: There are one or more devices that still need to be freed. Wait for USB_HOST_LIB_EVENT_FLAGS_ALL_FREE event
  *    - ESP_OK: All devices already freed (i.e., there were no devices)
- *  - Other: Error
+ *    - ESP_ERR_INVALID_STATE: Client must be deregistered
+ *    - ESP_ERR_NOT_FINISHED: There are one or more devices that still need to be freed,
+ *      wait for USB_HOST_LIB_EVENT_FLAGS_ALL_FREE event
  */
 esp_err_t usb_host_device_free_all(void);
 
@@ -292,7 +337,10 @@ esp_err_t usb_host_device_free_all(void);
  * @param[in] list_len Length of the empty list
  * @param[inout] dev_addr_list Empty list to be filled
  * @param[out] num_dev_ret Number of devices
- * @return esp_err_t
+ *
+ * @return
+ *    - ESP_OK: Device list filled successfully
+ *    - ESP_ERR_INVALID_ARG: Invalid argument
  */
 esp_err_t usb_host_device_addr_list_fill(int list_len, uint8_t *dev_addr_list, int *num_dev_ret);
 
@@ -309,7 +357,10 @@ esp_err_t usb_host_device_addr_list_fill(int list_len, uint8_t *dev_addr_list, i
  * @note This function can block
  * @param[in] dev_hdl Device handle
  * @param[out] dev_info Device information
- * @return esp_err_t
+ *
+ * @return
+ *    - ESP_OK: Device information obtained successfully
+ *    - ESP_ERR_INVALID_ARG: Invalid argument
  */
 esp_err_t usb_host_device_info(usb_device_handle_t dev_hdl, usb_device_info_t *dev_info);
 
@@ -327,7 +378,10 @@ esp_err_t usb_host_device_info(usb_device_handle_t dev_hdl, usb_device_info_t *d
  * @note No control transfer is sent. The device's descriptor is cached on enumeration
  * @param[in] dev_hdl Device handle
  * @param[out] device_desc Device descriptor
- * @return esp_err_t
+ *
+ * @return
+ *    - ESP_OK: Device descriptor obtained successfully
+ *    - ESP_ERR_INVALID_ARG: Invalid argument
  */
 esp_err_t usb_host_get_device_descriptor(usb_device_handle_t dev_hdl, const usb_device_desc_t **device_desc);
 
@@ -342,7 +396,10 @@ esp_err_t usb_host_get_device_descriptor(usb_device_handle_t dev_hdl, const usb_
  * @note No control transfer is sent. A device's active configuration descriptor is cached on enumeration
  * @param[in] dev_hdl Device handle
  * @param[out] config_desc Configuration descriptor
- * @return esp_err_t
+ *
+ * @return
+ *    - ESP_OK: Active configuration descriptor obtained successfully
+ *    - ESP_ERR_INVALID_ARG: Invalid argument
  */
 esp_err_t usb_host_get_active_config_descriptor(usb_device_handle_t dev_hdl, const usb_config_desc_t **config_desc);
 
@@ -351,17 +408,24 @@ esp_err_t usb_host_get_active_config_descriptor(usb_device_handle_t dev_hdl, con
  *
  * - The USB Host library only caches a device's active configuration descriptor.
  * - This function reads any configuration descriptor of a particular device (specified by bConfigurationValue).
- * - This function will read the specified configuration descriptor via control transfers, and allocate memory to store that descriptor.
+ * - This function will read the specified configuration descriptor via control transfers, and allocate memory
+ *   to store that descriptor.
  * - Users can call usb_host_free_config_desc() to free the descriptor's memory afterwards.
  *
  * @note This function can block
  * @note A client must call usb_host_device_open() on the device first
- * @param[in] client_hdl Client handle - usb_host_client_handle_events() should be called repeatedly in a separate task to handle client events
+ * @param[in] client_hdl Client handle - usb_host_client_handle_events() should be called repeatedly in a separate task
+ *            to handle client events
  * @param[in] dev_hdl Device handle
- * @param[out] config_desc_ret Returned configuration descriptor
  * @param[in] bConfigurationValue Index of device's configuration descriptor to be read
+ * @param[out] config_desc_ret Returned configuration descriptor
  * @note bConfigurationValue starts from index 1
- * @return esp_err_t
+ *
+ * @return
+ *    - ESP_OK: Configuration descriptor obtained successfully
+ *    - ESP_ERR_INVALID_ARG: Invalid argument
+ *    - ESP_ERR_NOT_SUPPORTED: Invalid bConfigurationValue value (the device does not have this configuration value)
+ *    - ESP_ERR_NO_MEM: Insufficient memory
  */
 esp_err_t usb_host_get_config_desc(usb_host_client_handle_t client_hdl, usb_device_handle_t dev_hdl, uint8_t bConfigurationValue, const usb_config_desc_t **config_desc_ret);
 
@@ -371,7 +435,10 @@ esp_err_t usb_host_get_config_desc(usb_host_client_handle_t client_hdl, usb_devi
  * This function frees a configuration descriptor that was returned by usb_host_get_config_desc()
  *
  * @param[out] config_desc Configuration descriptor
- * @return esp_err_t
+ *
+ * @return
+ *    - ESP_OK: Configuration descriptor freed successfully
+ *    - ESP_ERR_INVALID_ARG: Invalid argument
  */
 esp_err_t usb_host_free_config_desc(const usb_config_desc_t *config_desc);
 
@@ -388,7 +455,13 @@ esp_err_t usb_host_free_config_desc(const usb_config_desc_t *config_desc);
  * @param[in] dev_hdl Device handle
  * @param[in] bInterfaceNumber Interface number
  * @param[in] bAlternateSetting Interface alternate setting number
- * @return esp_err_t
+ *
+ * @return
+ *    - ESP_OK: Interface claimed successfully
+ *    - ESP_ERR_INVALID_ARG: Invalid argument
+ *    - ESP_ERR_INVALID_STATE: USB Host is not a correct state to claim an interface
+ *    - ESP_ERR_NOT_FOUND: Interface or EP not found
+ *    - ESP_ERR_NO_MEM: Insufficient memory
  */
 esp_err_t usb_host_interface_claim(usb_host_client_handle_t client_hdl, usb_device_handle_t dev_hdl, uint8_t bInterfaceNumber, uint8_t bAlternateSetting);
 
@@ -402,7 +475,12 @@ esp_err_t usb_host_interface_claim(usb_host_client_handle_t client_hdl, usb_devi
  * @param[in] client_hdl Client handle
  * @param[in] dev_hdl Device handle
  * @param[in] bInterfaceNumber Interface number
- * @return esp_err_t
+ *
+ * @return
+ *    - ESP_OK: Interface released successfully
+ *    - ESP_ERR_INVALID_ARG: Invalid argument
+ *    - ESP_ERR_INVALID_STATE: Client never opened the USB Device, or interface currently can not be freed
+ *    - ESP_ERR_NOT_FOUND: Interface number not found in the list of interfaces
  */
 esp_err_t usb_host_interface_release(usb_host_client_handle_t client_hdl, usb_device_handle_t dev_hdl, uint8_t bInterfaceNumber);
 
@@ -414,9 +492,14 @@ esp_err_t usb_host_interface_release(usb_host_client_handle_t client_hdl, usb_de
  * - Once halted, the endpoint must be cleared using usb_host_endpoint_clear() before it can communicate again
  *
  * @note This function can block
- * @param dev_hdl Device handle
+ * @param[in] dev_hdl Device handle
- * @param bEndpointAddress Endpoint address
+ * @param[in] bEndpointAddress Endpoint address
- * @return esp_err_t
+ *
+ * @return
+ *    - ESP_OK: Endpoint halted successfully
+ *    - ESP_ERR_INVALID_ARG: Invalid argument
+ *    - ESP_ERR_NOT_FOUND: Endpoint address not found
+ *    - ESP_ERR_INVALID_STATE: Endpoint pipe is not in the correct state/condition to execute a command
  */
 esp_err_t usb_host_endpoint_halt(usb_device_handle_t dev_hdl, uint8_t bEndpointAddress);
 
@@ -429,9 +512,14 @@ esp_err_t usb_host_endpoint_halt(usb_device_handle_t dev_hdl, uint8_t bEndpointA
  * - Flushing an endpoint will caused an queued up transfers to be canceled
  *
  * @note This function can block
- * @param dev_hdl Device handle
+ * @param[in] dev_hdl Device handle
- * @param bEndpointAddress Endpoint address
+ * @param[in] bEndpointAddress Endpoint address
- * @return esp_err_t
+ *
+ * @return
+ *    - ESP_OK: Endpoint flushed successfully
+ *    - ESP_ERR_INVALID_ARG: Invalid argument
+ *    - ESP_ERR_NOT_FOUND: Endpoint address not found
+ *    - ESP_ERR_INVALID_STATE: Endpoint pipe is not in the correct state/condition to execute a command
  */
 esp_err_t usb_host_endpoint_flush(usb_device_handle_t dev_hdl, uint8_t bEndpointAddress);
 
@@ -444,9 +532,14 @@ esp_err_t usb_host_endpoint_flush(usb_device_handle_t dev_hdl, uint8_t bEndpoint
  * - If the endpoint has any queued up transfers, clearing a halt will resume their execution
  *
  * @note This function can block
- * @param dev_hdl Device handle
+ * @param[in] dev_hdl Device handle
- * @param bEndpointAddress Endpoint address
+ * @param[in] bEndpointAddress Endpoint address
- * @return esp_err_t
+ *
+ * @return
+ *    - ESP_OK: Endpoint cleared successfully
+ *    - ESP_ERR_INVALID_ARG: Invalid argument
+ *    - ESP_ERR_NOT_FOUND: Endpoint address not found
+ *    - ESP_ERR_INVALID_STATE: Endpoint pipe is not in the correct state/condition to execute a command
  */
 esp_err_t usb_host_endpoint_clear(usb_device_handle_t dev_hdl, uint8_t bEndpointAddress);
 
@@ -463,7 +556,10 @@ esp_err_t usb_host_endpoint_clear(usb_device_handle_t dev_hdl, uint8_t bEndpoint
  * @param[in] data_buffer_size Size of the transfer's data buffer
  * @param[in] num_isoc_packets Number of isochronous packets in transfer (set to 0 for non-isochronous transfers)
  * @param[out] transfer Transfer object
- * @return esp_err_t
+ *
+ * @return
+ *    - ESP_OK: Transfer object allocated successfully
+ *    - ESP_ERR_NO_MEM: Insufficient memory
  */
 esp_err_t usb_host_transfer_alloc(size_t data_buffer_size, int num_isoc_packets, usb_transfer_t **transfer);
 
@@ -475,7 +571,9 @@ esp_err_t usb_host_transfer_alloc(size_t data_buffer_size, int num_isoc_packets,
  * - If a NULL pointer is passed, this function will simply return ESP_OK
  *
  * @param[in] transfer Transfer object
- * @return esp_err_t
+ *
+ * @return
+ *    - ESP_OK: Transfer object freed successfully
  */
 esp_err_t usb_host_transfer_free(usb_transfer_t *transfer);
 
@@ -487,7 +585,13 @@ esp_err_t usb_host_transfer_free(usb_transfer_t *transfer);
  * - On completion, the transfer's callback will be called from the client's usb_host_client_handle_events() function.
  *
  * @param[in] transfer Initialized transfer object
- * @return esp_err_t
+ *
+ * @return
+ *    - ESP_OK: Transfer submitted successfully
+ *    - ESP_ERR_INVALID_ARG: Invalid argument
+ *    - ESP_ERR_NOT_FINISHED: Transfer already in-flight
+ *    - ESP_ERR_NOT_FOUND: Endpoint address not found
+ *    - ESP_ERR_INVALID_STATE: Endpoint pipe is not in a correct state to submit transfer
  */
 esp_err_t usb_host_transfer_submit(usb_transfer_t *transfer);
 
@@ -501,7 +605,13 @@ esp_err_t usb_host_transfer_submit(usb_transfer_t *transfer);
  *
  * @param[in] client_hdl Client handle
  * @param[in] transfer Initialized transfer object
- * @return esp_err_t
+ *
+ * @return
+ *    - ESP_OK: Control transfer submitted successfully
+ *    - ESP_ERR_INVALID_ARG: Invalid argument
+ *    - ESP_ERR_NOT_FINISHED: Transfer already in-flight
+ *    - ESP_ERR_NOT_FOUND: Endpoint address not found
+ *    - ESP_ERR_INVALID_STATE: Endpoint pipe is not in a correct state to submit transfer
  */
 esp_err_t usb_host_transfer_submit_control(usb_host_client_handle_t client_hdl, usb_transfer_t *transfer);
 

components/usb/private_include/enum.h

@@ -101,7 +101,12 @@ typedef struct {
  *
  * @param[in]  enum_config Enumeration driver configuration
  * @param[out] client_ret Unique pointer to identify Enum Driver as a USB Host client
- * @return esp_err_t
+ *
+ * @return
+ *    - ESP_OK: Enumeration driver installed successfully
+ *    - ESP_ERR_INVALID_STATE: Enumeration driver is already installed
+ *    - ESP_ERR_INVALID_ARG: Invalid argument
+ *    - ESP_ERR_NO_MEM: Insufficient memory
  */
 esp_err_t enum_install(enum_config_t *enum_config, void **client_ret);
 
@@ -110,7 +115,9 @@ esp_err_t enum_install(enum_config_t *enum_config, void **client_ret);
  *
  * This must be called before uninstalling the HUB and USBH
  *
- *  @return esp_err_t
+ * @return
+ *    - ESP_OK: Enumeration driver uninstalled successfully
+ *    - ESP_ERR_INVALID_STATE: Enumeration driver is not installed
  */
 esp_err_t enum_uninstall(void);
 
@@ -120,8 +127,10 @@ esp_err_t enum_uninstall(void);
  * This will start the enumeration process for the device currently at address 0
  *
  * @param[in] uid  Unique device ID
- * @retval ESP_OK: Enumeration process started
+ *
- * @retval ESP_ERR_NOT_FOUND: No device at address 0
+ * @return
+ *    - ESP_OK: Enumeration process started
+ *    - ESP_ERR_NOT_FOUND: No device at address 0
  */
 esp_err_t enum_start(unsigned int uid);
 
@@ -132,7 +141,10 @@ esp_err_t enum_start(unsigned int uid);
  * handling of a request from the Enumerator driver (such as ENUM_EVENT_RESET_REQUIRED)
  *
  * @param[in] uid  Unique device ID
- * @return esp_err_t
+ *
+ * @return
+ *    - ESP_OK: Enumeration continues normally
+ *    - ESP_ERR_INVALID_STATE: Enumeration driver not installed, or enumeration process in not active
  */
 esp_err_t enum_proceed(unsigned int uid);
 
@@ -141,7 +153,11 @@ esp_err_t enum_proceed(unsigned int uid);
  *
  * This will cancel enumeration process for device object under enumeration
  *
- * @return esp_err_t
+ * @param[in] uid Unique device ID
+ *
+ * @return
+ *    - ESP_OK: Enumeration process canceled successfully
+ *    - ESP_ERR_INVALID_STATE: Enumeration driver not installed, or enumeration process in not active
  */
 esp_err_t enum_cancel(unsigned int uid);
 
@@ -150,7 +166,9 @@ esp_err_t enum_cancel(unsigned int uid);
  *
  * Processing function that must be called repeatedly to process enumeration stages
  *
- * @return esp_err_t
+ * @return
+ *    - ESP_OK: Enumeration continues normally
+ *    - ESP_ERR_INVALID_STATE: Enumeration driver not installed, or enumeration process in not active
  */
 esp_err_t enum_process(void);
 

components/usb/private_include/ext_hub.h

@@ -71,7 +71,11 @@ typedef struct {
  * - should be called within Hub Driver
  *
  * @param[in] config External Hub driver configuration
- * @return esp_err_t
+ *
+ * @return
+ *    - ESP_OK: External Hub driver successfully installed
+ *    - ESP_ERR_NO_MEM: Insufficient memory
+ *    - ESP_ERR_INVALID_STATE: External Hub driver already installed
  */
 esp_err_t ext_hub_install(const ext_hub_config_t* config);
 
@@ -81,7 +85,9 @@ esp_err_t ext_hub_install(const ext_hub_config_t* config);
  * Entry:
  * - should be called within Hub Driver
  *
- * @return esp_err_t
+ * @return
+ *    - ESP_OK: External Hub driver successfully uninstalled
+ *    - ESP_ERR_INVALID_STATE: External Hub driver is not installed, or the driver has unhandled devices
  */
 esp_err_t ext_hub_uninstall(void);
 
@@ -92,7 +98,9 @@ esp_err_t ext_hub_uninstall(void);
  * - should be called within Hub Driver
  *
  * @param[in] config External Hub driver configuration
- * @return Unique pointer to identify the External Hub as a USB Host client
+ *
+ * @return
+ *    - Unique pointer to identify the External Hub as a USB Host client
  */
 void *ext_hub_get_client(void);
 
@@ -103,7 +111,11 @@ void *ext_hub_get_client(void);
  *
  * @param[in] dev_hdl       USBH device handle
  * @param[out] ext_hub_hdl  External Hub device handle
- * @return esp_err_t
+ *
+ * @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_t ext_hub_get_handle(usb_device_handle_t dev_hdl, ext_hub_handle_t *ext_hub_hdl);
 
@@ -114,7 +126,10 @@ esp_err_t ext_hub_get_handle(usb_device_handle_t dev_hdl, ext_hub_handle_t *ext_
  *  - configure it's parameters (requesting hub descriptor)
  *
  * @param[in] dev_addr      Device bus address
- * @return esp_err_t
+ *
+ * @return
+ *    - ESP_OK: New device added successfully
+ *    - ESP_ERR_INVALID_STATE: External Hub driver is not installed, or not in correct state to add a new device
  */
 esp_err_t ext_hub_new_dev(uint8_t dev_addr);
 
@@ -125,7 +140,12 @@ esp_err_t ext_hub_new_dev(uint8_t dev_addr);
  *  - prepare the device to be freed
  *
  * @param[in] dev_addr       Device bus address
- * @return esp_err_t
+ *
+ * @return
+ *    - ESP_OK: Device freed successfully
+ *    - ESP_ERR_INVALID_STATE: External Hub driver is not installed
+ *    - ESP_ERR_INVALID_ARG: Invalid argument
+ *    - ESP_ERR_NOT_FOUND: Device address not found
  */
 esp_err_t ext_hub_dev_gone(uint8_t dev_addr);
 
@@ -135,8 +155,9 @@ esp_err_t ext_hub_dev_gone(uint8_t dev_addr);
  * Entry:
  * - should be called within Hub Driver when USB Host library need to be uninstalled
  *
- * @param[in] dev_addr       Device bus address
+ * @return
- * @return esp_err_t
+ *    - ESP_OK: All devices freed
+ *    - ESP_ERR_INVALID_STATE: External Hub driver is not installed
  */
 esp_err_t ext_hub_all_free(void);
 
@@ -146,7 +167,11 @@ esp_err_t ext_hub_all_free(void);
  * Enables Interrupt IN endpoint to get information about Hub or Ports statuses change
  *
  * @param[in] ext_hub_hdl     External Hub device handle
- * @return esp_err_t
+ *
+ * @return
+ *    - ESP_OK: External Hub or Ports statuses change completed
+ *    - ESP_ERR_INVALID_ARG: Invalid argument
+ *    - ESP_ERR_INVALID_STATE: External hub must be in configured state
  */
 esp_err_t ext_hub_status_handle_complete(ext_hub_handle_t ext_hub_hdl);
 
@@ -156,6 +181,10 @@ esp_err_t ext_hub_status_handle_complete(ext_hub_handle_t ext_hub_hdl);
  * External Hub driver process function that must be called repeatedly to process the driver's actions and events.
  * If blocking, the caller can block on the notification callback of source USB_PROC_REQ_SOURCE_HUB
  * to run this function.
+ *
+ * @return
+ *    - ESP_OK: All events handled
+ *    - ESP_ERR_INVALID_STATE: External Hub driver is not installed
  */
 esp_err_t ext_hub_process(void);
 
@@ -169,7 +198,13 @@ esp_err_t ext_hub_process(void);
  *
  * @param[in] ext_hub_hdl   External Hub handle
  * @param[in] port_num      Port number
- * @retval ESP_OK: Success
+ *
+ * @return
+ *    - ESP_OK: The port can be recycled
+ *    - ESP_ERR_INVALID_STATE: External Hub driver is not installed
+ *    - ESP_ERR_INVALID_ARG: Invalid argument
+ *    - ESP_ERR_INVALID_SIZE: External Hub port number out of the hub's range
+ *    - ESP_ERR_NOT_SUPPORTED: External Port Driver has not been installed
  */
 esp_err_t ext_hub_port_recycle(ext_hub_handle_t ext_hub_hdl, uint8_t port_num);
 
@@ -178,7 +213,13 @@ esp_err_t ext_hub_port_recycle(ext_hub_handle_t ext_hub_hdl, uint8_t port_num);
  *
  * @param[in] ext_hub_hdl   External Hub handle
  * @param[in] port_num      Port number
- * @retval ESP_OK: Success
+ *
+ * @return
+ *    - ESP_OK: The port can be reset
+ *    - ESP_ERR_INVALID_STATE: External Hub driver is not installed
+ *    - ESP_ERR_INVALID_ARG: Invalid argument
+ *    - ESP_ERR_INVALID_SIZE: External Hub port number out of the hub's range
+ *    - ESP_ERR_NOT_SUPPORTED: External Port Driver has not been installed
  */
 esp_err_t ext_hub_port_reset(ext_hub_handle_t ext_hub_hdl, uint8_t port_num);
 
@@ -187,7 +228,13 @@ esp_err_t ext_hub_port_reset(ext_hub_handle_t ext_hub_hdl, uint8_t port_num);
  *
  * @param[in] ext_hub_hdl   External Hub handle
  * @param[in] port_num      Port number
- * @retval ESP_OK: Success
+ *
+ * @return
+ *    - ESP_OK: Device on the External hub's port has been enumerated
+ *    - ESP_ERR_INVALID_STATE: External Hub driver is not installed
+ *    - ESP_ERR_INVALID_ARG: Invalid argument
+ *    - ESP_ERR_INVALID_SIZE: External Hub port number out of the hub's range
+ *    - ESP_ERR_NOT_SUPPORTED: External Port Driver has not been installed
  */
 esp_err_t ext_hub_port_active(ext_hub_handle_t ext_hub_hdl, uint8_t port_num);
 
@@ -196,7 +243,13 @@ esp_err_t ext_hub_port_active(ext_hub_handle_t ext_hub_hdl, uint8_t port_num);
  *
  * @param[in] ext_hub_hdl   External Hub handle
  * @param[in] port_num      Port number
- * @retval ESP_OK: Success
+ *
+ * @return
+ *    - ESP_OK: Device on the External hub's port can be disabled
+ *    - ESP_ERR_INVALID_STATE: External Hub driver is not installed
+ *    - ESP_ERR_INVALID_ARG: Invalid argument
+ *    - ESP_ERR_INVALID_SIZE: External Hub port number out of the hub's range
+ *    - ESP_ERR_NOT_SUPPORTED: External Port Driver has not been installed
  */
 esp_err_t ext_hub_port_disable(ext_hub_handle_t ext_hub_hdl, uint8_t port_num);
 
@@ -206,7 +259,13 @@ esp_err_t ext_hub_port_disable(ext_hub_handle_t ext_hub_hdl, uint8_t port_num);
  * @param[in] ext_hub_hdl   External Hub handle
  * @param[in] port_num      Port number
  * @param[out] speed        Devices' speed
- * @retval ESP_OK: Success
+ *
+ * @return
+ *    - ESP_OK: The device's speed obtained successfully
+ *    - ESP_ERR_INVALID_STATE: External Hub driver is not installed
+ *    - ESP_ERR_INVALID_ARG: Invalid argument
+ *    - ESP_ERR_INVALID_SIZE: External Hub port number out of the hub's range
+ *    - ESP_ERR_NOT_SUPPORTED: External Port Driver has not been installed
  */
 esp_err_t ext_hub_port_get_speed(ext_hub_handle_t ext_hub_hdl, uint8_t port_num, usb_speed_t *speed);
 
@@ -218,7 +277,12 @@ esp_err_t ext_hub_port_get_speed(ext_hub_handle_t ext_hub_hdl, uint8_t port_num,
  * @param[in] ext_hub_hdl   External Hub device handle
  * @param[in] port_num      Port number
  * @param[in] feature       Port Feature to set
- * @return esp_err_t
+ *
+ * @return
+ *    - ESP_OK: Port's feature set successfully
+ *    - ESP_ERR_INVALID_STATE: External Hub driver is not installed;
+ *    - ESP_ERR_INVALID_ARG: Invalid argument
+ *    - ESP_ERR_INVALID_SIZE: External Hub port number out of the hub's range
  */
 esp_err_t ext_hub_set_port_feature(ext_hub_handle_t ext_hub_hdl, uint8_t port_num, uint8_t feature);
 
@@ -228,7 +292,12 @@ esp_err_t ext_hub_set_port_feature(ext_hub_handle_t ext_hub_hdl, uint8_t port_nu
  * @param[in] ext_hub_hdl   External Hub device handle
  * @param[in] port_num      Port number
  * @param[in] feature       Port Feature to clear
- * @return esp_err_t
+ *
+ * @return
+ *    - ESP_OK: Port's feature cleared successfully
+ *    - ESP_ERR_INVALID_STATE: External Hub driver is not installed;
+ *    - ESP_ERR_INVALID_ARG: Invalid argument
+ *    - ESP_ERR_INVALID_SIZE: External Hub port number out of the hub's range
  */
 esp_err_t ext_hub_clear_port_feature(ext_hub_handle_t ext_hub_hdl, uint8_t port_num, uint8_t feature);
 
@@ -240,7 +309,12 @@ esp_err_t ext_hub_clear_port_feature(ext_hub_handle_t ext_hub_hdl, uint8_t port_
  *
  * @param[in] ext_hub_hdl   External Hub device handle
  * @param[in] port_num      Port number
- * @return esp_err_t
+ *
+ * @return
+ *    - ESP_OK: Port's status obtained successfully
+ *    - ESP_ERR_INVALID_STATE: External Hub driver is not installed;
+ *    - ESP_ERR_INVALID_ARG: Invalid argument
+ *    - ESP_ERR_INVALID_SIZE: External Hub port number out of the hub's range
  */
 esp_err_t ext_hub_get_port_status(ext_hub_handle_t ext_hub_hdl, uint8_t port_num);
 

components/usb/private_include/hcd.h

@@ -185,12 +185,13 @@ typedef struct {
  * @note Before calling this function, the Host Controller must already be un-clock gated and reset. The USB PHY
  *       (internal or external, and associated GPIOs) must already be configured.
  *
- * @param config HCD configuration
+ * @param[in] config HCD configuration
- * @retval ESP_OK: HCD successfully installed
+ *
- * @retval ESP_ERR_NO_MEM: Insufficient memory
+ * @return
- * @retval ESP_ERR_INVALID_STATE: HCD is already installed
+ *    - ESP_OK: HCD successfully installed
- * @retval ESP_ERR_NOT_FOUND: HCD could not allocate interrupt
+ *    - ESP_ERR_NO_MEM: Insufficient memory
- * @retval ESP_ERR_INVALID_ARG: Arguments are invalid
+ *    - ESP_ERR_INVALID_STATE: HCD is already installed
+ *    - ESP_ERR_INVALID_ARG: Arguments are invalid
  */
 esp_err_t hcd_install(const hcd_config_t *config);
 
@@ -203,8 +204,9 @@ esp_err_t hcd_install(const hcd_config_t *config);
  * @note This function will simply free the resources used by the HCD. The underlying Host Controller and USB PHY will
  *       not be disabled.
  *
- * @retval ESP_OK: HCD successfully uninstalled
+ * @return
- * @retval ESP_ERR_INVALID_STATE: HCD is not in the right condition to be uninstalled
+ *    - ESP_OK: HCD successfully uninstalled
+ *    - ESP_ERR_INVALID_STATE: HCD is not in the right condition to be uninstalled
  */
 esp_err_t hcd_uninstall(void);
 
@@ -220,11 +222,13 @@ esp_err_t hcd_uninstall(void);
  * @param[in] port_number Port number
  * @param[in] port_config Port configuration
  * @param[out] port_hdl Port handle
- * @retval ESP_OK: Port enabled
+ *
- * @retval ESP_ERR_NO_MEM: Insufficient memory
+ * @return
- * @retval ESP_ERR_INVALID_STATE: The port is already enabled
+ *    - ESP_OK: Port enabled
- * @retval ESP_ERR_NOT_FOUND: Port number not found
+ *    - ESP_ERR_NO_MEM: Insufficient memory
- * @retval ESP_ERR_INVALID_ARG: Arguments are invalid
+ *    - ESP_ERR_INVALID_STATE: The port is already enabled
+ *    - ESP_ERR_NOT_FOUND: Port number not found
+ *    - ESP_ERR_INVALID_ARG: Arguments are invalid
  */
 esp_err_t hcd_port_init(int port_number, const hcd_port_config_t *port_config, hcd_port_handle_t *port_hdl);
 
@@ -234,9 +238,11 @@ esp_err_t hcd_port_init(int port_number, const hcd_port_config_t *port_config, h
  * The port must be placed in the HCD_PORT_STATE_NOT_POWERED or HCD_PORT_STATE_RECOVERY state before it can be
  * deinitialized.
  *
- * @param port_hdl Port handle
+ * @param[in] port_hdl Port handle
- * @retval ESP_OK: Port disabled
+ *
- * @retval ESP_ERR_INVALID_STATE: The port is not in a condition to be disabled (not unpowered)
+ * @return
+ *    - ESP_OK: Port disabled
+ *    - ESP_ERR_INVALID_STATE: The port is not in a condition to be disabled (not unpowered)
  */
 esp_err_t hcd_port_deinit(hcd_port_handle_t port_hdl);
 
@@ -254,18 +260,20 @@ esp_err_t hcd_port_deinit(hcd_port_handle_t port_hdl);
  * @note For some of the commands that involve a blocking delay (e.g., reset and resume), if the port's state changes
  *       unexpectedly (e.g., a disconnect during a resume), this function will return ESP_ERR_INVALID_RESPONSE.
  *
- * @param port_hdl Port handle
+ * @param[in] port_hdl Port handle
- * @param command Command for the HCD port
+ * @param[in] command Command for the HCD port
- * @retval ESP_OK: Command executed successfully
+ *
- * @retval ESP_ERR_INVALID_STATE: Conditions have not been met to call this function
+ * @return
- * @retval ESP_ERR_INVALID_RESPONSE: The command is no longer valid due to a change in the port's state
+ *    - ESP_OK: Command executed successfully
+ *    - ESP_ERR_INVALID_STATE: Conditions have not been met to call this function
+ *    - ESP_ERR_INVALID_RESPONSE: The command is no longer valid due to a change in the port's state
  */
 esp_err_t hcd_port_command(hcd_port_handle_t port_hdl, hcd_port_cmd_t command);
 
 /**
  * @brief Get the port's current state
  *
- * @param port_hdl Port handle
+ * @param[in] port_hdl Port handle
  * @return hcd_port_state_t Current port state
  */
 hcd_port_state_t hcd_port_get_state(hcd_port_handle_t port_hdl);
@@ -277,11 +285,13 @@ hcd_port_state_t hcd_port_get_state(hcd_port_handle_t port_hdl);
  *
  * @note This function is only valid after a device directly to the port and has been reset
  *
- * @param[in port_hdl Port handle
+ * @param[in] port_hdl Port handle
  * @param[out] speed Speed of the port
- * @retval ESP_OK Device speed obtained
+ *
- * @retval ESP_ERR_INVALID_STATE: No valid device connected to the port
+ * @return
- * @retval ESP_ERR_INVALID_ARG: Invalid arguments
+ *    - ESP_OK Device speed obtained
+ *    - ESP_ERR_INVALID_STATE: No valid device connected to the port
+ *    - ESP_ERR_INVALID_ARG: Invalid arguments
  */
 esp_err_t hcd_port_get_speed(hcd_port_handle_t port_hdl, usb_speed_t *speed);
 
@@ -299,8 +309,10 @@ esp_err_t hcd_port_get_speed(hcd_port_handle_t port_hdl, usb_speed_t *speed);
  * @note This function is internally protected by a mutex. If multiple threads call this function, this function will
  *       can block.
  *
- * @param port_hdl Port handle
+ * @param[in] port_hdl Port handle
- * @return hcd_port_event_t The port event that was handled
+ *
+ * @return
+ *    - hcd_port_event_t The port event that was handled
  */
 hcd_port_event_t hcd_port_handle_event(hcd_port_handle_t port_hdl);
 
@@ -310,17 +322,21 @@ hcd_port_event_t hcd_port_handle_event(hcd_port_handle_t port_hdl);
  * The port must be in the HCD_PORT_STATE_RECOVERY state to be called. Recovering the port will involve issuing a soft
  * reset on the underlying USB controller. The port will be returned to the HCD_PORT_STATE_NOT_POWERED state.
  *
- * @param port_hdl Port handle
+ * @param[in] port_hdl Port handle
- * @retval ESP_OK Port recovered successfully
+ *
- * @retval ESP_ERR_INVALID_STATE Port is not in the HCD_PORT_STATE_RECOVERY state
+ * @return
+ *    - ESP_OK Port recovered successfully
+ *    - ESP_ERR_INVALID_STATE Port is not in the HCD_PORT_STATE_RECOVERY state
  */
 esp_err_t hcd_port_recover(hcd_port_handle_t port_hdl);
 
 /**
  * @brief Get the context variable of a port
  *
- * @param port_hdl Port handle
+ * @param[in] port_hdl Port handle
- * @return void* Context variable
+ *
+ * @return
+ *    - void* Context variable
  */
 void *hcd_port_get_context(hcd_port_handle_t port_hdl);
 
@@ -332,10 +348,12 @@ void *hcd_port_get_context(hcd_port_handle_t port_hdl);
  *  - Port does not have any pending events
  *  - Port does not have any allocated pipes
  *
- * @param port_hdl Port handle
+ * @param[in] port_hdl Port handle
- * @param bias Fifo bias
+ * @param[in] bias Fifo bias
- * @retval ESP_OK FIFO sizing successfully set
+ *
- * @retval ESP_ERR_INVALID_STATE Incorrect state for FIFO sizes to be set
+ * @return
+ *    - ESP_OK FIFO sizing successfully set
+ *    - ESP_ERR_INVALID_STATE Incorrect state for FIFO sizes to be set
  */
 esp_err_t hcd_port_set_fifo_bias(hcd_port_handle_t port_hdl, hcd_port_fifo_bias_t bias);
 
@@ -353,11 +371,12 @@ esp_err_t hcd_port_set_fifo_bias(hcd_port_handle_t port_hdl, hcd_port_fifo_bias_
  * @param[in] pipe_config Pipe configuration
  * @param[out] pipe_hdl Pipe handle
  *
- * @retval ESP_OK: Pipe successfully allocated
+ * @return
- * @retval ESP_ERR_NO_MEM: Insufficient memory
+ *    - ESP_OK: Pipe successfully allocated
- * @retval ESP_ERR_INVALID_ARG: Arguments are invalid
+ *    - ESP_ERR_NO_MEM: Insufficient memory
- * @retval ESP_ERR_INVALID_STATE: Host port is not in the correct state to allocate a pipe
+ *    - ESP_ERR_INVALID_ARG: Arguments are invalid
- * @retval ESP_ERR_NOT_SUPPORTED: The pipe's configuration cannot be supported
+ *    - ESP_ERR_INVALID_STATE: Host port is not in the correct state to allocate a pipe
+ *    - ESP_ERR_NOT_SUPPORTED: The pipe's configuration cannot be supported
  */
 esp_err_t hcd_pipe_alloc(hcd_port_handle_t port_hdl, const hcd_pipe_config_t *pipe_config, hcd_pipe_handle_t *pipe_hdl);
 
@@ -366,7 +385,8 @@ esp_err_t hcd_pipe_alloc(hcd_port_handle_t port_hdl, const hcd_pipe_config_t *pi
  *
  * @param[in] port_hdl Pipe handle
  *
- * @retval HCD pipe mps
+ * @return
+ *    - HCD pipe mps
  */
 int hcd_pipe_get_mps(hcd_pipe_handle_t pipe_hdl);
 
@@ -377,10 +397,11 @@ int hcd_pipe_get_mps(hcd_pipe_handle_t pipe_hdl);
  * must be in following condition before it can be freed:
  * - All URBs have been dequeued
  *
- * @param pipe_hdl Pipe handle
+ * @param[in] pipe_hdl Pipe handle
  *
- * @retval ESP_OK: Pipe successfully freed
+ * @return
- * @retval ESP_ERR_INVALID_STATE: Pipe is not in a condition to be freed
+ *    - ESP_OK: Pipe successfully freed
+ *    - ESP_ERR_INVALID_STATE: Pipe is not in a condition to be freed
  */
 esp_err_t hcd_pipe_free(hcd_pipe_handle_t pipe_hdl);
 
@@ -393,11 +414,12 @@ esp_err_t hcd_pipe_free(hcd_pipe_handle_t pipe_hdl);
  * - Pipe does not have any enqueued URBs
  * - Port cannot be resetting
  *
- * @param pipe_hdl Pipe handle
+ * @param[in] pipe_hdl Pipe handle
- * @param mps New Maximum Packet Size
+ * @param[in] mps New Maximum Packet Size
  *
- * @retval ESP_OK: Pipe successfully updated
+ * @return
- * @retval ESP_ERR_INVALID_STATE: Pipe is not in a condition to be updated
+ *    - ESP_OK: Pipe successfully updated
+ *    - ESP_ERR_INVALID_STATE: Pipe is not in a condition to be updated
  */
 esp_err_t hcd_pipe_update_mps(hcd_pipe_handle_t pipe_hdl, int mps);
 
@@ -410,27 +432,32 @@ esp_err_t hcd_pipe_update_mps(hcd_pipe_handle_t pipe_hdl, int mps);
  * - Pipe does not have any enqueued URBs
  * - Port cannot be resetting
  *
- * @param pipe_hdl Pipe handle
+ * @param[in] pipe_hdl Pipe handle
- * @param dev_addr New device address
+ * @param[in] dev_addr New device address
  *
- * @retval ESP_OK: Pipe successfully updated
+ * @return
- * @retval ESP_ERR_INVALID_STATE: Pipe is not in a condition to be updated
+ *    - ESP_OK: Pipe successfully updated
+ *    - ESP_ERR_INVALID_STATE: Pipe is not in a condition to be updated
  */
 esp_err_t hcd_pipe_update_dev_addr(hcd_pipe_handle_t pipe_hdl, uint8_t dev_addr);
 
 /**
  * @brief Get the context variable of a pipe from its handle
  *
- * @param pipe_hdl Pipe handle
+ * @param[in] pipe_hdl Pipe handle
- * @return void* Context variable
+ *
+ * @return
+ *    - void* Context variable
  */
 void *hcd_pipe_get_context(hcd_pipe_handle_t pipe_hdl);
 
 /**
  * @brief Get the current state of the pipe
  *
- * @param pipe_hdl Pipe handle
+ * @param[in] pipe_hdl Pipe handle
- * @return hcd_pipe_state_t Current state of the pipe
+ *
+ * @return
+ *    - hcd_pipe_state_t Current state of the pipe
  */
 hcd_pipe_state_t hcd_pipe_get_state(hcd_pipe_handle_t pipe_hdl);
 
@@ -440,8 +467,10 @@ hcd_pipe_state_t hcd_pipe_get_state(hcd_pipe_handle_t pipe_hdl);
  * Returns the current number of URBs that have been enqueued (via hcd_urb_enqueue()) and have yet to be dequeued (via
  * hcd_urb_dequeue()).
  *
- * @param pipe_hdl Pipe handle
+ * @param[in] pipe_hdl Pipe handle
- * @return Number of in-flight URBs
+ *
+ * @return
+ *    - Number of in-flight URBs
  */
 unsigned int hcd_pipe_get_num_urbs(hcd_pipe_handle_t pipe_hdl);
 
@@ -452,10 +481,12 @@ unsigned int hcd_pipe_get_num_urbs(hcd_pipe_handle_t pipe_hdl);
  *
  * @note This function can block
  *
- * @param pipe_hdl Pipe handle
+ * @param[in] pipe_hdl Pipe handle
- * @param command Pipe command
+ * @param[in] command Pipe command
- * @retval ESP_OK: Command executed successfully
+ *
- * @retval ESP_ERR_INVALID_STATE: The pipe is not in the correct state/condition too execute the command
+ * @return
+ *    - ESP_OK: Command executed successfully
+ *    - ESP_ERR_INVALID_STATE: The pipe is not in the correct state/condition too execute the command
  */
 esp_err_t hcd_pipe_command(hcd_pipe_handle_t pipe_hdl, hcd_pipe_cmd_t command);
 
@@ -465,8 +496,10 @@ esp_err_t hcd_pipe_command(hcd_pipe_handle_t pipe_hdl, hcd_pipe_cmd_t command);
  * This function allows a pipe to be polled for events (i.e., when callbacks are not used). Once an event has been
  * obtained, this function reset the last event of the pipe to HCD_PIPE_EVENT_NONE.
  *
- * @param pipe_hdl Pipe handle
+ * @param[in] pipe_hdl Pipe handle
- * @return hcd_pipe_event_t Last pipe event to occur
+ *
+ * @return
+ *    - hcd_pipe_event_t Last pipe event to occur
  */
 hcd_pipe_event_t hcd_pipe_get_event(hcd_pipe_handle_t pipe_hdl);
 
@@ -481,10 +514,12 @@ hcd_pipe_event_t hcd_pipe_get_event(hcd_pipe_handle_t pipe_hdl);
  * - The pipe must be in the HCD_PIPE_STATE_ACTIVE state
  * - The pipe cannot be executing a command
  *
- * @param pipe_hdl Pipe handle
+ * @param[in] pipe_hdl Pipe handle
- * @param urb URB to enqueue
+ * @param[in] urb URB to enqueue
- * @retval ESP_OK: URB enqueued successfully
+ *
- * @retval ESP_ERR_INVALID_STATE: Conditions not met to enqueue URB
+ * @return
+ *    - ESP_OK: URB enqueued successfully
+ *    - ESP_ERR_INVALID_STATE: Conditions not met to enqueue URB
  */
 esp_err_t hcd_urb_enqueue(hcd_pipe_handle_t pipe_hdl, urb_t *urb);
 
@@ -495,8 +530,10 @@ esp_err_t hcd_urb_enqueue(hcd_pipe_handle_t pipe_hdl, urb_t *urb);
  * multiple URBs that can be dequeued, this function should be called repeatedly until all URBs are dequeued. If a pipe
  * has no more URBs to dequeue, this function will return NULL.
  *
- * @param pipe_hdl Pipe handle
+ * @param[in] pipe_hdl Pipe handle
- * @return urb_t* Dequeued URB, or NULL if no more URBs to dequeue
+ *
+ * @return
+ *    - urb_t* Dequeued URB, or NULL if no more URBs to dequeue
  */
 urb_t *hcd_urb_dequeue(hcd_pipe_handle_t pipe_hdl);
 
@@ -507,9 +544,11 @@ urb_t *hcd_urb_dequeue(hcd_pipe_handle_t pipe_hdl);
  * "canceled" and can then be dequeued. If the URB is currently in-flight or has already completed, the URB will not be
  * affected by this function.
  *
- * @param urb URB to abort
+ * @param[in] urb URB to abort
- * @retval ESP_OK: URB successfully aborted, or was not affected by this function
+ *
- * @retval ESP_ERR_INVALID_STATE: URB was never enqueued
+ * @return
+ *    - ESP_OK: URB successfully aborted, or was not affected by this function
+ *    - ESP_ERR_INVALID_STATE: URB was never enqueued
  */
 esp_err_t hcd_urb_abort(urb_t *urb);
 

components/usb/private_include/hub.h

@@ -79,7 +79,12 @@ typedef struct {
  *
  * @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
+ *
+ * @return
+ *    - ESP_OK: Hub driver installed successfully
+ *    - ESP_ERR_INVALID_STATE: Hub driver is not in correct state to be installed
+ *    - ESP_ERR_NO_MEM: Insufficient memory
+ *    - ESP_ERR_INVALID_ARG: Arguments are invalid
  */
 esp_err_t hub_install(hub_config_t *hub_config, void **client_ret);
 
@@ -92,7 +97,9 @@ esp_err_t hub_install(hub_config_t *hub_config, void **client_ret);
  * Exit:
  * - HCD root port deinitialized
  *
- * @return esp_err_t
+ * @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_t hub_uninstall(void);
 
@@ -103,7 +110,9 @@ esp_err_t hub_uninstall(void);
  *
  * @note This function should only be called from the Host Library task
  *
- * @return esp_err_t
+ * @return
+ *    - ESP_OK: Hub driver started successfully
+ *    - ESP_ERR_INVALID_STATE: Hub driver is not installed, or root port is in other state than not powered
  */
 esp_err_t hub_root_start(void);
 
@@ -112,7 +121,9 @@ esp_err_t hub_root_start(void);
  *
  * This will power OFF the root port
  *
- * @return esp_err_t
+ * @return
+ *    - ESP_OK: Hub driver started successfully
+ *    - ESP_ERR_INVALID_STATE: Hub driver is not installed, or root port is in not powered state
  */
 esp_err_t hub_root_stop(void);
 
@@ -126,8 +137,12 @@ esp_err_t hub_root_stop(void);
  * @param[in] parent_dev_hdl
  * @param[in] parent_port_num
  * @param[in] dev_uid Device's unique ID
+ *
  * @return
- *     - ESP_OK: Success
+ *    - 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_t hub_port_recycle(usb_device_handle_t parent_dev_hdl, uint8_t parent_port_num, unsigned int dev_uid);
 
@@ -138,8 +153,12 @@ esp_err_t hub_port_recycle(usb_device_handle_t parent_dev_hdl, uint8_t parent_po
  *
  * @param[in] parent_dev_hdl
  * @param[in] parent_port_num
+ *
  * @return
- *     - ESP_OK: Success
+ *    - ESP_OK: 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_t hub_port_reset(usb_device_handle_t parent_dev_hdl, uint8_t parent_port_num);
 
@@ -150,8 +169,11 @@ esp_err_t hub_port_reset(usb_device_handle_t parent_dev_hdl, uint8_t parent_port
  *
  * @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)
+ *
  * @return
- *     - ESP_OK: Success
+ *    - ESP_OK: Port activated successfully
+ *    - ESP_ERR_NOT_SUPPORTED: Activating External Port is not available (External Hub support disabled),
+ *      or ext hub port error
  */
 esp_err_t hub_port_active(usb_device_handle_t parent_dev_hdl, uint8_t parent_port_num);
 
@@ -162,10 +184,11 @@ esp_err_t hub_port_active(usb_device_handle_t parent_dev_hdl, uint8_t parent_por
  *
  * @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)
+ *
  * @return
- * @retval ESP_OK:                  Port has been disabled without error
+ *    - ESP_OK:                  Port has been disabled without error
- * @retval ESP_ERR_INVALID_STATE:   Port can't be disabled in current state
+ *    - ESP_ERR_INVALID_STATE:   Port can't be disabled in current state
- * @retval ESP_ERR_NOT_SUPPORTED:   This function is not support by the selected port
+ *    - ESP_ERR_NOT_SUPPORTED:   This function is not support by the selected port
  */
 esp_err_t hub_port_disable(usb_device_handle_t parent_dev_hdl, uint8_t parent_port_num);
 
@@ -176,8 +199,10 @@ esp_err_t hub_port_disable(usb_device_handle_t parent_dev_hdl, uint8_t parent_po
  * If device is has a HUB class, then it will be added as External Hub to Hub Driver.
  *
  * @param[in] dev_addr  Device bus address
+ *
  * @return
- *     - ESP_OK: Success
+ *    - ESP_OK: New device added successfully
+ *    - ESP_ERR_INVALID_STATE: Hub driver is not in a correct state
  */
 esp_err_t hub_notify_new_dev(uint8_t dev_addr);
 
@@ -187,8 +212,10 @@ esp_err_t hub_notify_new_dev(uint8_t dev_addr);
  * If the device was an External Hub, then it will be removed from the Hub Driver.
  *
  * @param[in] dev_addr  Device bus address
+ *
  * @return
- *     - ESP_OK: Success
+ *    - ESP_OK: A device removed successfully
+ *    - ESP_ERR_INVALID_STATE: Hub driver is not in a correct state
  */
 esp_err_t hub_notify_dev_gone(uint8_t dev_addr);
 
@@ -196,7 +223,8 @@ esp_err_t hub_notify_dev_gone(uint8_t dev_addr);
  * @brief Notify Hub driver that all devices should be freed
  *
  * @return
- *     - ESP_OK: Success
+ *    - ESP_OK: All the devices can be freed
+ *    - ESP_ERR_INVALID_STATE: Hub driver is not in a correct state
  */
 esp_err_t hub_notify_all_free(void);
 #endif // ENABLE_USB_HUBS
@@ -207,7 +235,8 @@ esp_err_t hub_notify_all_free(void);
  * Hub driver handling function that must be called repeatedly to process the Hub driver's events. If blocking, the
  * caller can block on the notification callback of source USB_PROC_REQ_SOURCE_HUB to run this function.
  *
- * @return esp_err_t
+ * @return
+ *    - ESP_OK: All events handled
  */
 esp_err_t hub_process(void);
 

components/usb/private_include/usb_private.h

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2015-2023 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2015-2024 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -78,16 +78,18 @@ typedef bool (*usb_proc_req_cb_t)(usb_proc_req_source_t source, bool in_isr, voi
  * - The constant fields of the URB are also set
  * - The data_buffer field of the URB is set to point to start of the allocated data buffer.
  *
- * @param data_buffer_size Size of the URB's data buffer
+ * @param[in] data_buffer_size Size of the URB's data buffer
- * @param num_isoc_packets Number of isochronous packet descriptors
+ * @param[in] num_isoc_packets Number of isochronous packet descriptors
- * @return urb_t* URB object
+ *
+ * @return
+ *    - urb_t* URB object
  */
 urb_t *urb_alloc(size_t data_buffer_size, int num_isoc_packets);
 
 /**
  * @brief Free a URB
  *
- * @param urb URB object
+ * @param[in] urb URB object
  */
 void urb_free(urb_t *urb);
 

components/usb/private_include/usbh.h

@@ -153,8 +153,13 @@ typedef struct {
  *
  * @note Before calling this function, the Host Controller must already be un-clock gated and reset. The USB PHY
  *       (internal or external, and associated GPIOs) must already be configured.
- * @param usbh_config USBH driver configuration
+ * @param[in] usbh_config USBH driver configuration
- * @return esp_err_t
+ *
+ * @return
+ *    - ESP_OK: USBH driver installed successfully
+ *    - ESP_ERR_INVALID_ARG: Invalid argument
+ *    - ESP_ERR_INVALID_STATE: USBH driver is already installed
+ *    - ESP_ERR_NO_MEM: Insufficient memory
  */
 esp_err_t usbh_install(const usbh_config_t *usbh_config);
 
@@ -166,7 +171,10 @@ esp_err_t usbh_install(const usbh_config_t *usbh_config);
  *
  * @note This function will simply free the resources used by the USBH. The underlying Host Controller and USB PHY will
  *       not be disabled.
- * @return esp_err_t
+ *
+ * @return
+ *    - ESP_OK: USBH driver uninstalled successfully
+ *    - ESP_ERR_INVALID_STATE: USBH driver is not installed, or has unfinished actions
  */
 esp_err_t usbh_uninstall(void);
 
@@ -178,7 +186,10 @@ esp_err_t usbh_uninstall(void);
  *   source. The USB_PROC_REQ_SOURCE_USBH source indicates that this function should be called.
  *
  * @note This function can block
- * @return esp_err_t
+ *
+ * @return
+ *    - ESP_OK: All devices with pending events have been handled
+ *    - ESP_ERR_INVALID_STATE: USBH driver is not installed
  */
 esp_err_t usbh_process(void);
 
@@ -189,7 +200,10 @@ esp_err_t usbh_process(void);
  *
  * @note This function can block
  * @param[out] num_devs_ret Current number of devices
- * @return esp_err_t
+ *
+ * @return
+ *    - ESP_OK: Number of devices obtained successfully
+ *    - ESP_ERR_INVALID_ARG: Invalid argument
  */
 esp_err_t usbh_devs_num(int *num_devs_ret);
 
@@ -204,7 +218,10 @@ esp_err_t usbh_devs_num(int *num_devs_ret);
  * @param[in] list_len Length of empty list
  * @param[inout] dev_addr_list Empty list to be filled
  * @param[out] num_dev_ret Number of devices filled into list
- * @return esp_err_t
+ *
+ * @return
+ *    - ESP_OK: Address list filled successfully
+ *    - ESP_ERR_INVALID_ARG: Invalid argument
  */
 esp_err_t usbh_devs_addr_list_fill(int list_len, uint8_t *dev_addr_list, int *num_dev_ret);
 
@@ -220,7 +237,12 @@ esp_err_t usbh_devs_addr_list_fill(int list_len, uint8_t *dev_addr_list, int *nu
  * usbh_dev_set_...() functions.
  *
  * @param[in] params   Device parameters, using for device creation
- * @return esp_err_t
+ *
+ * @return
+ *    - ESP_OK: Device added to the device pool successfully
+ *    - ESP_ERR_INVALID_ARG: Invalid argument
+ *    - ESP_ERR_NO_MEM: Insufficient memory
+ *    - ESP_ERR_NOT_FINISHED: Adding a device to the device pool not finished
  */
 esp_err_t usbh_devs_add(usbh_dev_params_t *params);
 
@@ -228,7 +250,10 @@ esp_err_t usbh_devs_add(usbh_dev_params_t *params);
  * @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
+ *
+ * @return
+ *    - ESP_OK: Device removed successfully
+ *    - ESP_ERR_NOT_FOUND: Device with provided uid not found
  */
 esp_err_t usbh_devs_remove(unsigned int uid);
 
@@ -239,8 +264,11 @@ esp_err_t usbh_devs_remove(unsigned int uid);
  *
  * @param[in] uid               Unique ID assigned to the device
  * @param[out] parent_info      Parent device handle
- * @param[out] port_num         Parent port number
+ *
- * @return esp_err_t
+ * @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);
 
@@ -262,7 +290,13 @@ esp_err_t usbh_devs_mark_all_free(void);
  *
  * @param[in] dev_addr Device address
  * @param[out] dev_hdl Device handle
- * @return esp_err_t
+ *
+ * @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 address not found
  */
 esp_err_t usbh_devs_open(uint8_t dev_addr, usb_device_handle_t *dev_hdl);
 
@@ -272,7 +306,10 @@ esp_err_t usbh_devs_open(uint8_t dev_addr, usb_device_handle_t *dev_hdl);
  * This is typically called after a device has been fully enumerated.
  *
  * @param[in] dev_hdl Device handle
- * @return esp_err_t
+ *
+ * @return
+ *    - ESP_OK: USBH_EVENT_NEW_DEV triggered successfully
+ *    - ESP_ERR_INVALID_STATE: Device is not in configured state
  */
 esp_err_t usbh_devs_new_dev_event(usb_device_handle_t dev_hdl);
 
@@ -282,9 +319,13 @@ esp_err_t usbh_devs_new_dev_event(usb_device_handle_t dev_hdl);
  * @brief Close a device
  *
  * @note Callers of this function must have opened the device via usbh_devs_open()
- * *
+ *
  * @param[in] dev_hdl Device handle
- * @return esp_err_t
+ *
+ * @return
+ *    - ESP_OK: Device closed successfully
+ *    - ESP_ERR_INVALID_ARG: Invalid argument
+ *    - ESP_ERR_NOT_ALLOWED: It is not allowed to close the device, it is locked for the enumeration
  */
 esp_err_t usbh_dev_close(usb_device_handle_t dev_hdl);
 
@@ -296,7 +337,10 @@ esp_err_t usbh_dev_close(usb_device_handle_t dev_hdl);
  *
  * @param[in] dev_hdl Device handle
  * @param[out] dev_addr Device's address
- * @return esp_err_t
+ *
+ * @return
+ *    - ESP_OK: Device's address obtained successfully
+ *    - ESP_ERR_INVALID_ARG: Invalid argument
  */
 esp_err_t usbh_dev_get_addr(usb_device_handle_t dev_hdl, uint8_t *dev_addr);
 
@@ -304,12 +348,14 @@ esp_err_t usbh_dev_get_addr(usb_device_handle_t dev_hdl, uint8_t *dev_addr);
  * @brief Get a device's information
  *
  * @note Callers of this function must have opened the device via usbh_devs_open()
- * @note It is possible that the device has not been enumerated yet, thus some
+ * @note It is possible that the device has not been enumerated yet, thus some fields may be NULL.
- * fields may be NULL.
  *
  * @param[in] dev_hdl Device handle
  * @param[out] dev_info Device information
- * @return esp_err_t
+ *
+ * @return
+ *    - ESP_OK: Device's information obtained successfully
+ *    - ESP_ERR_INVALID_ARG: Invalid argument
  */
 esp_err_t usbh_dev_get_info(usb_device_handle_t dev_hdl, usb_device_info_t *dev_info);
 
@@ -318,11 +364,14 @@ 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
+ * @note It is possible that the device has not been enumerated yet, thus the device descriptor could be NULL.
- * device descriptor could be NULL.
+ *
  * @param[in] dev_hdl Device handle
  * @param[out] dev_desc_ret Device descriptor
- * @return esp_err_t
+ *
+ * @return
+ *    - ESP_OK: Device's device descriptor obtained successfully
+ *    - ESP_ERR_INVALID_ARG: Invalid argument
  */
 esp_err_t usbh_dev_get_desc(usb_device_handle_t dev_hdl, const usb_device_desc_t **dev_desc_ret);
 
@@ -332,11 +381,14 @@ esp_err_t usbh_dev_get_desc(usb_device_handle_t dev_hdl, const usb_device_desc_t
  * @note Callers of this function must have opened the device via usbh_devs_open()
  * Simply returns a reference to the internally cached configuration descriptor
  *
- * @note It is possible that the device has not been enumerated yet, thus the
+ * @note It is possible that the device has not been enumerated yet, thus the configuration descriptor could be NULL.
- * configuration descriptor could be NULL.
+ *
  * @param[in] dev_hdl Device handle
- * @param config_desc_ret
+ * @param[out] config_desc_ret
- * @return esp_err_t
+ *
+ * @return
+ *    - ESP_OK: Device's active configuration descriptor obtained successfully
+ *    - ESP_ERR_INVALID_ARG: Invalid argument
  */
 esp_err_t usbh_dev_get_config_desc(usb_device_handle_t dev_hdl, const usb_config_desc_t **config_desc_ret);
 
@@ -353,7 +405,11 @@ esp_err_t usbh_dev_get_config_desc(usb_device_handle_t dev_hdl, const usb_config
  * when locking the device for enumeration.
  *
  * @param[in] dev_hdl Device handle
- * @return esp_err_t
+ *
+ * @return
+ *    - ESP_OK: Device is locked for enumeration successfully
+ *    - ESP_ERR_INVALID_ARG: Invalid argument
+ *    - ESP_ERR_INVALID_STATE: Device is in an invalid state and can't be locked for enumeration
  */
 esp_err_t usbh_dev_enum_lock(usb_device_handle_t dev_hdl);
 
@@ -363,7 +419,11 @@ esp_err_t usbh_dev_enum_lock(usb_device_handle_t dev_hdl);
  * @note Callers of this function must have opened the device via usbh_devs_open()
  *
  * @param[in] dev_hdl Device handle
- * @return esp_err_t
+ *
+ * @return
+ *    - ESP_OK: Device enumeration lock released successfully
+ *    - ESP_ERR_INVALID_ARG: Invalid argument
+ *    - ESP_ERR_INVALID_STATE: Device is in an invalid state and enumeration lock can't be released
  */
 esp_err_t usbh_dev_enum_unlock(usb_device_handle_t dev_hdl);
 
@@ -380,7 +440,13 @@ esp_err_t usbh_dev_enum_unlock(usb_device_handle_t dev_hdl);
  *
  * @param[in] dev_hdl Device handle
  * @param[in] wMaxPacketSize Maximum packet size
- * @return esp_err_t
+ *
+ * @return
+ *    - ESP_OK: EP0 MPS set successfully
+ *    - ESP_ERR_INVALID_ARG: Invalid argument
+ *    - ESP_ERR_INVALID_STATE: Device's EP0 MPS can only be updated when in the default state,
+ *      pipe is non in a condition to be updated
+ *    - ESP_ERR_NOT_ALLOWED: Device's enum_lock must be set before enumeration related data fields can be set
  */
 esp_err_t usbh_dev_set_ep0_mps(usb_device_handle_t dev_hdl, uint16_t wMaxPacketSize);
 
@@ -396,14 +462,20 @@ esp_err_t usbh_dev_set_ep0_mps(usb_device_handle_t dev_hdl, uint16_t wMaxPacketS
  * (see 'usbh_dev_enum_lock()')
  * @param[in] dev_hdl Device handle
  * @param[in] dev_addr Device address to set
- * @return esp_err_t
+ *
+ * @return
+ *    - ESP_OK: Device's address set successfully
+ *    - ESP_ERR_INVALID_ARG: Invalid argument
+ *    - ESP_ERR_INVALID_STATE: Device's EP0 MPS can only be updated when in the default state,
+ *      pipe is not in a condition to be updated
+ *    - ESP_ERR_NOT_ALLOWED: Device's enum_lock must be set before enumeration related data fields can be set
  */
 esp_err_t usbh_dev_set_addr(usb_device_handle_t dev_hdl, uint8_t dev_addr);
 
 /**
- * @brief Set a device's descriptor
+ * @brief Set a device's device descriptor
  *
- * Typically called during enumeration after obtaining the device's descriptor
+ * Typically called during enumeration after obtaining the device's device descriptor
  * via a GET_DESCRIPTOR request.
  *
  * @note Callers of this function must have opened the device via usbh_devs_open()
@@ -413,7 +485,13 @@ esp_err_t usbh_dev_set_addr(usb_device_handle_t dev_hdl, uint8_t dev_addr);
  *
  * @param[in] dev_hdl Device handle
  * @param[in] device_desc Device descriptor to copy
- * @return esp_err_t
+ *
+ * @return
+ *    - ESP_OK: Device's device descriptor set successfully
+ *    - ESP_ERR_INVALID_ARG: Invalid argument
+ *    - ESP_ERR_NO_MEM: Insufficient memory
+ *    - ESP_ERR_INVALID_STATE: Device's device descriptor can only be set in the default or addressed state
+ *    - ESP_ERR_NOT_ALLOWED: Device's enum_lock must be set before we can set its device descriptor
  */
 esp_err_t usbh_dev_set_desc(usb_device_handle_t dev_hdl, const usb_device_desc_t *device_desc);
 
@@ -430,7 +508,13 @@ esp_err_t usbh_dev_set_desc(usb_device_handle_t dev_hdl, const usb_device_desc_t
  *
  * @param[in] dev_hdl Device handle
  * @param[in] config_desc_full Configuration descriptor to copy
- * @return esp_err_t
+ *
+ * @return
+ *    - ESP_OK: Device's configuration descriptor set successfully
+ *    - ESP_ERR_INVALID_ARG: Invalid argument
+ *    - ESP_ERR_NO_MEM: Insufficient memory
+ *    - ESP_ERR_INVALID_STATE: Device's config descriptor can only be set when in the addressed state
+ *    - ESP_ERR_NOT_ALLOWED: Device's enum_lock must be set before we can set its config descriptor
  */
 esp_err_t usbh_dev_set_config_desc(usb_device_handle_t dev_hdl, const usb_config_desc_t *config_desc_full);
 
@@ -449,7 +533,13 @@ esp_err_t usbh_dev_set_config_desc(usb_device_handle_t dev_hdl, const usb_config
  * @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
+ *
+ * @return
+ *    - ESP_OK: Device's string descriptor set successfully
+ *    - ESP_ERR_INVALID_ARG: Invalid argument
+ *    - ESP_ERR_NO_MEM: Insufficient memory
+ *    - ESP_ERR_INVALID_STATE: Device's string descriptors can only be set when in the default state
+ *    - ESP_ERR_NOT_ALLOWED: Device's enum_lock must be set before we can set its string descriptors
  */
 esp_err_t usbh_dev_set_str_desc(usb_device_handle_t dev_hdl, const usb_str_desc_t *str_desc, int select);
 
@@ -472,7 +562,14 @@ esp_err_t usbh_dev_set_str_desc(usb_device_handle_t dev_hdl, const usb_str_desc_
  * @param[in] dev_hdl Device handle
  * @param[in] ep_config Endpoint configuration
  * @param[out] ep_hdl_ret Endpoint handle
- * @return esp_err_t
+ *
+ * @return
+ *    - ESP_OK: Endpoint allocated successfully
+ *    - ESP_ERR_INVALID_ARG: Invalid argument
+ *    - ESP_ERR_NO_MEM: Insufficient memory
+ *    - ESP_ERR_NOT_FOUND: Endpoint with this address has not been found in device's configuration descriptor
+ *    - ESP_ERR_INVALID_STATE: USBH is not in a correct state to allocate an endpoint
+ *    - ESP_ERR_NOT_SUPPORTED: The pipe's configuration cannot be supported
  */
 esp_err_t usbh_ep_alloc(usb_device_handle_t dev_hdl, usbh_ep_config_t *ep_config, usbh_ep_handle_t *ep_hdl_ret);
 
@@ -487,7 +584,12 @@ esp_err_t usbh_ep_alloc(usb_device_handle_t dev_hdl, usbh_ep_config_t *ep_config
  *
  * @note This function can block
  * @param[in] ep_hdl Endpoint handle
- * @return esp_err_t
+ *
+ * @return
+ *    - ESP_OK: Endpoint freed successfully
+ *    - ESP_ERR_INVALID_ARG: Invalid argument
+ *    - ESP_ERR_INVALID_STATE: Endpoint's underlying pipe has an in-flight URB
+ *    - ESP_ERR_NOT_FOUND: Endpoint with this address has not been allocated on the device
  */
 esp_err_t usbh_ep_free(usbh_ep_handle_t ep_hdl);
 
@@ -499,7 +601,11 @@ esp_err_t usbh_ep_free(usbh_ep_handle_t ep_hdl);
  * @param[in] dev_hdl Device handle
  * @param[in] bEndpointAddress Endpoint address
  * @param[out] ep_hdl_ret Endpoint handle
- * @return esp_err_t
+ *
+ * @return
+ *    - ESP_OK: Endpoint handle obtained successfully
+ *    - ESP_ERR_INVALID_ARG: Invalid argument
+ *    - ESP_ERR_NOT_FOUND: Endpoint with this address has not been allocated on the device
  */
 esp_err_t usbh_ep_get_handle(usb_device_handle_t dev_hdl, uint8_t bEndpointAddress, usbh_ep_handle_t *ep_hdl_ret);
 
@@ -510,7 +616,11 @@ esp_err_t usbh_ep_get_handle(usb_device_handle_t dev_hdl, uint8_t bEndpointAddre
  *
  * @param[in] ep_hdl Endpoint handle
  * @param[in] command Endpoint command
- * @return esp_err_t
+ *
+ * @return
+ *    - ESP_OK: Command executed successfully on an endpoint
+ *    - ESP_ERR_INVALID_ARG: Invalid argument
+ *    - ESP_ERR_INVALID_STATE: The pipe is not in the correct state/condition too execute the command
  */
 esp_err_t usbh_ep_command(usbh_ep_handle_t ep_hdl, usbh_ep_cmd_t command);
 
@@ -521,7 +631,9 @@ esp_err_t usbh_ep_command(usbh_ep_handle_t ep_hdl, usbh_ep_cmd_t command);
  *
  * @note This function can block
  * @param[in] ep_hdl Endpoint handle
- * @return Endpoint context
+ *
+ * @return
+ *    - Endpoint context
  */
 void *usbh_ep_get_context(usbh_ep_handle_t ep_hdl);
 
@@ -532,7 +644,11 @@ void *usbh_ep_get_context(usbh_ep_handle_t ep_hdl);
  *
  * @param[in] dev_hdl Device handle
  * @param[in] urb URB
- * @return esp_err_t
+ *
+ * @return
+ *    - ESP_OK: Control transfer submitted successfully
+ *    - ESP_ERR_INVALID_ARG: Invalid argument
+ *    - ESP_ERR_INVALID_STATE: The pipe is not in an active state or an URB can't be enqueued
  */
 esp_err_t usbh_dev_submit_ctrl_urb(usb_device_handle_t dev_hdl, urb_t *urb);
 
@@ -544,7 +660,11 @@ esp_err_t usbh_dev_submit_ctrl_urb(usb_device_handle_t dev_hdl, urb_t *urb);
  *
  * @param[in] ep_hdl Endpoint handle
  * @param[in] urb URB to enqueue
- * @return esp_err_t
+ *
+ * @return
+ *    - ESP_OK: URB enqueued successfully
+ *    - ESP_ERR_INVALID_ARG: Invalid argument
+ *    - ESP_ERR_INVALID_STATE: The pipe is not in an active state or an URB can't be enqueued
  */
 esp_err_t usbh_ep_enqueue_urb(usbh_ep_handle_t ep_hdl, urb_t *urb);
 
@@ -555,7 +675,10 @@ esp_err_t usbh_ep_enqueue_urb(usbh_ep_handle_t ep_hdl, urb_t *urb);
  *
  * @param[in] ep_hdl Endpoint handle
  * @param[out] urb_ret Dequeued URB, or NULL if no more URBs to dequeue
- * @return esp_err_t
+ *
+ * @return
+ *    - ESP_OK: URB dequeued successfully
+ *    - ESP_ERR_INVALID_ARG: Invalid argument
  */
 esp_err_t usbh_ep_dequeue_urb(usbh_ep_handle_t ep_hdl, urb_t **urb_ret);
 

components/usb/usb_host.c

@@ -477,6 +477,7 @@ esp_err_t usb_host_install(const usb_host_config_t *config)
         };
         ret = usb_new_phy(&phy_config, &host_lib_obj->constant.phy_handle);
         if (ret != ESP_OK) {
+            ESP_LOGE(USB_HOST_TAG, "PHY install error: %s", esp_err_to_name(ret));
             goto phy_err;
         }
     }
@@ -487,6 +488,7 @@ esp_err_t usb_host_install(const usb_host_config_t *config)
     };
     ret = hcd_install(&hcd_config);
     if (ret != ESP_OK) {
+        ESP_LOGE(USB_HOST_TAG, "HCD install error: %s", esp_err_to_name(ret));
         goto hcd_err;
     }
 
@@ -499,6 +501,7 @@ esp_err_t usb_host_install(const usb_host_config_t *config)
     };
     ret = usbh_install(&usbh_config);
     if (ret != ESP_OK) {
+        ESP_LOGE(USB_HOST_TAG, "USBH install error: %s", esp_err_to_name(ret));
         goto usbh_err;
     }
 
@@ -515,6 +518,7 @@ esp_err_t usb_host_install(const usb_host_config_t *config)
     };
     ret = enum_install(&enum_config, &host_lib_obj->constant.enum_client);
     if (ret != ESP_OK) {
+        ESP_LOGE(USB_HOST_TAG, "Enum. driver install error: %s", esp_err_to_name(ret));
         goto enum_err;
     }
 
@@ -527,6 +531,7 @@ esp_err_t usb_host_install(const usb_host_config_t *config)
     };
     ret = hub_install(&hub_config, &host_lib_obj->constant.hub_client);
     if (ret != ESP_OK) {
+        ESP_LOGE(USB_HOST_TAG, "Hub driver Install error: %s", esp_err_to_name(ret));
         goto hub_err;
     }
 
@@ -937,6 +942,7 @@ esp_err_t usb_host_device_open(usb_host_client_handle_t client_hdl, uint8_t dev_
     usb_device_handle_t dev_hdl;
     ret = usbh_devs_open(dev_addr, &dev_hdl);
     if (ret != ESP_OK) {
+        ESP_LOGE(USB_HOST_TAG, "usbh_devs_open error: %s", esp_err_to_name(ret));
         goto exit;
     }
 
@@ -1012,10 +1018,16 @@ esp_err_t usb_host_device_free_all(void)
     HOST_EXIT_CRITICAL();
     esp_err_t ret;
 #if ENABLE_USB_HUBS
-    hub_notify_all_free();
+    ret = hub_notify_all_free();
+    if (ret != ESP_OK) {
+        ESP_LOGE(USB_HOST_TAG, "Marking all devices as free in HUB error: %s", esp_err_to_name(ret));
+    }
 #endif // ENABLE_USB_HUBS
     ret = usbh_devs_mark_all_free();
     // If ESP_ERR_NOT_FINISHED is returned, caller must wait for USB_HOST_LIB_EVENT_FLAGS_ALL_FREE to confirm all devices are free
+    if (ret != ESP_OK) {
+        ESP_LOGE(USB_HOST_TAG, "Marking all devices as free in USBH error: %s", esp_err_to_name(ret));
+    }
     return ret;
 }
 
@@ -1078,7 +1090,7 @@ static esp_err_t get_config_desc_transfer(usb_host_client_handle_t client_hdl, u
     // Submit control transfer
     esp_err_t ret = usb_host_transfer_submit_control(client_hdl, ctrl_transfer);
     if (ret != ESP_OK) {
-        ESP_LOGE(USB_HOST_TAG, "Submit ctrl transfer failed");
+        ESP_LOGE(USB_HOST_TAG, "Submit ctrl transfer failed %s", esp_err_to_name(ret));
         return ret;
     }
 
@@ -1138,6 +1150,7 @@ esp_err_t usb_host_get_config_desc(usb_host_client_handle_t client_hdl, usb_devi
     // Initiate control transfer for short config descriptor
     ret = get_config_desc_transfer(client_hdl, ctrl_transfer, bConfigurationValue, SHORT_DESC_REQ_LEN);
     if (ret != ESP_OK) {
+        ESP_LOGE(USB_HOST_TAG, "Get short config desc. failed %s", esp_err_to_name(ret));
         goto exit;
     }
 
@@ -1147,6 +1160,7 @@ esp_err_t usb_host_get_config_desc(usb_host_client_handle_t client_hdl, usb_devi
     // Initiate control transfer for full config descriptor
     ret = get_config_desc_transfer(client_hdl, ctrl_transfer, bConfigurationValue, config_desc_short->wTotalLength);
     if (ret != ESP_OK) {
+        ESP_LOGE(USB_HOST_TAG, "Get full config desc. failed %s", esp_err_to_name(ret));
         goto exit;
     }
 
@@ -1202,6 +1216,7 @@ static esp_err_t ep_wrapper_alloc(usb_device_handle_t dev_hdl, const usb_ep_desc
     };
     ret = usbh_ep_alloc(dev_hdl, &ep_config, &ep_hdl);
     if (ret != ESP_OK) {
+        ESP_LOGE(USB_HOST_TAG, "EP allocation error %s", esp_err_to_name(ret));
         goto alloc_err;
     }
     // Initialize endpoint wrapper item
@@ -1259,6 +1274,7 @@ static esp_err_t interface_claim(client_t *client_obj, usb_device_handle_t dev_h
     int offset_intf;
     const usb_intf_desc_t *intf_desc = usb_parse_interface_descriptor(config_desc, bInterfaceNumber, bAlternateSetting, &offset_intf);
     if (intf_desc == NULL) {
+        ESP_LOGE(USB_HOST_TAG, "Interface %d not found in config. desc.", bInterfaceNumber);
         ret = ESP_ERR_NOT_FOUND;
         goto exit;
     }
@@ -1273,6 +1289,7 @@ static esp_err_t interface_claim(client_t *client_obj, usb_device_handle_t dev_h
         int offset_ep = offset_intf;
         const usb_ep_desc_t *ep_desc = usb_parse_endpoint_descriptor_by_index(intf_desc, i, config_desc->wTotalLength, &offset_ep);
         if (ep_desc == NULL) {
+            ESP_LOGE(USB_HOST_TAG, "EP desc. %d not found in Interface desc.", bInterfaceNumber);
             ret = ESP_ERR_NOT_FOUND;
             goto ep_alloc_err;
         }
@@ -1387,6 +1404,7 @@ esp_err_t usb_host_interface_claim(usb_host_client_handle_t client_hdl, usb_devi
     // Claim interface
     ret = interface_claim(client_obj, dev_hdl, config_desc, bInterfaceNumber, bAlternateSetting, &intf_obj);
     if (ret != ESP_OK) {
+        ESP_LOGE(USB_HOST_TAG, "Claiming interface error: %s", esp_err_to_name(ret));
         goto exit;
     }
     ret = ESP_OK;
@@ -1430,6 +1448,18 @@ esp_err_t usb_host_interface_release(usb_host_client_handle_t client_hdl, usb_de
     return ret;
 }
 
+/* Just print error returned from usbh_ep_get_handle() */
+static void print_error_ep_get_handle(esp_err_t err)
+{
+    ESP_LOGE(USB_HOST_TAG, "Get EP handle error: %s", esp_err_to_name(err));
+}
+
+/* Just print error returned from usbh_ep_command() */
+static void print_error_ep_command(esp_err_t err)
+{
+    ESP_LOGE(USB_HOST_TAG, "EP command error: %s", esp_err_to_name(err));
+}
+
 esp_err_t usb_host_endpoint_halt(usb_device_handle_t dev_hdl, uint8_t bEndpointAddress)
 {
     esp_err_t ret;
@@ -1437,9 +1467,13 @@ esp_err_t usb_host_endpoint_halt(usb_device_handle_t dev_hdl, uint8_t bEndpointA
 
     ret = usbh_ep_get_handle(dev_hdl, bEndpointAddress, &ep_hdl);
     if (ret != ESP_OK) {
+        print_error_ep_get_handle(ret);
         goto exit;
     }
     ret = usbh_ep_command(ep_hdl, USBH_EP_CMD_HALT);
+    if (ret != ESP_OK) {
+        print_error_ep_command(ret);
+    }
 
 exit:
     return ret;
@@ -1452,9 +1486,13 @@ esp_err_t usb_host_endpoint_flush(usb_device_handle_t dev_hdl, uint8_t bEndpoint
 
     ret = usbh_ep_get_handle(dev_hdl, bEndpointAddress, &ep_hdl);
     if (ret != ESP_OK) {
+        print_error_ep_get_handle(ret);
         goto exit;
     }
     ret = usbh_ep_command(ep_hdl, USBH_EP_CMD_FLUSH);
+    if (ret != ESP_OK) {
+        print_error_ep_command(ret);
+    }
 
 exit:
     return ret;
@@ -1467,9 +1505,13 @@ esp_err_t usb_host_endpoint_clear(usb_device_handle_t dev_hdl, uint8_t bEndpoint
 
     ret = usbh_ep_get_handle(dev_hdl, bEndpointAddress, &ep_hdl);
     if (ret != ESP_OK) {
+        print_error_ep_get_handle(ret);
         goto exit;
     }
     ret = usbh_ep_command(ep_hdl, USBH_EP_CMD_CLEAR);
+    if (ret != ESP_OK) {
+        print_error_ep_command(ret);
+    }
 
 exit:
     return ret;
@@ -1513,6 +1555,7 @@ esp_err_t usb_host_transfer_submit(usb_transfer_t *transfer)
 
     ret = usbh_ep_get_handle(transfer->device_handle, transfer->bEndpointAddress, &ep_hdl);
     if (ret != ESP_OK) {
+        print_error_ep_get_handle(ret);
         goto err;
     }
     ep_wrap = usbh_ep_get_context(ep_hdl);
@@ -1526,6 +1569,7 @@ esp_err_t usb_host_transfer_submit(usb_transfer_t *transfer)
 
     ret = usbh_ep_enqueue_urb(ep_hdl, urb_obj);
     if (ret != ESP_OK) {
+        ESP_LOGE(USB_HOST_TAG, "Enqueue URB error: %s", esp_err_to_name(ret));
         goto submit_err;
     }
     return ret;
@@ -1558,6 +1602,7 @@ esp_err_t usb_host_transfer_submit_control(usb_host_client_handle_t client_hdl,
     esp_err_t ret;
     ret = usbh_dev_submit_ctrl_urb(dev_hdl, urb_obj);
     if (ret != ESP_OK) {
+        ESP_LOGE(USB_HOST_TAG, "Submit CTRL URB error: %s", esp_err_to_name(ret));
         urb_obj->usb_host_inflight = false;
     }
     return ret;

components/usb/usbh.c

@@ -383,6 +383,7 @@ static esp_err_t device_alloc(usbh_dev_params_t *params, device_t **dev_obj_ret)
     hcd_pipe_handle_t default_pipe_hdl;
     ret = hcd_pipe_alloc(params->root_port_hdl, &pipe_config, &default_pipe_hdl);
     if (ret != ESP_OK) {
+        ESP_LOGE(USBH_TAG, "HCD Pipe alloc error: %s", esp_err_to_name(ret));
         goto err;
     }
     // Initialize device object
@@ -842,7 +843,7 @@ esp_err_t usbh_devs_addr_list_fill(int list_len, uint8_t *dev_addr_list, int *nu
 
 esp_err_t usbh_devs_add(usbh_dev_params_t *params)
 {
-    USBH_CHECK(params != NULL, ESP_ERR_NOT_ALLOWED);
+    USBH_CHECK(params != NULL, ESP_ERR_INVALID_ARG);
     USBH_CHECK(params->root_port_hdl != NULL, ESP_ERR_INVALID_ARG);
     esp_err_t ret;
     device_t *dev_obj;
@@ -1401,6 +1402,7 @@ esp_err_t usbh_ep_alloc(usb_device_handle_t dev_hdl, usbh_ep_config_t *ep_config
     // Allocate the endpoint object
     ret = endpoint_alloc(dev_obj, ep_desc, ep_config, &ep_obj);
     if (ret != ESP_OK) {
+        ESP_LOGE(USBH_TAG, "EP Alloc error: %s", esp_err_to_name(ret));
         goto alloc_err;
     }
 
@@ -1411,6 +1413,7 @@ esp_err_t usbh_ep_alloc(usb_device_handle_t dev_hdl, usbh_ep_config_t *ep_config
     if (dev_obj->dynamic.state != USB_DEVICE_STATE_CONFIGURED) {
         USBH_EXIT_CRITICAL();
         ret = ESP_ERR_INVALID_STATE;
+        ESP_LOGE(USBH_TAG, "USB Device must be in Configured state");
         goto dev_state_err;
     }
     USBH_EXIT_CRITICAL();
@@ -1423,6 +1426,7 @@ esp_err_t usbh_ep_alloc(usb_device_handle_t dev_hdl, usbh_ep_config_t *ep_config
     } else {
         // Endpoint is already allocated
         ret = ESP_ERR_INVALID_STATE;
+        ESP_LOGE(USBH_TAG, "EP with %d address already allocated", bEndpointAddress);
     }
 dev_state_err:
     xSemaphoreGive(p_usbh_obj->constant.mux_lock);
@@ -1531,6 +1535,7 @@ esp_err_t usbh_dev_submit_ctrl_urb(usb_device_handle_t dev_hdl, urb_t *urb)
 
     esp_err_t ret;
     if (hcd_pipe_get_state(dev_obj->constant.default_pipe) != HCD_PIPE_STATE_ACTIVE) {
+        ESP_LOGE(USBH_TAG, "HCD Pipe not in active state");
         ret = ESP_ERR_INVALID_STATE;
         goto hcd_err;
     }