diff --git a/components/usb/CMakeLists.txt b/components/usb/CMakeLists.txt index 50c5deb399..76aeb05ee7 100644 --- a/components/usb/CMakeLists.txt +++ b/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") diff --git a/components/usb/include/usb/usb_host_misc.h b/components/usb/include/usb/usb_helpers.h similarity index 80% rename from components/usb/include/usb/usb_host_misc.h rename to components/usb/include/usb/usb_helpers.h index ab04b471e2..d8405dd5fc 100644 --- a/components/usb/include/usb/usb_host_misc.h +++ b/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 @@ -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,7 +59,7 @@ 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) @@ -63,7 +67,7 @@ int usb_host_parse_interface_number_of_alternate(const usb_config_desc_t *config * 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 @@ -71,7 +75,7 @@ int usb_host_parse_interface_number_of_alternate(const usb_config_desc_t *config * @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; diff --git a/components/usb/include/usb/usb_host.h b/components/usb/include/usb/usb_host.h index dbc38bd385..6c104af6cf 100644 --- a/components/usb/include/usb/usb_host.h +++ b/components/usb/include/usb/usb_host.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 @@ -11,7 +15,7 @@ #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 diff --git a/components/usb/include/usb/usb_types_ch9.h b/components/usb/include/usb/usb_types_ch9.h index 4fe31b342f..7d40bc46e0 100644 --- a/components/usb/include/usb/usb_types_ch9.h +++ b/components/usb/include/usb/usb_types_ch9.h @@ -5,12 +5,7 @@ */ /* -Note: This header file contains the types and macros belong/relate to the USB2.0 protocol and are HW implementation -and mode (i.e., Host or Device) agnostic. - -- On the USB Host Stack, this header is only meant to be used on the HCD layer and above. For types and macros on the - Host stack that are HW implementation specific (i.e., HAL layer and below), add them to the "hal/usb_types_private.h" - header instead. +Warning: The USB Host Library API is still a beta version and may be subject to change */ #pragma once @@ -28,15 +23,20 @@ extern "C" /** * @brief USB2.0 device states + * + * See Table 9-1 of USB2.0 specification for more details + * + * @note The USB_DEVICE_STATE_NOT_ATTACHED is not part of the USB2.0 specification, but is a catch all state for devices + * that need to be cleaned up after a sudden disconnection or port error. */ typedef enum { - USB_DEVICE_STATE_NOT_ATTACHED, //Not in the USB spec, but is a catch all state for devices that need to be cleaned up after a sudden disconnection or port error - USB_DEVICE_STATE_ATTACHED, - USB_DEVICE_STATE_POWERED, - USB_DEVICE_STATE_DEFAULT, - USB_DEVICE_STATE_ADDRESS, - USB_DEVICE_STATE_CONFIGURED, - USB_DEVICE_STATE_SUSPENDED, + USB_DEVICE_STATE_NOT_ATTACHED, /**< The device was previously configured or suspended, but is no longer attached (either suddenly disconnected or a port error) */ + USB_DEVICE_STATE_ATTACHED, /**< Device is attached to the USB, but is not powered. */ + USB_DEVICE_STATE_POWERED, /**< Device is attached to the USB and powered, but has not been reset. */ + USB_DEVICE_STATE_DEFAULT, /**< Device is attached to the USB and powered and has been reset, but has not been assigned a unique address. Device responds at the default address. */ + USB_DEVICE_STATE_ADDRESS, /**< Device is attached to the USB, powered, has been reset, and a unique device address has been assigned. Device is not configured. */ + USB_DEVICE_STATE_CONFIGURED, /**< Device is attached to the USB, powered, has been reset, has a unique address, is configured, and is not suspended. The host may now use the function provided by the device. */ + USB_DEVICE_STATE_SUSPENDED, /**< Device is, at minimum, attached to the USB and is powered and has not seen bus activity for 3 ms. It may also have a unique address and be configured for use. However, because the device is suspended, the host may not use the device’s function. */ } usb_device_state_t; /** @@ -85,14 +85,16 @@ typedef enum { /** * @brief Structure representing a USB control transfer setup packet + * + * See Table 9-2 of USB2.0 specification for more details */ typedef union { struct { - uint8_t bmRequestType; - uint8_t bRequest; - uint16_t wValue; - uint16_t wIndex; - uint16_t wLength; + uint8_t bmRequestType; /**< Characteristics of request */ + uint8_t bRequest; /**< Specific request */ + uint16_t wValue; /**< Word-sized field that varies according to request */ + uint16_t wIndex; /**< Word-sized field that varies according to request; typically used to pass an index or offset */ + uint16_t wLength; /**< Number of bytes to transfer if there is a data stage */ } __attribute__((packed)); uint8_t val[USB_SETUP_PACKET_SIZE]; } usb_setup_packet_t; @@ -220,14 +222,14 @@ _Static_assert(sizeof(usb_setup_packet_t) == USB_SETUP_PACKET_SIZE, "Size of usb #define USB_STANDARD_DESC_SIZE 2 /** - * @brief Dummy USB standard descriptor + * @brief USB standard descriptor * - * All USB standard descriptors start with these two bytes. Use this type traversing over descriptors + * All USB standard descriptors start with these two bytes. Use this type when traversing over configuration descriptors */ typedef union { struct { - uint8_t bLength; - uint8_t bDescriptorType; + uint8_t bLength; /**< Size of the descriptor in bytes */ + uint8_t bDescriptorType; /**< Descriptor Type */ } USB_DESC_ATTR; uint8_t val[USB_STANDARD_DESC_SIZE]; } usb_standard_desc_t; @@ -242,23 +244,25 @@ _Static_assert(sizeof(usb_standard_desc_t) == USB_STANDARD_DESC_SIZE, "Size of u /** * @brief Structure representing a USB device descriptor + * + * See Table 9-8 of USB2.0 specification for more details */ typedef union { struct { - uint8_t bLength; - uint8_t bDescriptorType; - uint16_t bcdUSB; - uint8_t bDeviceClass; - uint8_t bDeviceSubClass; - uint8_t bDeviceProtocol; - uint8_t bMaxPacketSize0; - uint16_t idVendor; - uint16_t idProduct; - uint16_t bcdDevice; - uint8_t iManufacturer; - uint8_t iProduct; - uint8_t iSerialNumber; - uint8_t bNumConfigurations; + uint8_t bLength; /**< Size of the descriptor in bytes */ + uint8_t bDescriptorType; /**< DEVICE Descriptor Type */ + uint16_t bcdUSB; /**< USB Specification Release Number in Binary-Coded Decimal (i.e., 2.10 is 210H) */ + uint8_t bDeviceClass; /**< Class code (assigned by the USB-IF) */ + uint8_t bDeviceSubClass; /**< Subclass code (assigned by the USB-IF) */ + uint8_t bDeviceProtocol; /**< Protocol code (assigned by the USB-IF) */ + uint8_t bMaxPacketSize0; /**< Maximum packet size for endpoint zero (only 8, 16, 32, or 64 are valid) */ + uint16_t idVendor; /**< Vendor ID (assigned by the USB-IF) */ + uint16_t idProduct; /**< Product ID (assigned by the manufacturer) */ + uint16_t bcdDevice; /**< Device release number in binary-coded decimal */ + uint8_t iManufacturer; /**< Index of string descriptor describing manufacturer */ + uint8_t iProduct; /**< Index of string descriptor describing product */ + uint8_t iSerialNumber; /**< Index of string descriptor describing the device’s serial number */ + uint8_t bNumConfigurations; /**< Number of possible configurations */ } USB_DESC_ATTR; uint8_t val[USB_DEVICE_DESC_SIZE]; } usb_device_desc_t; @@ -307,19 +311,21 @@ _Static_assert(sizeof(usb_device_desc_t) == USB_DEVICE_DESC_SIZE, "Size of usb_d /** * @brief Structure representing a short USB configuration descriptor * + * See Table 9-10 of USB2.0 specification for more details + * * @note The full USB configuration includes all the interface and endpoint * descriptors of that configuration. */ typedef union { struct { - uint8_t bLength; - uint8_t bDescriptorType; - uint16_t wTotalLength; - uint8_t bNumInterfaces; - uint8_t bConfigurationValue; - uint8_t iConfiguration; - uint8_t bmAttributes; - uint8_t bMaxPower; + uint8_t bLength; /**< Size of the descriptor in bytes */ + uint8_t bDescriptorType; /**< CONFIGURATION Descriptor Type */ + uint16_t wTotalLength; /**< Total length of data returned for this configuration */ + uint8_t bNumInterfaces; /**< Number of interfaces supported by this configuration */ + uint8_t bConfigurationValue; /**< Value to use as an argument to the SetConfiguration() request to select this configuration */ + uint8_t iConfiguration; /**< Index of string descriptor describing this configuration */ + uint8_t bmAttributes; /**< Configuration characteristics */ + uint8_t bMaxPower; /**< Maximum power consumption of the USB device from the bus in this specific configuration when the device is fully operational. */ } USB_DESC_ATTR; uint8_t val[USB_CONFIG_DESC_SIZE]; } usb_config_desc_t; @@ -345,14 +351,14 @@ _Static_assert(sizeof(usb_config_desc_t) == USB_CONFIG_DESC_SIZE, "Size of usb_c */ typedef union { struct { - uint8_t bLength; - uint8_t bDescriptorType; - uint8_t bFirstInterface; - uint8_t bInterfaceCount; - uint8_t bFunctionClass; - uint8_t bFunctionSubClass; - uint8_t bFunctionProtocol; - uint8_t iFunction; + uint8_t bLength; /**< Size of the descriptor in bytes */ + uint8_t bDescriptorType; /**< INTERFACE ASSOCIATION Descriptor Type */ + uint8_t bFirstInterface; /**< Interface number of the first interface that is associated with this function */ + uint8_t bInterfaceCount; /**< Number of contiguous interfaces that are associated with this function */ + uint8_t bFunctionClass; /**< Class code (assigned by USB-IF) */ + uint8_t bFunctionSubClass; /**< Subclass code (assigned by USB-IF) */ + uint8_t bFunctionProtocol; /**< Protocol code (assigned by USB-IF) */ + uint8_t iFunction; /**< Index of string descriptor describing this function */ } USB_DESC_ATTR; uint8_t val[USB_IAD_DESC_SIZE]; } usb_iad_desc_t; @@ -367,18 +373,20 @@ _Static_assert(sizeof(usb_iad_desc_t) == USB_IAD_DESC_SIZE, "Size of usb_iad_des /** * @brief Structure representing a USB interface descriptor + * + * See Table 9-12 of USB2.0 specification for more details */ typedef union { struct { - uint8_t bLength; - uint8_t bDescriptorType; - uint8_t bInterfaceNumber; - uint8_t bAlternateSetting; - uint8_t bNumEndpoints; - uint8_t bInterfaceClass; - uint8_t bInterfaceSubClass; - uint8_t bInterfaceProtocol; - uint8_t iInterface; + uint8_t bLength; /**< Size of the descriptor in bytes */ + uint8_t bDescriptorType; /**< INTERFACE Descriptor Type */ + uint8_t bInterfaceNumber; /**< Number of this interface. */ + uint8_t bAlternateSetting; /**< Value used to select this alternate setting for the interface identified in the prior field */ + uint8_t bNumEndpoints; /**< Number of endpoints used by this interface (excluding endpoint zero). */ + uint8_t bInterfaceClass; /**< Class code (assigned by the USB-IF) */ + uint8_t bInterfaceSubClass; /**< Subclass code (assigned by the USB-IF) */ + uint8_t bInterfaceProtocol; /**< Protocol code (assigned by the USB) */ + uint8_t iInterface; /**< Index of string descriptor describing this interface */ } USB_DESC_ATTR; uint8_t val[USB_INTF_DESC_SIZE]; } usb_intf_desc_t; @@ -393,15 +401,17 @@ _Static_assert(sizeof(usb_intf_desc_t) == USB_INTF_DESC_SIZE, "Size of usb_intf_ /** * @brief Structure representing a USB endpoint descriptor + * + * See Table 9-13 of USB2.0 specification for more details */ typedef union { struct { - uint8_t bLength; - uint8_t bDescriptorType; - uint8_t bEndpointAddress; - uint8_t bmAttributes; - uint16_t wMaxPacketSize; - uint8_t bInterval; + uint8_t bLength; /**< Size of the descriptor in bytes */ + uint8_t bDescriptorType; /**< ENDPOINT Descriptor Type */ + uint8_t bEndpointAddress; /**< The address of the endpoint on the USB device described by this descriptor */ + uint8_t bmAttributes; /**< This field describes the endpoint’s attributes when it is configured using the bConfigurationValue. */ + uint16_t wMaxPacketSize; /**< Maximum packet size this endpoint is capable of sending or receiving when this configuration is selected. */ + uint8_t bInterval; /**< Interval for polling Isochronous and Interrupt endpoints. Expressed in frames or microframes depending on the device operating speed (1 ms for Low-Speed and Full-Speed or 125 us for USB High-Speed and above). */ } USB_DESC_ATTR; uint8_t val[USB_EP_DESC_SIZE]; } usb_ep_desc_t; @@ -451,9 +461,9 @@ _Static_assert(sizeof(usb_ep_desc_t) == USB_EP_DESC_SIZE, "Size of usb_ep_desc_t */ typedef union { struct { - uint8_t bLength; - uint8_t bDescriptorType; - uint16_t wData[1]; /* UTF-16LE encoded */ + uint8_t bLength; /**< Size of the descriptor in bytes */ + uint8_t bDescriptorType; /**< STRING Descriptor Type */ + uint16_t wData[1]; /**< UTF-16LE encoded */ } USB_DESC_ATTR; uint8_t val[USB_STR_DESC_SIZE]; } usb_str_desc_t; diff --git a/components/usb/include/usb/usb_types_stack.h b/components/usb/include/usb/usb_types_stack.h index 0db75d3788..438c22d9ef 100644 --- a/components/usb/include/usb/usb_types_stack.h +++ b/components/usb/include/usb/usb_types_stack.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 "usb/usb_types_ch9.h" @@ -101,7 +105,7 @@ typedef struct { * of the endpoint. * * @note For Bulk/Control/Interrupt IN transfers, the num_bytes must be a integer multiple of the endpoint's MPS - * @note This structure should be allocated via __insert_func_name__() + * @note This structure should be allocated via usb_host_transfer_alloc() * @note Once the transfer has be submitted, users should not modify the structure until the transfer has completed */ typedef struct usb_transfer_s usb_transfer_t; @@ -123,7 +127,7 @@ struct usb_transfer_s{ usb_device_handle_t device_handle; /**< Device handle */ uint8_t bEndpointAddress; /**< Endpoint Address */ usb_transfer_status_t status; /**< Status of the transfer */ - uint32_t timeout; /**< Timeout (in milliseconds) of the packet (currently not supported yet) */ + uint32_t timeout_ms; /**< Timeout (in milliseconds) of the packet (currently not supported yet) */ usb_transfer_cb_t callback; /**< Transfer callback */ void *context; /**< Context variable for transfer to associate transfer with something */ const int num_isoc_packets; /**< Only relevant to Isochronous. Number of service periods (i.e., intervals) to transfer data buffer over. */ diff --git a/components/usb/test/usb_host/msc_client_async_seq.c b/components/usb/test/usb_host/msc_client_async_seq.c index 6880e96ec7..7189f4cd61 100644 --- a/components/usb/test/usb_host/msc_client_async_seq.c +++ b/components/usb/test/usb_host/msc_client_async_seq.c @@ -143,7 +143,7 @@ void msc_client_async_seq_task(void *arg) usb_transfer_t *xfer_out = NULL; //Must be large enough to contain CBW and MSC reset control transfer usb_transfer_t *xfer_in = NULL; //Must be large enough to contain CSW and Data size_t out_worst_case_size = MAX(sizeof(mock_msc_bulk_cbw_t), sizeof(usb_setup_packet_t)); - size_t in_worst_case_size = usb_host_round_up_to_mps(MAX(MOCK_MSC_SCSI_SECTOR_SIZE * msc_obj.test_param.num_sectors_per_xfer, sizeof(mock_msc_bulk_csw_t)), MOCK_MSC_SCSI_BULK_EP_MPS); + size_t in_worst_case_size = usb_round_up_to_mps(MAX(MOCK_MSC_SCSI_SECTOR_SIZE * msc_obj.test_param.num_sectors_per_xfer, sizeof(mock_msc_bulk_csw_t)), MOCK_MSC_SCSI_BULK_EP_MPS); TEST_ASSERT_EQUAL(ESP_OK, usb_host_transfer_alloc(out_worst_case_size, 0, &xfer_out)); TEST_ASSERT_EQUAL(ESP_OK, usb_host_transfer_alloc(in_worst_case_size, 0, &xfer_in)); xfer_out->callback = msc_transfer_cb; @@ -207,7 +207,7 @@ void msc_client_async_seq_task(void *arg) } case TEST_STAGE_MSC_DATA: { ESP_LOGD(MSC_CLIENT_TAG, "Data"); - xfer_in->num_bytes = usb_host_round_up_to_mps(MOCK_MSC_SCSI_SECTOR_SIZE * msc_obj.test_param.num_sectors_per_xfer, MOCK_MSC_SCSI_BULK_EP_MPS); + xfer_in->num_bytes = usb_round_up_to_mps(MOCK_MSC_SCSI_SECTOR_SIZE * msc_obj.test_param.num_sectors_per_xfer, MOCK_MSC_SCSI_BULK_EP_MPS); xfer_in->bEndpointAddress = MOCK_MSC_SCSI_BULK_IN_EP_ADDR; TEST_ASSERT_EQUAL(ESP_OK, usb_host_transfer_submit(xfer_in)); //Next stage set from transfer callback @@ -215,7 +215,7 @@ void msc_client_async_seq_task(void *arg) } case TEST_STAGE_MSC_CSW: { ESP_LOGD(MSC_CLIENT_TAG, "CSW"); - xfer_in->num_bytes = usb_host_round_up_to_mps(sizeof(mock_msc_bulk_csw_t), MOCK_MSC_SCSI_BULK_EP_MPS); + xfer_in->num_bytes = usb_round_up_to_mps(sizeof(mock_msc_bulk_csw_t), MOCK_MSC_SCSI_BULK_EP_MPS); xfer_in->bEndpointAddress = MOCK_MSC_SCSI_BULK_IN_EP_ADDR; TEST_ASSERT_EQUAL(ESP_OK, usb_host_transfer_submit(xfer_in)); //Next stage set from transfer callback diff --git a/components/usb/test/usb_host/test_usb_host_misc.c b/components/usb/test/usb_host/test_usb_helpers.c similarity index 91% rename from components/usb/test/usb_host/test_usb_host_misc.c rename to components/usb/test/usb_host/test_usb_helpers.c index 465e7ca915..07f905a26c 100644 --- a/components/usb/test/usb_host/test_usb_host_misc.c +++ b/components/usb/test/usb_host/test_usb_helpers.c @@ -346,11 +346,11 @@ static void test_walk_desc(const usb_config_desc_t *config_desc) int offset = 0; const usb_standard_desc_t *cur_desc = (usb_standard_desc_t *)config_desc; for (int i = 0; i < TEST_NUM_INTF_DESC; i++) { - cur_desc = usb_host_parse_next_descriptor_of_type(cur_desc, config_desc->wTotalLength, USB_B_DESCRIPTOR_TYPE_INTERFACE, &offset); + cur_desc = usb_parse_next_descriptor_of_type(cur_desc, config_desc->wTotalLength, USB_B_DESCRIPTOR_TYPE_INTERFACE, &offset); TEST_ASSERT_NOT_EQUAL(NULL, cur_desc); } //Attempting to look for another interface descriptor should result in NULL - cur_desc = usb_host_parse_next_descriptor_of_type(cur_desc, config_desc->wTotalLength, USB_B_DESCRIPTOR_TYPE_INTERFACE, &offset); + cur_desc = usb_parse_next_descriptor_of_type(cur_desc, config_desc->wTotalLength, USB_B_DESCRIPTOR_TYPE_INTERFACE, &offset); TEST_ASSERT_EQUAL(NULL, cur_desc); } @@ -360,11 +360,11 @@ Test if the count of number of alternate descriptors is correct static void test_alt_intf_desc_count(const usb_config_desc_t *config_desc) { //bInterface 0 has no alternate interfaces - TEST_ASSERT_EQUAL(0, usb_host_parse_interface_number_of_alternate(config_desc, 0)); + TEST_ASSERT_EQUAL(0, usb_parse_interface_number_of_alternate(config_desc, 0)); //bInterface 1 has 1 alternate interface - TEST_ASSERT_EQUAL(1, usb_host_parse_interface_number_of_alternate(config_desc, 1)); + TEST_ASSERT_EQUAL(1, usb_parse_interface_number_of_alternate(config_desc, 1)); //Non existent bInterface 2 should return -1 - TEST_ASSERT_EQUAL(-1, usb_host_parse_interface_number_of_alternate(config_desc, 2)); + TEST_ASSERT_EQUAL(-1, usb_parse_interface_number_of_alternate(config_desc, 2)); } static void test_parse_intf_and_ep(const usb_config_desc_t *config_desc) @@ -372,37 +372,37 @@ static void test_parse_intf_and_ep(const usb_config_desc_t *config_desc) int offset_intf = 0; //Get bInterfaceNumber 0 (index 0) - const usb_intf_desc_t *intf_desc = usb_host_parse_interface(config_desc, 0, 0, &offset_intf); + const usb_intf_desc_t *intf_desc = usb_parse_interface_descriptor(config_desc, 0, 0, &offset_intf); TEST_ASSERT_NOT_EQUAL(NULL, intf_desc); //Should only have one endpoint int offset_ep = offset_intf; - const usb_ep_desc_t *ep_desc = usb_host_parse_endpoint_by_index(intf_desc, 0, config_desc->wTotalLength, &offset_ep); + const usb_ep_desc_t *ep_desc = usb_parse_endpoint_descriptor_by_index(intf_desc, 0, config_desc->wTotalLength, &offset_ep); TEST_ASSERT_NOT_EQUAL(NULL, ep_desc); TEST_ASSERT_EQUAL(0x83, ep_desc->bEndpointAddress); offset_ep = offset_intf; - ep_desc = usb_host_parse_endpoint_by_index(intf_desc, 1, config_desc->wTotalLength, &offset_ep); + ep_desc = usb_parse_endpoint_descriptor_by_index(intf_desc, 1, config_desc->wTotalLength, &offset_ep); TEST_ASSERT_EQUAL(NULL, ep_desc); //Get bInterfaceNumber 1 alternate setting 0 offset_intf = 0; - intf_desc = usb_host_parse_interface(config_desc, 1, 0, &offset_intf); + intf_desc = usb_parse_interface_descriptor(config_desc, 1, 0, &offset_intf); TEST_ASSERT_NOT_EQUAL(NULL, intf_desc); //Should have no endpoints offset_ep = offset_intf; - ep_desc = usb_host_parse_endpoint_by_index(intf_desc, 0, config_desc->wTotalLength, &offset_ep); + ep_desc = usb_parse_endpoint_descriptor_by_index(intf_desc, 0, config_desc->wTotalLength, &offset_ep); TEST_ASSERT_EQUAL(NULL, ep_desc); //Get bInterfaceNumber 1 alternate setting 1 offset_intf = 0; - intf_desc = usb_host_parse_interface(config_desc, 1, 1, &offset_intf); + intf_desc = usb_parse_interface_descriptor(config_desc, 1, 1, &offset_intf); TEST_ASSERT_NOT_EQUAL(NULL, intf_desc); //Should only have one endpoint offset_ep = offset_intf; - ep_desc = usb_host_parse_endpoint_by_index(intf_desc, 0, config_desc->wTotalLength, &offset_ep); + ep_desc = usb_parse_endpoint_descriptor_by_index(intf_desc, 0, config_desc->wTotalLength, &offset_ep); TEST_ASSERT_NOT_EQUAL(NULL, ep_desc); TEST_ASSERT_EQUAL(0x81, ep_desc->bEndpointAddress); offset_ep = offset_intf; - ep_desc = usb_host_parse_endpoint_by_index(intf_desc, 1, config_desc->wTotalLength, &offset_ep); + ep_desc = usb_parse_endpoint_descriptor_by_index(intf_desc, 1, config_desc->wTotalLength, &offset_ep); TEST_ASSERT_EQUAL(NULL, ep_desc); } @@ -410,26 +410,26 @@ static void test_parse_ep_by_address(const usb_config_desc_t *config_desc) { int offset_ep = 0; //Get bInterface 0 bAlternateSetting 0 EP 0x83 - const usb_ep_desc_t *ep_desc = usb_host_parse_endpoint_by_address(config_desc, 0, 0, 0x83, &offset_ep); + const usb_ep_desc_t *ep_desc = usb_parse_endpoint_descriptor_by_address(config_desc, 0, 0, 0x83, &offset_ep); TEST_ASSERT_NOT_EQUAL(NULL, ep_desc); TEST_ASSERT_EQUAL(0x83, ep_desc->bEndpointAddress); //Getting same EP address under different interface should return NULL offset_ep = 0; - ep_desc = usb_host_parse_endpoint_by_address(config_desc, 1, 0, 0x83, &offset_ep); + ep_desc = usb_parse_endpoint_descriptor_by_address(config_desc, 1, 0, 0x83, &offset_ep); TEST_ASSERT_EQUAL(NULL, ep_desc); //Get bInterface 1 bAlternateSetting 1 EP 0x81 offset_ep = 0; - ep_desc = usb_host_parse_endpoint_by_address(config_desc, 1, 1, 0x81, &offset_ep); + ep_desc = usb_parse_endpoint_descriptor_by_address(config_desc, 1, 1, 0x81, &offset_ep); TEST_ASSERT_NOT_EQUAL(NULL, ep_desc); TEST_ASSERT_EQUAL(0x81, ep_desc->bEndpointAddress); //Getting same EP address under different interface should return NULL offset_ep = 0; - ep_desc = usb_host_parse_endpoint_by_address(config_desc, 1, 0, 0x81, &offset_ep); + ep_desc = usb_parse_endpoint_descriptor_by_address(config_desc, 1, 0, 0x81, &offset_ep); TEST_ASSERT_EQUAL(NULL, ep_desc); } -TEST_CASE("Test USB Host descriptor parsing", "[usb_host][ignore]") +TEST_CASE("Test USB Helpers descriptor parsing", "[usb_host][ignore]") { const usb_config_desc_t *config_desc = (const usb_config_desc_t *)config_desc_bytes; test_walk_desc(config_desc); diff --git a/components/usb/usb_host_misc.c b/components/usb/usb_helpers.c similarity index 64% rename from components/usb/usb_host_misc.c rename to components/usb/usb_helpers.c index 072b547e31..e657c789b4 100644 --- a/components/usb/usb_host_misc.c +++ b/components/usb/usb_helpers.c @@ -8,12 +8,12 @@ #include #include #include -#include "usb/usb_host_misc.h" +#include "usb/usb_helpers.h" #include "usb/usb_types_ch9.h" // ---------------------------------------- Configuration Descriptor Parsing ------------------------------------------- -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) { assert(cur_desc != NULL && offset != NULL); if (*offset >= wTotalLength) { @@ -28,17 +28,17 @@ const usb_standard_desc_t *usb_host_parse_next_descriptor(const usb_standard_des return ret_desc; } -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) { assert(cur_desc != NULL && offset != NULL); int offset_temp = *offset; //We only want to update offset if we've actually found a descriptor //Keep stepping over descriptors until we find one of bDescriptorType or until we go out of bounds - const usb_standard_desc_t *ret_desc = usb_host_parse_next_descriptor(cur_desc, wTotalLength, &offset_temp); + const usb_standard_desc_t *ret_desc = usb_parse_next_descriptor(cur_desc, wTotalLength, &offset_temp); while (ret_desc != NULL) { if (ret_desc->bDescriptorType == bDescriptorType) { break; } - ret_desc = usb_host_parse_next_descriptor(ret_desc, wTotalLength, &offset_temp); + ret_desc = usb_parse_next_descriptor(ret_desc, wTotalLength, &offset_temp); } if (ret_desc != NULL) { //We've found a descriptor. Update the offset @@ -47,29 +47,29 @@ const usb_standard_desc_t *usb_host_parse_next_descriptor_of_type(const usb_stan return ret_desc; } -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) { assert(config_desc != NULL); int offset = 0; //Find the first interface descriptor of bInterfaceNumber - const usb_intf_desc_t *first_intf_desc = usb_host_parse_interface(config_desc, bInterfaceNumber, 0, &offset); + const usb_intf_desc_t *first_intf_desc = usb_parse_interface_descriptor(config_desc, bInterfaceNumber, 0, &offset); if (first_intf_desc == NULL) { return -1; //bInterfaceNumber not found } int num_alt_setting = 0; - const usb_intf_desc_t *next_intf_desc = (const usb_intf_desc_t *)usb_host_parse_next_descriptor_of_type((const usb_standard_desc_t *)first_intf_desc, config_desc->wTotalLength, USB_B_DESCRIPTOR_TYPE_INTERFACE, &offset); + const usb_intf_desc_t *next_intf_desc = (const usb_intf_desc_t *)usb_parse_next_descriptor_of_type((const usb_standard_desc_t *)first_intf_desc, config_desc->wTotalLength, USB_B_DESCRIPTOR_TYPE_INTERFACE, &offset); while (next_intf_desc != NULL) { if (next_intf_desc->bInterfaceNumber != bInterfaceNumber) { break; } num_alt_setting++; - next_intf_desc = (const usb_intf_desc_t *)usb_host_parse_next_descriptor_of_type((const usb_standard_desc_t *)next_intf_desc, config_desc->wTotalLength, USB_B_DESCRIPTOR_TYPE_INTERFACE, &offset); + next_intf_desc = (const usb_intf_desc_t *)usb_parse_next_descriptor_of_type((const usb_standard_desc_t *)next_intf_desc, config_desc->wTotalLength, USB_B_DESCRIPTOR_TYPE_INTERFACE, &offset); } return num_alt_setting; } -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) { assert(config_desc != NULL); if (bInterfaceNumber >= config_desc->bNumInterfaces) { @@ -78,12 +78,12 @@ const usb_intf_desc_t *usb_host_parse_interface(const usb_config_desc_t *config_ //Walk to first interface descriptor of bInterfaceNumber int offset_temp = 0; - const usb_intf_desc_t *next_intf_desc = (const usb_intf_desc_t *)usb_host_parse_next_descriptor_of_type((const usb_standard_desc_t *)config_desc, config_desc->wTotalLength, USB_B_DESCRIPTOR_TYPE_INTERFACE, &offset_temp); + const usb_intf_desc_t *next_intf_desc = (const usb_intf_desc_t *)usb_parse_next_descriptor_of_type((const usb_standard_desc_t *)config_desc, config_desc->wTotalLength, USB_B_DESCRIPTOR_TYPE_INTERFACE, &offset_temp); while (next_intf_desc != NULL) { if (next_intf_desc->bInterfaceNumber == bInterfaceNumber) { break; //We found the first interface descriptor with matching bInterfaceNumber } - next_intf_desc = (const usb_intf_desc_t *)usb_host_parse_next_descriptor_of_type((const usb_standard_desc_t *)next_intf_desc, config_desc->wTotalLength, USB_B_DESCRIPTOR_TYPE_INTERFACE, &offset_temp); + next_intf_desc = (const usb_intf_desc_t *)usb_parse_next_descriptor_of_type((const usb_standard_desc_t *)next_intf_desc, config_desc->wTotalLength, USB_B_DESCRIPTOR_TYPE_INTERFACE, &offset_temp); } if (next_intf_desc == NULL) { return NULL; //Couldn't find a interface with bInterfaceNumber @@ -101,7 +101,7 @@ const usb_intf_desc_t *usb_host_parse_interface(const usb_config_desc_t *config_ break; } //Get the next interface descriptor - next_intf_desc = (const usb_intf_desc_t *)usb_host_parse_next_descriptor_of_type((const usb_standard_desc_t *)next_intf_desc, config_desc->wTotalLength, USB_B_DESCRIPTOR_TYPE_INTERFACE, &offset_temp); + next_intf_desc = (const usb_intf_desc_t *)usb_parse_next_descriptor_of_type((const usb_standard_desc_t *)next_intf_desc, config_desc->wTotalLength, USB_B_DESCRIPTOR_TYPE_INTERFACE, &offset_temp); } if (next_intf_desc != NULL && offset != NULL) { *offset = offset_temp; @@ -109,7 +109,7 @@ const usb_intf_desc_t *usb_host_parse_interface(const usb_config_desc_t *config_ return next_intf_desc; } -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) { assert(intf_desc != NULL && offset != NULL); if (index >= intf_desc->bNumEndpoints) { @@ -120,7 +120,7 @@ const usb_ep_desc_t *usb_host_parse_endpoint_by_index(const usb_intf_desc_t *int bool ep_found = true; const usb_standard_desc_t *next_desc = (const usb_standard_desc_t *)intf_desc; for (int i = 0; i <= index; i++) { - next_desc = usb_host_parse_next_descriptor_of_type((const usb_standard_desc_t *)next_desc, wTotalLength, USB_B_DESCRIPTOR_TYPE_ENDPOINT, &offset_temp); + next_desc = usb_parse_next_descriptor_of_type((const usb_standard_desc_t *)next_desc, wTotalLength, USB_B_DESCRIPTOR_TYPE_ENDPOINT, &offset_temp); if (next_desc == NULL) { ep_found = false; break; @@ -133,13 +133,13 @@ const usb_ep_desc_t *usb_host_parse_endpoint_by_index(const usb_intf_desc_t *int return NULL; } -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) { assert(config_desc != NULL); //Find the interface descriptor int offset_intf; - const usb_intf_desc_t *intf_desc = usb_host_parse_interface(config_desc, bInterfaceNumber, bAlternateSetting, &offset_intf); + const usb_intf_desc_t *intf_desc = usb_parse_interface_descriptor(config_desc, bInterfaceNumber, bAlternateSetting, &offset_intf); if (intf_desc == NULL) { return NULL; } @@ -150,7 +150,7 @@ const usb_ep_desc_t *usb_host_parse_endpoint_by_address(const usb_config_desc_t const usb_ep_desc_t *ep_desc = NULL; for (int index = 0; index < intf_desc->bNumEndpoints; index++) { offset_ep = offset_intf; - ep_desc = usb_host_parse_endpoint_by_index(intf_desc, index, config_desc->wTotalLength, &offset_ep); + ep_desc = usb_parse_endpoint_descriptor_by_index(intf_desc, index, config_desc->wTotalLength, &offset_ep); if (ep_desc == NULL) { break; } diff --git a/components/usb/usb_host.c b/components/usb/usb_host.c index f745001b22..5759fd6a41 100644 --- a/components/usb/usb_host.c +++ b/components/usb/usb_host.c @@ -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 +*/ + #include #include #include "freertos/FreeRTOS.h" @@ -921,7 +925,7 @@ static esp_err_t interface_claim(client_t *client_obj, usb_device_handle_t dev_h //We need to walk to configuration descriptor to find the correct interface descriptor, and each of its constituent endpoint descriptors //Find the interface descriptor and allocate the interface object int offset_intf; - const usb_intf_desc_t *intf_desc = usb_host_parse_interface(config_desc, bInterfaceNumber, bAlternateSetting, &offset_intf); + const usb_intf_desc_t *intf_desc = usb_parse_interface_descriptor(config_desc, bInterfaceNumber, bAlternateSetting, &offset_intf); if (intf_desc == NULL) { ret = ESP_ERR_NOT_FOUND; goto exit; @@ -935,7 +939,7 @@ static esp_err_t interface_claim(client_t *client_obj, usb_device_handle_t dev_h //Find each endpoint descriptor in the interface by index, and allocate those endpoints for (int i = 0; i < intf_desc->bNumEndpoints; i++) { int offset_ep = offset_intf; - const usb_ep_desc_t *ep_desc = usb_host_parse_endpoint_by_index(intf_desc, i, config_desc->wTotalLength, &offset_ep); + const usb_ep_desc_t *ep_desc = usb_parse_endpoint_descriptor_by_index(intf_desc, i, config_desc->wTotalLength, &offset_ep); if (ep_desc == NULL) { ret = ESP_ERR_NOT_FOUND; goto ep_alloc_err; diff --git a/components/usb/usbh.c b/components/usb/usbh.c index d05cf6a000..b8e8cfd784 100644 --- a/components/usb/usbh.c +++ b/components/usb/usbh.c @@ -17,7 +17,7 @@ #include "esp_heap_caps.h" #include "hcd.h" #include "usbh.h" -#include "usb/usb_host_misc.h" +#include "usb/usb_helpers.h" #include "usb/usb_types_ch9.h" //Device action flags. Listed in the order they should handled in. Some actions are mutually exclusive diff --git a/docs/conf_common.py b/docs/conf_common.py index 46dcddd920..33328995c9 100644 --- a/docs/conf_common.py +++ b/docs/conf_common.py @@ -49,6 +49,7 @@ LEGACY_DOCS = ['api-guides/build-system-legacy.rst', 'get-started-legacy/**'] USB_DOCS = ['api-reference/peripherals/usb_device.rst', + 'api-reference/peripherals/usb_host.rst', 'api-guides/usb-otg-console.rst', 'api-guides/dfu.rst'] diff --git a/docs/doxygen/Doxyfile_esp32s2 b/docs/doxygen/Doxyfile_esp32s2 index b0264e7274..c1fdf45624 100644 --- a/docs/doxygen/Doxyfile_esp32s2 +++ b/docs/doxygen/Doxyfile_esp32s2 @@ -14,4 +14,8 @@ INPUT += \ $(PROJECT_PATH)/components/touch_element/include/touch_element/touch_element.h \ $(PROJECT_PATH)/components/touch_element/include/touch_element/touch_button.h \ $(PROJECT_PATH)/components/touch_element/include/touch_element/touch_slider.h \ - $(PROJECT_PATH)/components/touch_element/include/touch_element/touch_matrix.h + $(PROJECT_PATH)/components/touch_element/include/touch_element/touch_matrix.h \ + $(PROJECT_PATH)/components/usb/include/usb/usb_helpers.h \ + $(PROJECT_PATH)/components/usb/include/usb/usb_host.h \ + $(PROJECT_PATH)/components/usb/include/usb/usb_types_ch9.h \ + $(PROJECT_PATH)/components/usb/include/usb/usb_types_stack.h diff --git a/docs/doxygen/Doxyfile_esp32s3 b/docs/doxygen/Doxyfile_esp32s3 index 021e46ae76..88174f2144 100644 --- a/docs/doxygen/Doxyfile_esp32s3 +++ b/docs/doxygen/Doxyfile_esp32s3 @@ -6,4 +6,8 @@ INPUT += \ $(PROJECT_PATH)/components/hal/include/hal/pcnt_types.h \ $(PROJECT_PATH)/components/driver/include/driver/pcnt.h \ $(PROJECT_PATH)/components/soc/$(IDF_TARGET)/include/soc/touch_sensor_channel.h \ - $(PROJECT_PATH)/components/driver/$(IDF_TARGET)/include/driver/touch_sensor.h + $(PROJECT_PATH)/components/driver/$(IDF_TARGET)/include/driver/touch_sensor.h \ + $(PROJECT_PATH)/components/usb/include/usb/usb_helpers.h \ + $(PROJECT_PATH)/components/usb/include/usb/usb_host.h \ + $(PROJECT_PATH)/components/usb/include/usb/usb_types_ch9.h \ + $(PROJECT_PATH)/components/usb/include/usb/usb_types_stack.h diff --git a/docs/en/api-reference/peripherals/index.rst b/docs/en/api-reference/peripherals/index.rst index d52fbd8e7f..29a0bf94da 100644 --- a/docs/en/api-reference/peripherals/index.rst +++ b/docs/en/api-reference/peripherals/index.rst @@ -34,5 +34,6 @@ Peripherals API TWAI UART :SOC_USB_OTG_SUPPORTED: USB Device + :SOC_USB_OTG_SUPPORTED: USB Host Code examples for this API section are provided in the :example:`peripherals` directory of ESP-IDF examples. \ No newline at end of file diff --git a/docs/en/api-reference/peripherals/usb_host.rst b/docs/en/api-reference/peripherals/usb_host.rst new file mode 100644 index 0000000000..91a2ae44d1 --- /dev/null +++ b/docs/en/api-reference/peripherals/usb_host.rst @@ -0,0 +1,26 @@ +USB Host +======== + +.. warning:: + The USB Host Library API is a beta version thus is subject to change. + +The following document lists the API and types of the USB Host Library (that is currently under development). + +API Reference +------------- + +The API of the USB Host Library is separated into the following header files. However, it is sufficient for applications to only ``#include "usb/usb_host.h"`` and all of USB Host Library headers will also be included. + +- :component_file:`usb/include/usb/usb_host.h` contains the functions and types of the USB Host Library +- :component_file:`usb/include/usb/usb_helpers.h` contains various helper functions that are related to the USB protocol such as descriptor parsing. +- :component_file:`usb/include/usb/usb_types_stack.h` contains types that are are used across multiple layers of the USB Host stack. +- :component_file:`usb/include/usb/usb_types_ch9.h` contains types and macros related to Chapter 9 of the USB2.0 specification (i.e., descriptors and standard requests). + + +.. include-build-file:: inc/usb_host.inc + +.. include-build-file:: inc/usb_helpers.inc + +.. include-build-file:: inc/usb_types_stack.inc + +.. include-build-file:: inc/usb_types_ch9.inc diff --git a/docs/zh_CN/api-reference/peripherals/index.rst b/docs/zh_CN/api-reference/peripherals/index.rst index 373b041ed5..0232a33d4a 100644 --- a/docs/zh_CN/api-reference/peripherals/index.rst +++ b/docs/zh_CN/api-reference/peripherals/index.rst @@ -33,6 +33,7 @@ :esp32s2: Touch Element TWAI UART - :SOC_USB_OTG_SUPPORTED: USB Device + :SOC_USB_OTG_SUPPORTED: USB 设备 (Device) + :SOC_USB_OTG_SUPPORTED: USB 主机 (Host) 本部分的 API 示例代码存放在 ESP-IDF 示例项目的 :example:`peripherals` 目录下。 \ No newline at end of file diff --git a/docs/zh_CN/api-reference/peripherals/usb_host.rst b/docs/zh_CN/api-reference/peripherals/usb_host.rst new file mode 100644 index 0000000000..64ba8042f5 --- /dev/null +++ b/docs/zh_CN/api-reference/peripherals/usb_host.rst @@ -0,0 +1 @@ +.. include:: ../../../en/api-reference/peripherals/usb_host.rst \ No newline at end of file