USB Host

警告

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.

• usb/include/usb/usb_host.h contains the functions and types of the USB Host Library

• usb/include/usb/usb_helpers.h contains various helper functions that are related to the USB protocol such as descriptor parsing.

• usb/include/usb/usb_types_stack.h contains types that are are used across multiple layers of the USB Host stack.

• 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).

Header File

• components/usb/include/usb/usb_host.h

Functions

esp_err_t usb_host_install(const usb_host_config_t *config)

Install the USB Host Library.

• This function should only once to install the USB Host Library

• This function should be called before any other USB Host Library functions are called

Return

esp_err_t

Parameters

• [in] config: USB Host Library configuration

esp_err_t usb_host_uninstall(void)

Uninstall the USB Host Library.

• This function should be called to uninstall the USB Host Library, thereby freeing its resources

• All clients must have been deregistered before calling this function

• All devices must have been freed by calling usb_host_device_free_all() and receiving the USB_HOST_LIB_EVENT_FLAGS_ALL_FREE event flag

Return

esp_err_t

esp_err_t usb_host_lib_handle_events(TickType_t timeout_ticks, uint32_t *event_flags_ret)

Handle USB Host Library events.

• This function handles all of the USB Host Library’s processing and should be called repeatedly in a loop

• Check event_flags_ret to see if an flags are set indicating particular USB Host Library events

Return

esp_err_t

Parameters

• [in] timeout_ticks: Timeout in ticks to wait for an event to occur

• [out] event_flags_ret: Event flags that indicate what USB Host Library event occurred

esp_err_t usb_host_client_register(const usb_host_client_config_t *client_config, usb_host_client_handle_t *client_hdl_ret)

Register a client of the USB Host Library.

• This function registers a client of the USB Host Library

• Once a client is registered, its processing function usb_host_client_handle_events() should be called repeatedly

Return

esp_err_t

Parameters

• [in] client_config: Client configuration

• [out] client_hdl_ret: Client handle

esp_err_t usb_host_client_deregister(usb_host_client_handle_t client_hdl)

Deregister a USB Host Library client.

• This function deregisters a client of the USB Host Library

• The client must have closed all previously opened devices before attempting to deregister

Return

esp_err_t

Parameters

• [in] client_hdl: Client handle

esp_err_t usb_host_client_handle_events(usb_host_client_handle_t client_hdl, TickType_t timeout_ticks)

USB Host Library client processing function.

• This function handles all of a client’s processing and should be called repeatedly in a loop

Return

esp_err_t

Parameters

• [in] client_hdl: Client handle

• [in] timeout_ticks: Timeout in ticks to wait for an event to occur

esp_err_t usb_host_client_unblock(usb_host_client_handle_t client_hdl)

Unblock a client.

• This function simply unblocks a client if it is blocked on the usb_host_client_handle_events() function.

• This function is useful when need to unblock a client in order to deregister it.

Return

esp_err_t

Parameters

• [in] client_hdl: Client handle

esp_err_t usb_host_device_open(usb_host_client_handle_t client_hdl, uint8_t dev_addr, usb_device_handle_t *dev_hdl_ret)

Open a device.

• This function allows a client to open a device

• A client must open a device first before attempting to use it (e.g., sending transfers, device requests etc.)

Return

esp_err_t

Parameters

• [in] client_hdl: Client handle

• [in] dev_addr: Device’s address

• [out] dev_hdl_ret: Device’s handle

esp_err_t usb_host_device_close(usb_host_client_handle_t client_hdl, usb_device_handle_t dev_hdl)

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 (claimed interfaces must also be released)

• A client must close all devices it has opened before deregistering

Return

esp_err_t

Parameters

• [in] client_hdl: Client handle

• [in] dev_hdl: Device handle

esp_err_t usb_host_device_free_all(void)

Indicate that all devices can be freed when possible.

• This function marks all devices as waiting to be freed

• If a device is not opened by any clients, it will be freed immediately

• If a device is opened by at least one client, the device will be free when the last client closes that device.

• Wait for the USB_HOST_LIB_EVENT_FLAGS_ALL_FREE flag to be set by usb_host_lib_handle_events() in order to know when all devices have been freed

• This function is useful when cleaning up devices before uninstalling the USB Host Library

Return

esp_err_t

esp_err_t usb_host_device_info(usb_device_handle_t dev_hdl, usb_device_info_t *dev_info)

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

Return

esp_err_t

Parameters

• [in] dev_hdl: Device handle

• [out] dev_info: Device information

esp_err_t usb_host_get_device_descriptor(usb_device_handle_t dev_hdl, const usb_device_desc_t **device_desc)

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

• This function simple returns a pointer to the cached descriptor

Note

No control transfer is sent. The device’s descriptor is cached on enumeration

Return

esp_err_t

Parameters

• [in] dev_hdl: Device handle

• [out] device_desc: Device descriptor

esp_err_t usb_host_get_active_config_descriptor(usb_device_handle_t dev_hdl, const usb_config_desc_t **config_desc)

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

• This function simple returns a pointer to the cached descriptor

Note

No control transfer is sent. A device’s active configuration descriptor is cached on enumeration

Return

esp_err_t

Parameters

• [in] dev_hdl: Device handle

• [out] config_desc: Configuration descriptor

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)

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.

Return

esp_err_t

Parameters

• [in] client_hdl: Client handle

• [in] dev_hdl: Device handle

• [in] bInterfaceNumber: Interface number

• [in] bAlternateSetting: Interface alternate setting number

esp_err_t usb_host_interface_release(usb_host_client_handle_t client_hdl, usb_device_handle_t dev_hdl, uint8_t bInterfaceNumber)

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

Return

esp_err_t

Parameters

• [in] client_hdl: Client handle

• [in] dev_hdl: Device handle

• [in] bInterfaceNumber: Interface number

esp_err_t usb_host_endpoint_halt(usb_device_handle_t dev_hdl, uint8_t bEndpointAddress)

Halt a particular endpoint.

• The device must have been opened by a client

• The endpoint must be part of an interface claimed by a client

• Once halted, the endpoint must be cleared using usb_host_endpoint_clear() before it can communicate again

Return

esp_err_t

Parameters

• dev_hdl: Device handle

• bEndpointAddress: Endpoint address

esp_err_t usb_host_endpoint_flush(usb_device_handle_t dev_hdl, uint8_t bEndpointAddress)

Flush a particular endpoint.

• The device must have been opened by a client

• The endpoint must be part of an interface claimed by a client

• The endpoint must have been halted (either through a transfer error, or usb_host_endpoint_halt())

• Flushing an endpoint will caused an queued up transfers to be canceled

Return

esp_err_t

Parameters

• dev_hdl: Device handle

• bEndpointAddress: Endpoint address

esp_err_t usb_host_endpoint_clear(usb_device_handle_t dev_hdl, uint8_t bEndpointAddress)

Clear a halt on a particular endpoint.

• The device must have been opened by a client

• The endpoint must be part of an interface claimed by a client

• The endpoint must have been halted (either through a transfer error, or usb_host_endpoint_halt())

• If the endpoint has any queued up transfers, clearing a halt will resume their execution

Return

esp_err_t

Parameters

• dev_hdl: Device handle

• bEndpointAddress: Endpoint address

esp_err_t usb_host_transfer_alloc(size_t data_buffer_size, int num_isoc_packets, usb_transfer_t **transfer)

Allocate a transfer object.

• This function allocates a transfer object

• Each transfer object has a fixed sized buffer specified on allocation

• A transfer object can be re-used indefinitely

• A transfer can be submitted using usb_host_transfer_submit() or usb_host_transfer_submit_control()

Return

esp_err_t

Parameters

• [in] data_buffer_size: Size of the transfer’s data buffer

• [in] num_isoc_packets: Number of isochronous packets in transfer (set to 0 for non-isochronous transfers)

• [out] transfer: Transfer object

esp_err_t usb_host_transfer_free(usb_transfer_t *transfer)

Free a transfer object.

• Free a transfer object previously allocated using usb_host_transfer_alloc()

• The transfer must not be in-flight when attempting to free it

Return

esp_err_t

Parameters

• [in] transfer: Transfer object

esp_err_t usb_host_transfer_submit(usb_transfer_t *transfer)

Submit a non-control transfer.

• Submit a transfer to a particular endpoint. The device and endpoint number is specified inside the transfer

• The transfer must be properly initialized before submitting

• On completion, the transfer’s callback will be called from the client’s usb_host_client_handle_events() function.

Return

esp_err_t

Parameters

• [in] transfer: Initialized transfer object

esp_err_t usb_host_transfer_submit_control(usb_host_client_handle_t client_hdl, usb_transfer_t *transfer)

Submit a control transfer.

• Submit a control transfer to a particular device. The client must have opened the device first

• The transfer must be properly initialized before submitting. The first 8 bytes of the transfer’s data buffer should contain the control transfer setup packet

• On completion, the transfer’s callback will be called from the client’s usb_host_client_handle_events() function.

Return

esp_err_t

Parameters

• [in] client_hdl: Client handle

• [in] transfer: Initialized transfer object

esp_err_t usb_host_transfer_cancel(usb_transfer_t *transfer)

Cancel a submitted transfer.

• Cancel a previously submitted transfer

• In its current implementation, any transfer that is already in-flight will not be canceled

Return

esp_err_t

Parameters

• transfer: Transfer object

Structures

struct usb_host_client_event_msg_t

Client event message.

Client event messages are sent to each client of the USB Host Library in order to notify them of various USB Host Library events such as:

• Addition of new devices

• Removal of existing devices

Note

The event message structure has a union with members corresponding to each particular event. Based on the event type, only the relevant member field should be accessed.

Public Members

usb_host_client_event_t event

Type of event

uint8_t address

New device’s address

usb_device_handle_t dev_hdl

The handle of the device that was gone

struct usb_host_config_t

USB Host Library configuration.

Configuration structure of the USB Host Library. Provided in the usb_host_install() function

Public Members

int intr_flags

Interrupt flags for the underlying ISR used by the USB Host stack

struct usb_host_client_config_t

USB Host Library Client configuration.

Configuration structure for a USB Host Library client. Provided in usb_host_client_register()

Public Members

usb_host_client_event_cb_t client_event_callback

Client’s event callback function

void *callback_arg

Event callback function argument

int max_num_event_msg

Maximum number of event messages that can be stored (e.g., 3)

Macros

USB_HOST_LIB_EVENT_FLAGS_NO_CLIENTS

All clients have been deregistered from the USB Host Library

USB_HOST_LIB_EVENT_FLAGS_ALL_FREE

The USB Host Library has freed all devices

Type Definitions

typedef void *usb_host_client_handle_t

Handle to a client using the USB Host Library

typedef void (*usb_host_client_event_cb_t)(const usb_host_client_event_msg_t *event_msg, void *arg)

Client event callback.

• Each client of the USB Host Library must register an event callback to receive event messages from the USB Host Library.

• The client event callback is run from the context of the clients usb_host_client_handle_events() function

Enumerations

enum usb_host_client_event_t

The type event in a client event message.

Values:

USB_HOST_CLIENT_EVENT_NEW_DEV

A new device has been enumerated and added to the USB Host Library

USB_HOST_CLIENT_EVENT_DEV_GONE

A device opened by the client is now gone

Header File

• components/usb/include/usb/usb_helpers.h

Functions

const usb_standard_desc_t *usb_parse_next_descriptor(const usb_standard_desc_t *cur_desc, uint16_t wTotalLength, int *offset)

Get the next descriptor.

Given a particular descriptor within a full configuration descriptor, get the next descriptor within the configuration descriptor. This is a convenience function that can be used to walk each individual descriptor within a full configuration descriptor.

Return

usb_standard_desc_t* Next descriptor, NULL if end of configuration descriptor reached

Parameters

• [in] cur_desc: Current descriptor

• [in] wTotalLength: Total length of the configuration descriptor

• [inout] offset: Byte offset relative to the start of the configuration descriptor. On input, it is the offset of the current descriptor. On output, it is the offset of the returned descriptor.

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)

Get the next descriptor of a particular type.

Given a particular descriptor within a full configuration descriptor, get the next descriptor of a particular type (i.e., using the bDescriptorType value) within the configuration descriptor.

Return

usb_standard_desc_t* Next descriptor, NULL if end descriptor is not found or configuration descriptor reached

Parameters

• [in] cur_desc: Current descriptor

• [in] wTotalLength: Total length of the configuration descriptor

• [in] bDescriptorType: Type of the next descriptor to get

• [inout] offset: Byte offset relative to the start of the configuration descriptor. On input, it is the offset of the current descriptor. On output, it is the offset of the returned descriptor.

int usb_parse_interface_number_of_alternate(const usb_config_desc_t *config_desc, uint8_t bInterfaceNumber)

Get the number of alternate settings for a bInterfaceNumber.

Given a particular configuration descriptor, for a particular bInterfaceNumber, get the number of alternate settings available for that interface (i.e., the max possible value of bAlternateSetting for that bInterfaceNumber).

Return

int The number of alternate settings that the interface has, -1 if bInterfaceNumber not found

Parameters

• [in] config_desc: Pointer to the start of a full configuration descriptor

• [in] bInterfaceNumber: Interface number

const usb_intf_desc_t *usb_parse_interface_descriptor(const usb_config_desc_t *config_desc, uint8_t bInterfaceNumber, uint8_t bAlternateSetting, int *offset)

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_parse_interface_number_of_alternate()

Return

const usb_intf_desc_t* Pointer to interface descriptor, NULL if not found.

Parameters

• [in] config_desc: Pointer to the start of a full configuration descriptor

• [in] bInterfaceNumber: Interface number

• [in] bAlternateSetting: Alternate setting number

• [out] offset: Byte offset of the interface descriptor relative to the start of the configuration descriptor. Can be NULL.

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)

Get an endpoint descriptor within an interface descriptor.

Given an interface descriptor, get the Nth endpoint descriptor of the interface. The number of endpoints in an interface is indicated by the bNumEndpoints field of the interface descriptor.

Note

If bNumEndpoints is 0, it means the interface uses the default endpoint only

Return

const usb_ep_desc_t* Pointer to endpoint descriptor, NULL if not found.

Parameters

• [in] intf_desc: Pointer to thee start of an interface descriptor

• [in] index: Endpoint index

• [in] wTotalLength: Total length of the containing configuration descriptor

• [inout] offset: Byte offset relative to the start of the configuration descriptor. On input, it is the offset of the interface descriptor. On output, it is the offset of the endpoint descriptor.

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)

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.

Return

const usb_ep_desc_t* Pointer to endpoint descriptor, NULL if not found.

Parameters

• [in] config_desc: Pointer to the start of a full configuration descriptor

• [in] bInterfaceNumber: Interface number

• [in] bAlternateSetting: Alternate setting number

• [in] bEndpointAddress: Endpoint address

• [out] offset: Byte offset of the endpoint descriptor relative to the start of the configuration descriptor. Can be NULL

static int usb_round_up_to_mps(int num_bytes, int mps)

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.

Return

int Round up integer multiple of MPS

Parameters

• [in] num_bytes: Number of bytes

• [in] mps: MPS

Header File

• components/usb/include/usb/usb_types_stack.h

Structures

struct usb_device_info_t

Basic information of an enumerated device.

Public Members

usb_speed_t speed

Device’s speed

uint8_t dev_addr

Device’s address

uint8_t bMaxPacketSize0

The maximum packet size of the device’s default endpoint

uint8_t bConfigurationValue

Device’s current configuration number

struct usb_isoc_packet_desc_t

Isochronous packet descriptor.

If the number of bytes in an Isochronous transfer is larger than the MPS of the endpoint, the transfer is split into multiple packets transmitted at the endpoint’s specified interval. An array of Isochronous packet descriptors describes how an Isochronous transfer should be split into multiple packets.

Public Members

int num_bytes

Number of bytes to transmit/receive in the packet. IN packets should be integer multiple of MPS

int actual_num_bytes

Actual number of bytes transmitted/received in the packet

usb_transfer_status_t status

Status of the packet

struct usb_transfer_s

Public Members

uint8_t *const data_buffer

Pointer to data buffer

const size_t data_buffer_size

Size of the data buffer in bytes

int num_bytes

Number of bytes to transfer. Control transfers should include the size of the setup packet. Isochronous transfer should be the total transfer size of all packets. For non-control IN transfers, num_bytes should be an integer multiple of MPS.

int actual_num_bytes

Actual number of bytes transferred

uint32_t flags

Transfer flags

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_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.

usb_isoc_packet_desc_t isoc_packet_desc[0]

Descriptors for each Isochronous packet

Macros

USB_TRANSFER_FLAG_ZERO_PACK

(For bulk OUT only). Indicates that a bulk OUT transfers should always terminate with a short packet, even if it means adding an extra zero length packet

Type Definitions

typedef void *usb_device_handle_t

Handle of a USB Device connected to a USB Host.

typedef struct usb_transfer_s usb_transfer_t

USB transfer structure.

This structure is used to represent a transfer from a software client to an endpoint over the USB bus. Some of the fields are made const on purpose as they are fixed on allocation. Users should call the appropriate USB Host Library function to allocate a USB transfer structure instead of allocating this structure themselves.

The transfer type is inferred from the endpoint this transfer is sent to. Depending on the transfer type, users should note the following:

• Bulk: This structure represents a single bulk transfer. If the number of bytes exceeds the endpoint’s MPS, the transfer will be split into multiple MPS sized packets followed by a short packet.

• Control: This structure represents a single control transfer. This first 8 bytes of the data_buffer must be filled with the setup packet (see usb_setup_packet_t). The num_bytes field should be the total size of the transfer (i.e., size of setup packet + wLength).

• Interrupt: Represents an interrupt transfer. If num_bytes exceeds the MPS of the endpoint, the transfer will be split into multiple packets, and each packet is transferred at the endpoint’s specified interval.

• Isochronous: Represents a stream of bytes that should be transferred to an endpoint at a fixed rate. The transfer is split into packets according to the each isoc_packet_desc. A packet is transferred at each interval 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 usb_host_transfer_alloc()

Note

Once the transfer has be submitted, users should not modify the structure until the transfer has completed

typedef void (*usb_transfer_cb_t)(usb_transfer_t *transfer)

USB transfer completion callback.

Enumerations

enum usb_speed_t

USB Standard Speeds.

Values:

USB_SPEED_LOW = 0

USB Low Speed (1.5 Mbit/s)

USB_SPEED_FULL

USB Full Speed (12 Mbit/s)

enum usb_transfer_type_t

The type of USB transfer.

Note

The enum values need to match the bmAttributes field of an EP descriptor

Values:

USB_TRANSFER_TYPE_CTRL = 0

USB_TRANSFER_TYPE_ISOCHRONOUS

USB_TRANSFER_TYPE_BULK

USB_TRANSFER_TYPE_INTR

enum usb_transfer_status_t

The status of a particular transfer.

Values:

USB_TRANSFER_STATUS_COMPLETED

The transfer was successful (but may be short)

USB_TRANSFER_STATUS_ERROR

The transfer failed because due to excessive errors (e.g. no response or CRC error)

USB_TRANSFER_STATUS_TIMED_OUT

The transfer failed due to a time out

USB_TRANSFER_STATUS_CANCELED

The transfer was canceled

USB_TRANSFER_STATUS_STALL

The transfer was stalled

USB_TRANSFER_STATUS_OVERFLOW

The transfer as more data was sent than was requested

USB_TRANSFER_STATUS_SKIPPED

ISOC packets only. The packet was skipped due to system latency or bus overload

Header File

• components/usb/include/usb/usb_types_ch9.h

Unions

union usb_setup_packet_t

#include <usb_types_ch9.h>

Structure representing a USB control transfer setup packet.

See Table 9-2 of USB2.0 specification for more details

Public Members

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

struct usb_setup_packet_t::[anonymous] [anonymous]

uint8_t val[USB_SETUP_PACKET_SIZE]

union usb_standard_desc_t

#include <usb_types_ch9.h>

USB standard descriptor.

All USB standard descriptors start with these two bytes. Use this type when traversing over configuration descriptors

Public Members

uint8_t bLength

Size of the descriptor in bytes

uint8_t bDescriptorType

Descriptor Type

struct usb_standard_desc_t::[anonymous] USB_DESC_ATTR

uint8_t val[USB_STANDARD_DESC_SIZE]

union usb_device_desc_t

#include <usb_types_ch9.h>

Structure representing a USB device descriptor.

See Table 9-8 of USB2.0 specification for more details

Public Members

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

struct usb_device_desc_t::[anonymous] USB_DESC_ATTR

uint8_t val[USB_DEVICE_DESC_SIZE]

union usb_config_desc_t

#include <usb_types_ch9.h>

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.

Public Members

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.

struct usb_config_desc_t::[anonymous] USB_DESC_ATTR

uint8_t val[USB_CONFIG_DESC_SIZE]

union usb_iad_desc_t

#include <usb_types_ch9.h>

Structure representing a USB interface association descriptor.

Public Members

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

struct usb_iad_desc_t::[anonymous] USB_DESC_ATTR

uint8_t val[USB_IAD_DESC_SIZE]

union usb_intf_desc_t

#include <usb_types_ch9.h>

Structure representing a USB interface descriptor.

See Table 9-12 of USB2.0 specification for more details

Public Members

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

struct usb_intf_desc_t::[anonymous] USB_DESC_ATTR

uint8_t val[USB_INTF_DESC_SIZE]

union usb_ep_desc_t

#include <usb_types_ch9.h>

Structure representing a USB endpoint descriptor.

See Table 9-13 of USB2.0 specification for more details

Public Members

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).

struct usb_ep_desc_t::[anonymous] USB_DESC_ATTR

uint8_t val[USB_EP_DESC_SIZE]

union usb_str_desc_t

#include <usb_types_ch9.h>

Structure representing a USB string descriptor.

Public Members

uint8_t bLength

Size of the descriptor in bytes

uint8_t bDescriptorType

STRING Descriptor Type

uint16_t wData[1]

UTF-16LE encoded

struct usb_str_desc_t::[anonymous] USB_DESC_ATTR

uint8_t val[USB_STR_DESC_SIZE]

Macros

USB_DESC_ATTR

USB_B_DESCRIPTOR_TYPE_DEVICE

Descriptor types from USB2.0 specification table 9.5.

USB_B_DESCRIPTOR_TYPE_CONFIGURATION

USB_B_DESCRIPTOR_TYPE_STRING

USB_B_DESCRIPTOR_TYPE_INTERFACE

USB_B_DESCRIPTOR_TYPE_ENDPOINT

USB_B_DESCRIPTOR_TYPE_DEVICE_QUALIFIER

USB_B_DESCRIPTOR_TYPE_OTHER_SPEED_CONFIGURATION

USB_B_DESCRIPTOR_TYPE_INTERFACE_POWER

USB_B_DESCRIPTOR_TYPE_OTG

Descriptor types from USB 2.0 ECN.

USB_B_DESCRIPTOR_TYPE_DEBUG

USB_B_DESCRIPTOR_TYPE_INTERFACE_ASSOCIATION

USB_B_DESCRIPTOR_TYPE_SECURITY

Descriptor types from Wireless USB spec.

USB_B_DESCRIPTOR_TYPE_KEY

USB_B_DESCRIPTOR_TYPE_ENCRYPTION_TYPE

USB_B_DESCRIPTOR_TYPE_BOS

USB_B_DESCRIPTOR_TYPE_DEVICE_CAPABILITY

USB_B_DESCRIPTOR_TYPE_WIRELESS_ENDPOINT_COMP

USB_B_DESCRIPTOR_TYPE_WIRE_ADAPTER

USB_B_DESCRIPTOR_TYPE_RPIPE

USB_B_DESCRIPTOR_TYPE_CS_RADIO_CONTROL

USB_B_DESCRIPTOR_TYPE_PIPE_USAGE

Descriptor types from UAS specification.

USB_SETUP_PACKET_SIZE

Size of a USB control transfer setup packet in bytes.

USB_BM_REQUEST_TYPE_DIR_OUT

Bit masks belonging to the bmRequestType field of a setup packet.

USB_BM_REQUEST_TYPE_DIR_IN

USB_BM_REQUEST_TYPE_TYPE_STANDARD

USB_BM_REQUEST_TYPE_TYPE_CLASS

USB_BM_REQUEST_TYPE_TYPE_VENDOR

USB_BM_REQUEST_TYPE_TYPE_RESERVED

USB_BM_REQUEST_TYPE_TYPE_MASK

USB_BM_REQUEST_TYPE_RECIP_DEVICE

USB_BM_REQUEST_TYPE_RECIP_INTERFACE

USB_BM_REQUEST_TYPE_RECIP_ENDPOINT

USB_BM_REQUEST_TYPE_RECIP_OTHER

USB_BM_REQUEST_TYPE_RECIP_MASK

USB_B_REQUEST_GET_STATUS

Bit masks belonging to the bRequest field of a setup packet.

USB_B_REQUEST_CLEAR_FEATURE

USB_B_REQUEST_SET_FEATURE

USB_B_REQUEST_SET_ADDRESS

USB_B_REQUEST_GET_DESCRIPTOR

USB_B_REQUEST_SET_DESCRIPTOR

USB_B_REQUEST_GET_CONFIGURATION

USB_B_REQUEST_SET_CONFIGURATION

USB_B_REQUEST_GET_INTERFACE

USB_B_REQUEST_SET_INTERFACE

USB_B_REQUEST_SYNCH_FRAME

USB_W_VALUE_DT_DEVICE

Bit masks belonging to the wValue field of a setup packet.

USB_W_VALUE_DT_CONFIG

USB_W_VALUE_DT_STRING

USB_W_VALUE_DT_INTERFACE

USB_W_VALUE_DT_ENDPOINT

USB_W_VALUE_DT_DEVICE_QUALIFIER

USB_W_VALUE_DT_OTHER_SPEED_CONFIG

USB_W_VALUE_DT_INTERFACE_POWER

USB_SETUP_PACKET_INIT_SET_ADDR(setup_pkt_ptr, addr)

Initializer for a SET_ADDRESS request.

Sets the address of a connected device

USB_SETUP_PACKET_INIT_GET_DEVICE_DESC(setup_pkt_ptr)

Initializer for a request to get a device’s device descriptor.

USB_SETUP_PACKET_INIT_GET_CONFIG(setup_pkt_ptr)

Initializer for a request to get a device’s current configuration number.

USB_SETUP_PACKET_INIT_GET_CONFIG_DESC(setup_pkt_ptr, desc_index, desc_len)

Initializer for a request to get one of the device’s current configuration descriptor.

• desc_index indicates the configuration’s index number

• Number of bytes of the configuration descriptor to get

USB_SETUP_PACKET_INIT_SET_CONFIG(setup_pkt_ptr, config_num)

Initializer for a request to set a device’s current configuration number.

USB_SETUP_PACKET_INIT_SET_INTERFACE(setup_pkt_ptr, intf_num, alt_setting_num)

Initializer for a request to set an interface’s alternate setting.

USB_STANDARD_DESC_SIZE

Size of dummy USB standard descriptor.

USB_DEVICE_DESC_SIZE

Size of a USB device descriptor in bytes.

USB_CLASS_PER_INTERFACE

Possible base class values of the bDeviceClass field of a USB device descriptor.

USB_CLASS_AUDIO

USB_CLASS_COMM

USB_CLASS_HID

USB_CLASS_PHYSICAL

USB_CLASS_STILL_IMAGE

USB_CLASS_PRINTER

USB_CLASS_MASS_STORAGE

USB_CLASS_HUB

USB_CLASS_CDC_DATA

USB_CLASS_CSCID

USB_CLASS_CONTENT_SEC

USB_CLASS_VIDEO

USB_CLASS_WIRELESS_CONTROLLER

USB_CLASS_PERSONAL_HEALTHCARE

USB_CLASS_AUDIO_VIDEO

USB_CLASS_BILLBOARD

USB_CLASS_USB_TYPE_C_BRIDGE

USB_CLASS_MISC

USB_CLASS_APP_SPEC

USB_CLASS_VENDOR_SPEC

USB_SUBCLASS_VENDOR_SPEC

Vendor specific subclass code.

USB_CONFIG_DESC_SIZE

Size of a short USB configuration descriptor in bytes.

Note

The size of a full USB configuration includes all the interface and endpoint descriptors of that configuration.

USB_BM_ATTRIBUTES_ONE

Bit masks belonging to the bmAttributes field of a configuration descriptor.

USB_BM_ATTRIBUTES_SELFPOWER

USB_BM_ATTRIBUTES_WAKEUP

USB_BM_ATTRIBUTES_BATTERY

USB_IAD_DESC_SIZE

Size of a USB interface association descriptor in bytes.

USB_INTF_DESC_SIZE

Size of a USB interface descriptor in bytes.

USB_EP_DESC_SIZE

Size of a USB endpoint descriptor in bytes.

USB_B_ENDPOINT_ADDRESS_EP_NUM_MASK

Bit masks belonging to the bEndpointAddress field of an endpoint descriptor.

USB_B_ENDPOINT_ADDRESS_EP_DIR_MASK

USB_BM_ATTRIBUTES_XFERTYPE_MASK

Bit masks belonging to the bmAttributes field of an endpoint descriptor.

USB_BM_ATTRIBUTES_XFER_CONTROL

USB_BM_ATTRIBUTES_XFER_ISOC

USB_BM_ATTRIBUTES_XFER_BULK

USB_BM_ATTRIBUTES_XFER_INT

USB_BM_ATTRIBUTES_SYNCTYPE_MASK

USB_BM_ATTRIBUTES_SYNC_NONE

USB_BM_ATTRIBUTES_SYNC_ASYNC

USB_BM_ATTRIBUTES_SYNC_ADAPTIVE

USB_BM_ATTRIBUTES_SYNC_SYNC

USB_BM_ATTRIBUTES_USAGETYPE_MASK

USB_BM_ATTRIBUTES_USAGE_DATA

USB_BM_ATTRIBUTES_USAGE_FEEDBACK

USB_BM_ATTRIBUTES_USAGE_IMPLICIT_FB

USB_EP_DESC_GET_XFERTYPE(desc_ptr)

Macro helpers to get information about an endpoint from its descriptor.

USB_EP_DESC_GET_EP_NUM(desc_ptr)

USB_EP_DESC_GET_EP_DIR(desc_ptr)

USB_EP_DESC_GET_MPS(desc_ptr)

USB_STR_DESC_SIZE

Size of a short USB string descriptor in bytes.

Enumerations

enum usb_device_state_t

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.

Values:

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.

提供有关此文档的反馈