USB Common API

USB Common Functions

void usb_os_sleep_ms(u32 ms)

Delays execution for a specified number of milliseconds.

参数:

ms -- [in] The duration to sleep in milliseconds.

void usb_os_delay_us(u32 us)

Delays execution for a specified number of microseconds.

参数:

us -- [in] The duration to delay in microseconds.

u32 usb_os_get_timestamp_ms(void)

Gets the current time stamp in milliseconds.

返回:

The current time stamp in milliseconds.

u64 usb_os_get_timestamp_us(void)

Gets the current time stamp in microseconds.

返回:

The current time stamp in microseconds.

u32 usb_os_get_time_tick(u8 speed)

Gets the current time tick.

返回值:

The -- current time tick.

void usb_os_memset(void *buf, u8 val, u32 size)

Fills a block of memory with a specified value.

参数:

• buf -- [out] Pointer to the memory block to fill.

• val -- [in] The value to be set.

• size -- [in] The number of bytes to be set to the value.

void usb_os_memcpy(void *dst, const void *src, u32 size)

Copies a block of memory from a source to a destination.

参数:

• dst -- [out] Pointer to the destination array where the content is to be copied.

• src -- [in] Pointer to the source of data to be copied.

• size -- [in] The number of bytes to copy.

void *usb_os_malloc(u32 size)

Allocates a block of memory from the heap.

参数:

size -- [in] The size of the memory block to allocate, in bytes.

返回:

A pointer to the allocated memory, or NULL if the request fails.

void usb_os_mfree(void *handle)

Frees a previously allocated block of memory.

参数:

handle -- [in] A pointer to the memory block to be freed.

int usb_os_lock_create(usb_os_lock_t *lock)

Creates a new mutex.

参数:

lock -- [out] Pointer to the mutex handle to be created.

返回:

0 on success, non-zero on failure

int usb_os_lock_delete(usb_os_lock_t lock)

Deletes a mutex.

参数:

lock -- [in] The mutex handle to be deleted.

返回:

0 on success, non-zero on failure

int usb_os_lock(usb_os_lock_t lock)

Acquires a mutex (locks it).

参数:

lock -- [in] The mutex handle to be acquired.

返回:

0 on success, non-zero on failure

int usb_os_unlock(usb_os_lock_t lock)

Releases a mutex (unlocks it).

参数:

lock -- [in] The mutex handle to be released.

返回:

0 on success, non-zero on failure

int usb_os_enter_critical(u8 in_critical)

Enters a critical section (disables interrupts).

参数:

in_critical -- [in] Flag indicating if this should be a critical section.

返回:

0 on success, non-zero on failure

int usb_os_exit_critical(u8 in_critical)

Exits a critical section (enables interrupts).

参数:

in_critical -- [in] Flag indicating if this should be a critical section.

返回:

0 on success, non-zero on failure

int usb_os_sema_create(usb_os_sema_t *sema)

Creates a new binary or counting semaphore.

参数:

sema -- [out] Pointer to the semaphore handle to be created.

返回:

0 on success, non-zero on failure

int usb_os_sema_delete(usb_os_sema_t sema)

Deletes a semaphore.

参数:

sema -- [in] The semaphore handle to be deleted.

返回:

0 on success, non-zero on failure

int usb_os_sema_take(usb_os_sema_t sema, u32 timeout_ms)

Acquires a semaphore.

参数:

• sema -- [in] The semaphore handle to acquire.

• timeout_ms -- [in] The maximum time in milliseconds to wait for the semaphore.

返回:

0 on success, a negative error code on failure or timeout.

int usb_os_sema_give(usb_os_sema_t sema)

Releases a semaphore.

参数:

sema -- [in] The semaphore handle to release.

返回:

0 on success, non-zero on failure

int usb_os_queue_create(usb_os_queue_t *queue, u32 msg_num, u32 msg_size)

Creates a new message queue.

参数:

• queue -- [out] Pointer to the queue handle to be created.

• msg_num -- [in] The maximum number of messages the queue can hold.

• msg_size -- [in] The size of each message in bytes.

返回:

0 on success, non-zero on failure

int usb_os_queue_delete(usb_os_queue_t queue)

Deletes a message queue.

参数:

queue -- [in] The queue handle to be deleted.

返回:

0 on success, non-zero on failure

int usb_os_queue_send(usb_os_queue_t queue, void *msg, u32 wait_ms)

Sends a message to a queue.

参数:

• queue -- [in] The handle of the target queue.

• msg -- [in] A pointer to the message to be sent.

• wait_ms -- [in] The maximum time in milliseconds to wait if the queue is full.

返回:

0 on success, non-zero on failure

int usb_os_queue_receive(usb_os_queue_t queue, void *msg, u32 wait_ms)

Receives a message from a queue.

参数:

• queue -- [in] The handle of the target queue.

• msg -- [out] A pointer to a buffer to store the received message.

• wait_ms -- [in] The maximum time in milliseconds to wait if the queue is empty.

返回:

0 on success, a negative error code on failure or timeout.

u32 usb_os_get_free_heap_size(void)

Gets the size of the free heap memory.

返回:

The number of free bytes in the heap.

USB Common Constants

USB_LEN_DEV_QUALIFIER_DESC

Defines for the standard lengths of various USB descriptors.

Length of Device Qualifier descriptor.

USB_LEN_DEV_DESC

Length of Device descriptor.

USB_LEN_BOS_DESC

Length of BOS descriptor.

USB_LEN_CFG_DESC

Length of Configuration descriptor.

USB_LEN_IAD_DESC

Length of IAD descriptor.

USB_LEN_IF_DESC

Length of Interface descriptor.

USB_LEN_EP_DESC

Length of Endpoint descriptor.

USB_LEN_OTG_DESC

Length of OTG descriptor.

USB_LEN_LANGID_STR_DESC

Length of Language ID String descriptor.

USB_LEN_OTHER_SPEED_DESC_SIZ

Length of Other Speed Configuration descriptor.

USB_DESC_DEVICE

High-byte values for the wValue field in a GET_DESCRIPTOR request.

USB_DESC_CONFIGURATION

USB_DESC_STRING

USB_DESC_INTERFACE

USB_DESC_ENDPOINT

USB_DESC_DEVICE_QUALIFIER

USB_DESC_OTHER_SPEED_CONFIGURATION

USB_DESC_INTERFACE_POWER

USB_DESC_BOS

USB_DESC_HUB_DESC

USB_REQ_DIR_MASK

Defines for the bits within the bmRequestType field of a setup request.

Mask for data transfer direction bit.

USB_REQ_NUM_MASK

Mask for endpoint number.

USB_H2D

Host-to-Device direction.

USB_D2H

Device-to-Host direction.

USB_EP_IS_IN(ep_addr)

Check if the endpoint direction is IN.

USB_EP_IS_OUT(ep_addr)

Check if the endpoint direction is OUT.

USB_EP_NUM(ep_addr)

Get endpoint number from address.

USB_REQ_TYPE_STANDARD

Standard request type.

USB_REQ_TYPE_CLASS

Class-specific request type.

USB_REQ_TYPE_VENDOR

Vendor-specific request type.

USB_REQ_TYPE_MASK

Mask for request type bits.

USB_REQ_RECIPIENT_DEVICE

Request recipient is the device.

USB_REQ_RECIPIENT_INTERFACE

Request recipient is an interface.

USB_REQ_RECIPIENT_ENDPOINT

Request recipient is an endpoint.

USB_REQ_RECIPIENT_MASK

Mask for request recipient bits.

USB_REQ_GET_STATUS

Defines for standard USB request codes (USB Spec Table 9-4).

Get Status request.

USB_REQ_CLEAR_FEATURE

Clear Feature request.

USB_REQ_SET_FEATURE

Set Feature request.

USB_REQ_SET_ADDRESS

Set Address request.

USB_REQ_GET_DESCRIPTOR

Get Descriptor request.

USB_REQ_SET_DESCRIPTOR

Set Descriptor request.

USB_REQ_GET_CONFIGURATION

Get Configuration request.

USB_REQ_SET_CONFIGURATION

Set Configuration request.

USB_REQ_GET_INTERFACE

Get Interface request.

USB_REQ_SET_INTERFACE

Set Interface request.

USB_REQ_SYNCH_FRAME

Synch Frame request.

USB_DESC_TYPE_DEVICE

Defines for standard USB descriptor types (USB Spec Table 9-5).

Device descriptor type.

USB_DESC_TYPE_CONFIGURATION

Configuration descriptor type.

USB_DESC_TYPE_STRING

String descriptor type.

USB_DESC_TYPE_INTERFACE

Interface descriptor type.

USB_DESC_TYPE_ENDPOINT

Endpoint descriptor type.

USB_DESC_TYPE_DEVICE_QUALIFIER

Device Qualifier descriptor type.

USB_DESC_TYPE_OTHER_SPEED_CONFIGURATION

Other Speed Configuration descriptor type.

USB_DESC_TYPE_INTERFACE_POWER

Interface Power descriptor type.

USB_DESC_TYPE_IAD

Interface Association Descriptor (IAD) type.

USB_DESC_TYPE_BOS

Binary Device Object Store (BOS) descriptor type.

USB_DESC_TYPE_HUB

Hub descriptor type.

USB_CONFIG_REMOTE_WAKEUP

Defines for standard feature selectors used in Set/Clear Feature requests.

Configuration-level remote wakeup feature.

USB_CONFIG_SELF_POWERED

Configuration-level self-powered feature.

USB_FEATURE_EP_HALT

Endpoint halt feature selector.

USB_FEATURE_REMOTE_WAKEUP

Device remote wakeup feature selector.

USB_FEATURE_TEST_MODE

Test mode feature selector.

USB_EP_XFER_TYPE_MASK

Macros related to endpoint descriptors and addresses.

Mask to extract transfer type from bmAttributes.

USB_EP_MPS_SIZE_MASK

Mask for packet size in wMaxPacketSize.

USB_EP_MPS_TRANS_MASK

Mask for additional transactions in wMaxPacketSize.

USB_EP_MPS_TRANS_POS

Position of additional transactions field.

USB_EP0_OUT

Endpoint 0 OUT address.

USB_EP0_IN

Endpoint 0 IN address.

USB_HS_MAX_PACKET_SIZE

Defines for maximum packet sizes for various speeds and endpoint types.

High-Speed maximum packet size.

USB_FS_MAX_PACKET_SIZE

Full-Speed maximum packet size.

USB_MAX_EP0_SIZE

Maximum packet size for Endpoint 0.

USB_CTRL_MAX_MPS

Maximum MPS for any Control endpoint.

USB_XFER_MAX_MPS

Maximum MPS for any transfer.

USB_BULK_FS_MAX_MPS

Full-Speed Bulk maximum MPS.

USB_BULK_HS_MAX_MPS

High-Speed Bulk maximum MPS.

USB_INTR_FS_MAX_MPS

Full-Speed Interrupt maximum MPS.

USB_INTR_HS_MAX_MPS

High-Speed Interrupt maximum MPS.

USB_ISOC_FS_MAX_MPS

Full-Speed Isochronous maximum MPS.

USB_ISOC_HS_MAX_MPS

High-Speed Isochronous maximum MPS.

USB_CLASS_HUB

Defines related to the USB Hub Class specification.

USB device class type

USB_PORT_FEAT_CONNECTION

Feature selectors for Hub Port Get/Set/Clear Feature requests.

Port Connection feature.

USB_PORT_FEAT_ENABLE

Port Enable feature.

USB_PORT_FEAT_SUSPEND

Port Suspend feature.

USB_PORT_FEAT_OVER_CURRENT

Port Over-current feature.

USB_PORT_FEAT_RESET

Port Reset feature.

USB_PORT_FEAT_POWER

Port Power feature.

USB_PORT_FEAT_LOWSPEED

Port Low-speed device attached feature.

USB_PORT_FEAT_HIGHSPEED

Port High-speed device attached feature.

USB_PORT_FEAT_C_CONNECTION

Port Connection change feature.

USB_PORT_FEAT_C_ENABLE

Port Enable change feature.

USB_PORT_FEAT_C_SUSPEND

Port Suspend change feature.

USB_PORT_FEAT_C_OVER_CURRENT

Port Over-current change feature.

USB_PORT_FEAT_C_RESET

Port Reset change feature.

USB_PORT_STAT_CONNECTION

Bit definitions for the wPortStatus field returned by GetPortStatus.

Device is connected to the port.

USB_PORT_STAT_ENABLE

Port is enabled.

USB_PORT_STAT_SUSPEND

Port is suspended.

USB_PORT_STAT_OVERCURRENT

Port is in an over-current condition.

USB_PORT_STAT_RESET

Port is in reset.

USB_PORT_STAT_POWER

Port power is on.

USB_PORT_STAT_LOW_SPEED

A low-speed device is attached.

USB_PORT_STAT_HIGH_SPEED

A high-speed device is attached (EHCI).

USB_PORT_STAT_SUPER_SPEED

A super-speed device is attached (XHCI).

USB_PORT_STAT_SPEED_MASK

Mask to get port speed.

USB_PORT_STAT_C_CONNECTION

Bit definitions for the wPortChange field returned by GetPortStatus.

Connection status has changed.

USB_PORT_STAT_C_ENABLE

Enable status has changed.

USB_PORT_STAT_C_SUSPEND

Suspend status has changed.

USB_PORT_STAT_C_OVERCURRENT

Over-current status has changed.

USB_PORT_STAT_C_RESET

Reset completion has occurred.

USB_CDC_CLASS_CODE

USB Communication Device Class (CDC) Code

USB_CDC_COMM_INTERFACE_CLASS_CODE

CDC Communication Interface Class Code

USB_CDC_DATA_INTERFACE_CLASS_CODE

CDC Data Interface Class Code

USB_CDC_SUBCLASS_RESERVED

CDC Subclass Code: Reserved

USB_CDC_SUBCLASS_ACM

CDC Subclass Code: Abstract Control Model (ACM)

USB_CDC_CTRL_PROTOCOL_NO_CLASS_SPECIFIC

CDC Protocol Code: No class

USB_CDC_CTRL_PROTOCOL_COMMON_AT_COMMAND

CDC Protocol Code: AT cpmmand

USB_CDC_CTRL_PROTOCOL_VENDOR_SPECIFIC

CDC Protocol Code: Vendor

USB_CDC_ACM_SEND_ENCAPSULATED_COMMAND

CDC request to send an encapsulated command.

USB_CDC_ACM_GET_ENCAPSULATED_RESPONSE

CDC request to get an encapsulated response.

USB_CDC_ACM_SET_COMM_FEATURE

CDC request to set a communication feature.

USB_CDC_ACM_GET_COMM_FEATURE

CDC request to get a communication feature.

USB_CDC_ACM_CLEAR_COMM_FEATURE

CDC request to clear a communication feature.

USB_CDC_ACM_SET_LINE_CODING

CDC request to set the line coding properties.

USB_CDC_ACM_GET_LINE_CODING

CDC request to get the line coding properties.

USB_CDC_ACM_SET_CONTROL_LINE_STATE

CDC request to set the control line state.

USB_CDC_ACM_SEND_BREAK

CDC request to send a break condition.

USB_CDC_ACM_NOTIFY_NETWORK_CONNECTION

Notification: Network Connection

USB_CDC_ACM_NOTIFY_RESPONSE_AVAILABLE

Notification: Response Available

USB_CDC_ACM_NOTIFY_SERIAL_STATE

Notification: Serial State

USB_CDC_ACM_CTRL_DCD

bRxCarrier: State of DCD signal.

USB_CDC_ACM_CTRL_DSR

bTxCarrier: State of DSR signal.

USB_CDC_ACM_CTRL_BRK

bBreak: Break condition detected.

USB_CDC_ACM_CTRL_RI

bRingSignal: State of ring signal detection.

USB_CDC_ACM_CTRL_FRAMING

bFraming: A framing error has occurred.

USB_CDC_ACM_CTRL_PARITY

bParity: A parity error has occurred.

USB_CDC_ACM_CTRL_OVERRUN

bOverRun: Received data has been discarded.

USB_CDC_ACM_INTR_IN_PACKET_SIZE

Maximum packet size for Interrupt IN endpoint

USB_CDC_ACM_INTR_IN_REQUEST_SIZE

Notification request header size (bytes)

USB_CDC_ACM_INTR_IN_DATA_SIZE

Notification data payload size (bytes)

USB_CDC_ACM_LINE_CODING_SIZE

Line Coding structure size (Set/Get Line Coding data length)

USB_VERSION_ID_0201

USB Specification version 2.01.

USB_DEV_DESC_OFFSET_VID

Offset to idVendor in device descriptor.

USB_DEV_DESC_OFFSET_PID

Offset to idProduct in device descriptor.

USB_CFG_DESC_OFFSET_TYPE

Offset to bDescriptorType in configuration descriptor.

USB_CFG_DESC_OFFSET_TOTAL_LEN

Offset to wTotalLength in configuration descriptor.

USB_CFG_DESC_OFFSET_ATTR

Offset to bmAttributes in configuration descriptor.

USB_CFG_DESC_OFFSET_ATTR_BIT_SELF_POWERED

Self-powered bit in bmAttributes.

USB_CFG_DESC_OFFSET_ATTR_BIT_REMOTE_WAKEUP

Remote wakeup bit in bmAttributes.

USB_DEVICE_CAPABITY_TYPE

Device Capability descriptor type.

USB_OS_SEMA_TIMEOUT

Defines the maximum timeout value for semaphore operations.

USB_DMA_ALIGNED

Ensures a variable is aligned to the cache line size for DMA operations.

This is critical for DMA buffers to prevent data corruption due to cache coherency issues.

USB_IS_MEM_DMA_ALIGNED(x)

Checks if a memory address is aligned to the cache line size.

参数:

• x -- The memory address to check.

返回:

Non-zero if aligned, 0 otherwise.

USB_LOW_BYTE(x)

Extracts the low byte from a 16-bit value.

参数:

• x -- The 16-bit value.

返回:

The low byte (u8).

USB_HIGH_BYTE(x)

Extracts the high byte from a 16-bit value.

参数:

• x -- The 16-bit value.

返回:

The high byte (u8).

USB Common Types

typedef rtos_mutex_t usb_os_lock_t

Type definitions for abstracting OS objects.

Abstracted type for a mutex or lock.

typedef rtos_sema_t usb_os_sema_t

Abstracted type for a semaphore.

typedef rtos_queue_t usb_os_queue_t

Abstracted type for a message queue.

typedef rtos_task_t usb_os_task_t

Abstracted type for a task handle.

enum usb_cdc_acm_line_coding_parity_t

USB CDC Parity Type Definition.

备注

Corresponds to the bParityType field in the Line Coding structure

Values:

enumerator LINE_CODING_PARITY_NO

No Parity

enumerator LINE_CODING_PARITY_ODD

Odd Parity

enumerator LINE_CODING_PARITY_EVEN

Even Parity

enumerator LINE_CODING_PARITY_MARK

Mark Parity

enumerator LINE_CODING_PARITY_SPACE

Space Parity

enum usb_cdc_acm_line_coding_char_format_t

USB CDC Stop Bits Type Definition.

备注

Corresponds to the bCharFormat field in the Line Coding structure

Values:

enumerator LINE_CODING_CHAR_FORMAT_1_STOP_BITS

1 Stop Bit

enumerator LINE_CODING_CHAR_FORMAT_1_5_STOP_BITS

1.5 Stop Bits

enumerator LINE_CODING_CHAR_FORMAT_2_STOP_BITS

2 Stop Bits

enum usb_ch_ep_type_t

Defines the transfer type of a USB endpoint.

Corresponds to the bmAttributes field in the endpoint descriptor.

Values:

enumerator USB_CH_EP_TYPE_CTRL

Control Endpoint/pipe.

enumerator USB_CH_EP_TYPE_ISOC

Isochronous Endpoint/pipe.

enumerator USB_CH_EP_TYPE_BULK

Bulk Endpoint/pipe.

enumerator USB_CH_EP_TYPE_INTR

Interrupt Endpoint/pipe.

enum usb_speed_type_t

Defines the operational speeds for the USB controller.

Values:

enumerator USB_SPEED_HIGH

High Speed (480 Mbps).

enumerator USB_SPEED_HIGH_IN_FULL

High Speed core running in Full Speed mode.

enumerator USB_SPEED_LOW

Low Speed (1.5 Mbps).

enumerator USB_SPEED_FULL

Full Speed (12 Mbps).

union usb_cdc_line_coding_t

#include <usb_cdc_acm.h>

USB CDC Line Coding Structure (Standard Union)

Corresponds to the 7-byte data sent over USB Class Requests.

Public Members

u8 d8[USB_CDC_ACM_LINE_CODING_SIZE]

Raw byte array access

u32 dwDteRate

Data Terminal Rate (Baud Rate), unit: bps

u8 bCharFormat

Stop Bits, see usb_cdc_acm_line_coding_char_format_t

u8 bParityType

Parity Type, see usb_cdc_acm_line_coding_parity_t

u8 bDataBits

Data Bits (usually 5, 6, 7, 8, or 16)

struct usb_cdc_line_coding_t::[anonymous] b

Structured member access

struct usb_setup_req_t

#include <usb_ch9.h>

Standard USB setup request packet structure.

This structure represents the 8-byte setup packet sent during the setup phase of a control transfer. (USB Spec 2.0, Table 9-2)

Public Members

u8 bmRequestType

Characteristics of the request.

u8 bRequest

Specific request code.

u16 wValue

Request-specific value, often used for descriptor type and index.

u16 wIndex

Request-specific index, often an interface or endpoint number.

u16 wLength

Number of bytes to transfer in the data phase.

USB Device API

USB Device Functions

Composite CDC ACM Functions

int usbd_composite_cdc_acm_init(usbd_composite_dev_t *cdev, u16 bulk_out_xfer_size, u16 bulk_in_xfer_size, usbd_composite_cdc_acm_usr_cb_t *cb)

Initializes the CDC ACM composite function.

参数:

• cdev -- [in] Pointer to the composite device context.

• bulk_out_xfer_size -- [in] The desired transfer size for the Bulk OUT buffer.

• bulk_in_xfer_size -- [in] The desired transfer size for the Bulk IN buffer.

• cb -- [in] Pointer to the user callback structure.

返回:

0 on success, a negative error code on failure.

int usbd_composite_cdc_acm_deinit(void)

De-initializes the CDC ACM composite function.

返回:

0 on success, a negative error code on failure.

int usbd_composite_cdc_acm_transmit(u8 *buf, u32 len)

Transmits data over the CDC ACM Bulk IN endpoint.

参数:

• buf -- [in] Pointer to the data buffer to be transmitted.

• len -- [in] Length of the data in bytes.

返回:

0 on success, a negative error code on failure.

int usbd_composite_cdc_acm_notify_serial_state(u16 serial_state)

Sends a SERIAL_STATE notification to the host over the CDC ACM Interrupt IN endpoint..

参数:

serial_state -- [in] A bitmap of the serial line states (see USB_CDC_ACM_CTRL_DCD, etc.).

返回:

0 on success, a negative error code on failure.

Device CDC ACM Functions

int usbd_cdc_acm_init(u32 bulk_out_xfer_size, u32 bulk_in_xfer_size, usbd_cdc_acm_cb_t *cb)

Initializes class driver with application callback handler.

参数:

• bulk_out_xfer_size -- [in] BULK OUT xfer buffer malloc length.

• bulk_in_xfer_size -- [in] BULK IN xfer buffer malloc length.

• cb -- [in] Pointer to the user-defined callback structure.

返回:

0 on success, non-zero on failure.

int usbd_cdc_acm_deinit(void)

De-initializes the CDC ACM class driver.

返回:

0 on success, non-zero on failure.

int usbd_cdc_acm_transmit(u8 *buf, u32 len)

Transmits data to the host over the BULK IN endpoint.

参数:

• buf -- [in] Pointer to the data buffer to be transmitted.

• len -- [in] Length of the data in bytes.

返回:

0 on success, non-zero on failure.

int usbd_cdc_acm_notify_serial_state(u16 serial_state)

Sets new line coding properties over the INTR IN endpoint.

参数:

serial_state -- [in] New line coding properties.

返回:

0 on success, non-zero on failure.

Device Composite CDC ACM MSC Functions

int usbd_composite_init(u32 cdc_bulk_out_xfer_size, u32 cdc_bulk_in_xfer_size, usbd_composite_cdc_acm_usr_cb_t *cdc_cb, usbd_composite_cb_t *cb)

Init composite class.

参数:

• cdc_bulk_out_xfer_size -- [in] CDC ACM bulk out xfer buffer size

• cdc_bulk_in_xfer_size -- [in] CDC ACM bulk in xfer buffer size

• cdc_cb -- [in] CDC ACM user callback

• cb -- [in] Composite user callback

返回:

0 on success, non-zero on failure

void usbd_composite_deinit(void)

DeInit composite class.

返回:

None

Device Composite MSC Functions

int usbd_composite_msc_disk_init(void)

Initializes the underlying storage disk.

返回:

0 on success, non-zero on failure.

int usbd_composite_msc_disk_deinit(void)

De-initializes the underlying storage disk.

返回:

0 on success, non-zero on failure.

Device Core Functions For Applications

int usbd_init(usbd_config_t *cfg)

Initialize USB device core driver with configuration.

参数:

cfg -- [in] USB device configuration.

返回:

0 on success, non-zero on failure.

int usbd_deinit(void)

Deinitialize USB device core driver.

返回:

0 on success, non-zero on failure.

int usbd_get_status(void)

Get USB device attach status.

返回:

See usbd_attach_status_t.

int usbd_get_bus_status(u32 *status)

Get USB device bus status.

参数:

status -- [out] Return 0 on success, with the status parameter containing USB bus status represented as a bitwise combination of enumeration values:

• USB_DEV_BUS_STATUS_DN = BIT0, // D- line status bit.

• USB_DEV_BUS_STATUS_DP = BIT1, // D+ line status bit.

• USB_DEV_BUS_STATUS_SUSPEND = BIT2, //Suspend indication bit.

返回:

0 on success, non-zero on failure.

int usbd_wake_host(void)

Sends a remote wakeup signal to the USB host to resume communication.

返回:

0 on success, non-zero on failure.

Device Core Functions For Classes

int usbd_register_class(const usbd_class_driver_t *driver)

Register a device class driver, called in class initialization function.

参数:

driver -- [in] USB class driver.

返回:

0 on success, non-zero on failure.

int usbd_unregister_class(void)

Un-register a class, called in class de-initialization function.

返回:

0 on success, non-zero on failure.

int usbd_ep_init(usb_dev_t *dev, usbd_ep_t *ep)

Initialize an endpoint.

备注

Typically called in following scenarios:

• In the set_config callback function of the usbd_class_driver_t.

• In the setup callback function of the usbd_class_driver_t, when receiving specific requests (such as SET_INTERFACE) that require endpoint (re-)initialization.

参数:

• dev -- [in] USB device.

• ep -- [in] USB endpoint.

返回:

0 on success, non-zero on failure.

int usbd_ep_deinit(usb_dev_t *dev, usbd_ep_t *ep)

Deinitialize an endpoint.

备注

Typically called in following scenarios:

• In the clear_config callback function of the usbd_class_driver_t.

• In the setup callback function of the usbd_class_driver_t, when receiving specific requests (such as SET_INTERFACE) that require endpoint deinitialization.

参数:

• dev -- [in] USB device.

• ep -- [in] USB endpoint.

返回:

0 on success, non-zero on failure.

int usbd_ep_transmit(usb_dev_t *dev, usbd_ep_t *ep)

Initiates an IN transfer to the USB host through a specified endpoint.

备注

• The transfer executes asynchronously: function return doesn't indicate completion.

• Check transfer status via ep_data_in/ep0_data_in callback of the usbd_class_driver_t.

• Zero-Length Packet will be automatically transmitted as needed by device core driver.

参数:

• dev -- [in] USB device.

• ep -- [in] USB endpoint.

返回:

0 on success, non-zero on failure.

int usbd_ep_receive(usb_dev_t *dev, usbd_ep_t *ep)

Prepares to receive OUT transfer data from the USB host through a specified endpoint.

备注

• The transfer executes asynchronously: function return doesn't indicate completion.

• Retrieved data is available via the ep_data_out/ep0_data_out callback of the usbd_class_driver_t.

参数:

• dev -- [in] USB device.

• ep -- [in] USB endpoint.

返回:

0 on success, non-zero on failure.

int usbd_ep_set_stall(usb_dev_t *dev, usbd_ep_t *ep)

Sets the specified endpoint to STALL state.

参数:

• dev -- [in] USB device.

• ep -- [in] USB endpoint.

返回:

0 on success, non-zero on failure.

int usbd_ep_clear_stall(usb_dev_t *dev, usbd_ep_t *ep)

Clears the STALL state of the specified endpoint.

参数:

• dev -- [in] USB device.

• ep -- [in] USB endpoint.

返回:

0 on success, non-zero on failure.

int usbd_ep_is_stall(usb_dev_t *dev, usbd_ep_t *ep)

Checks whether the specified endpoint is in STALL state.

参数:

• dev -- [in] USB device.

• ep -- [in] USB endpoint.

返回:

• 1: The endpoint is stalled.

• 0: The endpoint is not stalled.

u16 usbd_get_str_desc(const char *str, u8 *desc)

Converts ASCII strings to UNICODE16-encoded USB string descriptors.

备注

The destination buffer must accommodate twice the source length plus 2 bytes (for the length, and type fields of string descriptor)

参数:

• str -- [in] Pointer to the null-terminated source ASCII string.

• desc -- [out] Formatted unicode string descriptor buffer where the USB descriptor will be written.

返回:

The total length of the generated descriptor in bytes.

Device HID Functions

int usbd_hid_init(u32 tx_buf_len, usbd_hid_usr_cb_t *cb)

Initializes class driver with application callback handler.

参数:

• tx_buf_len -- [in] transfer buffer length

• cb -- [in] Pointer to the user-defined callback structure.

返回:

0 on success, non-zero on failure.

int usbd_hid_deinit(void)

DeInitialize HID device.

返回:

0 on success, non-zero on failure.

int usbd_hid_send_data(u8 *buf, u32 len)

Transmits data to the host over the INTR IN endpoint.

参数:

• buf -- [in] Pointer to the data buffer to be transmitted.

• len -- [in] Length of the data in bytes.

返回:

0 on success, non-zero on failure.

Device MSC Functions

int usbd_msc_init(usbd_msc_cb_t *cb)

Initializes the MSC device class driver with application callback handler.

参数:

cb -- [in] Pointer to the user callback structure.

返回:

0 on success, non-zero on failure.

void usbd_msc_deinit(void)

De-initializes the MSC device class driver.

int usbd_msc_disk_init(void)

Initializes the underlying storage disk.

返回:

0 on success, non-zero on failure.

int usbd_msc_disk_deinit(void)

De-initializes the underlying storage disk.

返回:

0 on success, non-zero on failure.

Device UAC Functions

int usbd_uac_init(usbd_uac_cb_t *cb)

Initializes class driver with application callback handler.

参数:

cb -- [in] Pointer to the user-defined callback structure.

返回:

0 on success, non-zero on failure.

int usbd_uac_deinit(void)

DeInitialize UAC device.

返回:

0 on success, non-zero on failure.

u8 usbd_uac_config(const usbd_audio_cfg_t *uac_cfg, u8 is_record, u32 flag)

Set audio configuration to the UAC class.

参数:

• uac_cfg -- [in] Audio configure params

• is_record -- [in] 1 for recording, 0 for playback

• flag -- [in] Unused parameter

返回值:

0 -- on success, non-zero on failure.

u32 usbd_uac_start_play(void)

USB audio start play.

返回值:

0 -- on success, non-zero on failure.

void usbd_uac_stop_play(void)

USB audio stop play.

u32 usbd_uac_read(u8 *buffer, u32 size, u32 time_out_ms)

Read the data from the ring_buffer.

参数:

• buffer -- [in] write buffer handle used to save the data

• size -- [in] allow to write buffer size

• time_out_ms -- [in] if 0 means no wait, other value will set time_out_ms to read buffer,if read data for more than time_out_ms, it will return.

返回值:

return -- the read data length in bytes

u32 usbd_uac_get_read_frame_cnt(void)

Get the read frame packet count.

返回值:

return -- avail packet count

Device Vendor Functions

int usbd_vendor_init(usbd_vendor_cb_t *cb)

Initializes class driver with application callback handler.

参数:

cb -- [in] Pointer to the user-defined callback structure.

返回:

0 on success, non-zero on failure.

int usbd_vendor_deinit(void)

De-initializes the Vendor class driver.

返回:

0 on success, non-zero on failure.

int usbd_vendor_transmit_ctrl_data(u8 *buf, u32 len)

Transmits data to the host over the CTRL endpoint.

参数:

• buf -- [in] Pointer to the data buffer to be transmitted.

• len -- [in] Length of the data in bytes.

返回:

0 on success, non-zero on failure.

int usbd_vendor_transmit_bulk_data(u8 *buf, u32 len)

Transmits data to the host over the BULK IN endpoint.

参数:

• buf -- [in] Pointer to the data buffer to be transmitted.

• len -- [in] Length of the data in bytes.

返回:

0 on success, non-zero on failure.

int usbd_vendor_receive_bulk_data(void)

Receives data to the host over the BULK OUT endpoint.

返回:

0 on success, non-zero on failure.

int usbd_vendor_transmit_intr_data(u8 *buf, u32 len)

Transmits data to the host over the INTR IN endpoint.

参数:

• buf -- [in] Pointer to the data buffer to be transmitted.

• len -- [in] Length of the data in bytes.

返回:

0 on success, non-zero on failure.

int usbd_vendor_receive_intr_data(void)

Receives data to the host over the INTR OUT endpoint.

返回:

0 on success, non-zero on failure.

int usbd_vendor_transmit_isoc_data(u8 *buf, u32 len)

Transmits data to the host over the ISOC IN endpoint.

参数:

• buf -- [in] Pointer to the data buffer to be transmitted.

• len -- [in] Length of the data in bytes.

返回:

0 on success, non-zero on failure.

int usbd_vendor_receive_isoc_data(void)

Receives data to the host over the ISOC OUT endpoint.

返回:

0 on success, non-zero on failure.

USB Device Constants

Composite CDC ACM Constants

CONFIG_COMP_CDC_ACM_NOTIFY

Configuration macro to enable or disable the CDC ACM notification endpoint.

Set to 1 to enable the Interrupt IN endpoint for sending notifications like SERIAL_STATE. Set to 0 to disable. Enable/Disable notification feature.

COMP_CDC_ACM_HS_INTR_IN_INTERVAL

High-speed Interrupt IN endpoint polling interval.

COMP_CDC_ACM_FS_INTR_IN_INTERVAL

Full-speed Interrupt IN endpoint polling interval.

Device CDC ACM Constants

CONFIG_CDC_ACM_NOTIFY

Enable/Disable notification feature.

CONFIG_CDC_ACM_NOTIFY_LOOP_TEST

Enable notification loopback test mode.

CONFIG_CDC_ACM_BULK_TX_SKIP_MEMCPY

Skip memcpy BULK IN DATA from application in class

USBD_CDC_ACM_VID

Vendor ID.

USBD_CDC_ACM_PID

Product ID.

USBD_CDC_ACM_SELF_POWERED

Device is self-powered.

USBD_CDC_ACM_REMOTE_WAKEUP_EN

Remote wakeup is enabled.

USBD_CDC_ACM_LANGID_STRING

Language ID for string descriptors (0x0409 = English

USBD_CDC_ACM_MFG_STRING

Manufacturer string.

USBD_CDC_ACM_PROD_HS_STRING

Product string for High-Speed mode.

USBD_CDC_ACM_PROD_FS_STRING

Product string for Full-Speed mode.

USBD_CDC_ACM_SN_STRING

Serial number string.

USBD_CDC_ACM_BULK_IN_EP

USBD_CDC_ACM_BULK_OUT_EP

USBD_CDC_ACM_INTR_IN_EP

USBD_CDC_ACM_HS_INTR_IN_INTERVAL

High speed INTR IN interval

USBD_CDC_ACM_FS_INTR_IN_INTERVAL

Full speed INTR IN interval

USBD_CDC_ACM_CTRL_BUF_SIZE

Control transfer buffer size.

Device Composite Constants

USBD_COMP_VID

Vendor ID.

USBD_COMP_PID

Product ID.

USBD_COMP_LANGID

Language ID string (0x0409 for U.S. English).

USBD_COMP_SELF_POWERED

Set to 1 if device is self-powered, 0 for bus-powered.

USBD_COMP_REMOTE_WAKEUP_EN

Set to 1 if remote wakeup is enabled, 0 for disable.

USBD_COMP_MFG_STRING

Manufacturer string.

USBD_COMP_PROD_STRING

Product string.

USBD_COMP_SN_STRING

Serial number string.

Device Composite MSC Constants

COMP_MSC_TX_THREAD_PRIORITY

TX thread priority

COMP_MSC_RX_THREAD_PRIORITY

RX thread priority

COMP_MSC_HS_MAX_PACKET_SIZE

High speed BULK IN & OUT packet size

COMP_MSC_FS_MAX_PACKET_SIZE

Full speed BULK IN & OUT packet size

COMP_MSC_FIX_CV_TEST_ISSUE

Enable for CV test

COMP_MSC_BLK_BITS

Number of bits per block (log2(512)).

COMP_MSC_BLK_SIZE

Block size in bytes (512).

COMP_MSC_BUFLEN

Default size of the internal data buffer.

COMP_MSC_REQUEST_RESET

Bulk-Only Mass Storage Reset request.

COMP_MSC_REQUEST_GET_MAX_LUN

Get Max LUN request.

COMP_MSC_CB_WRAP_LEN

Standard CBW length

COMP_MSC_CB_SIGN

Standard dCBWSignature, spells out USBC

COMP_MSC_MAX_DATA

COMP_MSC_CS_WRAP_LEN

Standard CSW length

COMP_MSC_CS_SIGN

Standard dCSWSignature, spells out 'USBS'

COMP_MSC_CSW_CMD_PASSED

The pass status of the command execution

COMP_MSC_CSW_CMD_FAILED

The fail status of the command execution

COMP_MSC_CSW_PHASE_ERROR

The phase error status of the command execution

COMP_MSC_IDLE

COMP_MSC_DATA_OUT

COMP_MSC_DATA_IN

COMP_MSC_LAST_DATA_IN

COMP_MSC_SEND_DATA

COMP_MSC_NO_DATA

COMP_MSC_STATUS_NORMAL

Normal working status

COMP_MSC_STATUS_RECOVERY

Get MSC Reset request for recovery

COMP_MSC_STATUS_ERROR

Error status

COMP_MSC_SENSE_LIST_DEPTH

Depth of the SCSI sense data list.

Device Core Constants

USBD_IDX_LANGID_STR

USB device string descriptor index.

USBD_IDX_MFC_STR

USBD_IDX_PRODUCT_STR

USBD_IDX_SERIAL_STR

USBD_IDX_MS_OS_STR

USBD_SOF_INTR

USB device interrupt enable flag.

Start of (micro)Frame Interrupt (GINTSTS.Sof).

USBD_EOPF_INTR

End of Periodic Frame Interrupt (GINTSTS.EOPF).

USBD_EPMIS_INTR

Endpoint Mismatch Interrupt (GINTSTS.EPMis).

USBD_TP_TRACE_DEBUG

This define is used to trace transfer performance

USBD_MAX_NUM_INTERFACES

USBD_MAX_NUM_CONFIGURATION

Device HID Constants

USBD_HID_MOUSE_DEVICE

HID device type, act as a mouse.

USBD_HID_KEYBOARD_DEVICE

HID device type, act as a keyboard.

USBD_HID_DEVICE_TYPE

HID device type.

USBD_HID_VID

Vendor ID.

USBD_HID_PID

Product ID.

USBD_HID_LANGID_STRING

Language ID for string descriptors (0x0409 = English

USBD_HID_MFG_STRING

Manufacturer string.

USBD_HID_PROD_HS_STRING

Product string for High-Speed mode.

USBD_HID_PROD_FS_STRING

Product string for High-Speed mode.

USBD_HID_SN_STRING

Serial number string.

USBD_HID_SELF_POWERED

Device is self-powered.

USBD_HID_CTRL_BUF_SIZE

CTRL maximum buffer size

USBD_HID_INTR_IN_BUF_SIZE

INTR IN maximum buffer size

USBD_HID_INTR_OUT_BUF_SIZE

INTR OUT maximum buffer size

USBD_HID_STRING_MANUFACTURER

Manufacture string index.

USBD_HID_STRING_PRODUCT

Product string index.

USBD_HID_STRING_SERIALNUMBER

Serial number string index.

USBD_HID_STRING_STRING_INTERFACE

String interface string index.

USBD_HID_INTERRUPT_OUT_EP_ADDRESS

EP for INTR OUT

USBD_HID_INTERRUPT_IN_EP_ADDRESS

EP for INTR IN

USBD_HID_HS_INT_MAX_PACKET_SIZE

High speed INTR maximum packet size

USBD_HID_FS_INT_MAX_PACKET_SIZE

High speed INTR OUT maximum packet size

USBD_HID_DESC_SIZE

HID descriptor size.

USBD_HID_DESC_ITEM_LENGTH_OFFSET

Mouse Reserved. all bit should set to 1.

USBD_HID_CFG_DESC_ITEM_LENGTH_OFFSET

Mouse Reserved. all bit should set to 1.

USBD_HID_MOUSE_BUTTON_LEFT

Mouse Left button. 0: release, 1: press.

USBD_HID_MOUSE_BUTTON_RIGHT

Mouse Right button. 0: release, 1: press.

USBD_HID_MOUSE_BUTTON_MIDDLE

Mouse Wheel button. 0: release, 1: press.

USBD_HID_MOUSE_BUTTON_RESERVED

Mouse Reserved. all bit should set to 1.

Device MSC Constants

USBD_MSC_TX_THREAD_PRIORITY

TX thread priority

USBD_MSC_RX_THREAD_PRIORITY

RX thread priority

USBD_MSC_VID

Vendor ID.

USBD_MSC_PID

Product ID.

USBD_MSC_SELF_POWERED

Set to 1 if device is self-powered, 0 for bus-powered.

USBD_MSC_CONFIG_DESC_SIZE

Size of the MSC configuration descriptor.

USBD_MSC_LANGID_STRING

Language ID string (0x0409 for U.S. English).

USBD_MSC_MFG_STRING

Manufacturer string.

USBD_MSC_PROD_HS_STRING

Product string for High-Speed.

USBD_MSC_PROD_FS_STRING

Product string for Full-Speed.

USBD_MSC_SN_STRING

Serial number string.

USBD_MSC_BULK_IN_EP

Endpoint for BULK IN.

USBD_MSC_BULK_OUT_EP

Endpoint for BULK OUT.

USBD_MSC_HS_MAX_PACKET_SIZE

High-Speed BULK IN & OUT maximum packet size.

USBD_MSC_FS_MAX_PACKET_SIZE

Full-Speed BULK IN & OUT maximum packet size.

USBD_MSC_CTRL_BUF_SIZE

Control transfer buffer size

USBD_MSC_FIX_CV_TEST_ISSUE

USBD_MSC_BLK_BITS

Number of bits per block (log2(512)).

USBD_MSC_BLK_SIZE

Block size in bytes (512).

USBD_MSC_BUFLEN

Default size of the internal data buffer.

USBD_MSC_REQUEST_RESET

Bulk-Only Mass Storage Reset request.

USBD_MSC_REQUEST_GET_MAX_LUN

Get Max LUN request.

USBD_MSC_CB_WRAP_LEN

Standard CBW length

USBD_MSC_CB_SIGN

Standard dCBWSignature, spells out USBC

USBD_MSC_CS_WRAP_LEN

Standard CSW length

USBD_MSC_CS_SIGN

Standard dCSWSignature, spells out 'USBS'

USBD_MSC_CSW_CMD_PASSED

The pass status of the command execution

USBD_MSC_CSW_CMD_FAILED

The fail status of the command execution

USBD_MSC_CSW_PHASE_ERROR

The phase error status of the command execution

USBD_MSC_IDLE

Idle state

USBD_MSC_DATA_OUT

Data Out state

USBD_MSC_DATA_IN

Data In state

USBD_MSC_LAST_DATA_IN

Last Data In state

USBD_MSC_SEND_DATA

Send Immediate data

USBD_MSC_NO_DATA

No data Stage

USBD_MSC_STATUS_NORMAL

Normal working status

USBD_MSC_STATUS_RECOVERY

Get MSC Reset request for recovery

USBD_MSC_STATUS_ERROR

Error status

USBD_MSC_SENSE_LIST_DEPTH

Depth of the SCSI sense data list.

Device UAC Constants

USBD_UAC_DEBUG

Enable/Disable UAC debug feature.

USBD_UAC_VID

Vendor ID.

USBD_UAC_PID

Product ID.

USBD_UAC_ISOC_IN_EP

EP for ISOC IN.

USBD_UAC_ISOC_OUT_EP

EP for ISOC OUT.

USBD_UAC_CH_CNT_2

Audio 2 channel count.

USBD_UAC_CH_CNT_4

Audio 4 channel count.

USBD_UAC_CH_CNT_6

Audio 6 channel count.

USBD_UAC_CH_CNT_8

Audio 8 channel count.

USBD_UAC_BYTE_WIDTH_2

Audio 2 bytes width.

USBD_UAC_BYTE_WIDTH_3

Audio 3 bytes width.

USBD_UAC_BYTE_WIDTH_4

Audio 4 bytes width.

USBD_UAC_DEFAULT_CH_CNT

Default audio channel count.

USBD_UAC_DEFAULT_BYTE_WIDTH

Default audio byte width.

USBD_UAC_SAMPLING_FREQ_44K

Audio 44100 sample frequency.

USBD_UAC_SAMPLING_FREQ_48K

Audio 48000 sample frequency.

USBD_UAC_SAMPLING_FREQ_96K

Audio 96000 sample frequency.

USBD_UAC_SAMPLING_FREQ_192K

Audio 192000 sample frequency.

Device Vendor Constants

USBD_VENDOR_BULK_OUT_XFER_CNT

Number of BULK OUT test transfers (test count)

USBD_VENDOR_INTR_OUT_XFER_CNT

Number of INTR OUT test transfers (test count)

USBD_VENDOR_ISOC_OUT_XFER_CNT

Number of ISOC OUT test transfers (test count)

USBD_VENDOR_VID

Vendor ID

USBD_VENDOR_PID

Product ID

USBD_VENDOR_CLASS_CODE

Device class code (0xFF = Vendor Specific)

USBD_VENDOR_SUBCLASS_CODE

Device subclass code (0x00 = No specific subclass)

USBD_VENDOR_PROTOCOL

Device protocol code (0x00 = No specific protocol)

USBD_VENDOR_SELF_POWERED

Device is self-powered

USBD_VENDOR_REMOTE_WAKEUP_EN

Remote wakeup is enabled

USBD_VENDOR_CONFIG_DESC_SIZE

Total size (bytes) of the configuration descriptor

USBD_VENDOR_LANGID_STRING

Language ID for string descriptors (0x0409 = English

USBD_VENDOR_MFG_STRING

Manufacturer string

USBD_VENDOR_PROD_HS_STRING

Product string for High-Speed mode

USBD_VENDOR_PROD_FS_STRING

Product string for Full-Speed mode

USBD_VENDOR_SN_STRING

Serial number string

USBD_VENDOR_BULK_IN_EP

EP for BULK IN

USBD_VENDOR_BULK_OUT_EP

EP for BULK OUT

USBD_VENDOR_INTR_IN_EP

EP for INTR IN

USBD_VENDOR_INTR_OUT_EP

EP for INTR OUT

USBD_VENDOR_ISOC_IN_EP

EP for ISOC IN

USBD_VENDOR_ISOC_OUT_EP

EP for ISOC OUT

USBD_VENDOR_HS_BULK_MPS

High speed BULK IN & OUT maximum packet size

USBD_VENDOR_FS_BULK_MPS

Full speed BULK IN & OUT maximum packet size

USBD_VENDOR_HS_INTR_MPS

High speed INTR IN & OUT maximum packet size

USBD_VENDOR_FS_INTR_MPS

Full speed INTR IN & OUT maximum packet size

USBD_VENDOR_HS_ISOC_MPS

High speed ISOC IN & OUT maximum packet size

USBD_VENDOR_FS_ISOC_MPS

Full speed ISOC IN & OUT maximum packet size

USBD_VENDOR_HS_INTR_IN_INTERVAL

High speed INTR IN interval

USBD_VENDOR_HS_INTR_OUT_INTERVAL

High speed INTR OUT interval

USBD_VENDOR_FS_INTR_IN_INTERVAL

Full speed INTR IN interval

USBD_VENDOR_FS_INTR_OUT_INTERVAL

Full speed INTR OUT interval

USBD_VENDOR_HS_ISOC_IN_INTERVAL

High speed ISOC IN interval

USBD_VENDOR_HS_ISOC_OUT_INTERVAL

High speed ISOC OUT interval

USBD_VENDOR_FS_ISOC_IN_INTERVAL

Full speed ISOC IN interval

USBD_VENDOR_FS_ISOC_OUT_INTERVAL

Full speed ISOC OUT interval

USB Device Types

Composite CDC ACM Types

struct usbd_composite_cdc_acm_usr_cb_t

#include <usbd_composite_cdc_acm.h>

User callback structure for CDC ACM events.

This structure allows the application layer to handle key CDC ACM events.

Public Members

int (*init)(void)

Called during class driver initialization for application resource setup.

int (*deinit)(void)

Called during class driver deinitialization for resource cleanup.

int (*setup)(usb_setup_req_t *req, u8 *buf)

Called during control transfer SETUP/DATA phases to handle application-specific control requests.

int (*received)(u8 *buf, u32 len)

Called when new data is received on the Bulk OUT endpoint.

void (*transmitted)(u8 status)

Called after data transmission on the Bulk IN endpoint is complete.

struct usbd_composite_cdc_acm_ntf_t

#include <usbd_composite_cdc_acm.h>

CDC ACM Notification Structure.

This structure defines the format for sending notifications (like SERIAL_STATE) on the Interrupt IN endpoint. This is only available if CONFIG_COMP_CDC_ACM_NOTIFY is enabled.

Public Members

u8 bmRequestType

D7: 0=Host-to-Device, 1=Device-to-Host. D6-5: 1=Class. D4-0: 0=Device, 1=Interface, 2=Endpoint.

u8 bNotificationType

Notification code, e.g., USB_CDC_NOTIFY_SERIAL_STATE.

u16 wValue

Typically 0.

u16 wIndex

The interface number.

u16 wLength

Size of the notification data payload.

u8 buf[USB_CDC_ACM_INTR_IN_DATA_SIZE]

Notification data payload.

struct usbd_composite_cdc_acm_dev_t

#include <usbd_composite_cdc_acm.h>

CDC ACM device context structure.

This main structure holds the state and configuration for the CDC ACM function.

Public Members

usbd_composite_dev_t *cdev

Pointer to the parent composite device structure.

usbd_composite_cdc_acm_usr_cb_t *cb

Pointer to the user-registered callback structure.

usbd_ep_t ep_bulk_in

Bulk IN endpoint handler.

usbd_ep_t ep_bulk_out

Bulk OUT endpoint handler.

usbd_ep_t ep_intr_in

Interrupt IN endpoint handler (for notifications).

Device CDC ACM Types

struct usbd_cdc_acm_ntf_t

#include <usbd_cdc_acm.h>

Structure for CDC ACM notifications sent to the host.

This is a packed structure used for sending notifications like SERIAL_STATE over the INTERRUPT IN endpoint.

Public Members

u8 bmRequestType

D7: Data transfer direction (1=Device-to-Host), D6-5: Type (1=Class), D4-0: Recipient (1=Interface).

u8 bNotificationType

Notification code, e.g., USB_CDC_ACM_NOTIFY_SERIAL_STATE.

u16 wValue

Varies by notification. For SERIAL_STATE, it's 0.

u16 wIndex

Interface number.

u16 wLength

Size of the notification data payload.

u8 buf[USB_CDC_ACM_INTR_IN_DATA_SIZE]

Notification data payload.

struct usbd_cdc_acm_cb_t

#include <usbd_cdc_acm.h>

Structure containing callback functions for the CDC ACM class.

The user application should provide an instance of this structure to handle class-specific events.

Public Members

int (*init)(void)

Called when the CDC ACM class driver initialization for application resource setup.

Return:

0 on success, non-zero on failure.

int (*deinit)(void)

Called when the CDC ACM device is de-initialized for resource cleanup.

Return:

0 on success, non-zero on failure.

int (*setup)(usb_setup_req_t *req, u8 *buf)

Called to handle class-specific SETUP requests.

Param req:

[in] Pointer to the setup request packet.

Param buf:

[out] Pointer to a buffer for data stage of control transfers.

Return:

0 on success, non-zero on failure.

int (*received)(u8 *buf, u32 len)

Called when new data is received from the host on the BULK OUT endpoint.

Param buf:

[in] Pointer to the received data buffer.

Param len:

[in] Length of the received data in bytes.

Return:

0 on success, non-zero on failure.

void (*transmitted)(u8 status)

Called when a data transmission to the host on the BULK IN endpoint is complete.

Param status:

[in] The status of the transmission.

void (*status_changed)(u8 old_status, u8 status)

Called when USB attach status changes for application to support hot-plug events.

Param old_status:

[in] The previous attach status.

Param status:

[in] The new attach status.

struct usbd_cdc_acm_dev_t

#include <usbd_cdc_acm.h>

Structure representing the CDC ACM device instance.

Public Members

usb_setup_req_t ctrl_req

Stores the current control request.

usbd_ep_t ep_bulk_in

BULK IN endpoint structure.

usbd_ep_t ep_bulk_out

BULK OUT endpoint structure.

usbd_ep_t ep_intr_in

INTERRUPT IN endpoint structure.

usb_dev_t *dev

Pointer to the USB device instance.

usbd_cdc_acm_cb_t *cb

Pointer to the user-defined callback structure.

u16 intr_notify_idx

Index for managing interrupt notifications.

Device Composite Types

struct usbd_composite_cb_t

#include <usbd_composite_config.h>

Composite user callback structure.

Public Members

void (*status_changed)(u8 old_status, u8 status)

Callback invoked when USB status change. See usbd_attach_status_t.

Called upon connection state changed for hot-plug support (e.g. do reinitialization on host disconnection)

Param old_status:

[in] Previous status of USB device.

Param status:

[in] Current status of USB device.

Return:

None Called upon USB attach status changes for application to support hot-plug events.

int (*set_config)(void)

Called in the set_config callback of usbd_class_driver_t to notifies application layer that the class driver becomes operational.

Return:

None

struct usbd_composite_dev_t

#include <usbd_composite_config.h>

Composite device structure.

Public Members

usb_setup_req_t ctrl_req

Control setup request.

usbd_composite_cb_t *cb

Composite user callback

usb_dev_t *dev

USB device instance

Device Core Types

enum usbd_state_t

USB device state.

Values:

enumerator USBD_STATE_INIT

Initial state, before enumeration.

enumerator USBD_STATE_DEFAULT

Default state, after reset.

enumerator USBD_STATE_ADDRESSED

Addressed state, after SET_ADDRESS.

enumerator USBD_STATE_CONFIGURED

Configured state, after SET_CONFIGURATION.

enumerator USBD_STATE_SUSPENDED

Suspended state.

enum usbd_attach_status_t

USB device attach status.

Values:

enumerator USBD_ATTACH_STATUS_INIT

Initial status.

enumerator USBD_ATTACH_STATUS_ATTACHED

Device is attached to the host.

enumerator USBD_ATTACH_STATUS_DETACHED

Device is detached from the host.

typedef struct _usbd_class_driver_t usbd_class_driver_t

Defines the structure for the USB class driver callbacks.

备注

All the device class driver callback functions are invoked in interrupt context. Time-consuming or blocking operations must not be executed within these callback functions.

struct usbd_ep_t

#include <usbd.h>

Defines the structure for an USB endpoint.

Public Members

u8 *xfer_buf

Pointer to the transfer buffer.

u8 *rem_xfer_buf

Pointer to the remaining part of the transfer buffer.

u32 xfer_len

Total length of the data to transfer.

u32 rem_xfer_len

Remaining length of data to transfer (used for EP0).

u32 xfer_buf_len

Total length of the class transfer buffer.

u16 mps

Maximum Packet Size for this endpoint (0-64KB).

u8 addr

Endpoint address (includes direction).

u8 num

Endpoint number (0-15).

u8 type

Endpoint type (Control, Bulk, Isochronous, Interrupt).

u8 binterval

Polling interval for the endpoint.

u8 skip_dcache_pre_clean

Skip DCache_Clean in TRX API and it will be called in class.

u8 skip_dcache_post_invalidate

Skip DCache_Invalidate when RX complete and it will be called in class.

u8 xfer_state

Current state of the class transfer.

u8 tx_zlp

Flag to indicate if a Zero-Length Packet should be sent.

u8 dis_zlp

Flag to disable Zero-Length Packet for the current transfer.

u8 is_busy

Flag indicating if the endpoint is currently busy.

struct usbd_config_t

#include <usbd.h>

Defines the core driver configuration parameters for the USB device.

Public Members

u32 nptx_max_epmis_cnt

Threshold count of EPMis interrupts for non-periodic IN transfers.

If the mismatch count exceeds this value, the GINTSTS.EPMis interrupt is handled. This is only active if USBD_EPMIS_INTR is enabled (Shared FIFO mode only).

u32 ext_intr_enable

Enables extra interrupts.

Optional USB interrupt enable flags:

• USBD_SOF_INTR: For SOF-based timing synchronization.

• USBD_EOPF_INTR: For ISOC transfers parity setting in slave mode.

• USBD_EPMIS_INTR: To handle endpoint mismatches in shared FIFO mode. For restarting IN transfers, applicable to scenarios with multiple non-periodic IN endpoints.

u16 rx_fifo_depth

RxFIFO depth in dwords which must not exceed hardware limits(Dedicated FIFO mode only).

u16 ptx_fifo_depth[USB_MAX_ENDPOINTS - 1]

Depth of TxFIFO n (for n=1 to USB_MAX_ENDPOINTS-1) in dwords which must not exceed hardware limits.

ptx_fifo_depth[i] corresponds to TxFIFO i+1 (Dedicated FIFO mode only).

备注

• For SoCs with shared USB FIFO, no FIFO depth configuration is required.

• For SoCs with dedicated USB FIFO, observe the following constraint: rx_fifo_depth + all ptx_fifo_depth[n] <= Hardware total FIFO depth

u8 speed

USB device speed mode. See usb_speed_type_t.

• USB_SPEED_HIGH: USB 2.0 High-Speed PHY (for HS-capable SoCs).

• USB_SPEED_HIGH_IN_FULL: USB 2.0 PHY operating in Full-Speed mode (for HS-capable SoCs with low bandwidth applcations like UAC).

• USB_SPEED_FULL: USB 1.1 Full-Speed transceiver (for FS-only SoCs).

u8 isr_priority

Priority of the USB interrupt.

u8 isr_in_critical

Flag to process USB ISR within a critical section.

u8 intr_use_ptx_fifo

Use Periodic TxFIFO for Interrupt IN transfers (Shared TxFIFO mode only).

u8 tp_trace

Enable/disable tracing for transfer performance.

struct usb_dev_t

#include <usbd.h>

Defines the main USB device structure.

Public Members

u64 isr_process_time_max

[Debug] Maximum ISR handler processing time

u64 isr_process_time

[Debug] Current ISR handler processing time

u64 isr_enter_period_max

[Debug] Maximum interval between two consecutive ISR processing

u64 isr_enter_period

[Debug] Current time between last two consecutive ISR processing

u64 isr_enter_time

[Debug] Timestamp of current ISR handler entry

usbd_ep_t ep0_in

Control endpoint 0 IN.

usbd_ep_t ep0_out

Control endpoint 0 OUT.

struct _usbd_class_driver_t *driver

Pointer to the active class driver.

void *pcd

Pointer to the low-level PCD (Platform Controller Driver) handle.

u32 ep0_out_intr

Previous interrupt status for EP0 OUT.

u16 ep0_data_len

Data length for the current EP0 transfer.

u8 ep0_state

Current state of the EP0 state machine.

u8 ep0_old_state

Previous state of the EP0 state machine.

u8 dev_config

Current device configuration index.

u8 dev_speed

Current device speed. See usb_speed_type_t.

u8 dev_state

Current device state. See usbd_state_t.

u8 dev_old_state

Previous device state.

u8 dev_attach_status

Current device attach status. See usbd_attach_status_t.

u8 dev_old_attach_status

Previous device attach status.

u8 test_mode

Flag indicating if the device is in a test mode.

u8 self_powered

Power source status: 0 for bus-powered, 1 for self-powered.

u8 remote_wakeup_en

Remote wakeup enable or not, 0-disabled, 1-enabled

u8 remote_wakeup

Remote wakeup flag.

u8 is_ready

Device ready or not, 0-disabled, 1-enabled

u8 is_connected

Device connected or not,0-disabled, 1-enabled

struct _usbd_class_driver_t

#include <usbd.h>

Defines the structure for the USB class driver callbacks.

备注

All the device class driver callback functions are invoked in interrupt context. Time-consuming or blocking operations must not be executed within these callback functions.

Public Members

u16 (*get_descriptor)(usb_dev_t *dev, usb_setup_req_t *req, u8 *buf)

Callback to get a descriptor during enumeration when host requests USB descriptors.

备注

The class driver must return the descriptor data buffer and length againt the wValue value of host setup request:

• USB_DESC_TYPE_DEVICE: Device Descriptor, mandatory.

• USB_DESC_TYPE_CONFIGURATION: Configuration Descriptor, mandatory.

• USB_DESC_TYPE_DEVICE_QUALIFIER: Device Qualifier Descriptor, required for dual-speed (FS/HS) devices |

• USB_DESC_TYPE_OTHER_SPEED_CONFIGURATION: Other Speed Configuration Descriptor, required for dual-speed (FS/HS) devices.

• USB_DESC_TYPE_STRING: String descriptors (language ID, manufacturer, product, serial), optional.

Param dev:

[in] USB device.

Param req:

[in] USB setup request.

Param buf:

[out] Buffer to store the requested descriptor.

Return:

The actual length of the descriptor.

int (*set_config)(usb_dev_t *dev, u8 config)

Callback to set the device configuration.

备注

Called upon SET_CONFIGURATION request in ADDRESSED state. The device class driver must:

• Initialize endpoints via usbd_ep_init.

• Prepare first OUT transfer via usbd_ep_receive.

Param dev:

[in] USB device.

Param config:

[in] The configuration index to be set.

Return:

0 on success, non-zero on failure.

int (*clear_config)(usb_dev_t *dev, u8 config)

Callback to clear the device configuration.

备注

Called upon:

• Core driver receives SET_CONFIGURATION control request in CONFIGURED state and needs to switch configuration.

• Core driver receives SET_CONFIGURATION control request in non-ADDRESSED/CONFIGURED state.

• Core driver processes enumeration complete interrupt (GINTSTS.EnumDone).

• Core driver processes Session end interrupt (GOTGINT.SesEndDet).

• USB core driver API usbd_deinit is called. Typically, the device class driver shall call usbd_ep_deinit to deinitialize the endpoints.

Param dev:

[in] USB device.

Param config:

[in] The configuration index to be cleared.

Return:

0 on success, non-zero on failure.

int (*setup)(usb_dev_t *dev, usb_setup_req_t *req)

Callback to handle class-specific or vendor-specific setup requests at control transfer setup phase.

• Standard interface requests (SET_INTERFACE/GET_INTERFACE/GET_STATUS).

• Class-specific requests per relevant class specifications.

• Vendor-defined requests for custom devices.

Param dev:

[in] USB device.

Param req:

[in] USB setup request.

Return:

0 on success, non-zero on failure.

int (*sof)(usb_dev_t *dev)

Callback invoked at the Start-of-Frame (SOF).

Called upon SOF interrupt (GINTSTS.Sof) for timing-sensitive operations (e.g. UAC clock synchronization).

Param dev:

[in] USB device.

Return:

0 on success, non-zero on failure.

int (*ep0_data_in)(usb_dev_t *dev, u8 status)

Callback invoked when an IN data transfer on EP0 is complete.

Param dev:

[in] USB device.

Param status:

[in] Status of the completed transfer.

Return:

0 on success, non-zero on failure.

int (*ep0_data_out)(usb_dev_t *dev)

Callback invoked when an OUT data transfer on EP0 is complete.

备注

The device driver does not need to re-enable the control OUT transfer since it is automatically done in core driver.

Param dev:

[in] USB device.

Return:

0 on success, non-zero on failure.

int (*ep_data_in)(usb_dev_t *dev, u8 ep_addr, u8 status)

Callback invoked when a bulk/interrupt/isochronous IN data transfer on EP is complete.

备注

The device class driver may mark endpoint ready for next transfer or retry failed transfers.

Param dev:

[in] USB device structure.

Param ep_addr:

[in] Endpoint address.

Param status:

[in] Status of the completed transfer.

Return:

0 on success, non-zero on failure.

int (*ep_data_out)(usb_dev_t *dev, u8 ep_addr, u32 len)

Callback invoked when a bulk/interrupt/isochronous OUT data transfer on EP is complete.

备注

Typically, the device class driver shall:

• Process received data via application callback.

• Prepare next OUT transfer via usbd_ep_receive.

Param dev:

[in] USB device.

Param ep_addr:

[in] Endpoint address.

Param status:

[in] Status of the completed transfer.

Return:

0 on success, non-zero on failure.

void (*status_changed)(usb_dev_t *dev, u8 old_status, u8 status)

Callback invoked when USB status change. See usbd_attach_status_t.

Called upon connection state changed for hot-plug support (e.g. do reinitialization on host disconnection)

Param dev:

[in] USB device.

Param old_status:

[in] Previous status of USB device.

Param status:

[in] Current status of USB device.

Return:

None

Device HID Types

struct usbd_hid_usr_cb_t

#include <usbd_hid.h>

Structure containing callback functions for the HID class.

The user application should provide an instance of this structure to handle class-specific events.

Public Members

void (*init)(void)

Called when the HID class driver initialization for application resource setup.

void (*deinit)(void)

Called when the HID device is de-initialized for resource cleanup.

void (*setup)(void)

Called to handle class-specific SETUP requests.

void (*transmitted)(u8 status)

Called when a data transmission to the host on the BULK IN endpoint is complete.

Param status:

[in] The status of the transmission.

void (*status_changed)(u8 old_status, u8 status)

Called when USB attach status changes for application to support hot-plug events.

Param old_status:

[in] The previous attach status.

Param status:

[in] The new attach status.

Device MSC Types

struct usbd_msc_cb_t

#include <usbd_msc.h>

MSC user callback structure.

This structure holds pointers to user-defined callback functions that are invoked on various MSC events.

Public Members

void (*status_changed)(u8 old_status, u8 status)

Called when the USB device status changes for application to support USB hot-plug events.

Param old_status:

[in] The previous USB device status.

Param status:

[in] The new USB device status.

Device UAC Types

struct usbd_audio_cfg_t

#include <usbd_uac.h>

Public Members

u32 sampling_freq

Audio sample frequency param.

u8 byte_width

Audio byte width param.

u8 ch_cnt

Audio channel count param.

u8 enable

Audio enable.

struct usbd_uac_cb_t

#include <usbd_uac.h>

Public Members

usbd_audio_cfg_t in

Audio configuration parameters for record.

usbd_audio_cfg_t out

Audio configuration parameters for playback.

void *audio_ctx

Audio context params.

int (*init)(void)

Called when the UAC class driver initialization for application resource setup.

Return:

0 on success, non-zero on failure.

int (*deinit)(void)

Called when the UAC device is de-initialized for resource cleanup.

Return:

0 on success, non-zero on failure.

int (*setup)(usb_setup_req_t *req, u8 *buf)

Called to handle class-specific SETUP requests.

Param req:

[in] Pointer to the setup request packet.

Param buf:

[out] Pointer to a buffer for data stage of control transfers.

Return:

0 on success, non-zero on failure.

int (*set_config)(void)

Called when the UAC class driver initialization for application resource setup.

Return:

0 on success, non-zero on failure.

void (*status_changed)(u8 old_status, u8 status)

Called when USB attach status changes for application to support hot-plug events.

Param old_status:

[in] The previous attach status.

Param status:

[in] The new attach status.

void (*mute_changed)(u8 mute)

Called when the UAC class driver initialization for application resource setup.

Param mute:

[in] Mute value, 0 unmute, 1 mute

void (*volume_changed)(u8 volume)

Called when the UAC class driver initialization for application resource setup.

Param volume:

[in] Volume value, from 0~100

void (*format_changed)(u32 sampling_freq, u8 ch_cnt, u8 byte_width)

Called when the audio format changed in the UAC class driver.

Param sampling_freq:

[in] New sample frequency.

Param ch_cnt:

[in] New channel count. such as 2,4,6,8...

Param byte_width:

[in] New byte width, such as 1,2,3,4.

void (*sof)(void)

Called when the SOF interrupt occurs in the UAC class driver.

struct usbd_uac_buf_t

#include <usbd_uac.h>

Public Members

u8 *buf_raw

Pointer to the buffer.

u16 buf_valid_len

Valid buffer length.

struct usbd_uac_buf_ctrl_t

#include <usbd_uac.h>

Public Members

rtos_sema_t uac_isoc_sema

ISOC sema.

usbd_uac_buf_t *buf_array

Pointer to audio buffer array.

u8 *isoc_buf

Pointer to audio total buffer.

u16 isoc_mps

ISOC maximum packet size.

u16 buf_array_cnt

Valid audio buffer array count.

u8 uac_sema_valid

ISOC sema created.

u8 read_wait_sema

The sema is waiting.

u8 isoc_read_idx

Next read position.

u8 isoc_write_idx

Next write position.

u8 next_xfer

Audio transfer continue flag.

Device Vendor Types

struct usbd_vendor_cb_t

#include <usbd_vendor.h>

Structure containing callback functions for the Vendor class.

The user application should provide an instance of this structure to handle class-specific events.

Public Members

int (*init)(void)

Called when the USB class driver initialization for application resource setup.

Return:

0 on success, non-zero on failure.

int (*deinit)(void)

Called when the USB device is de-initialized for resource cleanup.

Return:

0 on success, non-zero on failure.

int (*setup)(usb_setup_req_t *req, u8 *buf)

Called to handle class-specific SETUP requests.

Param req:

[in] Pointer to the setup request packet.

Param buf:

[out] Pointer to a buffer for data stage of control transfers.

Return:

0 on success, non-zero on failure.

int (*set_config)(void)

Called when the USB device is configured.

Return:

0 on success, non-zero on failure.

int (*bulk_received)(u8 *buf, u32 len)

Called when new data is received from the host on the BULK OUT endpoint.

Param buf:

[in] Pointer to the received data buffer.

Param len:

[in] Length of the received data in bytes.

Return:

0 on success, non-zero on failure.

int (*intr_received)(u8 *buf, u32 len)

Called when new data is received from the host on the INTR OUT endpoint.

Param buf:

[in] Pointer to the received data buffer.

Param len:

[in] Length of the received data in bytes.

Return:

0 on success, non-zero on failure.

int (*isoc_received)(u8 *buf, u32 len)

Called when new data is received from the host on the ISOC OUT endpoint.

Param buf:

[in] Pointer to the received data buffer.

Param len:

[in] Length of the received data in bytes.

Return:

0 on success, non-zero on failure.

void (*bulk_transmitted)(u8 status)

Called when a data transmission to the host on the BULK IN endpoint is complete.

Param status:

[in] The status of the transmission.

void (*intr_transmitted)(u8 status)

Called when a data transmission to the host on the INTR IN endpoint is complete.

Param status:

[in] The status of the transmission.

void (*isoc_transmitted)(u8 status)

Called when a data transmission to the host on the ISOC IN endpoint is complete.

Param status:

[in] The status of the transmission.

void (*status_changed)(u8 old_status, u8 status)

Called when USB attach status changes for application to support hot-plug events.

Param old_status:

[in] The previous attach status.

Param status:

[in] The new attach status.

struct usbd_vendor_dev_t

#include <usbd_vendor.h>

Structure representing the Vendor device instance.

Public Members

usb_setup_req_t ctrl_req

Stores the current control request

usbd_ep_t ep_isoc_in

ISOC IN endpoint structure

usbd_ep_t ep_isoc_out

ISOC OUT endpoint structure

usbd_ep_t ep_bulk_in

BULK IN endpoint structure

usbd_ep_t ep_bulk_out

BULK OUT endpoint structure

usbd_ep_t ep_intr_in

INTR IN endpoint structure

usbd_ep_t ep_intr_out

INTR OUT endpoint structure

usb_dev_t *dev

Pointer to the USB device instance

usbd_vendor_cb_t *cb

Pointer to the user-defined callback structure

u8 alt_setting

Alternate setting number of the current interface

USB Host API

USB Host Functions

Host CDC ACM Functions

int usbh_cdc_acm_init(usbh_cdc_acm_cb_t *cb)

Initializes the CDC ACM host class driver.

参数:

cb -- [in] Pointer to the user-defined callback structure.

返回:

0 on success, non-zero on failure.

int usbh_cdc_acm_deinit(void)

De-initializes the CDC ACM host class driver.

返回:

0 on success, non-zero on failure.

int usbh_cdc_acm_set_line_coding(usb_cdc_line_coding_t *lc)

Sets the line coding parameters for the device.

参数:

lc -- [in] Pointer to the line coding structure.

返回:

0 on success, non-zero on failure.

int usbh_cdc_acm_get_line_coding(usb_cdc_line_coding_t *lc)

Gets the current line coding parameters from the device.

参数:

lc -- [out] Pointer to the structure where the line coding will be stored.

返回:

0 on success, non-zero on failure.

int usbh_cdc_acm_set_control_line_state(void)

Sets the control line state (DTR, RTS).

返回:

0 on success, non-zero on failure.

int usbh_cdc_acm_transmit(u8 *buf, u32 len)

Transmits data to the device over the BULK OUT pipe.

参数:

• buf -- [in] Pointer to the data buffer to be transmitted.

• len -- [in] Length of the data in bytes.

返回:

0 on success, non-zero on failure.

int usbh_cdc_acm_receive(u8 *buf, u32 len)

Prepares to receive data from the device over the BULK IN pipe.

参数:

• buf -- [in] Pointer to the buffer where received data will be stored.

• len -- [in] Length of the buffer in bytes.

返回:

0 on success, non-zero on failure.

int usbh_cdc_acm_notify_receive(u8 *buf, u32 len)

Prepares to receive notification data (e.g. Serial State) over the INTERRUPT IN pipe.

参数:

• buf -- [in] Pointer to the buffer where notification data will be stored.

• len -- [in] Length of the buffer in bytes.

返回:

0 on success, non-zero on failure.

u16 usbh_cdc_acm_get_bulk_ep_mps(void)

Gets the Maximum Packet Size (MPS) of the BULK endpoint.

返回:

The MPS in bytes.

Host CDC ECM Functions

int usbh_cdc_ecm_init(usbh_cdc_ecm_state_cb_t *cb, usbh_cdc_ecm_priv_data_t *priv)

Initializes the CDC ECM host class driver. Registers the application callback handler and user private parameters.

参数:

• cb -- [in] Pointer to the user-defined callback structure.

• priv -- [in] Pointer to the user-defined private parameter structure.

返回:

0 (HAL_OK) on success, non-zero on failure.

int usbh_cdc_ecm_deinit(void)

De-initializes the CDC ECM host class driver and releases resources.

返回:

0 (HAL_OK) on success, non-zero on failure.

int usbh_cdc_ecm_choose_config(usb_host_t *host)

Selects the appropriate configuration index.

参数:

host -- [in] USB Host Handle.

返回:

0 (HAL_OK) on success, non-zero on failure.

int usbh_cdc_ecm_check_config_desc(usb_host_t *host)

Validates the configuration descriptor of the connected device.

参数:

host -- [in] USB Host Handle.

返回:

0 (HAL_OK) on success, non-zero on failure.

u8 usbh_cdc_ecm_usb_is_ready(void)

Checks if the CDC ECM interface is fully configured and ready for data transfer.

返回:

1: Driver is ready (Enumerated & Configured). 0: Driver is not ready.

int usbh_cdc_ecm_send_data(u8 *buf, u32 len)

Transmits an Ethernet packet to the device via the Bulk OUT endpoint.

参数:

• buf -- [in] Pointer to the data buffer (Ethernet frame) to be transmitted.

• len -- [in] Length of the data in bytes.

返回:

0 (HAL_OK) on success, non-zero on failure.

int usbh_cdc_ecm_get_connect_status(void)

Gets the Ethernet physical link status.

返回:

1: Link Up (Cable connected). 0: Link Down (Cable disconnected or device not ready).

const u8 *usbh_cdc_ecm_process_mac_str(void)

Gets the MAC address of the connected device.

返回:

Pointer to the 6-byte MAC address array on success, NULL on failure.

Host Core Functions For Applications

int usbh_init(usbh_config_t *cfg, usbh_user_cb_t *cb)

Initialize USB host core driver with user configuration and callback.

参数:

• cfg -- [in] USB user configuration.

• cb -- [in] USB user callback.

返回:

0 on success, non-zero on failure.

int usbh_deinit(void)

Deinitialize USB host core driver.

返回:

0 on success, non-zero on failure.

Host Core Functions For Classes

int usbh_register_class(usbh_class_driver_t *driver)

Register a host class driver, called in class initialization function.

参数:

driver -- [in] USB class driver.

返回:

0 on success, non-zero on failure.

int usbh_unregister_class(usbh_class_driver_t *driver)

Un-register a class, called in class de-initialization function.

参数:

driver -- [in] USB class driver.

返回:

0 on success, non-zero on failure.

int usbh_open_pipe(usb_host_t *host, usbh_pipe_t *pipe, usbh_ep_desc_t *ep_desc)

Open a pipe.

参数:

• host -- [in] Host Handle.

• pipe -- [in] Pipe struct handle.

• ep_desc -- [in] Endpoint descriptor handle.

返回:

0 on success, non-zero on failure.

int usbh_close_pipe(usb_host_t *host, usbh_pipe_t *pipe)

Close a pipe.

参数:

• host -- [in] Host Handle.

• pipe -- [in] Pipe struct handle.

返回:

0 on success, non-zero on failure.

u8 usbh_get_configuration(usb_host_t *host, usbh_dev_id_t *id)

Get the config idx by devicd id information.

参数:

• host -- [in] Host Handle.

• id -- [in] Device id information.

返回:

config index

int usbh_set_configuration(usb_host_t *host, u8 cfg)

Set the config index for bNumConfigurations>1 in device descriptor.

参数:

• host -- [in] Host Handle.

• cfg -- [in] Config index.

返回:

0 on success, non-zero on failure.

usbh_itf_data_t *usbh_get_interface_descriptor(usb_host_t *host, usbh_dev_id_t *id)

Get the interface descriptor by devicd id information.

备注

NULL means interface not found.

参数:

• host -- [in] Host Handle.

• id -- [in] Device id information.

返回:

interface descriptor handler.

u8 *usbh_find_next_descriptor(u8 *buf, u32 *len, u8 desc_type)

Find next standard descriptor that matches the descriptor type.

参数:

• buf -- [in] buffer to find.

• len -- [in] buffer length.

• desc_type -- [in] Descriptor type.

返回:

Pointer of next standard descriptor.

u32 usbh_get_tick(usb_host_t *host)

Get the current time ticks.

参数:

host -- [in] Host Handle.

返回:

tick count.

u32 usbh_get_elapsed_ticks(usb_host_t *host, u32 start_tick)

Get the elapse ticks.

参数:

• host -- [in] Host Handle.

• start_tick -- [in] Start tick count.

返回:

Tick count.

u32 usbh_get_current_frame_number(usb_host_t *host)

Get current frame number.

参数:

host -- [in] Host Handle.

返回:

Current frame number.

u32 usbh_get_elapsed_frame_cnt(usb_host_t *host, u32 start_frame)

Get the elapse frame number.

参数:

• host -- [in] Host Handle.

• start_frame -- [in] Start frame number.

返回:

Tick count.

usbh_urb_state_t usbh_get_urb_state(usb_host_t *host, usbh_pipe_t *pipe)

Get the URB state.

参数:

• host -- [in] Host handle.

• pipe -- [in] Pipe struct handle.

返回:

URB state.

int usbh_notify_composite_class_state_change(usb_host_t *host, u8 pipe_num, u8 owner)

Notify composite class state change.

参数:

• host -- [in] Host Handle.

• pipe_num -- [in] Pipe number.

• owner -- [in] Notify owner class.

返回:

0 on success, non-zero on failure.

int usbh_ctrl_set_interface(usb_host_t *host, u8 itf_num, u8 alt_setting)

Send SET_INTERFACE standard request to device.

参数:

• host -- [in] Host Handle.

• itf_num -- [in] Interface number.

• alt_setting -- [in] Interface alternate setting number.

返回:

0 on success, non-zero on failure.

int usbh_ctrl_set_feature(usb_host_t *host, u8 value)

Send SET_FEATURE standard request to device (remote wakeup feature,..)

参数:

• host -- [in] Host handler.

• value -- [in] Feature value.

返回:

0 on success, non-zero on failure.

int usbh_ctrl_clear_feature(usb_host_t *host, u8 ep_num)

Send CLEAR_FEATURE standard request to device.

参数:

• host -- [in] Host Handle.

• ep_num -- [in] Endpoint number.

返回:

0 on success, non-zero on failure.

int usbh_ctrl_request(usb_host_t *host, usbh_setup_req_t *req, u8 *buf)

Send control request to device.

参数:

• host -- [in] Host Handle.

• req -- [in] Control request.

• buf -- [in] Data buffer.

返回:

0 on success, non-zero on failure.

int usbh_transfer_data(usb_host_t *host, usbh_pipe_t *pipe)

Start one data transfer.

参数:

• host -- [in] Host Handle.

• pipe -- [in] Pipe struct handle.

返回:

0 on success, non-zero on failure.

u32 usbh_get_last_transfer_size(usb_host_t *host, usbh_pipe_t *pipe)

Get the last transfer data size of specific pipe.

参数:

• host -- [in] Host Handle.

• pipe -- [in] Pipe struct handle.

返回:

None

int usbh_transfer_process(usb_host_t *host, usbh_pipe_t *pipe)

Start one transfer and handle result.

参数:

• host -- [in] Host Handle.

• pipe -- [in] Pipe struct handle.

返回:

0 on success, non-zero on failure.

int usbh_enable_nak_interrupt(usb_host_t *host, u8 pipe_num)

Enable NAK mask for the pipe.

参数:

• host -- [in] Host Handle.

• pipe_num -- [in] Pipe number.

返回:

0 on success, non-zero on failure.

int usbh_check_nak_timeout(usb_host_t *host, u8 pipe_num, u32 tick_cnt)

Check NAK time out.

参数:

• host -- [in] Host Handle.

• pipe_num -- [in] Pipe number.

• tick_cnt -- [in] Timout tick count.

返回:

0 on success, non-zero on failure.

int usbh_increase_busy_cnt(usb_host_t *host, u8 pipe_num, u8 step)

Increase pipe busy count.

参数:

• host -- [in] Host Handle.

• pipe_num -- [in] Pipe number.

• step -- [in] Increase step.

返回:

0 on success, non-zero on failure.

int usbh_prepare_retransfer(usb_host_t *host, u8 pipe_num)

Prepare for retransfer.

参数:

• host -- [in] Host Handle.

• pipe_num -- [in] Pipe number.

返回:

0 on success, non-zero on failure.

void usbh_suspend(void)

USB Host enter suspend.

返回:

None

void usbh_resume(void)

USB Host exit suspend.

返回:

None

int usbh_select_test_mode(u8 mode)

USB Host Port Test Control.

参数:

mode -- [in] Test mode.

返回:

0 on success, non-zero on failure.

Host MSC Functions

int usbh_msc_init(usbh_msc_cb_t *cb)

Initializes the MSC class driver with application callback handler.

参数:

cb -- [in] Pointer to a user callback structure.

返回:

0 on success, non-zero on failure.

int usbh_msc_deinit(void)

De-initializes the MSC class driver.

返回:

0 on success, non-zero on failure.

Host UAC Functions

int usbh_uac_init(usbh_uac_cb_t *cb, int frame_cnt)

Initialize the UAC Class Driver.

参数:

• cb -- Pointer to the user callback structure.

• frame_cnt -- Configuration for ring buffer size (frame count).

返回值:

Status -- (0: Success, <0: Failure)

int usbh_uac_deinit(void)

De-initialize the UAC Class Driver and release resources.

返回值:

Status --

int usbh_uac_set_alt_setting(u8 dir, u8 channels, u8 bit_width, u32 sampling_freq)

Configure the UAC Audio Format. Finds the matching Alternate Setting and sends the SET_INTERFACE request.

参数:

• dir -- Direction (0: Playback/OUT, 1: Record/IN).

• channels -- Number of channels.

• bit_width -- Bit width.

• sampling_freq -- Sampling frequency in Hz.

返回值:

Status --

const usbh_audio_fmt_t *usbh_uac_get_alt_setting(u8 dir, u8 *fmt_cnt)

Get the list of audio formats supported by the connected device.

参数:

• dir -- Direction (0: Playback/OUT, 1: Record/IN).

• fmt_cnt -- Pointer to store the number of formats found.

返回值:

Pointer -- to the array of supported formats.

u32 usbh_uac_get_frame_size(u8 dir)

Calculate the frame size (in bytes) based on current configuration.

参数:

dir -- Direction.

返回值:

Frame -- size in bytes.

int usbh_uac_set_volume(u8 volume)

Set the volume level percentage.

参数:

volume -- Volume level (0-100).

返回值:

Status --

int usbh_uac_set_mute(u8 mute)

Set the mute state.

参数:

mute -- 1 to mute, 0 to unmute.

返回值:

Status --

u32 usbh_uac_write(u8 *buffer, u32 size, u32 timeout_ms)

Write audio data to the UAC driver ring buffer.

参数:

• buffer -- Pointer to the PCM data buffer.

• size -- Size of data to write (in bytes).

• timeout_ms -- Timeout in milliseconds to wait if buffer is full.

返回值:

Actual -- number of bytes written.

void usbh_uac_start_play(void)

Start the audio playback process. Enables SOF handling and prepares for data transmission.

void usbh_uac_stop_play(void)

Stop the audio playback process.

Host UVC Functions

int usbh_uvc_init(usbh_uvc_ctx_t *cfg, usbh_uvc_cb_t *cb)

Initializes the UVC host class driver. Registers the application callback handler and global context.

参数:

• cfg -- [in] Pointer to the global UVC context configuration.

• cb -- [in] Pointer to the user-defined callback structure.

返回:

0 on success, non-zero on failure.

void usbh_uvc_deinit(void)

De-initializes the UVC host class driver and releases resources.

int usbh_uvc_stream_on(usbh_uvc_s_ctx_t *para, u32 itf_num)

Starts video streaming on the specified interface.

参数:

• para -- [in] Pointer to the stream parameters (resolution, format, etc.).

• itf_num -- [in] Interface number to start streaming on.

返回:

0 on success, non-zero on failure.

int usbh_uvc_stream_off(u32 itf_num)

Stops video streaming on the specified interface.

参数:

itf_num -- [in] Interface number to stop streaming on.

返回:

0 on success, non-zero on failure.

int usbh_uvc_stream_state(u32 itf_num)

Gets the current streaming state of an interface.

参数:

itf_num -- [in] Interface number to check.

返回:

Current streaming state (e.g., STREAMING_ON or STREAMING_OFF).

int usbh_uvc_set_param(usbh_uvc_s_ctx_t *para, u32 itf_num)

Sets video streaming parameters for the interface. Performs negotiation (PROBE/COMMIT) with the device.

参数:

• para -- [in] Pointer to the desired stream parameters.

• itf_num -- [in] Interface number.

返回:

0 on success, non-zero on failure.

usbh_uvc_frame_t *usbh_uvc_get_frame(u32 itf_num)

Retrieves a ready video frame from the driver's output queue.

参数:

itf_num -- [in] Interface number.

返回:

Pointer to a valid usbh_uvc_frame_t if available, otherwise NULL.

void usbh_uvc_put_frame(usbh_uvc_frame_t *frame, u32 itf_num)

Returns a processed frame back to the driver's free pool. Must be called after the application finishes using the frame.

参数:

• frame -- [in] Pointer to the frame to be released.

• itf_num -- [in] Interface number.

Host Vendor Functions

int usbh_vendor_init(usbh_vendor_cb_t *cb)

Initialize the Vendor Class driver.

参数:

cb -- Pointer to the application callback structure.

返回:

0 on success, non-zero on failure.

int usbh_vendor_deinit(void)

De-Initialize the Vendor Class driver.

返回:

0 on success, non-zero on failure.

int usbh_vendor_bulk_transmit(u8 *buf, u32 len, u32 test_cnt)

Start a BULK transmission.

参数:

• buf -- Pointer to the data buffer to be transmitted.

• len -- Length of the data in bytes.

• test_cnt -- Count of transfer for test. (usually 1 for normal use).

返回值:

Status. --

int usbh_vendor_bulk_receive(u8 *buf, u32 len, u32 test_cnt)

Start a BULK reception.

参数:

• buf -- Pointer to the buffer where received data will be stored.

• len -- Expected length of data in bytes.

• test_cnt -- Count of transfer for test.(usually 1 for normal use).

返回:

0 on success, non-zero on failure.

int usbh_vendor_intr_transmit(u8 *buf, u32 len, u32 test_cnt)

Start an INTERRUPT transmission.

参数:

• buf -- Pointer to the data buffer to be transmitted.

• len -- Length of the data in bytes.

• test_cnt -- Count of transfer for test.(usually 1 for normal use).

返回:

0 on success, non-zero on failure.

int usbh_vendor_intr_receive(u8 *buf, u32 len, u32 test_cnt)

Start an INTERRUPT reception.

参数:

• buf -- Pointer to the buffer where received data will be stored.

• len -- Expected length of data in bytes.

• test_cnt -- Count of transfer for test.(usually 1 for normal use).

返回:

0 on success, non-zero on failure.

int usbh_vendor_isoc_transmit(u8 *buf, u32 len, u32 test_cnt)

Start an ISOCHRONOUS transmission.

参数:

• buf -- Pointer to the data buffer to be transmitted.

• len -- Length of the data in bytes.

• test_cnt -- Count of transfer for test.(usually 1 for normal use).

返回:

0 on success, non-zero on failure.

int usbh_vendor_isoc_receive(u8 *buf, u32 len, u32 test_cnt)

Start an ISOCHRONOUS reception.

参数:

• buf -- Pointer to the buffer where received data will be stored.

• len -- Expected length of data in bytes.

• test_cnt -- Count of transfer for test.(usually 1 for normal use).

返回:

0 on success, non-zero on failure.

u16 usbh_vendor_get_bulk_ep_mps(void)

Get the Max Packet Size (MPS) of the BULK IN endpoint.

返回值:

Max -- packet size in bytes.

u16 usbh_vendor_get_intr_ep_mps(void)

Get the Max Packet Size (MPS) of the INTERRUPT IN endpoint.

返回值:

Max -- packet size in bytes.

USB Host Constants

Host CDC ACM Constants

Host CDC ECM Constants

USBH_CDC_ECM_STATE_TRACE_ENABLE

Enable or disable CDC ECM state trace logging.

USB_DEFAULT_VID

Default Vendor ID.

CDC_ECM_MAC_STR_LEN

Length of the MAC address in bytes.

CDC_ECM_CTRL_REG_BUF_LEN

Length of the ECM dongle control register buffer.

CDC_ECM_MUTICAST_FILTER_STR_LEN

Length of the ECM multicast filter control buffer.

Host Core Constants

USBH_DEV_ID_MATCH_VID

USBH_DEV_ID_MATCH_XX used in usbh_dev_id_t to specify which fields to match when searching for a device or interface.

USBH_DEV_ID_MATCH_PID

USBH_DEV_ID_MATCH_DEV_CLASS

USBH_DEV_ID_MATCH_DEV_SUBCLASS

USBH_DEV_ID_MATCH_DEV_PROTOCOL

USBH_DEV_ID_MATCH_ITF_CLASS

USBH_DEV_ID_MATCH_ITF_SUBCLASS

USBH_DEV_ID_MATCH_ITF_PROTOCOL

USBH_DEV_ID_MATCH_DEVICE

USBH_DEV_ID_MATCH_DEV_INFO

USBH_DEV_ID_MATCH_ITF_INFO

USBH_TP_TRACE_DEBUG

USBH_MAX_CLASS_NUM

USBH_MAX_HUB_PORT

USBH_EVENT_OWNER

USBH_SOF_INTR

Start of (micro)Frame GINTSTS.Sof. For host class driver to handle timing issues in SOF callback of usbh_class_driver_t

usbh_notify_class_state_change(host, pipe_num)

Notifies the host core that the class state has changed.

This is a convenience macro for usbh_notify_composite_class_state_change with owner set to USBH_EVENT_OWNER.

参数:

• host -- Pointer to the usb_host_t.

• pipe_num -- The pipe number associated with the change.

Host MSC Constants

USBH_MSC_BOT_RESET

MSC reset request code.

USBH_MSC_GET_MAX_LUN

MSC get maximum LUN request code.

MSC_CLASS_CODE

MSC interface class code.

USBH_MSC_BOT

MSC Bulk-Only Transport interface protocol code.

USBH_MSC_TRANSPARENT

MSC SCSI Transparent Command Set interface sub-class code.

USBH_BOT_CBW_SIGNATURE

'USBC' signature for the Command Block Wrapper (CBW).

USBH_BOT_CBW_TAG

A default tag for CBW, should be unique per command.

USBH_BOT_CSW_SIGNATURE

'USBS' signature for the Command Status Wrapper (CSW).

USBH_BOT_CBW_LENGTH

Length of a CBW in bytes.

USBH_BOT_CSW_LENGTH

Length of a CSW in bytes.

USBH_BOT_DATA_LENGTH

Generic data buffer length for small transfers.

USBH_MSC_MAX_LUN

Maximum number of logical units (LUNs) supported.

Host UAC Constants

USBH_UAC_DEBUG

Enable/Disable UAC debug logging (1: Enable, 0: Disable)

USBH_UAC_TERM_MAX_CNT

Maximum number of Audio Terminals supported

USBH_UAC_FU_MAX_CNT

Maximum number of Feature Units supported

USBH_UAC_MAX_CHANNEL

Maximum number of audio channels supported (e.g., 8 for 7.1 audio)

USBH_UAC_ALT_SETTING_MAX

Maximum number of Alternate Settings per interface

USBH_UAC_FREQ_FORMAT_MAX

Maximum number of discrete sampling frequencies per format

Host UVC Constants

USBH_UVC_USE_HW

Disable usage of UVC hardware decoder.

USBH_UVC_GET_FRAME_TIMEOUT

Timeout for getting a frame in ms.

USBH_UVC_FORMAT_MJPEG

Motion-JPEG format.

USBH_UVC_FORMAT_YUV

Uncompressed YUV format.

USBH_UVC_FORMAT_H264

H.264 format.

USBH_UVC_URB_NUMS

Number of URBs used for streaming.

USBH_UVC_URB_SIZE

Size of each URB buffer in bytes.

USBH_UVC_VIDEO_FRAME_NUMS

Number of video frame buffers. Fixed to 3 if using HW decoder.

USBH_UVC_DECODE_TASK_STACK

Stack size for the decode task in bytes.

USBH_UVC_DECODE_TASK_PRIORITY

Priority of the decode task.

UBSH_UVC_REQUEST_BUF_LEN

Length of the UVC control request buffer.

USBH_HW_UVC_DUMP_ERR

Host Vendor Constants

VENDOR_CLASS_CODE

Vendor Specific Class Code

VENDOR_SUBCLASS_CODE

Vendor Specific SubClass Code

VENDOR_PROTOCOL

Vendor Specific Protocol Code

USBH_VENDOR_MASK_ALL_EPS

Mask for All Endpoints

USBH_VENDOR_MASK_BULK_IN

Mask for Bulk IN transfer

USBH_VENDOR_MASK_BULK_OUT

Mask for Bulk OUT transfer

USBH_VENDOR_MASK_INTR_IN

Mask for Interrupt IN transfer

USBH_VENDOR_MASK_INTR_OUT

Mask for Interrupt OUT transfer

USBH_VENDOR_MASK_ISOC_IN

Mask for Isochronous IN transfer

USBH_VENDOR_MASK_ISOC_OUT

Mask for Isochronous OUT transfer

USB Host Types

Host CDC ACM Types

enum usbh_cdc_acm_state_t

CDC ACM state machine.

Values:

enumerator USBH_CDC_ACM_STATE_IDLE

State IDLE: Ready for operation.

enumerator USBH_CDC_ACM_STATE_SET_LINE_CODING

State SET_LINE_CODING: Configuring line coding.

enumerator USBH_CDC_ACM_STATE_GET_LINE_CODING

State GET_LINE_CODING: Retrieving line coding.

enumerator USBH_CDC_ACM_STATE_SET_CONTROL_LINE_STATE

State SET_CONTROL_LINE_STATE: Setting control line state.

enumerator USBH_CDC_ACM_STATE_TRANSFER

State TRANSFER: Data transfer in progress.

enumerator USBH_CDC_ACM_STATE_ERROR

State ERROR: Error occurred.

struct usbh_cdc_acm_cb_t

#include <usbh_cdc_acm.h>

Structure containing callback functions for the CDC ACM host class.

The user application should provide an instance of this structure to handle class-specific events.

Public Members

int (*init)(void)

Called when the CDC ACM host driver initialization.

Return:

0 on success, non-zero on failure.

int (*deinit)(void)

Called when the CDC ACM host driver de-initialization.

Return:

0 on success, non-zero on failure.

int (*attach)(void)

Called when a CDC ACM device is attached.

Return:

0 on success, non-zero on failure.

int (*detach)(void)

Called when a CDC ACM device is detached.

Return:

0 on success, non-zero on failure.

int (*setup)(void)

Called to handle class-specific SETUP requests completion.

Return:

0 on success, non-zero on failure.

int (*notify)(u8 *buf, u32 len, u8 status)

Called when interrupt data is received from the device (e.g. Serial State).

Param buf:

[in] Pointer to the received data buffer.

Param len:

[in] Length of the received data in bytes.

Param status:

[in] The status of the transfer.

Return:

0 on success, non-zero on failure.

int (*receive)(u8 *buf, u32 len, u8 status)

Called when data is received from the device on the BULK IN pipe.

Param buf:

[in] Pointer to the received data buffer.

Param len:

[in] Length of the received data in bytes.

Param status:

[in] The status of the transfer.

Return:

0 on success, non-zero on failure.

int (*transmit)(u8 status)

Called when a data transmission to the device on the BULK OUT pipe is complete.

Param status:

[in] The status of the transmission.

Return:

0 on success, non-zero on failure.

int (*line_coding_changed)(usb_cdc_line_coding_t *line_coding)

Called when the line coding parameters have changed.

Param line_coding:

[in] Pointer to the new line coding structure.

Return:

0 on success, non-zero on failure.

struct usbh_cdc_acm_host_t

#include <usbh_cdc_acm.h>

Structure representing the CDC ACM host instance.

Public Members

usbh_pipe_t bulk_in

BULK IN pipe structure.

usbh_pipe_t bulk_out

BULK OUT pipe structure.

usbh_pipe_t intr_in

INTERRUPT IN pipe structure.

usb_host_t *host

Pointer to the USB host instance.

usbh_cdc_acm_cb_t *cb

Pointer to the user-defined callback structure.

usb_cdc_line_coding_t *line_coding

Current line coding of the device.

usb_cdc_line_coding_t *user_line_coding

User requested line coding.

usbh_cdc_acm_state_t state

Current state of the CDC ACM host driver.

Host CDC ECM Types

struct usbh_cdc_ecm_priv_data_t

#include <usbh_cdc_ecm.h>

USB CDC ECM Host Private Data Structure.

Public Members

u16 *led_array

Pointer to the LED status array; each u16 element represents the state or brightness of an LED.

u8 *mac_value

Pointer to the MAC address buffer; typically points to a 6-byte physical address.

u8 led_cnt

LED count; indicates the number of valid elements in the led_array.

struct usbh_cdc_ecm_state_cb_t

#include <usbh_cdc_ecm.h>

Public Members

int (*init)(void)

Callback invoked during CDC ECM class driver initialization. Used for application-specific resource setup.

Return:

0 on success, non-zero on failure.

int (*deinit)(void)

Callback invoked during CDC ECM class driver de-initialization. Used for application-specific resource cleanup.

Return:

0 on success, non-zero on failure.

int (*attach)(void)

Callback invoked when a device is attached. Used to report the connection status to the application.

Return:

0 on success, non-zero on failure.

int (*detach)(void)

Callback invoked when a device is detached. Used to report the disconnection status to the application.

Return:

0 on success, non-zero on failure.

int (*setup)(void)

Callback invoked when the host setup phase is complete. Indicates that the host is ready for data transfer.

Return:

0 on success, non-zero on failure.

int (*bulk_received)(u8 *buf, u32 len)

Callback invoked when a bulk IN data transfer (Receive) is complete.

Param buf:

[in] Pointer to the buffer containing received data.

Param len:

[in] Length of the valid received data in bytes.

Return:

0 on success, non-zero on failure.

struct usbh_cdc_ecm_pipe_info_t

#include <usbh_cdc_ecm.h>

Public Members

usbh_ep_desc_t ep_desc

Endpoint descriptor.

usbh_pipe_t pipe

USB Host pipe handle.

u8 *buf

Malloc buffer for RX data.

u32 buf_len

Length of the RX buffer.

u32 busy_tick

Timestamp for busy detection.

u8 valid

Validity flag for this pipe info.

Host Core Types

enum usbh_ep_xfer_state_t

Defines the transfer states for an endpoint's pipe.

Values:

enumerator USBH_EP_XFER_IDLE

The endpoint is idle and ready for a new transfer.

enumerator USBH_EP_XFER_WAIT_SOF

For periodic transfers, waiting for the correct SOF interval. Check interval in SOF callback.

enumerator USBH_EP_XFER_START

A new transfer is starting.

enumerator USBH_EP_XFER_BUSY

The endpoint is currently busy with a transfer.

enumerator USBH_EP_XFER_ERROR

An error occurred during the last transfer.

enumerator USBH_EP_XFER_STATE_MAX

Sentinel value for state validation.

enum usbh_state_t

Defines the connection states of the USB host.

Values:

enumerator USBH_STATE_IDLE

The host is idle.

enumerator USBH_STATE_DETACHED

A device has been detached.

enumerator USBH_STATE_ATTACH

A device has been attached and is being enumerated.

enumerator USBH_STATE_SETUP

The device is in the setup/configured phase.

enumerator USBH_STATE_MAX

Sentinel value for state validation.

enum usbh_urb_state_t

Defines the states of a USB Request Block (URB).

Values:

enumerator USBH_URB_IDLE

The URB is idle, no transfer is active.

enumerator USBH_URB_DONE

The URB has completed successfully.

enumerator USBH_URB_BUSY

The URB is currently being processed.

enumerator USBH_URB_ERROR

The URB completed with an error.

enumerator USBH_URB_STALL

The URB resulted in a STALL condition.

enum usbh_msg_t

Defines message types for user process callbacks of usbh_user_cb_t.

Values:

enumerator USBH_MSG_USER_SET_CONFIG

Message to request user to set the configuration.

enumerator USBH_MSG_CONNECTED

Message indicating a device has been successfully connected and configured.

enumerator USBH_MSG_DISCONNECTED

Message indicating a device has been disconnected.

enumerator USBH_MSG_PROBE_FAIL

Message indicating that device probing failed due to mismatched device properties.

enumerator USBH_MSG_ATTACH_FAIL

Message indicating device attachment failed.

enumerator USBH_MSG_ERROR

Message indicating a general error occurred.

enum usbh_tick_source_t

Defines the source for the USB host tick counter.

Values:

enumerator USBH_SW_TICK

Use a software-based timer (e.g., system timestamp) as the tick source. It does not require responding to additional interrupts, resulting in lower CPU usage. However, there may be deviations from SOF counting. Suitable for applications with low CPU usage requirements or when timing accuracy does not need to match SOF counting precision.

enumerator USBH_SOF_TICK

Use the SOF (Start-of-Frame) interrupt as the tick source. Since it needs to periodically respond to SOF interrupts, CPU usage is higher, but timing accuracy matches SOF counting precision.

enumerator USBH_TICK_ERROR

typedef struct _usbh_itf_data_t usbh_itf_data_t

A structure to hold information about all alternate settings for a single interface number.

This forms a linked list where each node represents a unique interface number. Inside each node, it points to another linked list (itf_desc_array) of all alternate settings for that interface.

typedef struct _usb_host_t usb_host_t

USB host.

struct usbh_desc_header_t

#include <usbh.h>

Generic USB descriptor header.

All standard USB descriptors start with these two fields.

Public Members

u8 bLength

Size of this descriptor in bytes.

u8 bDescriptorType

Descriptor type.

struct usbh_dev_desc_t

#include <usbh.h>

USB standard device descriptor structure.

Public Members

u8 bLength

Size of this descriptor in bytes.

u8 bDescriptorType

DEVICE Descriptor Type.

u16 bcdUSB

USB specification version number (e.g., 0x0200 for USB 2.0).

u8 bDeviceClass

Class code (assigned by the USB-IF).

u8 bDeviceSubClass

Subclass code (assigned by the USB-IF).

u8 bDeviceProtocol

Protocol code (assigned by the USB-IF). If equal to 0, each interface specifies its own class code if equal to 0xFF, the class code is vendor specified. Otherwise field is valid class code.

u8 bMaxPacketSize

Maximum packet size for endpoint zero (only 8, 16, 32, or 64 are valid).

u16 idVendor

Vendor ID (assigned by the USB-IF).

u16 idProduct

Product ID (assigned by the manufacturer).

u16 bcdDevice

Device release number in BCD format.

u8 iManufacturer

Index of string descriptor describing manufacturer.

u8 iProduct

Index of string descriptor describing product.

u8 iSerialNumber

Index of string descriptor for the serial number.

u8 bNumConfigurations

Number of possible configurations.

struct usbh_dev_bos_t

#include <usbh.h>

USB standard Binary Device Object Store (BOS) descriptor structure.

Public Members

u8 bLength

Size of this descriptor in bytes.

u8 bDescriptorType

BOS Descriptor Type.

u16 wTotalLength

Total length of the BOS descriptor and all its sub-descriptors.

u8 bNumDeviceCaps

The number of device capability descriptors in the BOS.

struct usbh_ep_desc_t

#include <usbh.h>

USB standard endpoint descriptor structure.

Public Members

u8 bLength

Size of this descriptor in bytes.

u8 bDescriptorType

ENDPOINT Descriptor Type.

u8 bEndpointAddress

The address of the endpoint on the USB device.

u8 bmAttributes

Endpoint attributes (transfer type, etc.).

u16 wMaxPacketSize

Maximum packet size this endpoint is capable of sending or receiving.

u8 bInterval

Interval for polling endpoint for data transfers.

struct usbh_itf_desc_t

#include <usbh.h>

USB standard interface descriptor structure.

Public Members

u8 bLength

Size of this descriptor in bytes.

u8 bDescriptorType

INTERFACE Descriptor Type.

u8 bInterfaceNumber

Number of this interface.

u8 bAlternateSetting

Value used to select this alternate setting.

u8 bNumEndpoints

Number of endpoints used by this interface (excluding endpoint zero).

u8 bInterfaceClass

Class code (assigned by the USB-IF).

u8 bInterfaceSubClass

Subclass code (assigned by the USB-IF).

u8 bInterfaceProtocol

Protocol code (assigned by the USB-IF).

u8 iInterface

Index of string descriptor describing this interface.

usbh_ep_desc_t *ep_desc_array

Endpoint descriptors

struct _usbh_itf_data_t

#include <usbh.h>

A structure to hold information about all alternate settings for a single interface number.

This forms a linked list where each node represents a unique interface number. Inside each node, it points to another linked list (itf_desc_array) of all alternate settings for that interface.

Public Members

struct _usbh_itf_data_t *next

Pointer to the next info structure for a different interface number but has the same class/subclass/protocol.

usbh_itf_desc_t *itf_desc_array

Pointer to a linked list of all alternate settings for this interface number (bAlternateSetting 0, 1, 2...).

u8 *raw_data

Pointer to the start of the raw interface descriptor data for class-specific parsing.

u32 raw_data_len

The total length of the entire interface descriptor in bytes.

u8 alt_setting_cnt

Count of alternate settings for this interface number.

struct usbh_cfg_desc_t

#include <usbh.h>

USB configuration descriptor.

Public Members

u8 bLength

Size of this descriptor in bytes.

u8 bDescriptorType

CONFIGURATION Descriptor Type.

u16 wTotalLength

Total length of data returned for this configuration.

u8 bNumInterfaces

The number of interfaces supported by this configuration.

u8 bConfigurationValue

Value to use as an argument to select this configuration.

u8 iConfiguration

Index of string descriptor describing this configuration.

u8 bmAttributes

Configuration characteristics (D7:Bus Powered, D6:Self Powered, D5:Remote Wakeup, D4..0 Reserved (0)).

u8 bMaxPower

Maximum power consumption of the device from the bus in 2mA units.

usbh_itf_data_t *itf_data_array

Save all interfaces info in this struct, total count is defined by bNumInterfaces, each interface is indentified by bInterfaceNumber: 0/1/2...

struct usbh_hub_desc_t

#include <usbh.h>

USB standard hub descriptor structure. (USB 2.0 Spec, 11.23.2.1).

Public Members

u8 bLength

Size of this descriptor in bytes.

u8 bDescriptorType

HUB Descriptor Type.

u8 bNbrPorts

Number of downstream ports that this hub supports.

u16 wHubCharacteristics

Hub characteristics (power switching, over-current protection, etc.). D1...D0: Logical Power Switching Mode D2: Identifies a Compound Device D4...D3: Over-current Protection Mode D6...D5: TT Think TIme D7: Port Indicators Supported D15...D8: Reserved

u8 bPwrOn2PwrGood

Time (in 2ms intervals) from when power is turned on to when power is good.

u8 bHubContrCurrent

Maximum current requirements of the hub controller in mA. add 1 bit for hub status change; round to bytes

u8 DeviceRemovable[(USBH_MAX_HUB_PORT + 1 + 7) / 8]

Indicates if a port has a removable device attached. Bit 0: Reserved for future use. Bit 1: Port 1 Bit n: Port n (implementation-dependent, up to a maximum of 255 ports).

u8 PortPwrCtrlMask[(USBH_MAX_HUB_PORT + 1 + 7) / 8]

Port power control mask (obsolete). This field exists for reasons of compatibility with software written for 1.0 compliant devices. All bits in this field should be set to 1B. This field has one bit for each port on the hub with additional pad bits, if necessary, to make the number of bits in the field an integer multiple of 8.

union usbh_setup_req_t

#include <usbh.h>

Union for a standard USB setup request packet.

Public Members

u32 d32[2]

64-bit access to the setup packet data.

usb_setup_req_t req

Access as a structured setup request.

struct usbh_event_msg_t

#include <usbh.h>

Packed structure for a USB event message.

Public Members

u16 tick

Tick count when the event occurred.

u8 pipe_num

Pipe number associated with the event.

u8 type

Message type, corresponds to usbh_event_type_t.

u8 owner

Owner of the message (e.g., core, class).

union usbh_event_t

#include <usbh.h>

Union for a USB event.

Public Members

u32 d32

32-bit access to the event data.

usbh_event_msg_t msg

Access as a structured event message.

struct usbh_config_t

#include <usbh.h>

USB host user configuration structure.

Public Members

u32 ext_intr_enable

Allows class drivers to enable optional interrupts, (e.g., USBH_SOF_INTR is used for host class driver to handle timing issues in SOF callback).

u16 rx_fifo_depth

RxFIFO depth in dwords (Dedicated FIFO only). Min value 16 and max value restricted by SoC hardware.

u16 nptx_fifo_depth

Non-periodic TxFIFO depth in dwords (Dedicated FIFO only). Min value 16 and max value restricted by SoC hardware.

u16 ptx_fifo_depth

Periodic TxFIFO depth in dwords (Dedicated FIFO only). Min value 16 and max value restricted by SoC hardware.

u8 isr_priority

USB ISR priority.

u8 isr_in_critical

Flag to process USB ISR within a critical section (0: Disable, 1: Enable).

u8 main_task_priority

USB main task priority, the main task processes the USB host messages.

u8 speed

USB speed mode. See usb_speed_type_t.

• USB_SPEED_HIGH: USB 2.0 High-Speed mode(for HS-capable SoCs).

• USB_SPEED_HIGH_IN_FULL: USB 2.0 PHY operating in Full-Speed mode(for HS-capable SoCs with low bandwidth applcations like UAC).

• USB_SPEED_FULL: USB 1.1 Full-Speed mode(for FS-only SoCs).

u8 tick_source

Tick source for getting the usb host tick of USB host core driver, see usbh_tick_source_t. Which is used to trigger periodic transfers based on the endpoint interval and to detect transfer timeouts.

u8 xfer_retry_max_cnt

Maximum number of retries for a failed transfer.

u8 hub_support

Support 1-level HUB (0: Disable, 1: Enable).

u8 tp_trace

Enable/disable tracing for transfer performance.

struct usbh_pipe_t

#include <usbh.h>

USB pipe structure for managing data transfers to/from an endpoint.

Public Members

u8 *xfer_buf

Pointer to the transfer buffer.

u32 xfer_len

Total length of the data to transfer.

u32 frame_num

Frame number for the transfer (from HFNUM register, max 0x3FFF).

u32 tick

Host tick count at the start of the transfer (based on SOF or timestamp).

u16 max_timeout_tick

Maximum wait timeout in ticks for this transfer.

u16 ep_interval

Endpoint polling interval in ticks.

u16 ep_mps

Endpoint Maximum Packet Size (0-64KB).

u8 ep_trans

Number of transactions per microframe (1-3, for HS isochronous).

u8 ep_is_in

Endpoint direction: 1 for IN, 0 for OUT.

u8 ep_addr

Endpoint address (including direction bit).

u8 ep_type

Endpoint type, USB_CH_EP_TYPE_XXX (Control, Bulk, Interrupt, Isochronous).

u8 pipe_num

Host pipe/channel number assigned to this endpoint.

u8 xfer_state

Current transfer state. See usbh_ep_xfer_state_t.

u8 trx_zlp

Flag to indicate if a Zero-Length Packet is required, only for BULK xfer with xfer_len is N*mps.

u8 retry_cnt

Current retry count for the transfer.

struct usbh_dev_id_t

#include <usbh.h>

Structure for defining device/interface properties to match against.

This is used by class drivers to identify supported devices.

Public Members

u16 mMatchFlags

u16 idVendor

u16 idProduct

u8 bDeviceClass

u8 bDeviceSubClass

u8 bDeviceProtocol

u8 bInterfaceClass

u8 bInterfaceSubClass

u8 bInterfaceProtocol

struct usbh_class_driver_t

#include <usbh.h>

Structure defining the interface for a USB class driver.

Public Members

const usbh_dev_id_t *id_table

A table of device IDs that this driver supports.

int (*attach)(struct _usb_host_t *host)

Called after SET_CONFIGURATION request when a supported device is attached.

Param host:

[in] USB host.

Return:

0 on success, non-zero on failure.

int (*detach)(struct _usb_host_t *host)

Called when a supported device is detached.

Param host:

[in] USB host.

Return:

0 on success, non-zero on failure.

int (*setup)(struct _usb_host_t *host)

Called after attach to handle class-specific standard control requests.

Param host:

[in] USB host.

Return:

0 on success, non-zero on failure.

int (*process)(struct _usb_host_t *host, u32 msg)

Main processing loop for the class driver after class setup to process class-specific transfers.

Param host:

[in] USB host.

Param msg:

[in] usbh_msg_t.

Return:

0 on success, non-zero on failure.

int (*sof)(struct _usb_host_t *host)

Called at each Start-of-Frame (SOF) interrupt for class-specific timing process.

Param host:

[in] USB host.

Return:

0 on success, non-zero on failure.

int (*completed)(struct _usb_host_t *host, u8 pipe)

Called when a transfer on a specific pipe completes.

Param host:

[in] USB host.

Param pipe:

[in] Pipe number.

Return:

0 on success, non-zero on failure.

struct usbh_user_cb_t

#include <usbh.h>

Structure defining user-level callbacks.

Public Members

int (*process)(struct _usb_host_t *host, u8 msg)

Callback to handle class-independent events in the application.

Param host:

[in] USB host.

Param msg:

[in] usbh_msg_t.

Return:

0 on success, non-zero on failure.

int (*validate)(struct _usb_host_t *host, u8 cfg_max)

Callback to validate a device when multiple devices are connected to a hub.

备注

The class can get all the config descriptor and check the interface class. if find the device, return HAL_OK, the enum process will use this device as the target device, else return !HAL_OK, the enum process will discard this device, and switch to check next hub port.

Param host:

[in] USB host.

Param cfg_max:

[in] bNumConfigurations.

Return:

0 on success, non-zero on failure.

struct _usb_host_t

#include <usbh.h>

USB host.

ISR Time Tracing

These fields are used for debugging time-sensitive transfers (like isochronous for audio applications) by measuring the execution time of the interrupt handler. Enabled by tp_trace in usbh_config_t.

• if the isr_process_time is relatively large, check whether the callback of the class has taken a long time.

• if the isr_enter_period is relatively large, check whether there is an operation to mask interrupts in the class.

u64 isr_enter_time

[Debug] Record the timestamp of interrupt handler entry.

u64 isr_enter_period

[Debug] The interval between two consecutive interrupt processing.

u64 isr_enter_period_max

[Debug] The maximum value of the interval between two consecutive interrupt processing.

u64 isr_process_time

[Debug] Time consumption for a complete interrupt handler processing.

u64 isr_process_time_max

[Debug] The maximum time recorded for a complete interrupt handler processing

Public Members

const usbh_dev_id_t *dev_id

Pointer to the active device ID.

usbh_dev_desc_t *dev_desc

Pointer to the device's descriptor.

usbh_user_cb_t *cb

Pointer to the user-provided callbacks.

void *core

Pointer for USB host core.

u8 dev_addr

The address of the attached device.

u8 dev_speed

The speed of the attached device.

u8 connect_state

The current connection state. See usbh_state_t.

Host MSC Types

struct usbh_msc_cb_t

#include <usbh_msc.h>

MSC user callback structure.

This structure allows the user application to register callbacks for key MSC events like device attachment and detachment.

Public Members

int (*attach)(void)

Called when device attached, used to report device connection status.

Return:

0 on success, non-zero on failure.

int (*detach)(void)

Called when device detached, used to report device disconnection status.

Return:

0 on success, non-zero on failure.

int (*setup)(void)

Called when device setup done, used to indicate that device is ready for bulk transfer.

Return:

0 on success, non-zero on failure.

Host UAC Types

struct usbh_uac_term_info

#include <usbh_uac1.h>

UAC 1.0 Audio Terminal Information structure. Describes an Input Terminal or Output Terminal in the audio function topology.

Public Members

u16 terminal_type

Terminal Type (e.g., 0x0101 USB Streaming, 0x0301 Speaker)

u8 terminal_id

ID of this Terminal

u8 source_id

ID of the entity to which this Terminal is connected

u8 is_input

Direction flag (1: Input Terminal, 0: Output Terminal)

struct usbh_uac_vol_ctrl_info

#include <usbh_uac1.h>

UAC 1.0 Feature Unit (Volume Control) Information structure.

Public Members

u16 channel_support[USBH_UAC_MAX_CHANNEL]

Bitmap of supported controls for each logical channel

u16 master_support

Bitmap of supported controls for the Master Channel (Channel 0)

u16 sink_type

Type of the sink terminal connected to this unit

u8 unit_id

ID of this Feature Unit

u8 source_id

ID of the source entity connected to this unit

u8 sink_id

ID of the sink entity connected to this unit

u8 num_channels

Number of logical audio channels

u8 control_size

Size of the control field in bytes (usually 1 or 2)

struct usbh_uac_ac_itf_info_t

#include <usbh_uac1.h>

Audio Control (AC) Interface Aggregated Information. Contains the topology of all Terminals and Units within the AC interface.

Public Members

usbh_uac_vol_ctrl_info controls[USBH_UAC_FU_MAX_CNT]

Array of Feature Units found

usbh_uac_term_info terminals[USBH_UAC_TERM_MAX_CNT]

Array of Terminals found

u32 volume_ctrl_count

Count of valid Feature Units

u32 terminal_count

Count of valid Terminals

u8 best_match_idx

Index of the best matching Feature Unit (for main volume control)

u8 ac_itf_idx

Interface index of the Audio Control interface

struct usbh_uac_buf_ctrl_t

#include <usbh_uac1.h>

Audio Buffer and Transmission Control Block. Manages ring buffers, synchronization, and isochronous packet sizing.

Public Members

usb_ringbuf_manager_t buf_manager

Ring buffer manager instance

rtos_sema_t isoc_sema

Semaphore for isochronous transfer synchronization

u32 sample_freq

Current sampling frequency (Hz, e.g., 48000)

u32 sample_rem

Remainder when dividing frequency by packets/sec (for fractional sample rates)

u32 sample_accum

Accumulator for fractional sample rate calculation

u32 last_sample_accum

Previous accumulator value

u32 pkt_per_second

Number of USB packets per second (e.g., 1000 for Full Speed)

u16 frame_cnt

Number of frames configured for the buffer

u16 written

Length of data already written to the current packet buffer

u16 mps

Endpoint Maximum Packet Size

u8 sema_valid

Flag indicating if the semaphore is valid

u8 write_wait_sema

Flag indicating if a write operation is waiting for the semaphore

u8 next_xfer

Flag to trigger the next transfer

struct usbh_uac_volume_info_t

#include <usbh_uac1.h>

Audio Volume Status Information.

Public Members

s16 volume

Current volume value (resolution depends on device, usually 1/256 dB)

s16 vol_min

Minimum volume supported by the device

s16 vol_max

Maximum volume supported by the device

u8 mute

Current mute state (1: Muted, 0: Unmuted)

struct usbh_uac_cb_t

#include <usbh_uac1.h>

UAC User Callback Interface.

Public Members

int (*init)(void)

Callback when UAC driver is initialized

int (*deinit)(void)

Callback when UAC driver is de-initialized

int (*attach)(void)

Callback when a UAC device is attached

int (*detach)(void)

Callback when a UAC device is detached

int (*setup)(void)

Callback during the Setup stage of a control transfer

int (*isoc_transmitted)(usbh_urb_state_t state)

Callback when isochronous OUT (Play) transfer completes

int (*isoc_received)(u8 *buf, u32 len)

Callback when isochronous IN (Record) data is received

struct usbh_uac_format_cfg_t

#include <usbh_uac1.h>

Audio Format Configuration Descriptor Information.

Public Members

u8 freq[USBH_UAC_FREQ_FORMAT_MAX][3]

List of supported sampling frequencies (3-byte format)

u8 bit_width

Bit resolution (e.g., 16, 24, 32 bits)

u8 channels

Number of channels

u8 freq_cnt

Count of supported sampling frequencies

struct usbh_uac_as_itf_alt_info_t

#include <usbh_uac1.h>

Audio Streaming (AS) Interface Alternate Setting Information.

Public Members

usbh_uac_format_cfg_t format_info

Audio format details for this setting

usbh_ep_desc_t ep_desc

Associated endpoint descriptor

u8 alt_setting

USB Alternate Setting number

struct usbh_audio_fmt_t

#include <usbh_uac1.h>

Generic Audio Format Structure (Used for API interaction).

Public Members

u32 sampling_freq

Sampling frequency in Hz

u8 bit_width

Bit depth

u8 ch_cnt

Channel count

struct usbh_uac_as_itf_info_t

#include <usbh_uac1.h>

Audio Streaming (AS) Interface Aggregated Information. Manages all Alternate Settings and formats for a specific AS interface.

Public Members

usbh_uac_as_itf_alt_info_t itf_info_array[USBH_UAC_ALT_SETTING_MAX]

Stores valid alternate settings (skipping Alt 0 which usually has 0 bandwidth)

usbh_pipe_t pipe

USB Pipe information associated with this interface

usbh_audio_fmt_t *fmt_array

Array of all parsed audio formats

u16 packet_size_small

Size of a small packet in samples (for non-integer freq ratios)

u16 packet_size_large

Size of a large packet in samples

u8 as_itf_num

Interface number of this AS interface

u8 alt_setting_cnt

Count of Alternate Settings available

u8 fmt_array_cnt

Count of items in fmt_array

u8 choose_alt_idx

Index of the currently selected setting in the internal array

u8 choose_freq_idx

Index of the currently selected frequency

Host UVC Types

enum usbh_uvc_streaming_state_t

UVC Streaming State.

Values:

enumerator STREAMING_OFF

Streaming is currently stopped.

enumerator STREAMING_ON

Streaming is active.

enum usbh_uvc_stream_data_state_t

UVC Stream Data Transfer State.

Values:

enumerator STREAM_STATE_IDLE

Idle state, no data transfer.

enumerator STREAM_DATA_IN

Data IN transfer state.

enum usbh_uvc_frame_state_t

UVC Frame Buffer State.

Values:

enumerator UVC_FRAME_INIT

Frame buffer initialized / empty.

enumerator UVC_FRAME_FLYING

Frame is being filled (memcpying/receiving).

enumerator UVC_FRAME_READY

Frame is complete and ready to commit to application.

enumerator UVC_FRAME_INUSE

Frame is currently held by the application.

struct usbh_uvc_s_ctx_t

#include <usbh_uvc_intf.h>

UVC Stream Context / Parameters.

Public Members

int fmt_type

Video format type (e.g., USBH_UVC_FORMAT_MJPEG).

int width

Video frame width in pixels.

int height

Video frame height in pixels.

int frame_rate

Video frame rate (fps).

u32 frame_buf_size

Size of a single video frame buffer in bytes.

struct usbh_uvc_ctx_t

#include <usbh_uvc_intf.h>

UVC Global Context.

struct usbh_uvc_cb_t

#include <usbh_uvc_intf.h>

UVC Host User Callback Interface.

Public Members

int (*init)(void)

Callback invoked during UVC driver initialization. Used for application-specific resource setup.

Return:

0 on success, non-zero on failure.

int (*deinit)(void)

Callback invoked during UVC driver de-initialization. Used for application-specific resource cleanup.

Return:

0 on success, non-zero on failure.

int (*attach)(void)

Callback invoked when a UVC device is attached.

Return:

0 on success, non-zero on failure.

int (*detach)(void)

Callback invoked when a UVC device is detached.

Return:

0 on success, non-zero on failure.

int (*setup)(void)

Callback invoked when the device setup phase is complete.

Return:

0 on success, non-zero on failure.

int (*setparam)(void)

Callback invoked when parameters need to be set/negotiated.

Return:

0 on success, non-zero on failure.

struct usbh_uvc_frame_t

#include <usbh_uvc_intf.h>

UVC Video Frame Structure. Represents a single video frame node in the queue.

Public Members

struct list_head list

Linked list node for queue management.

u8 *buf

Pointer to the data buffer containing the frame.

u32 index

Index of the frame in the pool.

u32 byteused

Actual number of bytes used in the buffer (frame size).

u32 err

Error flags associated with this frame.

u32 timestamp

Presentation timestamp of the frame.

usbh_uvc_frame_state_t state

Current state of this frame buffer.

Host Vendor Types

enum usbh_vendor_state_t

States for Vendor State Machine.

Values:

enumerator VENDOR_STATE_IDLE

Idle state

enumerator VENDOR_STATE_XFER

Data transfer start state

enumerator VENDOR_STATE_BUSY

Data transfer busy state

enumerator VENDOR_STATE_ERROR

Error state

struct usbh_vendor_cb_t

#include <usbh_vendor.h>

Vendor user callback interface structure.

Public Members

int (*init)(void)

Called when the host driver initialization.

Return:

0 on success, non-zero on failure.

int (*deinit)(void)

Called when the host driver de-initialization.

Return:

0 on success, non-zero on failure.

int (*attach)(void)

Called when device attached, used to report device connection status.

Return:

0 on success, non-zero on failure.

int (*detach)(void)

CCalled when device detached, used to report device disconnection status.

Return:

0 on success, non-zero on failure.

int (*setup)(void)

Called when device setup done, used to indicate that device is ready for data transfer.

Return:

0 on success, non-zero on failure.

int (*receive)(u8 ep_type, u8 *buf, u32 len, int status)

Called when IN transfer is completed, used for application to handle the received IN data.

Param ep_type:

Endpoint type (BULK/INTR/ISOC).

Param buf:

Pointer to the received data buffer.

Param len:

Length of received data in bytes.

Param status:

[in] The status of the transfer(0 for success)..

Return:

0 on success, non-zero on failure.

int (*transmit)(u8 ep_type)

Called when OUT transfer is completed, used to report OUT transfer completion status.

Param ep_type:

Endpoint type(BULK/INTR/ISOC)..

Return:

0 on success, non-zero on failure.

struct usbh_vendor_xfer_t

#include <usbh_vendor.h>

Vendor transfer control structure.

Public Members

usbh_pipe_t pipe

USB Host pipe handle

u8 *xfer_bk_buf

Backup pointer to the original user buffer

u8 *test_buf

Buffer for verification/testing

u32 test_mask

Bitmask to identify the active transfer

u32 xfer_max_len

Max length of a single transfer

u32 cur_frame

Current frame number (for ISOC synchronization)

u8 xfer_cnt

Current transfer count (for test loops)

u8 xfer_max_cnt

Target transfer count (for test loops)

struct usbh_vendor_host_t

#include <usbh_vendor.h>

Vendor Host Class Structure.

Public Members

usbh_vendor_xfer_t bulk_in_xfer

Bulk IN transfer handle

usbh_vendor_xfer_t bulk_out_xfer

Bulk OUT transfer handle

usbh_vendor_xfer_t intr_in_xfer

Interrupt IN transfer handle

usbh_vendor_xfer_t intr_out_xfer

Interrupt OUT transfer handle

usbh_vendor_xfer_t isoc_in_xfer

Isochronous IN transfer handle

usbh_vendor_xfer_t isoc_out_xfer

Isochronous OUT transfer handle

usbh_vendor_cb_t *cb

Pointer to user callback structure

usb_host_t *host

Pointer to USB Host core handle

usbh_vendor_state_t state

Current class state machine state

u8 *ctrl_buf

Buffer for control transfer

u32 ep_mask

Active endpoint mask