refactor(usb_host): Fixed function return values in usb_host stack:

    - updated doxygen for the whole usb_host stack
    - doxygen for test_apps is not updated
    - fixed error codes propagation problems in the usb_host stack

Author: peter-marcisovsky

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

@@ -1185,12 +1185,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;
     }
 
@@ -1204,12 +1206,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 class_specific_cb Class specific descriptor callback. Can be NULL
+ * @param[in] cfg_desc Configuration descriptor
+ * @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);