Add USB Host Library API docs

- This commit adds the API documentation for the USB Host Library.
- Warnings about the beta API are also added.
- usb_host_misc.h renamed to usb_helpers.h

components/usb/CMakeLists.txt

@@ -6,7 +6,7 @@ set(priv_require)
 if(CONFIG_USB_OTG_SUPPORTED)
     list(APPEND srcs "hcd.c"
                      "hub.c"
-                     "usb_host_misc.c"
+                     "usb_helpers.c"
                      "usb_host.c"
                      "usb_private.c"
                      "usbh.c")

components/usb/include/usb/usb_host_misc.h → components/usb/include/usb/usb_helpers.h

@@ -4,6 +4,10 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+/*
+Warning: The USB Host Library API is still a beta version and may be subject to change
+*/
+
 #pragma once
 
 #include <stdint.h>
@@ -28,7 +32,7 @@ extern "C" {
  *                      the current descriptor. On output, it is the offset of the returned descriptor.
  * @return usb_standard_desc_t* Next descriptor, NULL if end of configuration descriptor reached
  */
-const usb_standard_desc_t *usb_host_parse_next_descriptor(const usb_standard_desc_t *cur_desc, uint16_t wTotalLength, int *offset);
+const usb_standard_desc_t *usb_parse_next_descriptor(const usb_standard_desc_t *cur_desc, uint16_t wTotalLength, int *offset);
 
 /**
  * @brief Get the next descriptor of a particular type
@@ -43,7 +47,7 @@ const usb_standard_desc_t *usb_host_parse_next_descriptor(const usb_standard_des
  *                      the current descriptor. On output, it is the offset of the returned descriptor.
  * @return usb_standard_desc_t* Next descriptor, NULL if end descriptor is not found or configuration descriptor reached
  */
-const usb_standard_desc_t *usb_host_parse_next_descriptor_of_type(const usb_standard_desc_t *cur_desc, uint16_t wTotalLength, uint8_t bDescriptorType, int *offset);
+const usb_standard_desc_t *usb_parse_next_descriptor_of_type(const usb_standard_desc_t *cur_desc, uint16_t wTotalLength, uint8_t bDescriptorType, int *offset);
 
 /**
  * @brief Get the number of alternate settings for a bInterfaceNumber
@@ -55,23 +59,23 @@ const usb_standard_desc_t *usb_host_parse_next_descriptor_of_type(const usb_stan
  * @param[in] bInterfaceNumber Interface number
  * @return int The number of alternate settings that the interface has, -1 if bInterfaceNumber not found
  */
-int usb_host_parse_interface_number_of_alternate(const usb_config_desc_t *config_desc, uint8_t bInterfaceNumber);
+int usb_parse_interface_number_of_alternate(const usb_config_desc_t *config_desc, uint8_t bInterfaceNumber);
 
 /**
  * @brief Get a particular interface descriptor (using bInterfaceNumber and bAlternateSetting)
  *
  * Given a full configuration descriptor, get a particular interface descriptor.
  *
  * @note To get the number of alternate settings for a particular bInterfaceNumber, call
- *       usb_host_parse_interface_number_of_alternate()
+ *       usb_parse_interface_number_of_alternate()
  *
  * @param[in] config_desc Pointer to the start of a full configuration descriptor
  * @param[in] bInterfaceNumber Interface number
  * @param[in] bAlternateSetting Alternate setting number
  * @param[out] offset Byte offset of the interface descriptor relative to the start of the configuration descriptor. Can be NULL.
  * @return const usb_intf_desc_t* Pointer to interface descriptor, NULL if not found.
  */
-const usb_intf_desc_t *usb_host_parse_interface(const usb_config_desc_t *config_desc, uint8_t bInterfaceNumber, uint8_t bAlternateSetting, int *offset);
+const usb_intf_desc_t *usb_parse_interface_descriptor(const usb_config_desc_t *config_desc, uint8_t bInterfaceNumber, uint8_t bAlternateSetting, int *offset);
 
 /**
  * @brief Get an endpoint descriptor within an interface descriptor
@@ -88,10 +92,10 @@ const usb_intf_desc_t *usb_host_parse_interface(const usb_config_desc_t *config_
  *                      of the interface descriptor. On output, it is the offset of the endpoint descriptor.
  * @return const usb_ep_desc_t* Pointer to endpoint descriptor, NULL if not found.
  */
-const usb_ep_desc_t *usb_host_parse_endpoint_by_index(const usb_intf_desc_t *intf_desc, int index, uint16_t wTotalLength, int *offset);
+const usb_ep_desc_t *usb_parse_endpoint_descriptor_by_index(const usb_intf_desc_t *intf_desc, int index, uint16_t wTotalLength, int *offset);
 
 /**
- * @brief Get an endpoint descriptor based on the endpoint's address
+ * @brief Get an endpoint descriptor based on an endpoint's address
  *
  * Given a configuration descriptor, get an endpoint descriptor based on it's bEndpointAddress, bAlternateSetting, and
  * bInterfaceNumber.
@@ -103,12 +107,12 @@ const usb_ep_desc_t *usb_host_parse_endpoint_by_index(const usb_intf_desc_t *int
  * @param[out] offset Byte offset of the endpoint descriptor relative to the start of the configuration descriptor. Can be NULL
  * @return const usb_ep_desc_t* Pointer to endpoint descriptor, NULL if not found.
  */
-const usb_ep_desc_t *usb_host_parse_endpoint_by_address(const usb_config_desc_t *config_desc, uint8_t bInterfaceNumber, uint8_t bAlternateSetting, uint8_t bEndpointAddress, int *offset);
+const usb_ep_desc_t *usb_parse_endpoint_descriptor_by_address(const usb_config_desc_t *config_desc, uint8_t bInterfaceNumber, uint8_t bAlternateSetting, uint8_t bEndpointAddress, int *offset);
 
 // ------------------------------------------------------ Misc ---------------------------------------------------------
 
 /**
- * @brief Round up to an integer multiple of an endpoint's MPS
+ * @brief Round up to an integer multiple of endpoint's MPS
  *
  * This is a convenience function to round up a size/length to an endpoint's MPS (Maximum packet size). This is useful
  * when calculating transfer or buffer lengths of IN endpoints.
@@ -117,7 +121,7 @@ const usb_ep_desc_t *usb_host_parse_endpoint_by_address(const usb_config_desc_t
  * @param[in] mps MPS
  * @return int Round up integer multiple of MPS
  */
-static inline int usb_host_round_up_to_mps(int num_bytes, int mps)
+static inline int usb_round_up_to_mps(int num_bytes, int mps)
 {
     if (num_bytes < 0 || mps < 0) {
         return 0;

components/usb/include/usb/usb_host.h

@@ -4,14 +4,18 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+/*
+Warning: The USB Host Library API is still a beta version and may be subject to change
+*/
+
 #pragma once
 
 #include <stdint.h>
 #include "freertos/FreeRTOS.h"
 #include "esp_err.h"
 #include "esp_intr_alloc.h"
 //Include the other USB Host Library headers as well
-#include "usb/usb_host_misc.h"
+#include "usb/usb_helpers.h"
 #include "usb/usb_types_ch9.h"
 #include "usb/usb_types_stack.h"
 
@@ -197,7 +201,7 @@ esp_err_t usb_host_device_open(usb_host_client_handle_t client_hdl, uint8_t dev_
  * @brief Close a device
  *
  * - This function allows a client to close a device
- * - A client must close a device after it has finished using the device
+ * - A client must close a device after it has finished using the device (claimed interfaces must also be released)
  * - A client must close all devices it has opened before deregistering
  *
  * @param[in] client_hdl Client handle
@@ -225,7 +229,7 @@ esp_err_t usb_host_device_free_all(void);
 // ------------------- Cached Requests ---------------------
 
 /**
- * @brief Get a device's information
+ * @brief Get device's information
  *
  * - This function gets some basic information of a device
  * - The device must be opened first before attempting to get its information
@@ -241,7 +245,7 @@ esp_err_t usb_host_device_info(usb_device_handle_t dev_hdl, usb_device_info_t *d
 // ----------------- Cached Descriptors --------------------
 
 /**
- * @brief Get a device's device descriptor
+ * @brief Get device's device descriptor
  *
  * - A client must call usb_host_device_open() first
  * - No control transfer is sent. The device's descriptor is cached on enumeration
@@ -255,7 +259,7 @@ esp_err_t usb_host_device_info(usb_device_handle_t dev_hdl, usb_device_info_t *d
 esp_err_t usb_host_get_device_descriptor(usb_device_handle_t dev_hdl, const usb_device_desc_t **device_desc);
 
 /**
- * @brief Get a device's active configuration descriptor
+ * @brief Get device's active configuration descriptor
  *
  * - A client must call usb_host_device_open() first
  * - No control transfer is sent. The device's active configuration descriptor is cached on enumeration
@@ -271,7 +275,7 @@ esp_err_t usb_host_get_active_config_descriptor(usb_device_handle_t dev_hdl, con
 // ----------------------------------------------- Interface Functions -------------------------------------------------
 
 /**
- * @brief Function for a client to claim an device's interface
+ * @brief Function for a client to claim a device's interface
  *
  * - A client must claim a device's interface before attempting to communicate with any of its endpoints
  * - Once an interface is claimed by a client, it cannot be claimed by any other client.
@@ -285,7 +289,7 @@ esp_err_t usb_host_get_active_config_descriptor(usb_device_handle_t dev_hdl, con
 esp_err_t usb_host_interface_claim(usb_host_client_handle_t client_hdl, usb_device_handle_t dev_hdl, uint8_t bInterfaceNumber, uint8_t bAlternateSetting);
 
 /**
- * @brief Function for a client to release a device's interface
+ * @brief Function for a client to release a previously claimed interface
  *
  * - A client should release a device's interface after it no longer needs to communicate with the interface
  * - A client must release all of its interfaces of a device it has claimed before being able to close the device