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.

Author: Dazza0

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

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,15 +896,15 @@ 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;
 }
 
 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 ---------------------------------------------------

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 @@ esp_err_t usbh_dev_open(uint8_t dev_addr, usb_device_handle_t *dev_hdl)
     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 |