alex/esp-idf
alex/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf.git synced 2024-09-19 14:26:01 -04:00
Code Issues Actions 3 Packages Projects Releases Wiki Activity

Merge branch 'refactor/usb_host_add_func_ret_values_description' into 'master'

Browse Source 
Refactor: USB Host add function return values description

Closes IDF-10455

See merge request espressif/esp-idf!32106
This commit is contained in:
Peter Marcisovsky 2024-09-05 15:20:04 +08:00
commit 0c388cf576
14 changed files with 674 additions and 213 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
components/usb/enum.c
View File

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

4
components/usb/ext_hub.c
View File

@ -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;
}

1
components/usb/hcd_dwc.c
View File

@ -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();

11
components/usb/hub.c
View File

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

12
components/usb/include/usb/usb_helpers.h
View File

@ -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);

188
components/usb/include/usb/usb_host.h
View File

@ -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 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);

32
components/usb/private_include/enum.h
View File

@ -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);

108
components/usb/private_include/ext_hub.h
View File

@ -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 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);
@ -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);

189
components/usb/private_include/hcd.h
View File

@ -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);

57
components/usb/private_include/hub.h
View File

@ -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);

12
components/usb/private_include/usb_private.h
View File

@ -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);

207
components/usb/private_include/usbh.h
View File

@ -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);
@ -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);

49
components/usb/usb_host.c
View File

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

7
components/usb/usbh.c
View File

@ -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;
}