alex/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf.git synced 2025-12-07 17:08:49 +00:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
- 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
This commit is contained in:
Peter Marcisovsky
2024-07-12 13:32:18 +02:00
parent 657d250d96
commit 07dc67c640
14 changed files with 674 additions and 213 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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