espressif/esp-idf
1
0
Fork 1
mirror of https://github.com/espressif/esp-idf.git synced 2025-07-30 18:57:19 +02:00
Code Issues Packages Projects Releases Wiki Activity

refactor(usb/usbh): Rename device pool functions and ref_count

Browse Source 
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.
This commit is contained in:
Darian Leung
2024-04-03 11:24:03 +08:00
parent 72d6c31ac7
commit fe206dab59
3 changed files with 32 additions and 32 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@ -178,13 +178,13 @@ esp_err_t usbh_process(void);
* @param[out] num_devs_ret Current number of devices * @param[out] num_devs_ret Current number of devices
* @return esp_err_t * @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 * @brief Fill list with address of currently connected devices
* *
* - This function fills the provided list with the address of current 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 * - If there are more devices than the list_len, this function will only fill
* up to list_len number of devices. * 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 * @param[out] num_dev_ret Number of devices filled into list
* @return esp_err_t * @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 * @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 * @return
* - ESP_OK: There were no devices to free to begin with. Current state is all free * - 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_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 * @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 * @param[out] dev_hdl Device handle
* @return esp_err_t * @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 * @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 * @param[in] dev_hdl Device handle
* @return esp_err_t * @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 --------------------------------------------------- // ------------------------------------------------ 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 * 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 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 * - 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 * - Once the client allocates an endpoint, the client is now owns/manages the endpoint. No other client should use or

12
components/usb/usb_host.c
View File

@ -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); HOST_CHECK_FROM_CRIT(p_host_lib_obj != NULL, ESP_ERR_INVALID_STATE);
num_clients_temp = p_host_lib_obj->dynamic.flags.num_clients; num_clients_temp = p_host_lib_obj->dynamic.flags.num_clients;
HOST_EXIT_CRITICAL(); HOST_EXIT_CRITICAL();
usbh_num_devs(&num_devs_temp); usbh_devs_num(&num_devs_temp);
// Write back return values // Write back return values
info_ret->num_devices = num_devs_temp; 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; esp_err_t ret;
usb_device_handle_t dev_hdl; 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) { if (ret != ESP_OK) {
goto exit; 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; return ret;
already_opened: already_opened:
ESP_ERROR_CHECK(usbh_dev_close(dev_hdl)); ESP_ERROR_CHECK(usbh_devs_close(dev_hdl));
exit: exit:
return ret; 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); _clear_client_opened_device(client_obj, dev_addr);
HOST_EXIT_CRITICAL(); HOST_EXIT_CRITICAL();
ESP_ERROR_CHECK(usbh_dev_close(dev_hdl)); ESP_ERROR_CHECK(usbh_devs_close(dev_hdl));
ret = ESP_OK; ret = ESP_OK;
exit: exit:
xSemaphoreGive(p_host_lib_obj->constant.mux_lock); 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_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(); HOST_EXIT_CRITICAL();
esp_err_t ret; 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 // 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; 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) 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); 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 --------------------------------------------------- // ------------------------------------------------- Device Requests ---------------------------------------------------

34
components/usb/usbh.c
View File

@ -64,7 +64,7 @@ struct device_s {
uint32_t action_flags; uint32_t action_flags;
int num_ctrl_xfers_inflight; int num_ctrl_xfers_inflight;
usb_device_state_t state; usb_device_state_t state;
uint32_t ref_count; uint32_t open_count;
} dynamic; } dynamic;
// Mux protected members must be protected by the USBH mux_lock when accessed // Mux protected members must be protected by the USBH mux_lock when accessed
struct { struct {
@ -702,7 +702,7 @@ esp_err_t usbh_process(void)
// ---------------------------------------------- Device Pool Functions ------------------------------------------------ // ---------------------------------------------- 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); USBH_CHECK(num_devs_ret != NULL, ESP_ERR_INVALID_ARG);
xSemaphoreTake(p_usbh_obj->constant.mux_lock, portMAX_DELAY); 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; 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_CHECK(dev_addr_list != NULL && num_dev_ret != NULL, ESP_ERR_INVALID_ARG);
USBH_ENTER_CRITICAL(); 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; return ESP_OK;
} }
esp_err_t usbh_dev_mark_all_free(void) esp_err_t usbh_devs_mark_all_free(void)
{ {
USBH_ENTER_CRITICAL(); USBH_ENTER_CRITICAL();
/* /*
@ -763,11 +763,11 @@ esp_err_t usbh_dev_mark_all_free(void)
while (dev_obj_cur != NULL) { while (dev_obj_cur != NULL) {
// Keep a copy of the next item first in case we remove the current item // 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); dev_obj_next = TAILQ_NEXT(dev_obj_cur, dynamic.tailq_entry);
if (dev_obj_cur->dynamic.ref_count == 0) { if (dev_obj_cur->dynamic.open_count == 0) {
// Device is not referenced. Can free immediately. // Device is not opened. Can free immediately.
call_proc_req_cb |= _dev_set_actions(dev_obj_cur, DEV_ACTION_FREE); call_proc_req_cb |= _dev_set_actions(dev_obj_cur, DEV_ACTION_FREE);
} else { } 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; 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 // 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; 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); USBH_CHECK(dev_hdl != NULL, ESP_ERR_INVALID_ARG);
esp_err_t ret; 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: exit:
if (found_dev_obj != NULL) { 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) { if (dev_obj->dynamic.flags.is_gone || dev_obj->dynamic.flags.waiting_free) {
ret = ESP_ERR_INVALID_STATE; ret = ESP_ERR_INVALID_STATE;
} else { } else {
dev_obj->dynamic.ref_count++; dev_obj->dynamic.open_count++;
*dev_hdl = (usb_device_handle_t)found_dev_obj; *dev_hdl = (usb_device_handle_t)found_dev_obj;
ret = ESP_OK; ret = ESP_OK;
} }
@ -822,18 +822,18 @@ exit:
return ret; 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); USBH_CHECK(dev_hdl != NULL, ESP_ERR_INVALID_ARG);
device_t *dev_obj = (device_t *)dev_hdl; device_t *dev_obj = (device_t *)dev_hdl;
USBH_ENTER_CRITICAL(); USBH_ENTER_CRITICAL();
dev_obj->dynamic.ref_count--; dev_obj->dynamic.open_count--;
bool call_proc_req_cb = false; bool call_proc_req_cb = false;
if (dev_obj->dynamic.ref_count == 0) { if (dev_obj->dynamic.open_count == 0) {
// Sanity check. // Sanity check.
assert(dev_obj->dynamic.num_ctrl_xfers_inflight == 0); // There cannot be any control transfer in-flight 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) { 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 // 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); 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(); USBH_ENTER_CRITICAL();
dev_obj->dynamic.flags.is_gone = 1; dev_obj->dynamic.flags.is_gone = 1;
// Check if the device can be freed immediately // Check if the device can be freed immediately
if (dev_obj->dynamic.ref_count == 0) { if (dev_obj->dynamic.open_count == 0) {
// Device is not currently referenced at all. Can free immediately. // Device is not currently opened at all. Can free immediately.
call_proc_req_cb = _dev_set_actions(dev_obj, DEV_ACTION_FREE); call_proc_req_cb = _dev_set_actions(dev_obj, DEV_ACTION_FREE);
} else { } 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, call_proc_req_cb = _dev_set_actions(dev_obj,
DEV_ACTION_EPn_HALT_FLUSH | DEV_ACTION_EPn_HALT_FLUSH |
DEV_ACTION_EP0_FLUSH | DEV_ACTION_EP0_FLUSH |