From c14eae95cd664fd89c66029a721d385ba00c6cd8 Mon Sep 17 00:00:00 2001 From: Darian Leung Date: Fri, 29 Mar 2024 21:29:01 +0800 Subject: [PATCH 1/6] refactor(usb/host): Refactor USBH function grouping This commit rearranges the USBH functions into new groupings to provide a clearer abstraction. This is in preparation for refactoring/removing the Hub related functions in the USBH API. This commit DOES NOT MAKE ANY BEHAVIORAL CHANGES to the code. Functions are now grouped into... - USBH Processing: Functions dealing with overall USBH processing - Device Pool: Functions that add/remove/open/close devices from the internal device pool - Device: Functions that pertain to setting/getting a particular device - Endpoints: Functions that pertain to a particular endpoint - Transfer: Functions that pertain to sending transfers --- components/usb/private_include/usbh.h | 96 +++++++------ components/usb/usbh.c | 196 +++++++++++++------------- 2 files changed, 148 insertions(+), 144 deletions(-) diff --git a/components/usb/private_include/usbh.h b/components/usb/private_include/usbh.h index 75be2b1f66..fe80799f87 100644 --- a/components/usb/private_include/usbh.h +++ b/components/usb/private_include/usbh.h @@ -130,7 +130,7 @@ typedef struct { void *event_cb_arg; /**< USBH event callback argument */ } usbh_config_t; -// ------------------------------------------------- USBH Functions ---------------------------------------------------- +// -------------------------------------------- USBH Processing Functions ---------------------------------------------- /** * @brief Installs the USBH driver @@ -169,6 +169,8 @@ esp_err_t usbh_uninstall(void); */ esp_err_t usbh_process(void); +// ---------------------------------------------- Device Pool Functions ------------------------------------------------ + /** * @brief Get the current number of devices * @@ -178,10 +180,6 @@ esp_err_t usbh_process(void); */ esp_err_t usbh_num_devs(int *num_devs_ret); -// ------------------------------------------------ Device Functions --------------------------------------------------- - -// --------------------- Device Pool ----------------------- - /** * @brief Fill list with address of currently connected devices * @@ -197,6 +195,17 @@ esp_err_t usbh_num_devs(int *num_devs_ret); */ esp_err_t usbh_dev_addr_list_fill(int list_len, uint8_t *dev_addr_list, int *num_dev_ret); +/** + * @brief Mark that all devices should be freed at the next possible opportunity + * + * A device marked as free will not be freed until the last client using the device has called usbh_dev_close() + * + * @return + * - ESP_OK: There were no devices to free to begin with. Current state is all free + * - ESP_ERR_NOT_FINISHED: One or more devices still need to be freed (but have been marked "to be freed") + */ +esp_err_t usbh_dev_mark_all_free(void); + /** * @brief Open a device by address * @@ -218,18 +227,9 @@ esp_err_t usbh_dev_open(uint8_t dev_addr, usb_device_handle_t *dev_hdl); */ esp_err_t usbh_dev_close(usb_device_handle_t dev_hdl); -/** - * @brief Mark that all devices should be freed at the next possible opportunity - * - * A device marked as free will not be freed until the last client using the device has called usbh_dev_close() - * - * @return - * - ESP_OK: There were no devices to free to begin with. Current state is all free - * - ESP_ERR_NOT_FINISHED: One or more devices still need to be freed (but have been marked "to be freed") - */ -esp_err_t usbh_dev_mark_all_free(void); +// ------------------------------------------------ Device Functions --------------------------------------------------- -// ------------------- Single Device ---------------------- +// ----------------------- Getters ------------------------- /** * @brief Get a device's address @@ -275,15 +275,6 @@ esp_err_t usbh_dev_get_desc(usb_device_handle_t dev_hdl, const usb_device_desc_t */ esp_err_t usbh_dev_get_config_desc(usb_device_handle_t dev_hdl, const usb_config_desc_t **config_desc_ret); -/** - * @brief Submit a control transfer (URB) to a device - * - * @param[in] dev_hdl Device handle - * @param[in] urb URB - * @return esp_err_t - */ -esp_err_t usbh_dev_submit_ctrl_urb(usb_device_handle_t dev_hdl, urb_t *urb); - // ----------------------------------------------- Endpoint Functions ------------------------------------------------- /** @@ -334,6 +325,39 @@ esp_err_t usbh_ep_free(usbh_ep_handle_t ep_hdl); */ esp_err_t usbh_ep_get_handle(usb_device_handle_t dev_hdl, uint8_t bEndpointAddress, usbh_ep_handle_t *ep_hdl_ret); +/** + * @brief Execute a command on a particular endpoint + * + * Endpoint commands allows executing a certain action on an endpoint (e.g., halting, flushing, clearing etc) + * + * @param[in] ep_hdl Endpoint handle + * @param[in] command Endpoint command + * @return esp_err_t + */ +esp_err_t usbh_ep_command(usbh_ep_handle_t ep_hdl, usbh_ep_cmd_t command); + +/** + * @brief Get the context of an endpoint + * + * Get the context variable assigned to and endpoint on allocation. + * + * @note This function can block + * @param[in] ep_hdl Endpoint handle + * @return Endpoint context + */ +void *usbh_ep_get_context(usbh_ep_handle_t ep_hdl); + +// ----------------------------------------------- Transfer Functions -------------------------------------------------- + +/** + * @brief Submit a control transfer (URB) to a device + * + * @param[in] dev_hdl Device handle + * @param[in] urb URB + * @return esp_err_t + */ +esp_err_t usbh_dev_submit_ctrl_urb(usb_device_handle_t dev_hdl, urb_t *urb); + /** * @brief Enqueue a URB to an endpoint * @@ -357,28 +381,6 @@ esp_err_t usbh_ep_enqueue_urb(usbh_ep_handle_t ep_hdl, urb_t *urb); */ esp_err_t usbh_ep_dequeue_urb(usbh_ep_handle_t ep_hdl, urb_t **urb_ret); -/** - * @brief Execute a command on a particular endpoint - * - * Endpoint commands allows executing a certain action on an endpoint (e.g., halting, flushing, clearing etc) - * - * @param[in] ep_hdl Endpoint handle - * @param[in] command Endpoint command - * @return esp_err_t - */ -esp_err_t usbh_ep_command(usbh_ep_handle_t ep_hdl, usbh_ep_cmd_t command); - -/** - * @brief Get the context of an endpoint - * - * Get the context variable assigned to and endpoint on allocation. - * - * @note This function can block - * @param[in] ep_hdl Endpoint handle - * @return Endpoint context - */ -void *usbh_ep_get_context(usbh_ep_handle_t ep_hdl); - // -------------------------------------------------- Hub Functions ---------------------------------------------------- // ------------------- Device Related ---------------------- diff --git a/components/usb/usbh.c b/components/usb/usbh.c index a50f4fc944..26daf4a3ff 100644 --- a/components/usb/usbh.c +++ b/components/usb/usbh.c @@ -561,7 +561,7 @@ static inline void handle_prop_new_dev(device_t *dev_obj) p_usbh_obj->constant.event_cb(&event_data, p_usbh_obj->constant.event_cb_arg); } -// ------------------------------------------------- USBH Functions ---------------------------------------------------- +// -------------------------------------------- USBH Processing Functions ---------------------------------------------- esp_err_t usbh_install(const usbh_config_t *usbh_config) { @@ -700,6 +700,8 @@ esp_err_t usbh_process(void) return ESP_OK; } +// ---------------------------------------------- Device Pool Functions ------------------------------------------------ + esp_err_t usbh_num_devs(int *num_devs_ret) { USBH_CHECK(num_devs_ret != NULL, ESP_ERR_INVALID_ARG); @@ -709,10 +711,6 @@ esp_err_t usbh_num_devs(int *num_devs_ret) return ESP_OK; } -// ------------------------------------------------ Device Functions --------------------------------------------------- - -// --------------------- Device Pool ----------------------- - esp_err_t usbh_dev_addr_list_fill(int list_len, uint8_t *dev_addr_list, int *num_dev_ret) { USBH_CHECK(dev_addr_list != NULL && num_dev_ret != NULL, ESP_ERR_INVALID_ARG); @@ -743,6 +741,48 @@ esp_err_t usbh_dev_addr_list_fill(int list_len, uint8_t *dev_addr_list, int *num return ESP_OK; } +esp_err_t usbh_dev_mark_all_free(void) +{ + USBH_ENTER_CRITICAL(); + /* + Go through the device list and mark each device as waiting to be closed. If the device is not opened at all, we can + disable it immediately. + Note: We manually traverse the list because we need to add/remove items while traversing + */ + bool call_proc_req_cb = false; + bool wait_for_free = false; + for (int i = 0; i < 2; i++) { + device_t *dev_obj_cur; + device_t *dev_obj_next; + // Go through pending list first as it's more efficient + if (i == 0) { + dev_obj_cur = TAILQ_FIRST(&p_usbh_obj->dynamic.devs_pending_tailq); + } else { + dev_obj_cur = TAILQ_FIRST(&p_usbh_obj->dynamic.devs_idle_tailq); + } + while (dev_obj_cur != NULL) { + // Keep a copy of the next item first in case we remove the current item + dev_obj_next = TAILQ_NEXT(dev_obj_cur, dynamic.tailq_entry); + if (dev_obj_cur->dynamic.ref_count == 0) { + // Device is not referenced. Can free immediately. + call_proc_req_cb |= _dev_set_actions(dev_obj_cur, DEV_ACTION_FREE); + } else { + // Device is still referenced. Just mark it as waiting to be freed + dev_obj_cur->dynamic.flags.waiting_free = 1; + } + // At least one device needs to be freed. User needs to wait for USBH_EVENT_ALL_FREE event + wait_for_free = true; + dev_obj_cur = dev_obj_next; + } + } + USBH_EXIT_CRITICAL(); + + if (call_proc_req_cb) { + p_usbh_obj->constant.proc_req_cb(USB_PROC_REQ_SOURCE_USBH, false, p_usbh_obj->constant.proc_req_cb_arg); + } + return (wait_for_free) ? ESP_ERR_NOT_FINISHED : ESP_OK; +} + esp_err_t usbh_dev_open(uint8_t dev_addr, usb_device_handle_t *dev_hdl) { USBH_CHECK(dev_hdl != NULL, ESP_ERR_INVALID_ARG); @@ -808,49 +848,9 @@ esp_err_t usbh_dev_close(usb_device_handle_t dev_hdl) return ESP_OK; } -esp_err_t usbh_dev_mark_all_free(void) -{ - USBH_ENTER_CRITICAL(); - /* - Go through the device list and mark each device as waiting to be closed. If the device is not opened at all, we can - disable it immediately. - Note: We manually traverse the list because we need to add/remove items while traversing - */ - bool call_proc_req_cb = false; - bool wait_for_free = false; - for (int i = 0; i < 2; i++) { - device_t *dev_obj_cur; - device_t *dev_obj_next; - // Go through pending list first as it's more efficient - if (i == 0) { - dev_obj_cur = TAILQ_FIRST(&p_usbh_obj->dynamic.devs_pending_tailq); - } else { - dev_obj_cur = TAILQ_FIRST(&p_usbh_obj->dynamic.devs_idle_tailq); - } - while (dev_obj_cur != NULL) { - // Keep a copy of the next item first in case we remove the current item - dev_obj_next = TAILQ_NEXT(dev_obj_cur, dynamic.tailq_entry); - if (dev_obj_cur->dynamic.ref_count == 0) { - // Device is not referenced. Can free immediately. - call_proc_req_cb |= _dev_set_actions(dev_obj_cur, DEV_ACTION_FREE); - } else { - // Device is still referenced. Just mark it as waiting to be freed - dev_obj_cur->dynamic.flags.waiting_free = 1; - } - // At least one device needs to be freed. User needs to wait for USBH_EVENT_ALL_FREE event - wait_for_free = true; - dev_obj_cur = dev_obj_next; - } - } - USBH_EXIT_CRITICAL(); +// ------------------------------------------------ Device Functions --------------------------------------------------- - if (call_proc_req_cb) { - p_usbh_obj->constant.proc_req_cb(USB_PROC_REQ_SOURCE_USBH, false, p_usbh_obj->constant.proc_req_cb_arg); - } - return (wait_for_free) ? ESP_ERR_NOT_FINISHED : ESP_OK; -} - -// ------------------- Single Device ---------------------- +// ----------------------- Getters ------------------------- esp_err_t usbh_dev_get_addr(usb_device_handle_t dev_hdl, uint8_t *dev_addr) { @@ -928,40 +928,7 @@ exit: return ret; } -esp_err_t usbh_dev_submit_ctrl_urb(usb_device_handle_t dev_hdl, urb_t *urb) -{ - USBH_CHECK(dev_hdl != NULL && urb != NULL, ESP_ERR_INVALID_ARG); - device_t *dev_obj = (device_t *)dev_hdl; - USBH_CHECK(urb_check_args(urb), ESP_ERR_INVALID_ARG); - bool xfer_is_in = ((usb_setup_packet_t *)urb->transfer.data_buffer)->bmRequestType & USB_BM_REQUEST_TYPE_DIR_IN; - USBH_CHECK(transfer_check_usb_compliance(&(urb->transfer), USB_TRANSFER_TYPE_CTRL, dev_obj->constant.desc->bMaxPacketSize0, xfer_is_in), ESP_ERR_INVALID_ARG); - - USBH_ENTER_CRITICAL(); - USBH_CHECK_FROM_CRIT(dev_obj->dynamic.state == USB_DEVICE_STATE_CONFIGURED, ESP_ERR_INVALID_STATE); - // Increment the control transfer count first - dev_obj->dynamic.num_ctrl_xfers_inflight++; - USBH_EXIT_CRITICAL(); - - esp_err_t ret; - if (hcd_pipe_get_state(dev_obj->constant.default_pipe) != HCD_PIPE_STATE_ACTIVE) { - ret = ESP_ERR_INVALID_STATE; - goto hcd_err; - } - ret = hcd_urb_enqueue(dev_obj->constant.default_pipe, urb); - if (ret != ESP_OK) { - goto hcd_err; - } - ret = ESP_OK; - return ret; - -hcd_err: - USBH_ENTER_CRITICAL(); - dev_obj->dynamic.num_ctrl_xfers_inflight--; - USBH_EXIT_CRITICAL(); - return ret; -} - -// ----------------------------------------------- Interface Functions ------------------------------------------------- +// ----------------------------------------------- Endpoint Functions ------------------------------------------------- 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) { @@ -1074,6 +1041,57 @@ esp_err_t usbh_ep_get_handle(usb_device_handle_t dev_hdl, uint8_t bEndpointAddre return ret; } +esp_err_t usbh_ep_command(usbh_ep_handle_t ep_hdl, usbh_ep_cmd_t command) +{ + USBH_CHECK(ep_hdl != NULL, ESP_ERR_INVALID_ARG); + + endpoint_t *ep_obj = (endpoint_t *)ep_hdl; + // Send the command to the EP's underlying pipe + return hcd_pipe_command(ep_obj->constant.pipe_hdl, (hcd_pipe_cmd_t)command); +} + +void *usbh_ep_get_context(usbh_ep_handle_t ep_hdl) +{ + assert(ep_hdl); + endpoint_t *ep_obj = (endpoint_t *)ep_hdl; + return hcd_pipe_get_context(ep_obj->constant.pipe_hdl); +} + +// ----------------------------------------------- Transfer Functions -------------------------------------------------- + +esp_err_t usbh_dev_submit_ctrl_urb(usb_device_handle_t dev_hdl, urb_t *urb) +{ + USBH_CHECK(dev_hdl != NULL && urb != NULL, ESP_ERR_INVALID_ARG); + device_t *dev_obj = (device_t *)dev_hdl; + USBH_CHECK(urb_check_args(urb), ESP_ERR_INVALID_ARG); + bool xfer_is_in = ((usb_setup_packet_t *)urb->transfer.data_buffer)->bmRequestType & USB_BM_REQUEST_TYPE_DIR_IN; + USBH_CHECK(transfer_check_usb_compliance(&(urb->transfer), USB_TRANSFER_TYPE_CTRL, dev_obj->constant.desc->bMaxPacketSize0, xfer_is_in), ESP_ERR_INVALID_ARG); + + USBH_ENTER_CRITICAL(); + USBH_CHECK_FROM_CRIT(dev_obj->dynamic.state == USB_DEVICE_STATE_CONFIGURED, ESP_ERR_INVALID_STATE); + // Increment the control transfer count first + dev_obj->dynamic.num_ctrl_xfers_inflight++; + USBH_EXIT_CRITICAL(); + + esp_err_t ret; + if (hcd_pipe_get_state(dev_obj->constant.default_pipe) != HCD_PIPE_STATE_ACTIVE) { + ret = ESP_ERR_INVALID_STATE; + goto hcd_err; + } + ret = hcd_urb_enqueue(dev_obj->constant.default_pipe, urb); + if (ret != ESP_OK) { + goto hcd_err; + } + ret = ESP_OK; + return ret; + +hcd_err: + USBH_ENTER_CRITICAL(); + dev_obj->dynamic.num_ctrl_xfers_inflight--; + USBH_EXIT_CRITICAL(); + return ret; +} + esp_err_t usbh_ep_enqueue_urb(usbh_ep_handle_t ep_hdl, urb_t *urb) { USBH_CHECK(ep_hdl != NULL && urb != NULL, ESP_ERR_INVALID_ARG); @@ -1104,22 +1122,6 @@ esp_err_t usbh_ep_dequeue_urb(usbh_ep_handle_t ep_hdl, urb_t **urb_ret) return ESP_OK; } -esp_err_t usbh_ep_command(usbh_ep_handle_t ep_hdl, usbh_ep_cmd_t command) -{ - USBH_CHECK(ep_hdl != NULL, ESP_ERR_INVALID_ARG); - - endpoint_t *ep_obj = (endpoint_t *)ep_hdl; - // Send the command to the EP's underlying pipe - return hcd_pipe_command(ep_obj->constant.pipe_hdl, (hcd_pipe_cmd_t)command); -} - -void *usbh_ep_get_context(usbh_ep_handle_t ep_hdl) -{ - assert(ep_hdl); - endpoint_t *ep_obj = (endpoint_t *)ep_hdl; - return hcd_pipe_get_context(ep_obj->constant.pipe_hdl); -} - // -------------------------------------------------- Hub Functions ---------------------------------------------------- // ------------------- Device Related ---------------------- From 8aa9a42f2b9a89647aefc16bd5e7b109e8d5f7d8 Mon Sep 17 00:00:00 2001 From: Darian Leung Date: Wed, 3 Apr 2024 11:24:03 +0800 Subject: [PATCH 2/6] refactor(usb/usbh): Rename device pool functions and ref_count This commit renames the following APIs and variables in the USBH: - Rename the prefix of device pool functions from 'usbh_dev_...' to 'usbh_devs_...'. - Rename 'ref_count' to 'open_count'. This variable tracks the number of times a device has been opened. --- components/usb/private_include/usbh.h | 18 +++++++------- components/usb/usb_host.c | 12 +++++----- components/usb/usbh.c | 34 +++++++++++++-------------- 3 files changed, 32 insertions(+), 32 deletions(-) diff --git a/components/usb/private_include/usbh.h b/components/usb/private_include/usbh.h index fe80799f87..6dee5e55b4 100644 --- a/components/usb/private_include/usbh.h +++ b/components/usb/private_include/usbh.h @@ -178,13 +178,13 @@ esp_err_t usbh_process(void); * @param[out] num_devs_ret Current number of devices * @return esp_err_t */ -esp_err_t usbh_num_devs(int *num_devs_ret); +esp_err_t usbh_devs_num(int *num_devs_ret); /** * @brief Fill list with address of currently connected devices * * - This function fills the provided list with the address of current connected devices - * - Device address can then be used in usbh_dev_open() + * - Device address can then be used in usbh_devs_open() * - If there are more devices than the list_len, this function will only fill * up to list_len number of devices. * @@ -193,18 +193,18 @@ esp_err_t usbh_num_devs(int *num_devs_ret); * @param[out] num_dev_ret Number of devices filled into list * @return esp_err_t */ -esp_err_t usbh_dev_addr_list_fill(int list_len, uint8_t *dev_addr_list, int *num_dev_ret); +esp_err_t usbh_devs_addr_list_fill(int list_len, uint8_t *dev_addr_list, int *num_dev_ret); /** * @brief Mark that all devices should be freed at the next possible opportunity * - * A device marked as free will not be freed until the last client using the device has called usbh_dev_close() + * A device marked as free will not be freed until the last client using the device has called usbh_devs_close() * * @return * - ESP_OK: There were no devices to free to begin with. Current state is all free * - ESP_ERR_NOT_FINISHED: One or more devices still need to be freed (but have been marked "to be freed") */ -esp_err_t usbh_dev_mark_all_free(void); +esp_err_t usbh_devs_mark_all_free(void); /** * @brief Open a device by address @@ -215,17 +215,17 @@ esp_err_t usbh_dev_mark_all_free(void); * @param[out] dev_hdl Device handle * @return esp_err_t */ -esp_err_t usbh_dev_open(uint8_t dev_addr, usb_device_handle_t *dev_hdl); +esp_err_t usbh_devs_open(uint8_t dev_addr, usb_device_handle_t *dev_hdl); /** * @brief CLose a device * - * Device can be opened by calling usbh_dev_open() + * Device can be opened by calling usbh_devs_open() * * @param[in] dev_hdl Device handle * @return esp_err_t */ -esp_err_t usbh_dev_close(usb_device_handle_t dev_hdl); +esp_err_t usbh_devs_close(usb_device_handle_t dev_hdl); // ------------------------------------------------ Device Functions --------------------------------------------------- @@ -282,7 +282,7 @@ esp_err_t usbh_dev_get_config_desc(usb_device_handle_t dev_hdl, const usb_config * * This function allows clients to allocate a non-default endpoint (i.e., not EP0) on a connected device * - * - A client must have opened the device using usbh_dev_open() before attempting to allocate an endpoint on the device + * - A client must have opened the device using usbh_devs_open() before attempting to allocate an endpoint on the device * - A client should call this function to allocate all endpoints in an interface that the client has claimed. * - A client must allocate an endpoint using this function before attempting to communicate with it * - Once the client allocates an endpoint, the client is now owns/manages the endpoint. No other client should use or diff --git a/components/usb/usb_host.c b/components/usb/usb_host.c index 11fd7810aa..b9b12dafcc 100644 --- a/components/usb/usb_host.c +++ b/components/usb/usb_host.c @@ -574,7 +574,7 @@ esp_err_t usb_host_lib_info(usb_host_lib_info_t *info_ret) HOST_CHECK_FROM_CRIT(p_host_lib_obj != NULL, ESP_ERR_INVALID_STATE); num_clients_temp = p_host_lib_obj->dynamic.flags.num_clients; HOST_EXIT_CRITICAL(); - usbh_num_devs(&num_devs_temp); + usbh_devs_num(&num_devs_temp); // Write back return values info_ret->num_devices = num_devs_temp; @@ -820,7 +820,7 @@ esp_err_t usb_host_device_open(usb_host_client_handle_t client_hdl, uint8_t dev_ esp_err_t ret; usb_device_handle_t dev_hdl; - ret = usbh_dev_open(dev_addr, &dev_hdl); + ret = usbh_devs_open(dev_addr, &dev_hdl); if (ret != ESP_OK) { goto exit; } @@ -841,7 +841,7 @@ esp_err_t usb_host_device_open(usb_host_client_handle_t client_hdl, uint8_t dev_ return ret; already_opened: - ESP_ERROR_CHECK(usbh_dev_close(dev_hdl)); + ESP_ERROR_CHECK(usbh_devs_close(dev_hdl)); exit: return ret; } @@ -883,7 +883,7 @@ esp_err_t usb_host_device_close(usb_host_client_handle_t client_hdl, usb_device_ _clear_client_opened_device(client_obj, dev_addr); HOST_EXIT_CRITICAL(); - ESP_ERROR_CHECK(usbh_dev_close(dev_hdl)); + ESP_ERROR_CHECK(usbh_devs_close(dev_hdl)); ret = ESP_OK; exit: xSemaphoreGive(p_host_lib_obj->constant.mux_lock); @@ -896,7 +896,7 @@ esp_err_t usb_host_device_free_all(void) HOST_CHECK_FROM_CRIT(p_host_lib_obj->dynamic.flags.num_clients == 0, ESP_ERR_INVALID_STATE); // All clients must have been deregistered HOST_EXIT_CRITICAL(); esp_err_t ret; - ret = usbh_dev_mark_all_free(); + 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 return ret; } @@ -904,7 +904,7 @@ esp_err_t usb_host_device_free_all(void) esp_err_t usb_host_device_addr_list_fill(int list_len, uint8_t *dev_addr_list, int *num_dev_ret) { HOST_CHECK(dev_addr_list != NULL && num_dev_ret != NULL, ESP_ERR_INVALID_ARG); - return usbh_dev_addr_list_fill(list_len, dev_addr_list, num_dev_ret); + return usbh_devs_addr_list_fill(list_len, dev_addr_list, num_dev_ret); } // ------------------------------------------------- Device Requests --------------------------------------------------- diff --git a/components/usb/usbh.c b/components/usb/usbh.c index 26daf4a3ff..06d6f8d942 100644 --- a/components/usb/usbh.c +++ b/components/usb/usbh.c @@ -64,7 +64,7 @@ struct device_s { uint32_t action_flags; int num_ctrl_xfers_inflight; usb_device_state_t state; - uint32_t ref_count; + uint32_t open_count; } dynamic; // Mux protected members must be protected by the USBH mux_lock when accessed struct { @@ -702,7 +702,7 @@ esp_err_t usbh_process(void) // ---------------------------------------------- Device Pool Functions ------------------------------------------------ -esp_err_t usbh_num_devs(int *num_devs_ret) +esp_err_t usbh_devs_num(int *num_devs_ret) { USBH_CHECK(num_devs_ret != NULL, ESP_ERR_INVALID_ARG); xSemaphoreTake(p_usbh_obj->constant.mux_lock, portMAX_DELAY); @@ -711,7 +711,7 @@ esp_err_t usbh_num_devs(int *num_devs_ret) return ESP_OK; } -esp_err_t usbh_dev_addr_list_fill(int list_len, uint8_t *dev_addr_list, int *num_dev_ret) +esp_err_t usbh_devs_addr_list_fill(int list_len, uint8_t *dev_addr_list, int *num_dev_ret) { USBH_CHECK(dev_addr_list != NULL && num_dev_ret != NULL, ESP_ERR_INVALID_ARG); USBH_ENTER_CRITICAL(); @@ -741,7 +741,7 @@ esp_err_t usbh_dev_addr_list_fill(int list_len, uint8_t *dev_addr_list, int *num return ESP_OK; } -esp_err_t usbh_dev_mark_all_free(void) +esp_err_t usbh_devs_mark_all_free(void) { USBH_ENTER_CRITICAL(); /* @@ -763,11 +763,11 @@ esp_err_t usbh_dev_mark_all_free(void) while (dev_obj_cur != NULL) { // Keep a copy of the next item first in case we remove the current item dev_obj_next = TAILQ_NEXT(dev_obj_cur, dynamic.tailq_entry); - if (dev_obj_cur->dynamic.ref_count == 0) { - // Device is not referenced. Can free immediately. + if (dev_obj_cur->dynamic.open_count == 0) { + // Device is not opened. Can free immediately. call_proc_req_cb |= _dev_set_actions(dev_obj_cur, DEV_ACTION_FREE); } else { - // Device is still referenced. Just mark it as waiting to be freed + // Device is still opened. Just mark it as waiting to be freed dev_obj_cur->dynamic.flags.waiting_free = 1; } // At least one device needs to be freed. User needs to wait for USBH_EVENT_ALL_FREE event @@ -783,7 +783,7 @@ esp_err_t usbh_dev_mark_all_free(void) return (wait_for_free) ? ESP_ERR_NOT_FINISHED : ESP_OK; } -esp_err_t usbh_dev_open(uint8_t dev_addr, usb_device_handle_t *dev_hdl) +esp_err_t usbh_devs_open(uint8_t dev_addr, usb_device_handle_t *dev_hdl) { USBH_CHECK(dev_hdl != NULL, ESP_ERR_INVALID_ARG); esp_err_t ret; @@ -806,11 +806,11 @@ esp_err_t usbh_dev_open(uint8_t dev_addr, usb_device_handle_t *dev_hdl) } exit: if (found_dev_obj != NULL) { - // The device is not in a state to be referenced + // The device is not in a state to be opened if (dev_obj->dynamic.flags.is_gone || dev_obj->dynamic.flags.waiting_free) { ret = ESP_ERR_INVALID_STATE; } else { - dev_obj->dynamic.ref_count++; + dev_obj->dynamic.open_count++; *dev_hdl = (usb_device_handle_t)found_dev_obj; ret = ESP_OK; } @@ -822,18 +822,18 @@ exit: return ret; } -esp_err_t usbh_dev_close(usb_device_handle_t dev_hdl) +esp_err_t usbh_devs_close(usb_device_handle_t dev_hdl) { USBH_CHECK(dev_hdl != NULL, ESP_ERR_INVALID_ARG); device_t *dev_obj = (device_t *)dev_hdl; USBH_ENTER_CRITICAL(); - dev_obj->dynamic.ref_count--; + dev_obj->dynamic.open_count--; bool call_proc_req_cb = false; - if (dev_obj->dynamic.ref_count == 0) { + if (dev_obj->dynamic.open_count == 0) { // Sanity check. assert(dev_obj->dynamic.num_ctrl_xfers_inflight == 0); // There cannot be any control transfer in-flight - assert(!dev_obj->dynamic.flags.waiting_free); // This can only be set when ref count reaches 0 + assert(!dev_obj->dynamic.flags.waiting_free); // This can only be set when open_count reaches 0 if (dev_obj->dynamic.flags.is_gone || dev_obj->dynamic.flags.waiting_free) { // Device is already gone or is awaiting to be freed. Trigger the USBH process to free the device call_proc_req_cb = _dev_set_actions(dev_obj, DEV_ACTION_FREE); @@ -1152,11 +1152,11 @@ esp_err_t usbh_hub_dev_gone(usb_device_handle_t dev_hdl) USBH_ENTER_CRITICAL(); dev_obj->dynamic.flags.is_gone = 1; // Check if the device can be freed immediately - if (dev_obj->dynamic.ref_count == 0) { - // Device is not currently referenced at all. Can free immediately. + if (dev_obj->dynamic.open_count == 0) { + // Device is not currently opened at all. Can free immediately. call_proc_req_cb = _dev_set_actions(dev_obj, DEV_ACTION_FREE); } else { - // Device is still being referenced. Flush endpoints and propagate device gone event + // Device is still opened. Flush endpoints and propagate device gone event call_proc_req_cb = _dev_set_actions(dev_obj, DEV_ACTION_EPn_HALT_FLUSH | DEV_ACTION_EP0_FLUSH | From 3358f3ec467fdb5fb020128656fbac177e9e43c6 Mon Sep 17 00:00:00 2001 From: Darian Leung Date: Wed, 3 Apr 2024 19:23:47 +0800 Subject: [PATCH 3/6] refactor(usb/hcd): Allow port resets with allocated pipes This commit updates the HCD API to allow port resets to occur even if pipes are allocated. The pipes cannot be active and the port reset will simply restore the pipes (by reinitializing their channel registers) following the reset. Changes: - Allow port resets while channels are allocated - Remove pipe persistance API 'hcd_pipe_set_persist_reset()' --- components/hal/include/hal/usb_dwc_hal.h | 17 ++- components/usb/hcd_dwc.c | 167 +++++++---------------- components/usb/hub.c | 1 - components/usb/private_include/hcd.h | 14 -- 4 files changed, 54 insertions(+), 145 deletions(-) diff --git a/components/hal/include/hal/usb_dwc_hal.h b/components/hal/include/hal/usb_dwc_hal.h index 9b2a2c3bc3..33ac57be75 100644 --- a/components/hal/include/hal/usb_dwc_hal.h +++ b/components/hal/include/hal/usb_dwc_hal.h @@ -205,7 +205,7 @@ typedef struct { * - The peripheral must have been reset and clock un-gated * - The USB PHY (internal or external) and associated GPIOs must already be configured * - GPIO pins configured - * - Interrupt allocated but DISABLED (in case of an unknown interupt state) + * - Interrupt allocated but DISABLED (in case of an unknown interrupt state) * Exit: * - Checks to see if DWC_OTG is alive, and if HW version/config is correct * - HAl context initialized @@ -290,7 +290,7 @@ static inline void usb_dwc_hal_port_init(usb_dwc_hal_context_t *hal) /** * @brief Deinitialize the host port * - * - Will disable the host port's interrupts preventing further port aand channel events from ocurring + * - Will disable the host port's interrupts preventing further port aand channel events from occurring * * @param hal Context of the HAL layer */ @@ -333,7 +333,6 @@ static inline void usb_dwc_hal_port_toggle_power(usb_dwc_hal_context_t *hal, boo */ static inline void usb_dwc_hal_port_toggle_reset(usb_dwc_hal_context_t *hal, bool enable) { - HAL_ASSERT(hal->channels.num_allocd == 0); //Cannot reset if there are still allocated channels usb_dwc_ll_hprt_set_port_reset(hal->dev, enable); } @@ -447,7 +446,7 @@ static inline void usb_dwc_hal_port_periodic_enable(usb_dwc_hal_context_t *hal) /** * @brief Disable periodic scheduling * - * Disabling periodic scheduling will save a bit of DMA bandwith (as the controller will no longer fetch the schedule + * Disabling periodic scheduling will save a bit of DMA bandwidth (as the controller will no longer fetch the schedule * from the frame list). * * @note Before disabling periodic scheduling, it is the user's responsibility to ensure that all periodic channels have @@ -505,17 +504,17 @@ static inline usb_dwc_speed_t usb_dwc_hal_port_get_conn_speed(usb_dwc_hal_contex * @brief Disable the debounce lock * * This function must be called after calling usb_dwc_hal_port_check_if_connected() and will allow connection/disconnection - * events to occur again. Any pending connection or disconenction interrupts are cleared. + * events to occur again. Any pending connection or disconnection interrupts are cleared. * * @param hal Context of the HAL layer */ static inline void usb_dwc_hal_disable_debounce_lock(usb_dwc_hal_context_t *hal) { hal->flags.dbnc_lock_enabled = 0; - //Clear Conenction and disconenction interrupt in case it triggered again + //Clear Connection and disconnection interrupt in case it triggered again usb_dwc_ll_gintsts_clear_intrs(hal->dev, USB_DWC_LL_INTR_CORE_DISCONNINT); usb_dwc_ll_hprt_intr_clear(hal->dev, USB_DWC_LL_INTR_HPRT_PRTCONNDET); - //Reenable the hprt (connection) and disconnection interrupts + //Re-enable the hprt (connection) and disconnection interrupts usb_dwc_ll_gintmsk_en_intrs(hal->dev, USB_DWC_LL_INTR_CORE_PRTINT | USB_DWC_LL_INTR_CORE_DISCONNINT); } @@ -672,10 +671,10 @@ bool usb_dwc_hal_chan_request_halt(usb_dwc_hal_chan_t *chan_obj); /** * @brief Indicate that a channel is halted after a port error * - * When a port error occurs (e.g., discconect, overcurrent): + * When a port error occurs (e.g., disconnect, overcurrent): * - Any previously active channels will remain active (i.e., they will not receive a channel interrupt) * - Attempting to disable them using usb_dwc_hal_chan_request_halt() will NOT generate an interrupt for ISOC channels - * (probalby something to do with the periodic scheduling) + * (probably something to do with the periodic scheduling) * * However, the channel's enable bit can be left as 1 since after a port error, a soft reset will be done anyways. * This function simply updates the channels internal state variable to indicate it is halted (thus allowing it to be diff --git a/components/usb/hcd_dwc.c b/components/usb/hcd_dwc.c index f9834b7ad8..bc0c24ddaf 100644 --- a/components/usb/hcd_dwc.c +++ b/components/usb/hcd_dwc.c @@ -214,9 +214,7 @@ struct pipe_obj { uint32_t waiting_halt: 1; uint32_t pipe_cmd_processing: 1; uint32_t has_urb: 1; // Indicates there is at least one URB either pending, in-flight, or done - uint32_t persist: 1; // indicates that this pipe should persist through a run-time port reset - uint32_t reset_lock: 1; // Indicates that this pipe is undergoing a run-time reset - uint32_t reserved27: 27; + uint32_t reserved29: 29; }; uint32_t val; } cs_flags; @@ -560,28 +558,6 @@ static esp_err_t _pipe_cmd_clear(pipe_t *pipe); // ------------------------ Port --------------------------- -/** - * @brief Prepare persistent pipes for reset - * - * This function checks if all pipes are reset persistent and proceeds to free their underlying HAL channels for the - * persistent pipes. This should be called before a run time reset - * - * @param port Port object - * @return true All pipes are persistent and their channels are freed - * @return false Not all pipes are persistent - */ -static bool _port_persist_all_pipes(port_t *port); - -/** - * @brief Recovers all persistent pipes after a reset - * - * This function will recover all persistent pipes after a reset and reallocate their underlying HAl channels. This - * function should be called after a reset. - * - * @param port Port object - */ -static void _port_recover_all_pipes(port_t *port); - /** * @brief Checks if all pipes are in the halted state * @@ -1162,44 +1138,6 @@ esp_err_t hcd_uninstall(void) // ----------------------- Helpers ------------------------- -static bool _port_persist_all_pipes(port_t *port) -{ - if (port->num_pipes_queued > 0) { - // All pipes must be idle before we run-time reset - return false; - } - bool all_persist = true; - pipe_t *pipe; - // Check that each pipe is persistent - TAILQ_FOREACH(pipe, &port->pipes_idle_tailq, tailq_entry) { - if (!pipe->cs_flags.persist) { - all_persist = false; - break; - } - } - if (!all_persist) { - // At least one pipe is not persistent. All pipes must be freed or made persistent before we can reset - return false; - } - TAILQ_FOREACH(pipe, &port->pipes_idle_tailq, tailq_entry) { - pipe->cs_flags.reset_lock = 1; - usb_dwc_hal_chan_free(port->hal, pipe->chan_obj); - } - return true; -} - -static void _port_recover_all_pipes(port_t *port) -{ - pipe_t *pipe; - TAILQ_FOREACH(pipe, &port->pipes_idle_tailq, tailq_entry) { - pipe->cs_flags.persist = 0; - pipe->cs_flags.reset_lock = 0; - usb_dwc_hal_chan_alloc(port->hal, pipe->chan_obj, (void *)pipe); - usb_dwc_hal_chan_set_ep_char(port->hal, pipe->chan_obj, &pipe->ep_char); - } - CACHE_SYNC_FRAME_LIST(port->frame_list); -} - static bool _port_check_all_pipes_halted(port_t *port) { bool all_halted = true; @@ -1276,20 +1214,26 @@ static esp_err_t _port_cmd_power_off(port_t *port) static esp_err_t _port_cmd_reset(port_t *port) { esp_err_t ret; - // Port can only a reset when it is in the enabled or disabled states (in case of new connection) + + // Port can only a reset when it is in the enabled or disabled (in the case of a new connection)states. if (port->state != HCD_PORT_STATE_ENABLED && port->state != HCD_PORT_STATE_DISABLED) { ret = ESP_ERR_INVALID_STATE; goto exit; } - bool is_runtime_reset = (port->state == HCD_PORT_STATE_ENABLED) ? true : false; - if (is_runtime_reset && !_port_persist_all_pipes(port)) { - // If this is a run time reset, check all pipes that are still allocated can persist the reset + // Port can only be reset if all pipes are idle + if (port->num_pipes_queued > 0) { ret = ESP_ERR_INVALID_STATE; goto exit; } - // All pipes (if any_) are guaranteed to be persistent at this point. Proceed to resetting the bus + /* + Proceed to resetting the bus + - Update the port's state variable + - Hold the bus in the reset state for RESET_HOLD_MS. + - Return the bus to the idle state for RESET_RECOVERY_MS + */ port->state = HCD_PORT_STATE_RESETTING; - // Put and hold the bus in the reset state. If the port was previously enabled, a disabled event will occur after this + + // Place the bus into the reset state. If the port was previously enabled, a disabled event will occur after this usb_dwc_hal_port_toggle_reset(port->hal, true); HCD_EXIT_CRITICAL(); vTaskDelay(pdMS_TO_TICKS(RESET_HOLD_MS)); @@ -1299,7 +1243,8 @@ static esp_err_t _port_cmd_reset(port_t *port) ret = ESP_ERR_INVALID_RESPONSE; goto bailout; } - // Return the bus to the idle state and hold it for the required reset recovery time. Port enabled event should occur + + // Return the bus to the idle state. Port enabled event should occur usb_dwc_hal_port_toggle_reset(port->hal, false); HCD_EXIT_CRITICAL(); vTaskDelay(pdMS_TO_TICKS(RESET_RECOVERY_MS)); @@ -1309,16 +1254,20 @@ static esp_err_t _port_cmd_reset(port_t *port) ret = ESP_ERR_INVALID_RESPONSE; goto bailout; } - // Set FIFO sizes based on the selected biasing - usb_dwc_hal_set_fifo_bias(port->hal, port->fifo_bias); - // We start periodic scheduling only after a RESET command since SOFs only start after a reset - usb_dwc_hal_port_set_frame_list(port->hal, port->frame_list, FRAME_LIST_LEN); - usb_dwc_hal_port_periodic_enable(port->hal); + + // Reinitialize port registers. + usb_dwc_hal_set_fifo_bias(port->hal, port->fifo_bias); // Set FIFO biases + usb_dwc_hal_port_set_frame_list(port->hal, port->frame_list, FRAME_LIST_LEN); // Set periodic frame list + usb_dwc_hal_port_periodic_enable(port->hal); // Enable periodic scheduling + ret = ESP_OK; bailout: - if (is_runtime_reset) { - _port_recover_all_pipes(port); + // Reinitialize channel registers + pipe_t *pipe; + TAILQ_FOREACH(pipe, &port->pipes_idle_tailq, tailq_entry) { + usb_dwc_hal_chan_set_ep_char(port->hal, pipe->chan_obj, &pipe->ep_char); } + CACHE_SYNC_FRAME_LIST(port->frame_list); exit: return ret; } @@ -1987,8 +1936,7 @@ esp_err_t hcd_pipe_free(hcd_pipe_handle_t pipe_hdl) HCD_ENTER_CRITICAL(); // Check that all URBs have been removed and pipe has no pending events HCD_CHECK_FROM_CRIT(!pipe->multi_buffer_control.buffer_is_executing - && !pipe->cs_flags.has_urb - && !pipe->cs_flags.reset_lock, + && !pipe->cs_flags.has_urb, ESP_ERR_INVALID_STATE); // Remove pipe from the list of idle pipes (it must be in the idle list because it should have no queued URBs) TAILQ_REMOVE(&pipe->port->pipes_idle_tailq, pipe, tailq_entry); @@ -2011,8 +1959,7 @@ esp_err_t hcd_pipe_update_mps(hcd_pipe_handle_t pipe_hdl, int mps) HCD_ENTER_CRITICAL(); // Check if pipe is in the correct state to be updated HCD_CHECK_FROM_CRIT(!pipe->cs_flags.pipe_cmd_processing && - !pipe->cs_flags.has_urb && - !pipe->cs_flags.reset_lock, + !pipe->cs_flags.has_urb, ESP_ERR_INVALID_STATE); pipe->ep_char.mps = mps; // Update the underlying channel's registers @@ -2027,8 +1974,7 @@ esp_err_t hcd_pipe_update_dev_addr(hcd_pipe_handle_t pipe_hdl, uint8_t dev_addr) HCD_ENTER_CRITICAL(); // Check if pipe is in the correct state to be updated HCD_CHECK_FROM_CRIT(!pipe->cs_flags.pipe_cmd_processing && - !pipe->cs_flags.has_urb && - !pipe->cs_flags.reset_lock, + !pipe->cs_flags.has_urb, ESP_ERR_INVALID_STATE); pipe->ep_char.dev_addr = dev_addr; // Update the underlying channel's registers @@ -2043,8 +1989,7 @@ esp_err_t hcd_pipe_update_callback(hcd_pipe_handle_t pipe_hdl, hcd_pipe_callback HCD_ENTER_CRITICAL(); // Check if pipe is in the correct state to be updated HCD_CHECK_FROM_CRIT(!pipe->cs_flags.pipe_cmd_processing && - !pipe->cs_flags.has_urb && - !pipe->cs_flags.reset_lock, + !pipe->cs_flags.has_urb, ESP_ERR_INVALID_STATE); pipe->callback = callback; pipe->callback_arg = user_arg; @@ -2052,20 +1997,6 @@ esp_err_t hcd_pipe_update_callback(hcd_pipe_handle_t pipe_hdl, hcd_pipe_callback return ESP_OK; } -esp_err_t hcd_pipe_set_persist_reset(hcd_pipe_handle_t pipe_hdl) -{ - pipe_t *pipe = (pipe_t *)pipe_hdl; - HCD_ENTER_CRITICAL(); - // Check if pipe is in the correct state to be updated - HCD_CHECK_FROM_CRIT(!pipe->cs_flags.pipe_cmd_processing && - !pipe->cs_flags.has_urb && - !pipe->cs_flags.reset_lock, - ESP_ERR_INVALID_STATE); - pipe->cs_flags.persist = 1; - HCD_EXIT_CRITICAL(); - return ESP_OK; -} - void *hcd_pipe_get_context(hcd_pipe_handle_t pipe_hdl) { pipe_t *pipe = (pipe_t *)pipe_hdl; @@ -2102,27 +2033,22 @@ esp_err_t hcd_pipe_command(hcd_pipe_handle_t pipe_hdl, hcd_pipe_cmd_t command) esp_err_t ret = ESP_OK; HCD_ENTER_CRITICAL(); - // Cannot execute pipe commands the pipe is already executing a command, or if the pipe or its port are no longer valid - if (pipe->cs_flags.reset_lock) { - ret = ESP_ERR_INVALID_STATE; - } else { - pipe->cs_flags.pipe_cmd_processing = 1; - switch (command) { - case HCD_PIPE_CMD_HALT: { - ret = _pipe_cmd_halt(pipe); - break; - } - case HCD_PIPE_CMD_FLUSH: { - ret = _pipe_cmd_flush(pipe); - break; - } - case HCD_PIPE_CMD_CLEAR: { - ret = _pipe_cmd_clear(pipe); - break; - } - } - pipe->cs_flags.pipe_cmd_processing = 0; + pipe->cs_flags.pipe_cmd_processing = 1; + switch (command) { + case HCD_PIPE_CMD_HALT: { + ret = _pipe_cmd_halt(pipe); + break; } + case HCD_PIPE_CMD_FLUSH: { + ret = _pipe_cmd_flush(pipe); + break; + } + case HCD_PIPE_CMD_CLEAR: { + ret = _pipe_cmd_clear(pipe); + break; + } + } + pipe->cs_flags.pipe_cmd_processing = 0; HCD_EXIT_CRITICAL(); return ret; } @@ -2658,8 +2584,7 @@ esp_err_t hcd_urb_enqueue(hcd_pipe_handle_t pipe_hdl, urb_t *urb) // Check that pipe and port are in the correct state to receive URBs HCD_CHECK_FROM_CRIT(pipe->port->state == HCD_PORT_STATE_ENABLED // The pipe's port must be in the correct state && pipe->state == HCD_PIPE_STATE_ACTIVE // The pipe must be in the correct state - && !pipe->cs_flags.pipe_cmd_processing // Pipe cannot currently be processing a pipe command - && !pipe->cs_flags.reset_lock, // Pipe cannot be persisting through a port reset + && !pipe->cs_flags.pipe_cmd_processing, // Pipe cannot currently be processing a pipe command ESP_ERR_INVALID_STATE); // Use the URB's reserved_ptr to store the pipe's urb->hcd_ptr = (void *)pipe; diff --git a/components/usb/hub.c b/components/usb/hub.c index 52aa84e00a..6709bea64a 100644 --- a/components/usb/hub.c +++ b/components/usb/hub.c @@ -285,7 +285,6 @@ static bool enum_stage_start(enum_ctrl_t *enum_ctrl) static bool enum_stage_second_reset(enum_ctrl_t *enum_ctrl) { - ESP_ERROR_CHECK(hcd_pipe_set_persist_reset(enum_ctrl->pipe)); // Persist the default pipe through the reset if (hcd_port_command(p_hub_driver_obj->constant.root_port_hdl, HCD_PORT_CMD_RESET) != ESP_OK) { ESP_LOGE(HUB_DRIVER_TAG, "Failed to issue second reset"); return false; diff --git a/components/usb/private_include/hcd.h b/components/usb/private_include/hcd.h index f0c4a364b9..24ec22b085 100644 --- a/components/usb/private_include/hcd.h +++ b/components/usb/private_include/hcd.h @@ -434,20 +434,6 @@ esp_err_t hcd_pipe_update_dev_addr(hcd_pipe_handle_t pipe_hdl, uint8_t dev_addr) */ esp_err_t hcd_pipe_update_callback(hcd_pipe_handle_t pipe_hdl, hcd_pipe_callback_t callback, void *user_arg); -/** - * @brief Make a pipe persist through a run time reset - * - * Normally when a HCD_PORT_CMD_RESET is called, all pipes should already have been freed. However There may be cases - * (such as during enumeration) when a pipe must persist through a reset. This function will mark a pipe as - * persistent allowing it to survive a reset. When HCD_PORT_CMD_RESET is called, the pipe can continue to be used after - * the reset. - * - * @param pipe_hdl Pipe handle - * @retval ESP_OK: Pipe successfully marked as persistent - * @retval ESP_ERR_INVALID_STATE: Pipe is not in a condition to be made persistent - */ -esp_err_t hcd_pipe_set_persist_reset(hcd_pipe_handle_t pipe_hdl); - /** * @brief Get the context variable of a pipe from its handle * From df6c6f93fa984757bec0f1a59974e4229b8c5946 Mon Sep 17 00:00:00 2001 From: Darian Leung Date: Tue, 16 Apr 2024 01:51:30 +0800 Subject: [PATCH 4/6] refactor(usb/hub): Update Hub driver port request logic --- components/usb/hub.c | 79 ++++++++++++++++++++++++++++---------------- 1 file changed, 51 insertions(+), 28 deletions(-) diff --git a/components/usb/hub.c b/components/usb/hub.c index 6709bea64a..14b8f029c7 100644 --- a/components/usb/hub.c +++ b/components/usb/hub.c @@ -50,9 +50,12 @@ implement the bare minimum to control the root HCD port. // Hub driver action flags. LISTED IN THE ORDER THEY SHOULD BE HANDLED IN within hub_process(). Some actions are mutually exclusive #define HUB_DRIVER_FLAG_ACTION_ROOT_EVENT 0x01 -#define HUB_DRIVER_FLAG_ACTION_PORT 0x02 +#define HUB_DRIVER_FLAG_ACTION_PORT_REQ 0x02 #define HUB_DRIVER_FLAG_ACTION_ENUM_EVENT 0x04 +#define PORT_REQ_DISABLE 0x01 +#define PORT_REQ_RECOVER 0x02 + /** * @brief Root port states * @@ -185,6 +188,7 @@ typedef struct { uint32_t val; } flags; root_port_state_t root_port_state; + unsigned int port_reqs; } dynamic; // Single thread members don't require a critical section so long as they are never accessed from multiple threads struct { @@ -679,7 +683,8 @@ static void enum_stage_cleanup_failed(enum_ctrl_t *enum_ctrl) HUB_DRIVER_ENTER_CRITICAL(); // Enum could have failed due to a port error. If so, we need to trigger a port recovery if (p_hub_driver_obj->dynamic.root_port_state == ROOT_PORT_STATE_RECOVERY) { - p_hub_driver_obj->dynamic.flags.actions |= HUB_DRIVER_FLAG_ACTION_PORT; + p_hub_driver_obj->dynamic.port_reqs |= PORT_REQ_RECOVER; + p_hub_driver_obj->dynamic.flags.actions |= HUB_DRIVER_FLAG_ACTION_PORT_REQ; } else { // Otherwise, we move to the enum failed state and wait for the device to disconnect p_hub_driver_obj->dynamic.root_port_state = ROOT_PORT_STATE_ENUM_FAILED; @@ -839,7 +844,8 @@ static void root_port_handle_events(hcd_port_handle_t root_port_hdl) case ROOT_PORT_STATE_POWERED: // This occurred before enumeration case ROOT_PORT_STATE_ENUM_FAILED: // This occurred after a failed enumeration. // Therefore, there's no device and we can go straight to port recovery - p_hub_driver_obj->dynamic.flags.actions |= HUB_DRIVER_FLAG_ACTION_PORT; + p_hub_driver_obj->dynamic.port_reqs |= PORT_REQ_RECOVER; + p_hub_driver_obj->dynamic.flags.actions |= HUB_DRIVER_FLAG_ACTION_PORT_REQ; break; case ROOT_PORT_STATE_ENUM: // This occurred during enumeration. Therefore, we need to cleanup the failed enumeration @@ -867,6 +873,30 @@ static void root_port_handle_events(hcd_port_handle_t root_port_hdl) } } +static void root_port_req(hcd_port_handle_t root_port_hdl) +{ + unsigned int port_reqs; + + HUB_DRIVER_ENTER_CRITICAL(); + port_reqs = p_hub_driver_obj->dynamic.port_reqs; + p_hub_driver_obj->dynamic.port_reqs = 0; + HUB_DRIVER_EXIT_CRITICAL(); + + if (port_reqs & PORT_REQ_DISABLE) { + ESP_LOGD(HUB_DRIVER_TAG, "Disabling root port"); + // We allow this to fail in case a disconnect/port error happens while disabling. + hcd_port_command(p_hub_driver_obj->constant.root_port_hdl, HCD_PORT_CMD_DISABLE); + } + if (port_reqs & PORT_REQ_RECOVER) { + ESP_LOGD(HUB_DRIVER_TAG, "Recovering root port"); + ESP_ERROR_CHECK(hcd_port_recover(p_hub_driver_obj->constant.root_port_hdl)); + ESP_ERROR_CHECK(hcd_port_command(p_hub_driver_obj->constant.root_port_hdl, HCD_PORT_CMD_POWER_ON)); + HUB_DRIVER_ENTER_CRITICAL(); + p_hub_driver_obj->dynamic.root_port_state = ROOT_PORT_STATE_POWERED; + HUB_DRIVER_EXIT_CRITICAL(); + } +} + static void enum_handle_events(void) { bool stage_pass; @@ -1055,10 +1085,24 @@ esp_err_t hub_dev_is_free(uint8_t dev_addr) { assert(dev_addr == ENUM_DEV_ADDR); assert(p_hub_driver_obj->single_thread.root_dev_hdl); - p_hub_driver_obj->single_thread.root_dev_hdl = NULL; // Device is free, we can now request its port be recycled + hcd_port_state_t port_state = hcd_port_get_state(p_hub_driver_obj->constant.root_port_hdl); + p_hub_driver_obj->single_thread.root_dev_hdl = NULL; + HUB_DRIVER_ENTER_CRITICAL(); - p_hub_driver_obj->dynamic.flags.actions |= HUB_DRIVER_FLAG_ACTION_PORT; + // How the port is recycled will depend on the port's state + switch (port_state) { + case HCD_PORT_STATE_ENABLED: + p_hub_driver_obj->dynamic.port_reqs |= PORT_REQ_DISABLE; + break; + case HCD_PORT_STATE_RECOVERY: + p_hub_driver_obj->dynamic.port_reqs |= PORT_REQ_RECOVER; + break; + default: + abort(); // Should never occur + break; + } + p_hub_driver_obj->dynamic.flags.actions |= HUB_DRIVER_FLAG_ACTION_PORT_REQ; HUB_DRIVER_EXIT_CRITICAL(); p_hub_driver_obj->constant.proc_req_cb(USB_PROC_REQ_SOURCE_HUB, false, p_hub_driver_obj->constant.proc_req_cb_arg); @@ -1076,29 +1120,8 @@ esp_err_t hub_process(void) if (action_flags & HUB_DRIVER_FLAG_ACTION_ROOT_EVENT) { root_port_handle_events(p_hub_driver_obj->constant.root_port_hdl); } - if (action_flags & HUB_DRIVER_FLAG_ACTION_PORT) { - // Check current state of port - hcd_port_state_t port_state = hcd_port_get_state(p_hub_driver_obj->constant.root_port_hdl); - switch (port_state) { - case HCD_PORT_STATE_ENABLED: - // Port is still enabled with a connect device. Disable it. - ESP_LOGD(HUB_DRIVER_TAG, "Disabling root port"); - // We allow this to fail in case a disconnect/port error happens while disabling. - hcd_port_command(p_hub_driver_obj->constant.root_port_hdl, HCD_PORT_CMD_DISABLE); - break; - case HCD_PORT_STATE_RECOVERY: - // Port is in recovery after a disconnect/error. Recover it. - ESP_LOGD(HUB_DRIVER_TAG, "Recovering root port"); - ESP_ERROR_CHECK(hcd_port_recover(p_hub_driver_obj->constant.root_port_hdl)); - ESP_ERROR_CHECK(hcd_port_command(p_hub_driver_obj->constant.root_port_hdl, HCD_PORT_CMD_POWER_ON)); - HUB_DRIVER_ENTER_CRITICAL(); - p_hub_driver_obj->dynamic.root_port_state = ROOT_PORT_STATE_POWERED; - HUB_DRIVER_EXIT_CRITICAL(); - break; - default: - abort(); // Should never occur - break; - } + if (action_flags & HUB_DRIVER_FLAG_ACTION_PORT_REQ) { + root_port_req(p_hub_driver_obj->constant.root_port_hdl); } if (action_flags & HUB_DRIVER_FLAG_ACTION_ENUM_EVENT) { enum_handle_events(); From a602befe1b48d8d7529e23d60c9bf04c3ac520f7 Mon Sep 17 00:00:00 2001 From: Darian Leung Date: Wed, 10 Apr 2024 05:06:46 +0800 Subject: [PATCH 5/6] refactor(usb/usbh): Update USBH device creation and enumeration handling This commit updates how the USBH handles device creation and enumeration so that upper layers (such as the Hub driver) can use the USBH API for enumeration instead of calling the HCD. USBH Updates: USBH now creates unenumerated devices set to address 0 with no device/config descriptor. A newly created device can be opened and communicated with immediately (using control transfers). This allows the Hub driver to call the USBH instead of the HCD. Summary of USBH changes: - Added new APIs to add/remove a device. Devices are now created as unenumerated and can be immediately opened and communicated with. - Added new APIs to enumerate a device (see 'usbh_dev_set_...()' functions). Device must be locked (see 'usbh_dev_enum_lock()') before enumeration functions can be called. - Added UID for each device. This allows the particular USBH without needing to use the device's handle (which implies opening the device). Hub Driver Updates: Hub driver now calls the USBH for enumeration. Summary of USBH changes: - Replace all 'hcd_pipe_...()' calls with 'usbh_dev_...()' calls - Refactored port event handling to fit with new USBH API - Updated to use UID to uniquely identify devices without opening them USB Host Updates: - Reroute USBH control transfers to clients and hub driver --- components/usb/hcd_dwc.c | 14 - components/usb/hub.c | 230 ++++---- components/usb/private_include/hcd.h | 16 - components/usb/private_include/hub.h | 12 +- components/usb/private_include/usbh.h | 245 +++++---- components/usb/usb_host.c | 38 +- components/usb/usbh.c | 737 +++++++++++++++++--------- 7 files changed, 769 insertions(+), 523 deletions(-) diff --git a/components/usb/hcd_dwc.c b/components/usb/hcd_dwc.c index bc0c24ddaf..ebfd2c8e79 100644 --- a/components/usb/hcd_dwc.c +++ b/components/usb/hcd_dwc.c @@ -1983,20 +1983,6 @@ esp_err_t hcd_pipe_update_dev_addr(hcd_pipe_handle_t pipe_hdl, uint8_t dev_addr) return ESP_OK; } -esp_err_t hcd_pipe_update_callback(hcd_pipe_handle_t pipe_hdl, hcd_pipe_callback_t callback, void *user_arg) -{ - pipe_t *pipe = (pipe_t *)pipe_hdl; - HCD_ENTER_CRITICAL(); - // Check if pipe is in the correct state to be updated - HCD_CHECK_FROM_CRIT(!pipe->cs_flags.pipe_cmd_processing && - !pipe->cs_flags.has_urb, - ESP_ERR_INVALID_STATE); - pipe->callback = callback; - pipe->callback_arg = user_arg; - HCD_EXIT_CRITICAL(); - return ESP_OK; -} - void *hcd_pipe_get_context(hcd_pipe_handle_t pipe_hdl) { pipe_t *pipe = (pipe_t *)pipe_hdl; diff --git a/components/usb/hub.c b/components/usb/hub.c index 14b8f029c7..2735ef5a46 100644 --- a/components/usb/hub.c +++ b/components/usb/hub.c @@ -40,6 +40,7 @@ implement the bare minimum to control the root HCD port. #define ENUM_CTRL_TRANSFER_MAX_DATA_LEN CONFIG_USB_HOST_CONTROL_TRANSFER_MAX_SIZE #define ENUM_DEV_ADDR 1 // Device address used in enumeration +#define ENUM_DEV_UID 1 // Unique ID for device connected to root port #define ENUM_CONFIG_INDEX_DEFAULT 0 // Index used to get the first configuration descriptor of the device #define ENUM_SHORT_DESC_REQ_LEN 8 // Number of bytes to request when getting a short descriptor (just enough to get bMaxPacketSize0 or wTotalLength) #define ENUM_WORST_CASE_MPS_LS 8 // The worst case MPS of EP0 for a LS device @@ -63,9 +64,8 @@ implement the bare minimum to control the root HCD port. typedef enum { ROOT_PORT_STATE_NOT_POWERED, /**< Root port initialized and/or not powered */ ROOT_PORT_STATE_POWERED, /**< Root port is powered, device is not connected */ - ROOT_PORT_STATE_ENUM, /**< A device has been connected to the root port and is undergoing enumeration */ - ROOT_PORT_STATE_ENUM_FAILED, /**< Enumeration of a connected device has failed. Waiting for that device to be disconnected */ - ROOT_PORT_ACTIVE, /**< The connected device was enumerated and port is active */ + ROOT_PORT_STATE_DISABLED, /**< A device is connected but is disabled (i.e., not reset, no SOFs are sent) */ + ROOT_PORT_STATE_ENABLED, /**< A device is connected, port has been reset, SOFs are sent */ ROOT_PORT_STATE_RECOVERY, /**< Root port encountered an error and needs to be recovered */ } root_port_state_t; @@ -159,7 +159,6 @@ typedef struct { urb_t *urb; /**< URB used for enumeration control transfers. Max data length of ENUM_CTRL_TRANSFER_MAX_DATA_LEN */ // Initialized at start of a particular enumeration usb_device_handle_t dev_hdl; /**< Handle of device being enumerated */ - hcd_pipe_handle_t pipe; /**< Default pipe handle of the device being enumerated */ // Updated during enumeration enum_stage_t stage; /**< Current enumeration stage */ int expect_num_bytes; /**< Expected number of bytes for IN transfers stages. Set to 0 for OUT transfer */ @@ -192,7 +191,7 @@ typedef struct { } dynamic; // Single thread members don't require a critical section so long as they are never accessed from multiple threads struct { - usb_device_handle_t root_dev_hdl; // Indicates if an enumerated device is connected to the root port + unsigned int root_dev_uid; // UID of the device connected to root port. 0 if no device connected enum_ctrl_t enum_ctrl; } single_thread; // Constant members do no change after installation thus do not require a critical section @@ -245,40 +244,26 @@ const char *HUB_DRIVER_TAG = "HUB"; static bool root_port_callback(hcd_port_handle_t port_hdl, hcd_port_event_t port_event, void *user_arg, bool in_isr); /** - * @brief HCD pipe callback for the default pipe of the device under enumeration + * @brief Control transfer callback used for enumeration * - * - This callback is called from the context of the HCD, so any event handling should be deferred to hub_process() - * - This callback needs to call proc_req_cb to ensure that hub_process() gets a chance to run - * - * @param pipe_hdl HCD pipe handle - * @param pipe_event Pipe event - * @param user_arg Callback argument - * @param in_isr Whether callback is in an ISR context - * @return Whether a yield is required + * @param transfer Transfer object */ -static bool enum_dflt_pipe_callback(hcd_pipe_handle_t pipe_hdl, hcd_pipe_event_t pipe_event, void *user_arg, bool in_isr); +static void enum_transfer_callback(usb_transfer_t *transfer); // ------------------------------------------------- Enum Functions ---------------------------------------------------- static bool enum_stage_start(enum_ctrl_t *enum_ctrl) { - // Get the speed of the device, and set the enum MPS to the worst case size for now - usb_speed_t speed; - if (hcd_port_get_speed(p_hub_driver_obj->constant.root_port_hdl, &speed) != ESP_OK) { - return false; - } - enum_ctrl->bMaxPacketSize0 = (speed == USB_SPEED_LOW) ? ENUM_WORST_CASE_MPS_LS : ENUM_WORST_CASE_MPS_FS; - // Try to add the device to USBH - usb_device_handle_t enum_dev_hdl; - hcd_pipe_handle_t enum_dflt_pipe_hdl; - // We use NULL as the parent device to indicate the Root Hub port 1. We currently only support a single device - if (usbh_hub_add_dev(p_hub_driver_obj->constant.root_port_hdl, speed, &enum_dev_hdl, &enum_dflt_pipe_hdl) != ESP_OK) { - return false; - } - // Set our own default pipe callback - ESP_ERROR_CHECK(hcd_pipe_update_callback(enum_dflt_pipe_hdl, enum_dflt_pipe_callback, NULL)); - enum_ctrl->dev_hdl = enum_dev_hdl; - enum_ctrl->pipe = enum_dflt_pipe_hdl; + // Open the newly added device (at address 0) + ESP_ERROR_CHECK(usbh_devs_open(0, &p_hub_driver_obj->single_thread.enum_ctrl.dev_hdl)); + + // Get the speed of the device to set the initial MPS of EP0 + usb_device_info_t dev_info; + ESP_ERROR_CHECK(usbh_dev_get_info(p_hub_driver_obj->single_thread.enum_ctrl.dev_hdl, &dev_info)); + enum_ctrl->bMaxPacketSize0 = (dev_info.speed == USB_SPEED_LOW) ? ENUM_WORST_CASE_MPS_LS : ENUM_WORST_CASE_MPS_FS; + + // Lock the device for enumeration. This allows us call usbh_dev_set_...() functions during enumeration + ESP_ERROR_CHECK(usbh_dev_enum_lock(p_hub_driver_obj->single_thread.enum_ctrl.dev_hdl)); // Flag to gracefully exit the enumeration process if requested by the user in the enumeration filter cb #ifdef ENABLE_ENUM_FILTER_CALLBACK @@ -445,7 +430,7 @@ static bool enum_stage_transfer(enum_ctrl_t *enum_ctrl) abort(); break; } - if (hcd_urb_enqueue(enum_ctrl->pipe, enum_ctrl->urb) != ESP_OK) { + if (usbh_dev_submit_ctrl_urb(enum_ctrl->dev_hdl, enum_ctrl->urb) != ESP_OK) { ESP_LOGE(HUB_DRIVER_TAG, "Failed to submit: %s", enum_stage_strings[enum_ctrl->stage]); return false; } @@ -470,18 +455,10 @@ static bool enum_stage_wait(enum_ctrl_t *enum_ctrl) static bool enum_stage_transfer_check(enum_ctrl_t *enum_ctrl) { - // Dequeue the URB - urb_t *dequeued_enum_urb = hcd_urb_dequeue(enum_ctrl->pipe); - assert(dequeued_enum_urb == enum_ctrl->urb); - // Check transfer status - usb_transfer_t *transfer = &dequeued_enum_urb->transfer; + usb_transfer_t *transfer = &enum_ctrl->urb->transfer; if (transfer->status != USB_TRANSFER_STATUS_COMPLETED) { ESP_LOGE(HUB_DRIVER_TAG, "Bad transfer status %d: %s", transfer->status, enum_stage_strings[enum_ctrl->stage]); - if (transfer->status == USB_TRANSFER_STATUS_STALL) { - // EP stalled, clearing the pipe to execute further stages - ESP_ERROR_CHECK(hcd_pipe_command(enum_ctrl->pipe, HCD_PIPE_CMD_CLEAR)); - } return false; } // Check IN transfer returned the expected correct number of bytes @@ -508,8 +485,8 @@ static bool enum_stage_transfer_check(enum_ctrl_t *enum_ctrl) ret = false; break; } - // Update and save the MPS of the default pipe - if (hcd_pipe_update_mps(enum_ctrl->pipe, device_desc->bMaxPacketSize0) != ESP_OK) { + // Update and save the MPS of the EP0 + if (usbh_dev_set_ep0_mps(enum_ctrl->dev_hdl, device_desc->bMaxPacketSize0) != ESP_OK) { ESP_LOGE(HUB_DRIVER_TAG, "Failed to update MPS"); ret = false; break; @@ -520,16 +497,15 @@ static bool enum_stage_transfer_check(enum_ctrl_t *enum_ctrl) break; } case ENUM_STAGE_CHECK_ADDR: { - // Update the pipe and device's address, and fill the address into the device object - ESP_ERROR_CHECK(hcd_pipe_update_dev_addr(enum_ctrl->pipe, ENUM_DEV_ADDR)); - ESP_ERROR_CHECK(usbh_hub_enum_fill_dev_addr(enum_ctrl->dev_hdl, ENUM_DEV_ADDR)); + // Update the device's address + ESP_ERROR_CHECK(usbh_dev_set_addr(enum_ctrl->dev_hdl, ENUM_DEV_ADDR)); ret = true; break; } case ENUM_STAGE_CHECK_FULL_DEV_DESC: { - // Fill device descriptor into the device object + // Set the device's descriptor const usb_device_desc_t *device_desc = (const usb_device_desc_t *)(transfer->data_buffer + sizeof(usb_setup_packet_t)); - ESP_ERROR_CHECK(usbh_hub_enum_fill_dev_desc(enum_ctrl->dev_hdl, device_desc)); + ESP_ERROR_CHECK(usbh_dev_set_desc(enum_ctrl->dev_hdl, device_desc)); enum_ctrl->iManufacturer = device_desc->iManufacturer; enum_ctrl->iProduct = device_desc->iProduct; enum_ctrl->iSerialNumber = device_desc->iSerialNumber; @@ -558,10 +534,10 @@ static bool enum_stage_transfer_check(enum_ctrl_t *enum_ctrl) break; } case ENUM_STAGE_CHECK_FULL_CONFIG_DESC: { - // Fill configuration descriptor into the device object + // Set the device's configuration descriptor const usb_config_desc_t *config_desc = (usb_config_desc_t *)(transfer->data_buffer + sizeof(usb_setup_packet_t)); enum_ctrl->bConfigurationValue = config_desc->bConfigurationValue; - ESP_ERROR_CHECK(usbh_hub_enum_fill_config_desc(enum_ctrl->dev_hdl, config_desc)); + ESP_ERROR_CHECK(usbh_dev_set_config_desc(enum_ctrl->dev_hdl, config_desc)); ret = true; break; } @@ -638,7 +614,7 @@ static bool enum_stage_transfer_check(enum_ctrl_t *enum_ctrl) } else { // ENUM_STAGE_CHECK_FULL_PROD_STR_DESC select = 2; } - ESP_ERROR_CHECK(usbh_hub_enum_fill_str_desc(enum_ctrl->dev_hdl, str_desc, select)); + ESP_ERROR_CHECK(usbh_dev_set_str_desc(enum_ctrl->dev_hdl, str_desc, select)); ret = true; break; } @@ -653,43 +629,27 @@ static bool enum_stage_transfer_check(enum_ctrl_t *enum_ctrl) static void enum_stage_cleanup(enum_ctrl_t *enum_ctrl) { - // We currently only support a single device connected to the root port. Move the device handle from enum to root - HUB_DRIVER_ENTER_CRITICAL(); - p_hub_driver_obj->dynamic.root_port_state = ROOT_PORT_ACTIVE; - HUB_DRIVER_EXIT_CRITICAL(); - p_hub_driver_obj->single_thread.root_dev_hdl = enum_ctrl->dev_hdl; - usb_device_handle_t dev_hdl = enum_ctrl->dev_hdl; + // Unlock the device as we are done with the enumeration + ESP_ERROR_CHECK(usbh_dev_enum_unlock(enum_ctrl->dev_hdl)); + // Propagate a new device event + ESP_ERROR_CHECK(usbh_devs_new_dev_event(enum_ctrl->dev_hdl)); + // We are done with using the device. Close it. + ESP_ERROR_CHECK(usbh_devs_close(enum_ctrl->dev_hdl)); // Clear values in enum_ctrl enum_ctrl->dev_hdl = NULL; - enum_ctrl->pipe = NULL; - // Update device object after enumeration is done - ESP_ERROR_CHECK(usbh_hub_enum_done(dev_hdl)); } static void enum_stage_cleanup_failed(enum_ctrl_t *enum_ctrl) { - // Enumeration failed. Clear the enum device handle and pipe if (enum_ctrl->dev_hdl) { - // If enumeration failed due to a port event, we need to Halt, flush, and dequeue enum default pipe in case there - // was an in-flight URB. - ESP_ERROR_CHECK(hcd_pipe_command(enum_ctrl->pipe, HCD_PIPE_CMD_HALT)); - ESP_ERROR_CHECK(hcd_pipe_command(enum_ctrl->pipe, HCD_PIPE_CMD_FLUSH)); - hcd_urb_dequeue(enum_ctrl->pipe); // This could return NULL if there - ESP_ERROR_CHECK(usbh_hub_enum_failed(enum_ctrl->dev_hdl)); // Free the underlying device object first before recovering the port + // Close the device and unlock it as we done with enumeration + ESP_ERROR_CHECK(usbh_dev_enum_unlock(enum_ctrl->dev_hdl)); + ESP_ERROR_CHECK(usbh_devs_close(enum_ctrl->dev_hdl)); + // We allow this to fail in case the device object was already freed + usbh_devs_remove(ENUM_DEV_UID); } // Clear values in enum_ctrl enum_ctrl->dev_hdl = NULL; - enum_ctrl->pipe = NULL; - HUB_DRIVER_ENTER_CRITICAL(); - // Enum could have failed due to a port error. If so, we need to trigger a port recovery - if (p_hub_driver_obj->dynamic.root_port_state == ROOT_PORT_STATE_RECOVERY) { - p_hub_driver_obj->dynamic.port_reqs |= PORT_REQ_RECOVER; - p_hub_driver_obj->dynamic.flags.actions |= HUB_DRIVER_FLAG_ACTION_PORT_REQ; - } else { - // Otherwise, we move to the enum failed state and wait for the device to disconnect - p_hub_driver_obj->dynamic.root_port_state = ROOT_PORT_STATE_ENUM_FAILED; - } - HUB_DRIVER_EXIT_CRITICAL(); } static enum_stage_t get_next_stage(enum_stage_t old_stage, enum_ctrl_t *enum_ctrl) @@ -803,13 +763,13 @@ static bool root_port_callback(hcd_port_handle_t port_hdl, hcd_port_event_t port return p_hub_driver_obj->constant.proc_req_cb(USB_PROC_REQ_SOURCE_HUB, in_isr, p_hub_driver_obj->constant.proc_req_cb_arg); } -static bool enum_dflt_pipe_callback(hcd_pipe_handle_t pipe_hdl, hcd_pipe_event_t pipe_event, void *user_arg, bool in_isr) +static void enum_transfer_callback(usb_transfer_t *transfer) { - // Note: This callback may have triggered when a failed enumeration is already cleaned up (e.g., due to a failed port reset) + // We simply trigger a processing request to handle the completed enumeration control transfer HUB_DRIVER_ENTER_CRITICAL_SAFE(); p_hub_driver_obj->dynamic.flags.actions |= HUB_DRIVER_FLAG_ACTION_ENUM_EVENT; HUB_DRIVER_EXIT_CRITICAL_SAFE(); - return p_hub_driver_obj->constant.proc_req_cb(USB_PROC_REQ_SOURCE_HUB, in_isr, p_hub_driver_obj->constant.proc_req_cb_arg); + p_hub_driver_obj->constant.proc_req_cb(USB_PROC_REQ_SOURCE_HUB, false, p_hub_driver_obj->constant.proc_req_cb_arg); } // ---------------------- Handlers ------------------------- @@ -822,17 +782,32 @@ static void root_port_handle_events(hcd_port_handle_t root_port_hdl) // Nothing to do break; case HCD_PORT_EVENT_CONNECTION: { - if (hcd_port_command(root_port_hdl, HCD_PORT_CMD_RESET) == ESP_OK) { - ESP_LOGD(HUB_DRIVER_TAG, "Root port reset"); - // Start enumeration - HUB_DRIVER_ENTER_CRITICAL(); - p_hub_driver_obj->dynamic.flags.actions |= HUB_DRIVER_FLAG_ACTION_ENUM_EVENT; - p_hub_driver_obj->dynamic.root_port_state = ROOT_PORT_STATE_ENUM; - HUB_DRIVER_EXIT_CRITICAL(); - p_hub_driver_obj->single_thread.enum_ctrl.stage = ENUM_STAGE_START; - } else { + if (hcd_port_command(root_port_hdl, HCD_PORT_CMD_RESET) != ESP_OK) { ESP_LOGE(HUB_DRIVER_TAG, "Root port reset failed"); + goto reset_err; } + ESP_LOGD(HUB_DRIVER_TAG, "Root port reset"); + usb_speed_t speed; + if (hcd_port_get_speed(p_hub_driver_obj->constant.root_port_hdl, &speed) != ESP_OK) { + goto new_dev_err; + } + // Allocate a new device. We use a fixed ENUM_DEV_UID for now since we only support a single device + if (usbh_devs_add(ENUM_DEV_UID, speed, p_hub_driver_obj->constant.root_port_hdl) != ESP_OK) { + ESP_LOGE(HUB_DRIVER_TAG, "Failed to add device"); + goto new_dev_err; + } + p_hub_driver_obj->single_thread.root_dev_uid = ENUM_DEV_UID; + // Start enumeration + HUB_DRIVER_ENTER_CRITICAL(); + p_hub_driver_obj->dynamic.flags.actions |= HUB_DRIVER_FLAG_ACTION_ENUM_EVENT; + p_hub_driver_obj->dynamic.root_port_state = ROOT_PORT_STATE_ENABLED; + HUB_DRIVER_EXIT_CRITICAL(); + p_hub_driver_obj->single_thread.enum_ctrl.stage = ENUM_STAGE_START; + break; +new_dev_err: + // We allow this to fail in case a disconnect/port error happens while disabling. + hcd_port_command(p_hub_driver_obj->constant.root_port_hdl, HCD_PORT_CMD_DISABLE); +reset_err: break; } case HCD_PORT_EVENT_DISCONNECTION: @@ -842,18 +817,13 @@ static void root_port_handle_events(hcd_port_handle_t root_port_hdl) HUB_DRIVER_ENTER_CRITICAL(); switch (p_hub_driver_obj->dynamic.root_port_state) { case ROOT_PORT_STATE_POWERED: // This occurred before enumeration - case ROOT_PORT_STATE_ENUM_FAILED: // This occurred after a failed enumeration. - // Therefore, there's no device and we can go straight to port recovery + case ROOT_PORT_STATE_DISABLED: // This occurred after the device has already been disabled + // Therefore, there's no device object to clean up, and we can go straight to port recovery p_hub_driver_obj->dynamic.port_reqs |= PORT_REQ_RECOVER; p_hub_driver_obj->dynamic.flags.actions |= HUB_DRIVER_FLAG_ACTION_PORT_REQ; break; - case ROOT_PORT_STATE_ENUM: - // This occurred during enumeration. Therefore, we need to cleanup the failed enumeration - p_hub_driver_obj->dynamic.flags.actions |= HUB_DRIVER_FLAG_ACTION_ENUM_EVENT; - p_hub_driver_obj->single_thread.enum_ctrl.stage = ENUM_STAGE_CLEANUP_FAILED; - break; - case ROOT_PORT_ACTIVE: - // There was an enumerated device. We need to indicate to USBH that the device is gone + case ROOT_PORT_STATE_ENABLED: + // There is an enabled (active) device. We need to indicate to USBH that the device is gone pass_event_to_usbh = true; break; default: @@ -863,7 +833,10 @@ static void root_port_handle_events(hcd_port_handle_t root_port_hdl) p_hub_driver_obj->dynamic.root_port_state = ROOT_PORT_STATE_RECOVERY; HUB_DRIVER_EXIT_CRITICAL(); if (pass_event_to_usbh) { - ESP_ERROR_CHECK(usbh_hub_dev_gone(p_hub_driver_obj->single_thread.root_dev_hdl)); + // The port must have a device object + assert(p_hub_driver_obj->single_thread.root_dev_uid != 0); + // We allow this to fail in case the device object was already freed + usbh_devs_remove(p_hub_driver_obj->single_thread.root_dev_uid); } break; } @@ -955,7 +928,6 @@ static void enum_handle_events(void) stage_pass = true; break; default: - // Note: Don't abort here. The enum_dflt_pipe_callback() can trigger a HUB_DRIVER_FLAG_ACTION_ENUM_EVENT after a cleanup. stage_pass = true; break; } @@ -977,18 +949,22 @@ static void enum_handle_events(void) // ---------------------------------------------- Hub Driver Functions ------------------------------------------------- -esp_err_t hub_install(hub_config_t *hub_config) +esp_err_t hub_install(hub_config_t *hub_config, void **client_ret) { HUB_DRIVER_ENTER_CRITICAL(); HUB_DRIVER_CHECK_FROM_CRIT(p_hub_driver_obj == NULL, ESP_ERR_INVALID_STATE); HUB_DRIVER_EXIT_CRITICAL(); + esp_err_t ret; + // Allocate Hub driver object hub_driver_t *hub_driver_obj = heap_caps_calloc(1, sizeof(hub_driver_t), MALLOC_CAP_DEFAULT); urb_t *enum_urb = urb_alloc(sizeof(usb_setup_packet_t) + ENUM_CTRL_TRANSFER_MAX_DATA_LEN, 0); if (hub_driver_obj == NULL || enum_urb == NULL) { return ESP_ERR_NO_MEM; } - esp_err_t ret; + enum_urb->usb_host_client = (void *)hub_driver_obj; + enum_urb->transfer.callback = enum_transfer_callback; + // Install HCD port hcd_port_config_t port_config = { .fifo_bias = HUB_ROOT_HCD_PORT_FIFO_BIAS, @@ -1001,6 +977,7 @@ esp_err_t hub_install(hub_config_t *hub_config) if (ret != ESP_OK) { goto err; } + // Initialize Hub driver object hub_driver_obj->single_thread.enum_ctrl.stage = ENUM_STAGE_NONE; hub_driver_obj->single_thread.enum_ctrl.urb = enum_urb; @@ -1020,6 +997,9 @@ esp_err_t hub_install(hub_config_t *hub_config) } p_hub_driver_obj = hub_driver_obj; HUB_DRIVER_EXIT_CRITICAL(); + + // Write-back client_ret pointer + *client_ret = (void *)hub_driver_obj; ret = ESP_OK; return ret; @@ -1081,31 +1061,31 @@ esp_err_t hub_root_stop(void) return ret; } -esp_err_t hub_dev_is_free(uint8_t dev_addr) +esp_err_t hub_port_recycle(unsigned int dev_uid) { - assert(dev_addr == ENUM_DEV_ADDR); - assert(p_hub_driver_obj->single_thread.root_dev_hdl); - // Device is free, we can now request its port be recycled - hcd_port_state_t port_state = hcd_port_get_state(p_hub_driver_obj->constant.root_port_hdl); - p_hub_driver_obj->single_thread.root_dev_hdl = NULL; + if (dev_uid == p_hub_driver_obj->single_thread.root_dev_uid) { + // Device is free, we can now request its port be recycled + hcd_port_state_t port_state = hcd_port_get_state(p_hub_driver_obj->constant.root_port_hdl); + p_hub_driver_obj->single_thread.root_dev_uid = 0; + HUB_DRIVER_ENTER_CRITICAL(); + // How the port is recycled will depend on the port's state + switch (port_state) { + case HCD_PORT_STATE_ENABLED: + p_hub_driver_obj->dynamic.port_reqs |= PORT_REQ_DISABLE; + break; + case HCD_PORT_STATE_RECOVERY: + p_hub_driver_obj->dynamic.port_reqs |= PORT_REQ_RECOVER; + break; + default: + abort(); // Should never occur + break; + } + p_hub_driver_obj->dynamic.flags.actions |= HUB_DRIVER_FLAG_ACTION_PORT_REQ; + HUB_DRIVER_EXIT_CRITICAL(); - HUB_DRIVER_ENTER_CRITICAL(); - // How the port is recycled will depend on the port's state - switch (port_state) { - case HCD_PORT_STATE_ENABLED: - p_hub_driver_obj->dynamic.port_reqs |= PORT_REQ_DISABLE; - break; - case HCD_PORT_STATE_RECOVERY: - p_hub_driver_obj->dynamic.port_reqs |= PORT_REQ_RECOVER; - break; - default: - abort(); // Should never occur - break; + p_hub_driver_obj->constant.proc_req_cb(USB_PROC_REQ_SOURCE_HUB, false, p_hub_driver_obj->constant.proc_req_cb_arg); } - p_hub_driver_obj->dynamic.flags.actions |= HUB_DRIVER_FLAG_ACTION_PORT_REQ; - HUB_DRIVER_EXIT_CRITICAL(); - p_hub_driver_obj->constant.proc_req_cb(USB_PROC_REQ_SOURCE_HUB, false, p_hub_driver_obj->constant.proc_req_cb_arg); return ESP_OK; } diff --git a/components/usb/private_include/hcd.h b/components/usb/private_include/hcd.h index 24ec22b085..1fd3617307 100644 --- a/components/usb/private_include/hcd.h +++ b/components/usb/private_include/hcd.h @@ -418,22 +418,6 @@ esp_err_t hcd_pipe_update_mps(hcd_pipe_handle_t pipe_hdl, int mps); */ esp_err_t hcd_pipe_update_dev_addr(hcd_pipe_handle_t pipe_hdl, uint8_t dev_addr); -/** - * @brief Update a pipe's callback - * - * This function is intended to be called on default pipes at the end of enumeration to switch to a callback that - * handles the completion of regular control transfer. - * - Pipe is not current processing a command - * - Pipe does not have any enqueued URBs - * - Port cannot be resetting - * - * @param pipe_hdl Pipe handle - * @param callback Callback - * @param user_arg Callback argument - * @return esp_err_t - */ -esp_err_t hcd_pipe_update_callback(hcd_pipe_handle_t pipe_hdl, hcd_pipe_callback_t callback, void *user_arg); - /** * @brief Get the context variable of a pipe from its handle * diff --git a/components/usb/private_include/hub.h b/components/usb/private_include/hub.h index a096de8fd9..cf85ad861d 100644 --- a/components/usb/private_include/hub.h +++ b/components/usb/private_include/hub.h @@ -42,9 +42,10 @@ typedef struct { * - Initializes the HCD root port * * @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 */ -esp_err_t hub_install(hub_config_t *hub_config); +esp_err_t hub_install(hub_config_t *hub_config, void **client_ret); /** * @brief Uninstall Hub driver @@ -78,15 +79,16 @@ esp_err_t hub_root_start(void); esp_err_t hub_root_stop(void); /** - * @brief Indicate to the Hub driver that a device has been freed + * @brief Indicate to the Hub driver that a device's port can be recycled * - * Hub driver can now recover the port that the device was connected to + * The device connected to the port has been freed. The Hub driver can now + * recycled the port. * - * @param dev_addr Device address + * @param dev_uid Device's unique ID * @return * - ESP_OK: Success */ -esp_err_t hub_dev_is_free(uint8_t dev_addr); +esp_err_t hub_port_recycle(unsigned int dev_uid); /** * @brief Hub driver's processing function diff --git a/components/usb/private_include/usbh.h b/components/usb/private_include/usbh.h index 6dee5e55b4..a1b5b2a845 100644 --- a/components/usb/private_include/usbh.h +++ b/components/usb/private_include/usbh.h @@ -58,7 +58,7 @@ typedef struct { usb_device_handle_t dev_hdl; } dev_gone_data; struct { - uint8_t dev_addr; + unsigned int dev_uid; } dev_free_data; }; } usbh_event_data_t; @@ -195,6 +195,32 @@ esp_err_t usbh_devs_num(int *num_devs_ret); */ esp_err_t usbh_devs_addr_list_fill(int list_len, uint8_t *dev_addr_list, int *num_dev_ret); +/** + * @brief Create a device and add it to the device pool + * + * The created device will not be enumerated where the device's address is 0, + * device and config descriptor are NULL. The device will still have a default + * pipe, thus allowing control transfers to be submitted. + * + * - Call usbh_devs_open() before communicating with the device + * - Call usbh_dev_enum_lock() before enumerating the device via the various + * usbh_dev_set_...() functions. + * + * @param[in] uid Unique ID assigned to the device + * @param[in] dev_speed Device's speed + * @param[in] port_hdl Handle of the port that the device is connected to + * @return esp_err_t + */ +esp_err_t usbh_devs_add(unsigned int uid, usb_speed_t dev_speed, hcd_port_handle_t port_hdl); + +/** + * @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 + */ +esp_err_t usbh_devs_remove(unsigned int uid); + /** * @brief Mark that all devices should be freed at the next possible opportunity * @@ -227,6 +253,16 @@ esp_err_t usbh_devs_open(uint8_t dev_addr, usb_device_handle_t *dev_hdl); */ esp_err_t usbh_devs_close(usb_device_handle_t dev_hdl); +/** + * @brief Trigger a USBH_EVENT_NEW_DEV event for the device + * + * This is typically called after a device has been fully enumerated. + * + * @param[in] dev_hdl Device handle + * @return esp_err_t + */ +esp_err_t usbh_devs_new_dev_event(usb_device_handle_t dev_hdl); + // ------------------------------------------------ Device Functions --------------------------------------------------- // ----------------------- Getters ------------------------- @@ -245,7 +281,8 @@ esp_err_t usbh_dev_get_addr(usb_device_handle_t dev_hdl, uint8_t *dev_addr); /** * @brief Get a device's information * - * @note This function can block + * @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 @@ -257,6 +294,8 @@ 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. * @param[in] dev_hdl Device handle * @param[out] dev_desc_ret Device descriptor * @return esp_err_t @@ -268,13 +307,109 @@ esp_err_t usbh_dev_get_desc(usb_device_handle_t dev_hdl, const usb_device_desc_t * * Simply returns a reference to the internally cached configuration descriptor * - * @note This function can block + * @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 */ esp_err_t usbh_dev_get_config_desc(usb_device_handle_t dev_hdl, const usb_config_desc_t **config_desc_ret); +// ----------------------- Setters ------------------------- + +/** + * @brief Lock a device for enumeration + * + * - A device's enumeration lock must be set before any of its enumeration fields + * (e.g., address, device/config descriptors) can be set/updated. + * - The caller must be the sole opener of the device (see 'usbh_devs_open()') + * when locking the device for enumeration. + * + * @param[in] dev_hdl Device handle + * @return esp_err_t + */ +esp_err_t usbh_dev_enum_lock(usb_device_handle_t dev_hdl); + +/** + * @brief Release a device's enumeration lock + * + * @param[in] dev_hdl Device handle + * @return esp_err_t + */ +esp_err_t usbh_dev_enum_unlock(usb_device_handle_t dev_hdl); + +/** + * @brief Set the maximum packet size of EP0 for a device + * + * Typically called during enumeration after obtaining the first 8 bytes of the + * device's descriptor. + * + * @note The device's enumeration lock must be set before calling this function + * (see 'usbh_dev_enum_lock()') + * @param[in] dev_hdl Device handle + * @param[in] wMaxPacketSize Maximum packet size + * @return esp_err_t + */ +esp_err_t usbh_dev_set_ep0_mps(usb_device_handle_t dev_hdl, uint16_t wMaxPacketSize); + +/** + * @brief Set a device's address + * + * Typically called during enumeration after a SET_ADDRESSS request has be + * sent to the device. + * + * @note The device's enumeration lock must be set before calling this function + * (see 'usbh_dev_enum_lock()') + * @param[in] dev_hdl Device handle + * @param[in] dev_addr + * @return esp_err_t + */ +esp_err_t usbh_dev_set_addr(usb_device_handle_t dev_hdl, uint8_t dev_addr); + +/** + * @brief Set a device's descriptor + * + * Typically called during enumeration after obtaining the device's descriptor + * via a GET_DESCRIPTOR request. + * + * @note The device's enumeration lock must be set before calling this function + * (see 'usbh_dev_enum_lock()') + * @param[in] dev_hdl Device handle + * @param[in] device_desc Device descriptor to copy + * @return esp_err_t + */ +esp_err_t usbh_dev_set_desc(usb_device_handle_t dev_hdl, const usb_device_desc_t *device_desc); + +/** + * @brief Set a device's configuration descriptor + * + * Typically called during enumeration after obtaining the device's configuration + * descriptor via a GET_DESCRIPTOR request. + * + * @note The device's enumeration lock must be set before calling this function + * (see 'usbh_dev_enum_lock()') + * @param[in] dev_hdl Device handle + * @param[in] config_desc_full Configuration descriptor to copy + * @return esp_err_t + */ +esp_err_t usbh_dev_set_config_desc(usb_device_handle_t dev_hdl, const usb_config_desc_t *config_desc_full); + +/** + * @brief Set a device's string descriptor + * + * Typically called during enumeration after obtaining one of the device's string + * descriptor via a GET_DESCRIPTOR request. + * + * @note The device's enumeration lock must be set before calling this function + * (see 'usbh_dev_enum_lock()') + * @param[in] dev_hdl Device handle + * @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 + */ +esp_err_t usbh_dev_set_str_desc(usb_device_handle_t dev_hdl, const usb_str_desc_t *str_desc, int select); + // ----------------------------------------------- Endpoint Functions ------------------------------------------------- /** @@ -381,110 +516,6 @@ esp_err_t usbh_ep_enqueue_urb(usbh_ep_handle_t ep_hdl, urb_t *urb); */ esp_err_t usbh_ep_dequeue_urb(usbh_ep_handle_t ep_hdl, urb_t **urb_ret); -// -------------------------------------------------- Hub Functions ---------------------------------------------------- - -// ------------------- Device Related ---------------------- - -/** - * @brief Indicates to USBH the start of enumeration for a device - * - * - The Hub driver calls this function before it starts enumerating a new device. - * - The USBH will allocate a new device that will be initialized by the Hub driver using the remaining hub enumeration - * functions. - * - The new device's default pipe handle is returned to all the Hub driver to be used during enumeration. - * - * @note Hub Driver only - * @param[in] port_hdl Handle of the port that the device is connected to - * @param[in] dev_speed Device's speed - * @param[out] new_dev_hdl Device's handle - * @param[out] default_pipe_hdl Device's default pipe handle - * @return esp_err_t - */ -esp_err_t usbh_hub_add_dev(hcd_port_handle_t port_hdl, usb_speed_t dev_speed, usb_device_handle_t *new_dev_hdl, hcd_pipe_handle_t *default_pipe_hdl); - -/** - * @brief Indicates to the USBH that a device is gone - * - * @param dev_hdl Device handle - * @return esp_err_t - */ -esp_err_t usbh_hub_dev_gone(usb_device_handle_t dev_hdl); - -// ----------------- Enumeration Related ------------------- - -/** - * @brief Assign the enumerating device's address - * - * @note Hub Driver only - * @note Must call in sequence - * @param[in] dev_hdl Device handle - * @param dev_addr - * @return esp_err_t - */ -esp_err_t usbh_hub_enum_fill_dev_addr(usb_device_handle_t dev_hdl, uint8_t dev_addr); - -/** - * @brief Fill the enumerating device's descriptor - * - * @note Hub Driver only - * @note Must call in sequence - * @param[in] dev_hdl Device handle - * @param device_desc - * @return esp_err_t - */ -esp_err_t usbh_hub_enum_fill_dev_desc(usb_device_handle_t dev_hdl, const usb_device_desc_t *device_desc); - -/** - * @brief Fill the enumerating device's active configuration descriptor - * - * @note Hub Driver only - * @note Must call in sequence - * @note This function can block - * @param[in] dev_hdl Device handle - * @param config_desc_full - * @return esp_err_t - */ -esp_err_t usbh_hub_enum_fill_config_desc(usb_device_handle_t dev_hdl, const usb_config_desc_t *config_desc_full); - -/** - * @brief Fill one of the string descriptors of the enumerating device - * - * @note Hub Driver only - * @note Must call in sequence - * @param dev_hdl Device handle - * @param str_desc Pointer to string descriptor - * @param select Select which string descriptor. 0/1/2 for Manufacturer/Product/Serial Number string descriptors respectively - * @return esp_err_t - */ -esp_err_t usbh_hub_enum_fill_str_desc(usb_device_handle_t dev_hdl, const usb_str_desc_t *str_desc, int select); - -/** - * @brief Indicate the device enumeration is completed - * - * This will allow the device to be opened by clients, and also trigger a USBH_EVENT_NEW_DEV event. - * - * @note Hub Driver only - * @note Must call in sequence - * @note This function can block - * @param[in] dev_hdl Device handle - * @return esp_err_t - */ -esp_err_t usbh_hub_enum_done(usb_device_handle_t dev_hdl); - -/** - * @brief Indicate that device enumeration has failed - * - * This will cause the enumerating device's resources to be cleaned up - * The Hub Driver must guarantee that the enumerating device's default pipe is already halted, flushed, and dequeued. - * - * @note Hub Driver only - * @note Must call in sequence - * @note This function can block - * @param[in] dev_hdl Device handle - * @return esp_err_t - */ -esp_err_t usbh_hub_enum_failed(usb_device_handle_t dev_hdl); - #ifdef __cplusplus } #endif diff --git a/components/usb/usb_host.c b/components/usb/usb_host.c index b9b12dafcc..b2e5ed137a 100644 --- a/components/usb/usb_host.c +++ b/components/usb/usb_host.c @@ -148,6 +148,7 @@ typedef struct { SemaphoreHandle_t event_sem; SemaphoreHandle_t mux_lock; usb_phy_handle_t phy_handle; // Will be NULL if host library is installed with skip_phy_setup + void *hub_client; // Pointer to Hub driver (acting as a client). Used to reroute completed USBH control transfers } constant; } host_lib_t; @@ -171,8 +172,15 @@ static inline void _clear_client_opened_device(client_t *client_obj, uint8_t dev static inline bool _check_client_opened_device(client_t *client_obj, uint8_t dev_addr) { - assert(dev_addr != 0); - return (client_obj->dynamic.opened_dev_addr_map & (1 << (dev_addr - 1))); + bool ret; + + if (dev_addr != 0) { + ret = client_obj->dynamic.opened_dev_addr_map & (1 << (dev_addr - 1)); + } else { + ret = false; + } + + return ret; } static bool _unblock_client(client_t *client_obj, bool in_isr) @@ -268,14 +276,18 @@ static void usbh_event_callback(usbh_event_data_t *event_data, void *arg) case USBH_EVENT_CTRL_XFER: { assert(event_data->ctrl_xfer_data.urb != NULL); assert(event_data->ctrl_xfer_data.urb->usb_host_client != NULL); - // Redistribute done control transfer to the clients that submitted them - client_t *client_obj = (client_t *)event_data->ctrl_xfer_data.urb->usb_host_client; - - HOST_ENTER_CRITICAL(); - TAILQ_INSERT_TAIL(&client_obj->dynamic.done_ctrl_xfer_tailq, event_data->ctrl_xfer_data.urb, tailq_entry); - client_obj->dynamic.num_done_ctrl_xfer++; - _unblock_client(client_obj, false); - HOST_EXIT_CRITICAL(); + // Redistribute completed control transfers to the clients that submitted them + if (event_data->ctrl_xfer_data.urb->usb_host_client == p_host_lib_obj->constant.hub_client) { + // Redistribute to Hub driver. Simply call the transfer callback + event_data->ctrl_xfer_data.urb->transfer.callback(&event_data->ctrl_xfer_data.urb->transfer); + } else { + client_t *client_obj = (client_t *)event_data->ctrl_xfer_data.urb->usb_host_client; + HOST_ENTER_CRITICAL(); + TAILQ_INSERT_TAIL(&client_obj->dynamic.done_ctrl_xfer_tailq, event_data->ctrl_xfer_data.urb, tailq_entry); + client_obj->dynamic.num_done_ctrl_xfer++; + _unblock_client(client_obj, false); + HOST_EXIT_CRITICAL(); + } break; } case USBH_EVENT_NEW_DEV: { @@ -297,8 +309,8 @@ static void usbh_event_callback(usbh_event_data_t *event_data, void *arg) break; } case USBH_EVENT_DEV_FREE: { - // Let the Hub driver know that the device is free - ESP_ERROR_CHECK(hub_dev_is_free(event_data->dev_free_data.dev_addr)); + // Let the Hub driver know that the device is free and its port can be recycled + ESP_ERROR_CHECK(hub_port_recycle(event_data->dev_free_data.dev_uid)); break; } case USBH_EVENT_ALL_FREE: { @@ -420,7 +432,7 @@ esp_err_t usb_host_install(const usb_host_config_t *config) .enum_filter_cb = config->enum_filter_cb, #endif // ENABLE_ENUM_FILTER_CALLBACK }; - ret = hub_install(&hub_config); + ret = hub_install(&hub_config, &host_lib_obj->constant.hub_client); if (ret != ESP_OK) { goto hub_err; } diff --git a/components/usb/usbh.c b/components/usb/usbh.c index 06d6f8d942..b402e72a99 100644 --- a/components/usb/usbh.c +++ b/components/usb/usbh.c @@ -57,7 +57,8 @@ struct device_s { uint32_t in_pending_list: 1; uint32_t is_gone: 1; // Device is gone (disconnected or port error) uint32_t waiting_free: 1; // Device object is awaiting to be freed - uint32_t reserved29: 29; + uint32_t enum_lock: 1; // Device is locked for enumeration. Enum information (e.g., address, device/config desc etc) may change + uint32_t reserved28: 28; }; uint32_t val; } flags; @@ -74,17 +75,22 @@ struct device_s { */ endpoint_t *endpoints[NUM_NON_DEFAULT_EP]; } mux_protected; - // Constant members do not change after device allocation and enumeration thus do not require a critical section + // Constant members do not require a critical section struct { + // Assigned on device allocation and remain constant for the device's lifetime hcd_pipe_handle_t default_pipe; hcd_port_handle_t port_hdl; - uint8_t address; usb_speed_t speed; - const usb_device_desc_t *desc; - const usb_config_desc_t *config_desc; - const usb_str_desc_t *str_desc_manu; - const usb_str_desc_t *str_desc_product; - const usb_str_desc_t *str_desc_ser_num; + unsigned int uid; + /* + These fields are can only be changed when enum_lock is set, thus can be treated as constant + */ + uint8_t address; + usb_device_desc_t *desc; + usb_config_desc_t *config_desc; + usb_str_desc_t *str_desc_manu; + usb_str_desc_t *str_desc_product; + usb_str_desc_t *str_desc_ser_num; } constant; }; @@ -143,6 +149,50 @@ static bool _dev_set_actions(device_t *dev_obj, uint32_t action_flags); // ----------------------------------------------------- Helpers ------------------------------------------------------- +static device_t *_find_dev_from_uid(unsigned int uid) +{ + /* + THIS FUNCTION MUST BE CALLED FROM A CRITICAL SECTION + */ + device_t *dev_iter; + + // Search the device lists for a device with the specified address + TAILQ_FOREACH(dev_iter, &p_usbh_obj->dynamic.devs_idle_tailq, dynamic.tailq_entry) { + if (dev_iter->constant.uid == uid) { + return dev_iter; + } + } + TAILQ_FOREACH(dev_iter, &p_usbh_obj->dynamic.devs_pending_tailq, dynamic.tailq_entry) { + if (dev_iter->constant.uid == uid) { + return dev_iter; + } + } + + return NULL; +} + +static device_t *_find_dev_from_addr(uint8_t dev_addr) +{ + /* + THIS FUNCTION MUST BE CALLED FROM A CRITICAL SECTION + */ + device_t *dev_iter; + + // Search the device lists for a device with the specified address + TAILQ_FOREACH(dev_iter, &p_usbh_obj->dynamic.devs_idle_tailq, dynamic.tailq_entry) { + if (dev_iter->constant.address == dev_addr) { + return dev_iter; + } + } + TAILQ_FOREACH(dev_iter, &p_usbh_obj->dynamic.devs_pending_tailq, dynamic.tailq_entry) { + if (dev_iter->constant.address == dev_addr) { + return dev_iter; + } + } + + return NULL; +} + static inline bool check_ep_addr(uint8_t bEndpointAddress) { /* @@ -204,13 +254,21 @@ static bool urb_check_args(urb_t *urb) return true; } -static bool transfer_check_usb_compliance(usb_transfer_t *transfer, usb_transfer_type_t type, int mps, bool is_in) +static bool transfer_check_usb_compliance(usb_transfer_t *transfer, usb_transfer_type_t type, unsigned int mps, bool is_in) { if (type == USB_TRANSFER_TYPE_CTRL) { // Check that num_bytes and wLength are set correctly usb_setup_packet_t *setup_pkt = (usb_setup_packet_t *)transfer->data_buffer; - if (transfer->num_bytes != sizeof(usb_setup_packet_t) + setup_pkt->wLength) { - ESP_LOGE(USBH_TAG, "usb_transfer_t num_bytes and usb_setup_packet_t wLength mismatch"); + bool mismatch = false; + if (is_in) { + // For IN transfers, 'num_bytes >= sizeof(usb_setup_packet_t) + setup_pkt->wLength' due to MPS rounding + mismatch = (transfer->num_bytes < sizeof(usb_setup_packet_t) + setup_pkt->wLength); + } else { + // For OUT transfers, num_bytes must match 'sizeof(usb_setup_packet_t) + setup_pkt->wLength' + mismatch = (transfer->num_bytes != sizeof(usb_setup_packet_t) + setup_pkt->wLength); + } + if (mismatch) { + ESP_LOGE(USBH_TAG, "usb_transfer_t num_bytes %d and usb_setup_packet_t wLength %d mismatch", transfer->num_bytes, setup_pkt->wLength); return false; } } else if (type == USB_TRANSFER_TYPE_ISOCHRONOUS) { @@ -300,19 +358,21 @@ static void endpoint_free(endpoint_t *ep_obj) heap_caps_free(ep_obj); } -static esp_err_t device_alloc(hcd_port_handle_t port_hdl, usb_speed_t speed, device_t **dev_obj_ret) +static esp_err_t device_alloc(unsigned int uid, + usb_speed_t speed, + hcd_port_handle_t port_hdl, + device_t **dev_obj_ret) { - esp_err_t ret; device_t *dev_obj = heap_caps_calloc(1, sizeof(device_t), MALLOC_CAP_DEFAULT); - usb_device_desc_t *dev_desc = heap_caps_calloc(1, sizeof(usb_device_desc_t), MALLOC_CAP_DEFAULT); - if (dev_obj == NULL || dev_desc == NULL) { - ret = ESP_ERR_NO_MEM; - goto err; + if (dev_obj == NULL) { + return ESP_ERR_NO_MEM; } - // Allocate a pipe for EP0. We set the pipe callback to NULL for now + + esp_err_t ret; + // Allocate a pipe for EP0 hcd_pipe_config_t pipe_config = { - .callback = NULL, - .callback_arg = NULL, + .callback = ep0_pipe_callback, + .callback_arg = (void *)dev_obj, .context = (void *)dev_obj, .ep_desc = NULL, // No endpoint descriptor means we're allocating a pipe for EP0 .dev_speed = speed, @@ -327,15 +387,17 @@ static esp_err_t device_alloc(hcd_port_handle_t port_hdl, usb_speed_t speed, dev dev_obj->dynamic.state = USB_DEVICE_STATE_DEFAULT; dev_obj->constant.default_pipe = default_pipe_hdl; dev_obj->constant.port_hdl = port_hdl; - // Note: dev_obj->constant.address is assigned later during enumeration dev_obj->constant.speed = speed; - dev_obj->constant.desc = dev_desc; + dev_obj->constant.uid = uid; + // Note: Enumeration related dev_obj->constant fields are initialized later using usbh_dev_set_...() functions + + // Write-back device object *dev_obj_ret = dev_obj; ret = ESP_OK; + return ret; err: - heap_caps_free(dev_desc); heap_caps_free(dev_obj); return ret; } @@ -345,21 +407,24 @@ static void device_free(device_t *dev_obj) if (dev_obj == NULL) { return; } - // Configuration might not have been allocated (in case of early enumeration failure) - if (dev_obj->constant.config_desc) { - heap_caps_free((usb_config_desc_t *)dev_obj->constant.config_desc); + // Device descriptor might not have been set yet + if (dev_obj->constant.desc) { + heap_caps_free(dev_obj->constant.desc); } - // String descriptors might not have been allocated (in case of early enumeration failure) + // Configuration descriptor might not have been set yet + if (dev_obj->constant.config_desc) { + heap_caps_free(dev_obj->constant.config_desc); + } + // String descriptors might not have been set yet if (dev_obj->constant.str_desc_manu) { - heap_caps_free((usb_str_desc_t *)dev_obj->constant.str_desc_manu); + heap_caps_free(dev_obj->constant.str_desc_manu); } if (dev_obj->constant.str_desc_product) { - heap_caps_free((usb_str_desc_t *)dev_obj->constant.str_desc_product); + heap_caps_free(dev_obj->constant.str_desc_product); } if (dev_obj->constant.str_desc_ser_num) { - heap_caps_free((usb_str_desc_t *)dev_obj->constant.str_desc_ser_num); + heap_caps_free(dev_obj->constant.str_desc_ser_num); } - heap_caps_free((usb_device_desc_t *)dev_obj->constant.desc); ESP_ERROR_CHECK(hcd_pipe_free(dev_obj->constant.default_pipe)); heap_caps_free(dev_obj); } @@ -426,6 +491,9 @@ static bool epN_pipe_callback(hcd_pipe_handle_t pipe_hdl, hcd_pipe_event_t pipe_ static bool _dev_set_actions(device_t *dev_obj, uint32_t action_flags) { + /* + THIS FUNCTION MUST BE CALLED FROM A CRITICAL SECTION + */ if (action_flags == 0) { return false; } @@ -512,7 +580,7 @@ static inline void handle_prop_gone_evt(device_t *dev_obj) static inline void handle_free(device_t *dev_obj) { // Cache a copy of the device's address as we are about to free the device object - const uint8_t dev_addr = dev_obj->constant.address; + const unsigned int dev_uid = dev_obj->constant.uid; bool all_free; ESP_LOGD(USBH_TAG, "Freeing device %d", dev_obj->constant.address); @@ -536,7 +604,7 @@ static inline void handle_free(device_t *dev_obj) usbh_event_data_t event_data = { .event = USBH_EVENT_DEV_FREE, .dev_free_data = { - .dev_addr = dev_addr, + .dev_uid = dev_uid, } }; p_usbh_obj->constant.event_cb(&event_data, p_usbh_obj->constant.event_cb_arg); @@ -661,8 +729,6 @@ esp_err_t usbh_process(void) --------------------------------------------------------------------- */ USBH_EXIT_CRITICAL(); ESP_LOGD(USBH_TAG, "Processing actions 0x%"PRIx32"", action_flags); - // Sanity check. If the device is being freed, there must not be any other action flags set - assert(!(action_flags & DEV_ACTION_FREE) || action_flags == DEV_ACTION_FREE); if (action_flags & DEV_ACTION_EPn_HALT_FLUSH) { handle_epn_halt_flush(dev_obj); @@ -714,24 +780,42 @@ esp_err_t usbh_devs_num(int *num_devs_ret) esp_err_t usbh_devs_addr_list_fill(int list_len, uint8_t *dev_addr_list, int *num_dev_ret) { USBH_CHECK(dev_addr_list != NULL && num_dev_ret != NULL, ESP_ERR_INVALID_ARG); - USBH_ENTER_CRITICAL(); int num_filled = 0; device_t *dev_obj; - // Fill list with devices from idle tailq + + USBH_ENTER_CRITICAL(); + /* + Fill list with devices from idle tailq and pending tailq. Only devices that + are fully enumerated are added to the list. Thus, the following devices are + not excluded: + - Devices with their enum_lock set + - Devices not in the configured state + - Devices with address 0 + */ TAILQ_FOREACH(dev_obj, &p_usbh_obj->dynamic.devs_idle_tailq, dynamic.tailq_entry) { if (num_filled < list_len) { - dev_addr_list[num_filled] = dev_obj->constant.address; - num_filled++; + if (!dev_obj->dynamic.flags.enum_lock && + dev_obj->dynamic.state == USB_DEVICE_STATE_CONFIGURED && + dev_obj->constant.address != 0) { + dev_addr_list[num_filled] = dev_obj->constant.address; + num_filled++; + } } else { + // Address list is already full break; } } // Fill list with devices from pending tailq TAILQ_FOREACH(dev_obj, &p_usbh_obj->dynamic.devs_pending_tailq, dynamic.tailq_entry) { if (num_filled < list_len) { - dev_addr_list[num_filled] = dev_obj->constant.address; - num_filled++; + if (!dev_obj->dynamic.flags.enum_lock && + dev_obj->dynamic.state == USB_DEVICE_STATE_CONFIGURED && + dev_obj->constant.address != 0) { + dev_addr_list[num_filled] = dev_obj->constant.address; + num_filled++; + } } else { + // Address list is already full break; } } @@ -741,6 +825,82 @@ esp_err_t usbh_devs_addr_list_fill(int list_len, uint8_t *dev_addr_list, int *nu return ESP_OK; } +esp_err_t usbh_devs_add(unsigned int uid, usb_speed_t dev_speed, hcd_port_handle_t port_hdl) +{ + USBH_CHECK(port_hdl != NULL, ESP_ERR_INVALID_ARG); + esp_err_t ret; + device_t *dev_obj; + + // Allocate a device object (initialized to address 0) + ret = device_alloc(uid, dev_speed, port_hdl, &dev_obj); + if (ret != ESP_OK) { + return ret; + } + + // We need to take the mux_lock to access mux_protected members + xSemaphoreTake(p_usbh_obj->constant.mux_lock, portMAX_DELAY); + USBH_ENTER_CRITICAL(); + + // Check that there is not already a device with the same uid + if (_find_dev_from_uid(uid) != NULL) { + ret = ESP_ERR_INVALID_ARG; + goto exit; + } + // Check that there is not already a device currently with address 0 + if (_find_dev_from_addr(0) != NULL) { + ret = ESP_ERR_NOT_FINISHED; + goto exit; + } + // Add the device to the idle device list + TAILQ_INSERT_TAIL(&p_usbh_obj->dynamic.devs_idle_tailq, dev_obj, dynamic.tailq_entry); + p_usbh_obj->mux_protected.num_device++; + ret = ESP_OK; + +exit: + USBH_EXIT_CRITICAL(); + xSemaphoreGive(p_usbh_obj->constant.mux_lock); + + return ret; +} + +esp_err_t usbh_devs_remove(unsigned int uid) +{ + esp_err_t ret; + device_t *dev_obj; + bool call_proc_req_cb = false; + + USBH_ENTER_CRITICAL(); + dev_obj = _find_dev_from_uid(uid); + if (dev_obj == NULL) { + ret = ESP_ERR_NOT_FOUND; + goto exit; + } + // Mark the device as gone + dev_obj->dynamic.flags.is_gone = 1; + // Check if the device can be freed immediately + if (dev_obj->dynamic.open_count == 0) { + // Device is not currently opened at all. Can free immediately. + call_proc_req_cb = _dev_set_actions(dev_obj, DEV_ACTION_FREE); + } else { + // Device is still opened. Flush endpoints and propagate device gone event + call_proc_req_cb = _dev_set_actions(dev_obj, + DEV_ACTION_EPn_HALT_FLUSH | + DEV_ACTION_EP0_FLUSH | + DEV_ACTION_EP0_DEQUEUE | + DEV_ACTION_PROP_GONE_EVT); + } + ret = ESP_OK; +exit: + USBH_EXIT_CRITICAL(); + + // Call the processing request callback + if (call_proc_req_cb) { + p_usbh_obj->constant.proc_req_cb(USB_PROC_REQ_SOURCE_USBH, false, p_usbh_obj->constant.proc_req_cb_arg); + } + + return ret; +} + esp_err_t usbh_devs_mark_all_free(void) { USBH_ENTER_CRITICAL(); @@ -790,28 +950,17 @@ esp_err_t usbh_devs_open(uint8_t dev_addr, usb_device_handle_t *dev_hdl) USBH_ENTER_CRITICAL(); // Go through the device lists to find the device with the specified address - device_t *found_dev_obj = NULL; - device_t *dev_obj; - TAILQ_FOREACH(dev_obj, &p_usbh_obj->dynamic.devs_idle_tailq, dynamic.tailq_entry) { - if (dev_obj->constant.address == dev_addr) { - found_dev_obj = dev_obj; - goto exit; - } - } - TAILQ_FOREACH(dev_obj, &p_usbh_obj->dynamic.devs_pending_tailq, dynamic.tailq_entry) { - if (dev_obj->constant.address == dev_addr) { - found_dev_obj = dev_obj; - goto exit; - } - } -exit: - if (found_dev_obj != NULL) { - // The device is not in a state to be opened - if (dev_obj->dynamic.flags.is_gone || dev_obj->dynamic.flags.waiting_free) { + device_t *dev_obj = _find_dev_from_addr(dev_addr); + if (dev_obj != NULL) { + // Check if the device is in a state to be opened + if (dev_obj->dynamic.flags.is_gone || // Device is already gone (disconnected) + dev_obj->dynamic.flags.waiting_free) { // Device is waiting to be freed ret = ESP_ERR_INVALID_STATE; + } else if (dev_obj->dynamic.flags.enum_lock) { // Device's enum_lock is set + ret = ESP_ERR_NOT_ALLOWED; } else { dev_obj->dynamic.open_count++; - *dev_hdl = (usb_device_handle_t)found_dev_obj; + *dev_hdl = (usb_device_handle_t)dev_obj; ret = ESP_OK; } } else { @@ -828,6 +977,8 @@ esp_err_t usbh_devs_close(usb_device_handle_t dev_hdl) device_t *dev_obj = (device_t *)dev_hdl; USBH_ENTER_CRITICAL(); + // Device should never be closed while its enum_lock is + USBH_CHECK_FROM_CRIT(!dev_obj->dynamic.flags.enum_lock, ESP_ERR_NOT_ALLOWED); dev_obj->dynamic.open_count--; bool call_proc_req_cb = false; if (dev_obj->dynamic.open_count == 0) { @@ -845,6 +996,26 @@ esp_err_t usbh_devs_close(usb_device_handle_t dev_hdl) if (call_proc_req_cb) { p_usbh_obj->constant.proc_req_cb(USB_PROC_REQ_SOURCE_USBH, false, p_usbh_obj->constant.proc_req_cb_arg); } + + return ESP_OK; +} + +esp_err_t usbh_devs_new_dev_event(usb_device_handle_t dev_hdl) +{ + device_t *dev_obj = (device_t *)dev_hdl; + bool call_proc_req_cb = false; + + USBH_ENTER_CRITICAL(); + // Device must be in the configured state + USBH_CHECK_FROM_CRIT(dev_obj->dynamic.state == USB_DEVICE_STATE_CONFIGURED, ESP_ERR_INVALID_STATE); + call_proc_req_cb = _dev_set_actions(dev_obj, DEV_ACTION_PROP_NEW_DEV); + USBH_EXIT_CRITICAL(); + + // Call the processing request callback + if (call_proc_req_cb) { + p_usbh_obj->constant.proc_req_cb(USB_PROC_REQ_SOURCE_USBH, false, p_usbh_obj->constant.proc_req_cb_arg); + } + return ESP_OK; } @@ -870,28 +1041,26 @@ esp_err_t usbh_dev_get_info(usb_device_handle_t dev_hdl, usb_device_info_t *dev_ USBH_CHECK(dev_hdl != NULL && dev_info != NULL, ESP_ERR_INVALID_ARG); device_t *dev_obj = (device_t *)dev_hdl; - esp_err_t ret; - // Device must be configured, or not attached (if it suddenly disconnected) - USBH_ENTER_CRITICAL(); - if (!(dev_obj->dynamic.state == USB_DEVICE_STATE_CONFIGURED || dev_obj->dynamic.state == USB_DEVICE_STATE_NOT_ATTACHED)) { - USBH_EXIT_CRITICAL(); - ret = ESP_ERR_INVALID_STATE; - goto exit; - } - // Critical section for the dynamic members dev_info->speed = dev_obj->constant.speed; dev_info->dev_addr = dev_obj->constant.address; - dev_info->bMaxPacketSize0 = dev_obj->constant.desc->bMaxPacketSize0; - USBH_EXIT_CRITICAL(); - assert(dev_obj->constant.config_desc); - dev_info->bConfigurationValue = dev_obj->constant.config_desc->bConfigurationValue; - // String descriptors are allowed to be NULL as not all devices support them + // Device descriptor might not have been set yet + if (dev_obj->constant.desc) { + dev_info->bMaxPacketSize0 = dev_obj->constant.desc->bMaxPacketSize0; + } else { + // Use the default pipe's MPS instead + dev_info->bMaxPacketSize0 = hcd_pipe_get_mps(dev_obj->constant.default_pipe); + } + // Configuration descriptor might not have been set yet + if (dev_obj->constant.config_desc) { + dev_info->bConfigurationValue = dev_obj->constant.config_desc->bConfigurationValue; + } else { + dev_info->bConfigurationValue = 0; + } dev_info->str_desc_manufacturer = dev_obj->constant.str_desc_manu; dev_info->str_desc_product = dev_obj->constant.str_desc_product; dev_info->str_desc_serial_num = dev_obj->constant.str_desc_ser_num; - ret = ESP_OK; -exit: - return ret; + + return ESP_OK; } esp_err_t usbh_dev_get_desc(usb_device_handle_t dev_hdl, const usb_device_desc_t **dev_desc_ret) @@ -899,10 +1068,6 @@ esp_err_t usbh_dev_get_desc(usb_device_handle_t dev_hdl, const usb_device_desc_t USBH_CHECK(dev_hdl != NULL && dev_desc_ret != NULL, ESP_ERR_INVALID_ARG); device_t *dev_obj = (device_t *)dev_hdl; - USBH_ENTER_CRITICAL(); - USBH_CHECK_FROM_CRIT(dev_obj->dynamic.state == USB_DEVICE_STATE_CONFIGURED, ESP_ERR_INVALID_STATE); - USBH_EXIT_CRITICAL(); - *dev_desc_ret = dev_obj->constant.desc; return ESP_OK; } @@ -912,19 +1077,256 @@ esp_err_t usbh_dev_get_config_desc(usb_device_handle_t dev_hdl, const usb_config USBH_CHECK(dev_hdl != NULL && config_desc_ret != NULL, ESP_ERR_INVALID_ARG); device_t *dev_obj = (device_t *)dev_hdl; + *config_desc_ret = dev_obj->constant.config_desc; + + return ESP_OK; +} + +// ----------------------- Setters ------------------------- + +esp_err_t usbh_dev_enum_lock(usb_device_handle_t dev_hdl) +{ + USBH_CHECK(dev_hdl != NULL, ESP_ERR_INVALID_ARG); esp_err_t ret; - // Device must be in the configured state - USBH_ENTER_CRITICAL(); - if (dev_obj->dynamic.state != USB_DEVICE_STATE_CONFIGURED) { - USBH_EXIT_CRITICAL(); + device_t *dev_obj = (device_t *)dev_hdl; + + // We need to take the mux_lock to access mux_protected members + xSemaphoreTake(p_usbh_obj->constant.mux_lock, portMAX_DELAY); + + /* + The device's enum_lock can only be set when the following conditions are met: + - No other endpoints except EP0 have been allocated + - We are the sole opener + - Device's enum_lock is not already set + */ + // Check that no other endpoints except EP0 have been allocated + bool ep_found = false; + for (int i = 0; i < NUM_NON_DEFAULT_EP; i++) { + if (dev_obj->mux_protected.endpoints[i] != NULL) { + ep_found = true; + break; + } + } + if (ep_found) { ret = ESP_ERR_INVALID_STATE; goto exit; } + // Check that we are the sole opener and enum_lock is not already set + USBH_ENTER_CRITICAL(); + if (!dev_obj->dynamic.flags.enum_lock && (dev_obj->dynamic.open_count == 1)) { + dev_obj->dynamic.flags.enum_lock = true; + ret = ESP_OK; + } else { + ret = ESP_ERR_INVALID_STATE; + } USBH_EXIT_CRITICAL(); - assert(dev_obj->constant.config_desc); - *config_desc_ret = dev_obj->constant.config_desc; - ret = ESP_OK; + exit: + xSemaphoreGive(p_usbh_obj->constant.mux_lock); + + return ret; +} + +esp_err_t usbh_dev_enum_unlock(usb_device_handle_t dev_hdl) +{ + USBH_CHECK(dev_hdl != NULL, ESP_ERR_INVALID_ARG); + esp_err_t ret; + device_t *dev_obj = (device_t *)dev_hdl; + + USBH_ENTER_CRITICAL(); + // Device's enum_lock must have been previously set + if (dev_obj->dynamic.flags.enum_lock) { + assert(dev_obj->dynamic.open_count == 1); // We must still be the sole opener + dev_obj->dynamic.flags.enum_lock = false; + ret = ESP_OK; + } else { + ret = ESP_ERR_INVALID_STATE; + } + USBH_EXIT_CRITICAL(); + + return ret; +} + +esp_err_t usbh_dev_set_ep0_mps(usb_device_handle_t dev_hdl, uint16_t wMaxPacketSize) +{ + USBH_CHECK(dev_hdl != NULL, ESP_ERR_INVALID_ARG); + esp_err_t ret; + device_t *dev_obj = (device_t *)dev_hdl; + + USBH_ENTER_CRITICAL(); + // Device's EP0 MPS can only be updated when in the default state + if (dev_obj->dynamic.state != USB_DEVICE_STATE_DEFAULT) { + ret = ESP_ERR_INVALID_STATE; + goto exit; + } + // Device's enum_lock must be set before enumeration related data fields can be set + if (dev_obj->dynamic.flags.enum_lock) { + ret = hcd_pipe_update_mps(dev_obj->constant.default_pipe, wMaxPacketSize); + } else { + ret = ESP_ERR_NOT_ALLOWED; + } +exit: + USBH_EXIT_CRITICAL(); + + return ret; +} + +esp_err_t usbh_dev_set_addr(usb_device_handle_t dev_hdl, uint8_t dev_addr) +{ + USBH_CHECK(dev_hdl != NULL, ESP_ERR_INVALID_ARG); + esp_err_t ret; + device_t *dev_obj = (device_t *)dev_hdl; + + USBH_ENTER_CRITICAL(); + // Device's address can only be set when in the default state + USBH_CHECK_FROM_CRIT(dev_obj->dynamic.state == USB_DEVICE_STATE_DEFAULT, ESP_ERR_INVALID_STATE); + // Device's enum_lock must be set before enumeration related data fields can be set + USBH_CHECK_FROM_CRIT(dev_obj->dynamic.flags.enum_lock, ESP_ERR_NOT_ALLOWED); + // Update the device and default pipe's target address + ret = hcd_pipe_update_dev_addr(dev_obj->constant.default_pipe, dev_addr); + if (ret == ESP_OK) { + dev_obj->constant.address = dev_addr; + dev_obj->dynamic.state = USB_DEVICE_STATE_ADDRESS; + } + USBH_EXIT_CRITICAL(); + + return ret; +} + +esp_err_t usbh_dev_set_desc(usb_device_handle_t dev_hdl, const usb_device_desc_t *device_desc) +{ + USBH_CHECK(dev_hdl != NULL && device_desc != NULL, ESP_ERR_INVALID_ARG); + esp_err_t ret; + device_t *dev_obj = (device_t *)dev_hdl; + usb_device_desc_t *new_desc, *old_desc; + + // Allocate and copy new device descriptor + new_desc = heap_caps_malloc(sizeof(usb_device_desc_t), MALLOC_CAP_DEFAULT); + if (new_desc == NULL) { + return ESP_ERR_NO_MEM; + } + memcpy(new_desc, device_desc, sizeof(usb_device_desc_t)); + + USBH_ENTER_CRITICAL(); + // Device's descriptor can only be set in the default or addressed state + if (!(dev_obj->dynamic.state == USB_DEVICE_STATE_DEFAULT || dev_obj->dynamic.state == USB_DEVICE_STATE_ADDRESS)) { + ret = ESP_ERR_INVALID_STATE; + goto err; + } + // Device's enum_lock must be set before we can set its device descriptor + if (!dev_obj->dynamic.flags.enum_lock) { + ret = ESP_ERR_NOT_ALLOWED; + goto err; + } + old_desc = dev_obj->constant.desc; // Save old descriptor for cleanup + dev_obj->constant.desc = new_desc; // Assign new descriptor + USBH_EXIT_CRITICAL(); + + // Clean up old descriptor or failed assignment + heap_caps_free(old_desc); + ret = ESP_OK; + + return ret; + +err: + USBH_EXIT_CRITICAL(); + heap_caps_free(new_desc); + return ret; +} + +esp_err_t usbh_dev_set_config_desc(usb_device_handle_t dev_hdl, const usb_config_desc_t *config_desc_full) +{ + USBH_CHECK(dev_hdl != NULL && config_desc_full != NULL, ESP_ERR_INVALID_ARG); + esp_err_t ret; + device_t *dev_obj = (device_t *)dev_hdl; + usb_config_desc_t *new_desc, *old_desc; + + // Allocate and copy new config descriptor + new_desc = heap_caps_malloc(config_desc_full->wTotalLength, MALLOC_CAP_DEFAULT); + if (new_desc == NULL) { + return ESP_ERR_NO_MEM; + } + memcpy(new_desc, config_desc_full, config_desc_full->wTotalLength); + + USBH_ENTER_CRITICAL(); + // Device's config descriptor can only be set when in the addressed state + if (dev_obj->dynamic.state != USB_DEVICE_STATE_ADDRESS) { + ret = ESP_ERR_INVALID_STATE; + goto err; + } + // Device's enum_lock must be set before we can set its config descriptor + if (!dev_obj->dynamic.flags.enum_lock) { + ret = ESP_ERR_NOT_ALLOWED; + goto err; + } + old_desc = dev_obj->constant.config_desc; // Save old descriptor for cleanup + dev_obj->constant.config_desc = new_desc; // Assign new descriptor + dev_obj->dynamic.state = USB_DEVICE_STATE_CONFIGURED; + USBH_EXIT_CRITICAL(); + + // Clean up old descriptor or failed assignment + heap_caps_free(old_desc); + ret = ESP_OK; + + return ret; + +err: + USBH_EXIT_CRITICAL(); + heap_caps_free(new_desc); + return ret; +} + +esp_err_t usbh_dev_set_str_desc(usb_device_handle_t dev_hdl, const usb_str_desc_t *str_desc, int select) +{ + USBH_CHECK(dev_hdl != NULL && str_desc != NULL && (select >= 0 && select < 3), ESP_ERR_INVALID_ARG); + esp_err_t ret; + device_t *dev_obj = (device_t *)dev_hdl; + usb_str_desc_t *new_desc, *old_desc; + + // Allocate and copy new string descriptor + new_desc = heap_caps_malloc(str_desc->bLength, MALLOC_CAP_DEFAULT); + if (new_desc == NULL) { + return ESP_ERR_NO_MEM; + } + memcpy(new_desc, str_desc, str_desc->bLength); + + USBH_ENTER_CRITICAL(); + // Device's string descriptors can only be set when in the default state + if (dev_obj->dynamic.state != USB_DEVICE_STATE_CONFIGURED) { + ret = ESP_ERR_INVALID_STATE; + goto err; + } + // Device's enum_lock must be set before we can set its string descriptors + if (!dev_obj->dynamic.flags.enum_lock) { + ret = ESP_ERR_NOT_ALLOWED; + goto err; + } + // Assign to the selected descriptor + switch (select) { + case 0: + old_desc = dev_obj->constant.str_desc_manu; + dev_obj->constant.str_desc_manu = new_desc; + break; + case 1: + old_desc = dev_obj->constant.str_desc_product; + dev_obj->constant.str_desc_product = new_desc; + break; + default: // 2 + old_desc = dev_obj->constant.str_desc_ser_num; + dev_obj->constant.str_desc_ser_num = new_desc; + break; + } + USBH_EXIT_CRITICAL(); + + // Clean up old descriptor or failed assignment + heap_caps_free(old_desc); + ret = ESP_OK; + + return ret; + +err: + USBH_EXIT_CRITICAL(); + heap_caps_free(new_desc); return ret; } @@ -939,6 +1341,7 @@ esp_err_t usbh_ep_alloc(usb_device_handle_t dev_hdl, usbh_ep_config_t *ep_config esp_err_t ret; device_t *dev_obj = (device_t *)dev_hdl; endpoint_t *ep_obj; + USBH_CHECK(dev_obj->constant.config_desc, ESP_ERR_INVALID_STATE); // Configuration descriptor must be set // Find the endpoint descriptor from the device's current configuration descriptor const usb_ep_desc_t *ep_desc = usb_parse_endpoint_descriptor_by_address(dev_obj->constant.config_desc, ep_config->bInterfaceNumber, ep_config->bAlternateSetting, ep_config->bEndpointAddress, NULL); @@ -1065,10 +1468,11 @@ esp_err_t usbh_dev_submit_ctrl_urb(usb_device_handle_t dev_hdl, urb_t *urb) device_t *dev_obj = (device_t *)dev_hdl; USBH_CHECK(urb_check_args(urb), ESP_ERR_INVALID_ARG); bool xfer_is_in = ((usb_setup_packet_t *)urb->transfer.data_buffer)->bmRequestType & USB_BM_REQUEST_TYPE_DIR_IN; - USBH_CHECK(transfer_check_usb_compliance(&(urb->transfer), USB_TRANSFER_TYPE_CTRL, dev_obj->constant.desc->bMaxPacketSize0, xfer_is_in), ESP_ERR_INVALID_ARG); + // Device descriptor could still be NULL at this point, so we get the MPS from the pipe instead. + unsigned int mps = hcd_pipe_get_mps(dev_obj->constant.default_pipe); + USBH_CHECK(transfer_check_usb_compliance(&(urb->transfer), USB_TRANSFER_TYPE_CTRL, mps, xfer_is_in), ESP_ERR_INVALID_ARG); USBH_ENTER_CRITICAL(); - USBH_CHECK_FROM_CRIT(dev_obj->dynamic.state == USB_DEVICE_STATE_CONFIGURED, ESP_ERR_INVALID_STATE); // Increment the control transfer count first dev_obj->dynamic.num_ctrl_xfers_inflight++; USBH_EXIT_CRITICAL(); @@ -1121,156 +1525,3 @@ esp_err_t usbh_ep_dequeue_urb(usbh_ep_handle_t ep_hdl, urb_t **urb_ret) *urb_ret = hcd_urb_dequeue(ep_obj->constant.pipe_hdl); return ESP_OK; } - -// -------------------------------------------------- Hub Functions ---------------------------------------------------- - -// ------------------- Device Related ---------------------- - -esp_err_t usbh_hub_add_dev(hcd_port_handle_t port_hdl, usb_speed_t dev_speed, usb_device_handle_t *new_dev_hdl, hcd_pipe_handle_t *default_pipe_hdl) -{ - // Note: Parent device handle can be NULL if it's connected to the root hub - USBH_CHECK(new_dev_hdl != NULL, ESP_ERR_INVALID_ARG); - esp_err_t ret; - device_t *dev_obj; - ret = device_alloc(port_hdl, dev_speed, &dev_obj); - if (ret != ESP_OK) { - return ret; - } - // Write-back device handle - *new_dev_hdl = (usb_device_handle_t)dev_obj; - *default_pipe_hdl = dev_obj->constant.default_pipe; - ret = ESP_OK; - return ret; -} - -esp_err_t usbh_hub_dev_gone(usb_device_handle_t dev_hdl) -{ - USBH_CHECK(dev_hdl != NULL, ESP_ERR_INVALID_ARG); - device_t *dev_obj = (device_t *)dev_hdl; - bool call_proc_req_cb; - - USBH_ENTER_CRITICAL(); - dev_obj->dynamic.flags.is_gone = 1; - // Check if the device can be freed immediately - if (dev_obj->dynamic.open_count == 0) { - // Device is not currently opened at all. Can free immediately. - call_proc_req_cb = _dev_set_actions(dev_obj, DEV_ACTION_FREE); - } else { - // Device is still opened. Flush endpoints and propagate device gone event - call_proc_req_cb = _dev_set_actions(dev_obj, - DEV_ACTION_EPn_HALT_FLUSH | - DEV_ACTION_EP0_FLUSH | - DEV_ACTION_EP0_DEQUEUE | - DEV_ACTION_PROP_GONE_EVT); - } - USBH_EXIT_CRITICAL(); - - if (call_proc_req_cb) { - p_usbh_obj->constant.proc_req_cb(USB_PROC_REQ_SOURCE_USBH, false, p_usbh_obj->constant.proc_req_cb_arg); - } - return ESP_OK; -} - -// ----------------- Enumeration Related ------------------- - -esp_err_t usbh_hub_enum_fill_dev_addr(usb_device_handle_t dev_hdl, uint8_t dev_addr) -{ - USBH_CHECK(dev_hdl != NULL, ESP_ERR_INVALID_ARG); - device_t *dev_obj = (device_t *)dev_hdl; - - USBH_ENTER_CRITICAL(); - dev_obj->dynamic.state = USB_DEVICE_STATE_ADDRESS; - USBH_EXIT_CRITICAL(); - - // We can modify the info members outside the critical section - dev_obj->constant.address = dev_addr; - return ESP_OK; -} - -esp_err_t usbh_hub_enum_fill_dev_desc(usb_device_handle_t dev_hdl, const usb_device_desc_t *device_desc) -{ - USBH_CHECK(dev_hdl != NULL && device_desc != NULL, ESP_ERR_INVALID_ARG); - device_t *dev_obj = (device_t *)dev_hdl; - // We can modify the info members outside the critical section - memcpy((usb_device_desc_t *)dev_obj->constant.desc, device_desc, sizeof(usb_device_desc_t)); - return ESP_OK; -} - -esp_err_t usbh_hub_enum_fill_config_desc(usb_device_handle_t dev_hdl, const usb_config_desc_t *config_desc_full) -{ - USBH_CHECK(dev_hdl != NULL && config_desc_full != NULL, ESP_ERR_INVALID_ARG); - device_t *dev_obj = (device_t *)dev_hdl; - // Allocate memory to store the configuration descriptor - usb_config_desc_t *config_desc = heap_caps_malloc(config_desc_full->wTotalLength, MALLOC_CAP_DEFAULT); // Buffer to copy over full configuration descriptor (wTotalLength) - if (config_desc == NULL) { - return ESP_ERR_NO_MEM; - } - // Copy the configuration descriptor - memcpy(config_desc, config_desc_full, config_desc_full->wTotalLength); - // Assign the config desc to the device object - assert(dev_obj->constant.config_desc == NULL); - dev_obj->constant.config_desc = config_desc; - return ESP_OK; -} - -esp_err_t usbh_hub_enum_fill_str_desc(usb_device_handle_t dev_hdl, const usb_str_desc_t *str_desc, int select) -{ - USBH_CHECK(dev_hdl != NULL && str_desc != NULL && (select >= 0 && select < 3), ESP_ERR_INVALID_ARG); - device_t *dev_obj = (device_t *)dev_hdl; - // Allocate memory to store the manufacturer string descriptor - usb_str_desc_t *str_desc_fill = heap_caps_malloc(str_desc->bLength, MALLOC_CAP_DEFAULT); - if (str_desc_fill == NULL) { - return ESP_ERR_NO_MEM; - } - // Copy the string descriptor - memcpy(str_desc_fill, str_desc, str_desc->bLength); - // Assign filled string descriptor to the device object - switch (select) { - case 0: - assert(dev_obj->constant.str_desc_manu == NULL); - dev_obj->constant.str_desc_manu = str_desc_fill; - break; - case 1: - assert(dev_obj->constant.str_desc_product == NULL); - dev_obj->constant.str_desc_product = str_desc_fill; - break; - default: // 2 - assert(dev_obj->constant.str_desc_ser_num == NULL); - dev_obj->constant.str_desc_ser_num = str_desc_fill; - break; - } - return ESP_OK; -} - -esp_err_t usbh_hub_enum_done(usb_device_handle_t dev_hdl) -{ - USBH_CHECK(dev_hdl != NULL, ESP_ERR_INVALID_ARG); - device_t *dev_obj = (device_t *)dev_hdl; - - // We need to take the mux_lock to access mux_protected members - xSemaphoreTake(p_usbh_obj->constant.mux_lock, portMAX_DELAY); - USBH_ENTER_CRITICAL(); - dev_obj->dynamic.state = USB_DEVICE_STATE_CONFIGURED; - // Add the device to list of devices, then trigger a device event - TAILQ_INSERT_TAIL(&p_usbh_obj->dynamic.devs_idle_tailq, dev_obj, dynamic.tailq_entry); // Add it to the idle device list first - bool call_proc_req_cb = _dev_set_actions(dev_obj, DEV_ACTION_PROP_NEW_DEV); - USBH_EXIT_CRITICAL(); - p_usbh_obj->mux_protected.num_device++; - xSemaphoreGive(p_usbh_obj->constant.mux_lock); - - // Update the EP0's underlying pipe's callback - ESP_ERROR_CHECK(hcd_pipe_update_callback(dev_obj->constant.default_pipe, ep0_pipe_callback, (void *)dev_obj)); - // Call the processing request callback - if (call_proc_req_cb) { - p_usbh_obj->constant.proc_req_cb(USB_PROC_REQ_SOURCE_USBH, false, p_usbh_obj->constant.proc_req_cb_arg); - } - return ESP_OK; -} - -esp_err_t usbh_hub_enum_failed(usb_device_handle_t dev_hdl) -{ - USBH_CHECK(dev_hdl != NULL, ESP_ERR_INVALID_ARG); - device_t *dev_obj = (device_t *)dev_hdl; - device_free(dev_obj); - return ESP_OK; -} From 7db459d85f6db1388c25a7cc96dc79dabee8e944 Mon Sep 17 00:00:00 2001 From: Darian Leung Date: Wed, 17 Apr 2024 01:52:21 +0800 Subject: [PATCH 6/6] docs(usb): Add USBH maintainer notes --- docs/conf_common.py | 3 +- docs/docs_not_updated/esp32c5.txt | 1 + docs/docs_not_updated/esp32p4.txt | 1 + .../usb_host/usb_host_notes_index.rst | 2 +- .../usb_host/usb_host_notes_usbh.rst | 115 ++++++++++++++++++ .../usb_host/usb_host_notes_arch.rst | 3 +- .../usb_host/usb_host_notes_index.rst | 8 +- .../usb_host/usb_host_notes_usbh.rst | 1 + 8 files changed, 126 insertions(+), 8 deletions(-) create mode 100644 docs/en/api-reference/peripherals/usb_host/usb_host_notes_usbh.rst create mode 100644 docs/zh_CN/api-reference/peripherals/usb_host/usb_host_notes_usbh.rst diff --git a/docs/conf_common.py b/docs/conf_common.py index a0b4ace54c..2bdebec6ca 100644 --- a/docs/conf_common.py +++ b/docs/conf_common.py @@ -117,7 +117,8 @@ USB_DOCS = ['api-reference/peripherals/usb_device.rst', 'api-reference/peripherals/usb_host/usb_host_notes_arch.rst', 'api-reference/peripherals/usb_host/usb_host_notes_design.rst', 'api-reference/peripherals/usb_host/usb_host_notes_dwc_otg.rst', - 'api-reference/peripherals/usb_host/usb_host_notes_index.rst'] + 'api-reference/peripherals/usb_host/usb_host_notes_index.rst', + 'api-reference/peripherals/usb_host/usb_host_notes_usbh.rst'] I80_LCD_DOCS = ['api-reference/peripherals/lcd/i80_lcd.rst'] RGB_LCD_DOCS = ['api-reference/peripherals/lcd/rgb_lcd.rst'] diff --git a/docs/docs_not_updated/esp32c5.txt b/docs/docs_not_updated/esp32c5.txt index 786d076687..10ed4b965c 100644 --- a/docs/docs_not_updated/esp32c5.txt +++ b/docs/docs_not_updated/esp32c5.txt @@ -87,6 +87,7 @@ api-reference/peripherals/usb_host/usb_host_notes_arch.rst api-reference/peripherals/usb_host/usb_host_notes_index.rst api-reference/peripherals/usb_host/usb_host_notes_dwc_otg.rst api-reference/peripherals/usb_host/usb_host_notes_design.rst +api-reference/peripherals/usb_host/usb_host_notes_usbh.rst api-reference/peripherals/hmac.rst api-reference/peripherals/usb_device.rst api-reference/peripherals/sdspi_host.rst diff --git a/docs/docs_not_updated/esp32p4.txt b/docs/docs_not_updated/esp32p4.txt index 419e2293db..9568af83ef 100644 --- a/docs/docs_not_updated/esp32p4.txt +++ b/docs/docs_not_updated/esp32p4.txt @@ -16,6 +16,7 @@ api-reference/peripherals/usb_host/usb_host_notes_arch.rst api-reference/peripherals/usb_host/usb_host_notes_index.rst api-reference/peripherals/usb_host/usb_host_notes_dwc_otg.rst api-reference/peripherals/usb_host/usb_host_notes_design.rst +api-reference/peripherals/usb_host/usb_host_notes_usbh.rst api-reference/peripherals/usb_device.rst api-reference/peripherals/touch_element.rst api-reference/peripherals/spi_flash/xip_from_psram.inc diff --git a/docs/en/api-reference/peripherals/usb_host/usb_host_notes_index.rst b/docs/en/api-reference/peripherals/usb_host/usb_host_notes_index.rst index 0cff74a466..2d23befb42 100644 --- a/docs/en/api-reference/peripherals/usb_host/usb_host_notes_index.rst +++ b/docs/en/api-reference/peripherals/usb_host/usb_host_notes_index.rst @@ -21,12 +21,12 @@ This document is split into the following sections: usb_host_notes_design usb_host_notes_arch usb_host_notes_dwc_otg + usb_host_notes_usbh Todo: - USB Host Maintainers Notes (HAL & LL) - USB Host Maintainers Notes (HCD) -- USB Host Maintainers Notes (USBH) - USB Host Maintainers Notes (Hub) - USB Host Maintainers Notes (USB Host Library) diff --git a/docs/en/api-reference/peripherals/usb_host/usb_host_notes_usbh.rst b/docs/en/api-reference/peripherals/usb_host/usb_host_notes_usbh.rst new file mode 100644 index 0000000000..b1cd35fad9 --- /dev/null +++ b/docs/en/api-reference/peripherals/usb_host/usb_host_notes_usbh.rst @@ -0,0 +1,115 @@ +USB Host Driver (USBH) +====================== + +Introduction +------------ + +The USB Host Driver (henceforth referred to as USBH) provides a USB Host software interface which abstracts USB devices. The USBH interface provides APIs to... + +- manage the device pool (i.e., adding and removing devices) +- address and configure a device (i.e., setting device and configuration descriptors) +- submit transfers to a particular endpoint of a device + +Requirements +------------ + +USB Specification Requirements +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Chapter 10 of the USB 2.0 specification outlines some requirements of the USBH (referred to as USBD in the specification). The design of the USBH takes into consideration these requirements from the specification. + +- Default pipe of a device is owned by the USBH +- All other pipes are owned and managed by clients of the USBH +- USBH interface must provide the following services + + - Configuration and command mechanism + - Transfer services via both command and pipe mechanisms + - Event notification + - Status reporting and error recovery + +Host Stack Requirements +^^^^^^^^^^^^^^^^^^^^^^^ + +In addition to the USB 2.0 specification requirements, the USBH also takes into consideration the requirements set for the overall Host Stack (see :doc:`./usb_host_notes_design`): + +- USBH must not instantiate any tasks/threads +- USBH must be event driven, providing event callbacks and an event processing function + +Implementation & Usage +---------------------- + +Events & Processing +^^^^^^^^^^^^^^^^^^^ + +The USBH is completely event driven and all event handling is done via then ``usbh_process()`` function. The ``usbh_config_t.proc_req_cb`` callback provided on USBH installation will be called when processing is required. Typically, ``usbh_process()`` will be called from a dedicated thread/task. + +The USBH exposes the following event callbacks: + +- ``usbh_event_cb_t`` used to indicate various events regarding a particular device and control transfers to EP0. This callback is called from the context of ``usbh_process()`` +- ``usbh_ep_cb_t`` used to indicate events for all other endpoints. This callback is not called from the ``usbh_process()`` context (currently called from an HCD interrupt context). + +Device Pool +^^^^^^^^^^^ + +The USBH keeps track of all currently connected devices by internally maintaining a device pool (simply a linked list) where each device is represented by a device object. + +The USB 2.0 specification "assumes a specialized client of the USBD, called a hub driver, that acts as a clearinghouse for the addition and removal of devices from a particular hub". As a result, the USBH is completely reliant on an external client(s) (typically a Hub Driver) to inform the USBH of device addition and removal. The USBH provides the following APIs for device addition and removal: + +- ``usbh_devs_add()`` which will allocate a new device object and add it to the device pool. The newly added device will be unenumerated, meaning the device object will... + + - be assigned to address 0 + - have no device and configuration descriptor + +- ``usbh_devs_remove()`` which will indicate to the USBH that a device has been removed (such as due to a disconnection or a port error). + + - If the device is not currently opened (i.e., used by one or more clients), the USBH will free the underlying device object immediately. + - If the device is currently opened, a ``USBH_EVENT_DEV_GONE`` event will be propagated and the device will be flagged for removal. The last client to close the device will free the device object. + - When a device object is freed, a ``USBH_EVENT_DEV_FREE`` event will be propagated. This event is used to indicate that the device's upstream port can be recycled. + +Device Enumeration +^^^^^^^^^^^^^^^^^^ + +Newly added devices will need to be enumerated. The USBH provides various ``usbh_dev_set_...()`` functions to enumerate the device, such as assigning the device's address and setting device/configuration/string descriptors. Given that USBH devices can be shared by multiple clients, attempting to enumerate a device while another client has opened the device can cause issues. + +Thus, before calling any ``usbh_dev_set_...()`` enumeration function, a device must be locked for enumeration by calling ``usbh_dev_enum_lock()``. This prevents the device from being opened by any other client but the enumerating client. + +After enumeration is complete, the enumerating client can call ``usbh_devs_trigger_new_dev_event()`` to propagate a ``USBH_EVENT_NEW_DEV`` event. + +Device Usage +^^^^^^^^^^^^ + +Clients that want to use a device must open the device by calling ``usbh_devs_open()`` and providing the device's address. The device's address can either be obtained from a ``USBH_EVENT_NEW_DEV`` event or by calling ``usbh_devs_addr_list_fill()``. + +Opening a device will do the following: + +- Return a ``usb_device_handle_t`` device handle which can be used to refer to the device in various USBH functions +- Increment the device's internal ``open_count`` which indicates how many clients have opened the device. As long as ``open_count > 0``, the underlying device object will not be freed, thus guaranteeing that the device handle refers to a valid device object. + +Once a client no longer needs to use a device, the client should call ``usbh_devs_close()`` thus invalidating the device handle. + +.. note:: + + Most device related APIs accept ``usb_device_handle_t`` as an argument, which means that the calling client must have previously opened the device to obtain the device handle beforehand. This design choice is intentional in order to enforce an "open before use" pattern. + + However, a limited set of APIs (e.g., ``usbh_devs_remove()``) refer to devices using a Unique Identifier (``uid``) which is assigned on device addition (see ``usbh_devs_add()``). The use of ``uid`` in these functions allows their callers to refer to a device **without needing to open it** due to the lack of a ``usb_device_handle_t``. + + As a result, it is possible that a caller of a ``uid`` function may refer to a device that has already been freed. Thus, callers should account for a fact that these functions may return :c:macro:`ESP_ERR_NOT_FOUND`. + +Endpoints & Transfers +^^^^^^^^^^^^^^^^^^^^^ + +USBH supports transfer to default (i.e., EP0) and non-default endpoints. + +For non-default endpoints: + +- A client must first allocate the endpoint by calling ``usbh_ep_alloc()`` which assigns a ``usbh_ep_cb_t`` callback and returns a ``usbh_ep_handle_t`` endpoint handle so that the endpoint can be referred to. +- A client can then enqueue a ``urb_t`` transfer to the endpoint by calling ``usbh_ep_enqueue_urb()``. +- The ``usbh_ep_cb_t`` callback is called to indicate transfer completion +- The client must then dequeue the transfer using ``usbh_ep_dequeue_urb()`` + +Default endpoints are owned and managed by the USBH, thus API for control transfers are different: + +- EP0 is always allocated for each device, thus clients do no need to allocate EP0 or provide an endpoint callback. +- Clients call should call ``usbh_dev_submit_ctrl_urb()`` to submit a control transfer to a device's EP0. +- A ``USBH_EVENT_CTRL_XFER`` event will be propagated when the transfer is complete +- Control transfers do not need to be dequeued diff --git a/docs/zh_CN/api-reference/peripherals/usb_host/usb_host_notes_arch.rst b/docs/zh_CN/api-reference/peripherals/usb_host/usb_host_notes_arch.rst index bebedf8f35..3670348e5a 100644 --- a/docs/zh_CN/api-reference/peripherals/usb_host/usb_host_notes_arch.rst +++ b/docs/zh_CN/api-reference/peripherals/usb_host/usb_host_notes_arch.rst @@ -1,2 +1 @@ -.. include:: ../../../../en/api-reference/peripherals/usb_host/usb_host_notes_arch - .rst +.. include:: ../../../../en/api-reference/peripherals/usb_host/usb_host_notes_arch.rst diff --git a/docs/zh_CN/api-reference/peripherals/usb_host/usb_host_notes_index.rst b/docs/zh_CN/api-reference/peripherals/usb_host/usb_host_notes_index.rst index 020a913ef7..1ab83954de 100644 --- a/docs/zh_CN/api-reference/peripherals/usb_host/usb_host_notes_index.rst +++ b/docs/zh_CN/api-reference/peripherals/usb_host/usb_host_notes_index.rst @@ -21,14 +21,14 @@ USB 主机维护者注意事项（简介） usb_host_notes_design usb_host_notes_arch usb_host_notes_dwc_otg + usb_host_notes_usbh 待写章节： - USB 主机维护者注意事项（HAL 和 LL） -- USB 主机维护者注意事项 (HCD) -- USB 主机维护者注意事项 (USBH) -- USB 主机维护者注意事项 (Hub) -- USB 主机维护者注意事项 (USB Host Library) +- USB 主机维护者注意事项（HCD） +- USB 主机维护者注意事项（Hub） +- USB 主机维护者注意事项（USB Host Library） .. -------------------------------------------------- Introduction ----------------------------------------------------- diff --git a/docs/zh_CN/api-reference/peripherals/usb_host/usb_host_notes_usbh.rst b/docs/zh_CN/api-reference/peripherals/usb_host/usb_host_notes_usbh.rst new file mode 100644 index 0000000000..262547c0f0 --- /dev/null +++ b/docs/zh_CN/api-reference/peripherals/usb_host/usb_host_notes_usbh.rst @@ -0,0 +1 @@ +.. include:: ../../../../en/api-reference/peripherals/usb_host/usb_host_notes_usbh.rst