Mirrors/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf.git synced 2026-10-02 11:10:54 +03: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-10-10 12:51:06 +02:00
committed by peter.marcisovsky
parent 8ba7c287b0
commit f02ee8ef5d
14 changed files with 674 additions and 213 deletions
Download Patch File Download Diff File Expand all files Collapse all files
components/usb/private_include/hub.h
+43 -14
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);