From f7b31defc9cee064ce1f3bee7576c98689417987 Mon Sep 17 00:00:00 2001 From: Peter Marcisovsky Date: Fri, 12 Jul 2024 13:32:18 +0200 Subject: [PATCH] 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 --- components/usb/enum.c | 4 +- components/usb/ext_hub.c | 4 + components/usb/hcd_dwc.c | 1 + components/usb/hub.c | 11 + components/usb/include/usb/usb_helpers.h | 12 +- components/usb/include/usb/usb_host.h | 190 +++++++++++++---- components/usb/private_include/enum.h | 32 ++- components/usb/private_include/ext_hub.h | 108 ++++++++-- components/usb/private_include/hcd.h | 189 ++++++++++------- components/usb/private_include/hub.h | 57 +++-- components/usb/private_include/usb_private.h | 12 +- components/usb/private_include/usbh.h | 211 +++++++++++++++---- components/usb/usb_host.c | 49 ++++- components/usb/usbh.c | 7 +- 14 files changed, 674 insertions(+), 213 deletions(-) diff --git a/components/usb/enum.c b/components/usb/enum.c index 29711ee9f1..ec18294c51 100644 --- a/components/usb/enum.c +++ b/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; diff --git a/components/usb/ext_hub.c b/components/usb/ext_hub.c index fe5692ba79..913efa4bac 100644 --- a/components/usb/ext_hub.c +++ b/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; } diff --git a/components/usb/hcd_dwc.c b/components/usb/hcd_dwc.c index 93a2408f4c..53fdb0a189 100644 --- a/components/usb/hcd_dwc.c +++ b/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(); diff --git a/components/usb/hub.c b/components/usb/hub.c index ee32bdefcb..c33a88e6bc 100644 --- a/components/usb/hub.c +++ b/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; diff --git a/components/usb/include/usb/usb_helpers.h b/components/usb/include/usb/usb_helpers.h index faf430de39..63810b830d 100644 --- a/components/usb/include/usb/usb_helpers.h +++ b/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); diff --git a/components/usb/include/usb/usb_host.h b/components/usb/include/usb/usb_host.h index b9a1c4dabb..37270c5348 100644 --- a/components/usb/include/usb/usb_host.h +++ b/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_OK: All devices already freed (i.e., there were no devices) + * - 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 bEndpointAddress Endpoint address - * @return esp_err_t + * @param[in] dev_hdl Device handle + * @param[in] bEndpointAddress Endpoint address + * + * @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 bEndpointAddress Endpoint address - * @return esp_err_t + * @param[in] dev_hdl Device handle + * @param[in] bEndpointAddress Endpoint address + * + * @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 bEndpointAddress Endpoint address - * @return esp_err_t + * @param[in] dev_hdl Device handle + * @param[in] bEndpointAddress Endpoint address + * + * @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); diff --git a/components/usb/private_include/enum.h b/components/usb/private_include/enum.h index 0dc44cff69..b1869f2398 100644 --- a/components/usb/private_include/enum.h +++ b/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); diff --git a/components/usb/private_include/ext_hub.h b/components/usb/private_include/ext_hub.h index 9fde880fe7..f613641158 100644 --- a/components/usb/private_include/ext_hub.h +++ b/components/usb/private_include/ext_hub.h @@ -70,7 +70,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); @@ -80,7 +84,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); @@ -91,7 +97,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); @@ -102,7 +110,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); @@ -113,7 +125,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); @@ -124,7 +139,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); @@ -134,8 +154,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 esp_err_t + * @return + * - ESP_OK: All devices freed + * - ESP_ERR_INVALID_STATE: External Hub driver is not installed */ esp_err_t ext_hub_all_free(void); @@ -145,7 +166,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); @@ -155,6 +180,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); @@ -168,7 +197,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); @@ -177,7 +212,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); @@ -186,7 +227,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); @@ -195,7 +242,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); @@ -205,7 +258,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); @@ -217,7 +276,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); @@ -227,7 +291,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); @@ -239,7 +308,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); diff --git a/components/usb/private_include/hcd.h b/components/usb/private_include/hcd.h index 1fd3617307..8d24e31683 100644 --- a/components/usb/private_include/hcd.h +++ b/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 - * @retval ESP_OK: HCD successfully installed - * @retval ESP_ERR_NO_MEM: Insufficient memory - * @retval ESP_ERR_INVALID_STATE: HCD is already installed - * @retval ESP_ERR_NOT_FOUND: HCD could not allocate interrupt - * @retval ESP_ERR_INVALID_ARG: Arguments are invalid + * @param[in] config HCD configuration + * + * @return + * - ESP_OK: HCD successfully installed + * - ESP_ERR_NO_MEM: Insufficient memory + * - 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 - * @retval ESP_ERR_INVALID_STATE: HCD is not in the right condition to be uninstalled + * @return + * - 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 - * @retval ESP_ERR_INVALID_STATE: The port is already enabled - * @retval ESP_ERR_NOT_FOUND: Port number not found - * @retval ESP_ERR_INVALID_ARG: Arguments are invalid + * + * @return + * - ESP_OK: Port enabled + * - ESP_ERR_NO_MEM: Insufficient memory + * - 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 - * @retval ESP_OK: Port disabled - * @retval ESP_ERR_INVALID_STATE: The port is not in a condition to be disabled (not unpowered) + * @param[in] port_hdl Port handle + * + * @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 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 - * @retval ESP_ERR_INVALID_RESPONSE: The command is no longer valid due to a change in the port's state + * @param[in] port_hdl Port handle + * @param[in] command Command for the HCD port + * + * @return + * - 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 - * @retval ESP_ERR_INVALID_ARG: Invalid arguments + * + * @return + * - 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 - * @return hcd_port_event_t The port event that was handled + * @param[in] port_hdl Port handle + * + * @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 - * @retval ESP_OK Port recovered successfully - * @retval ESP_ERR_INVALID_STATE Port is not in the HCD_PORT_STATE_RECOVERY state + * @param[in] port_hdl Port handle + * + * @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 - * @return void* Context variable + * @param[in] port_hdl Port handle + * + * @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 bias Fifo bias - * @retval ESP_OK FIFO sizing successfully set - * @retval ESP_ERR_INVALID_STATE Incorrect state for FIFO sizes to be set + * @param[in] port_hdl Port handle + * @param[in] bias Fifo bias + * + * @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 - * @retval ESP_ERR_NO_MEM: Insufficient memory - * @retval ESP_ERR_INVALID_ARG: Arguments are invalid - * @retval ESP_ERR_INVALID_STATE: Host port is not in the correct state to allocate a pipe - * @retval ESP_ERR_NOT_SUPPORTED: The pipe's configuration cannot be supported + * @return + * - ESP_OK: Pipe successfully allocated + * - ESP_ERR_NO_MEM: Insufficient memory + * - ESP_ERR_INVALID_ARG: Arguments are invalid + * - 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 - * @retval ESP_ERR_INVALID_STATE: Pipe is not in a condition to be freed + * @return + * - 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 mps New Maximum Packet Size + * @param[in] pipe_hdl Pipe handle + * @param[in] mps New Maximum Packet Size * - * @retval ESP_OK: Pipe successfully updated - * @retval ESP_ERR_INVALID_STATE: Pipe is not in a condition to be updated + * @return + * - 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 dev_addr New device address + * @param[in] pipe_hdl Pipe handle + * @param[in] dev_addr New device address * - * @retval ESP_OK: Pipe successfully updated - * @retval ESP_ERR_INVALID_STATE: Pipe is not in a condition to be updated + * @return + * - 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 - * @return void* Context variable + * @param[in] pipe_hdl Pipe handle + * + * @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 - * @return hcd_pipe_state_t Current state of the pipe + * @param[in] pipe_hdl Pipe handle + * + * @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 - * @return Number of in-flight URBs + * @param[in] pipe_hdl Pipe handle + * + * @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 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 + * @param[in] pipe_hdl Pipe handle + * @param[in] command Pipe 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 - * @return hcd_pipe_event_t Last pipe event to occur + * @param[in] pipe_hdl Pipe handle + * + * @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 urb URB to enqueue - * @retval ESP_OK: URB enqueued successfully - * @retval ESP_ERR_INVALID_STATE: Conditions not met to enqueue URB + * @param[in] pipe_hdl Pipe handle + * @param[in] urb URB to enqueue + * + * @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 - * @return urb_t* Dequeued URB, or NULL if no more URBs to dequeue + * @param[in] pipe_hdl Pipe handle + * + * @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 - * @retval ESP_OK: URB successfully aborted, or was not affected by this function - * @retval ESP_ERR_INVALID_STATE: URB was never enqueued + * @param[in] urb URB to abort + * + * @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); diff --git a/components/usb/private_include/hub.h b/components/usb/private_include/hub.h index 65bc98ff46..a580c45855 100644 --- a/components/usb/private_include/hub.h +++ b/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 - * @retval 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_OK: Port has been disabled without error + * - ESP_ERR_INVALID_STATE: Port can't be disabled in current state + * - 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); diff --git a/components/usb/private_include/usb_private.h b/components/usb/private_include/usb_private.h index 0a081d4e5c..71fb23db7e 100644 --- a/components/usb/private_include/usb_private.h +++ b/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 num_isoc_packets Number of isochronous packet descriptors - * @return urb_t* URB object + * @param[in] data_buffer_size Size of the URB's data buffer + * @param[in] num_isoc_packets Number of isochronous packet descriptors + * + * @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); diff --git a/components/usb/private_include/usbh.h b/components/usb/private_include/usbh.h index c4097ec107..7777acd6e2 100644 --- a/components/usb/private_include/usbh.h +++ b/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 - * @return esp_err_t + * @param[in] usbh_config USBH driver configuration + * + * @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); @@ -250,8 +278,8 @@ esp_err_t usbh_devs_get_parent_info(unsigned int uid, usb_parent_dev_info_t *par * A device marked as free will not be freed until the last client using the device has called usbh_devs_close() * * @return - * - ESP_OK: There were no devices to free to begin with. Current state is all free - * - ESP_ERR_NOT_FINISHED: One or more devices still need to be freed (but have been marked "to be freed") + * - ESP_OK: There were no devices to free to begin with. Current state is all free + * - ESP_ERR_NOT_FINISHED: One or more devices still need to be freed (but have been marked "to be freed") */ esp_err_t usbh_devs_mark_all_free(void); @@ -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 - * fields may be NULL. + * @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 + * + * @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 - * device descriptor could be NULL. + * @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 + * + * @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 - * configuration descriptor could be NULL. + * @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 + * @param[out] config_desc_ret + * + * @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); diff --git a/components/usb/usb_host.c b/components/usb/usb_host.c index 9d41be06af..13492aa3b4 100644 --- a/components/usb/usb_host.c +++ b/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; diff --git a/components/usb/usbh.c b/components/usb/usbh.c index 5d60bc543f..59dff2fe6a 100644 --- a/components/usb/usbh.c +++ b/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; }