USB Common API

USB Common Functions

USB App Functions

static inline int usb_app_ctx_begin(usb_app_ctx_t *ctx)

Move an idle app to RUNNING and create its join semaphore.

备注

Not atomic: the caller serializes every start of an app, as the USB app manager thread and a standalone example entry do

参数:

ctx -- App lifecycle state

返回值:

RTK_SUCCESS, -RTK_ERR_BUSY -- if the app is not idle, or the semaphore error

static inline u8 usb_app_ctx_claim_stop(usb_app_ctx_t *ctx)

Claim the right to tear the app down.

备注

Called by the stop entry and by a worker that found the stack dead. Exactly one of them wins; the loser must not free anything.

参数:

ctx -- App lifecycle state

返回值:

1 -- if the caller owns the teardown, 0 otherwise

static inline int usb_app_ctx_join(usb_app_ctx_t *ctx, u32 count)

Wait for workers to leave.

参数:
  • ctx -- App lifecycle state

  • count -- Number of workers to join

返回值:

RTK_SUCCESS, or -- -RTK_ERR_TIMEOUT if one did not leave in time

static inline void usb_app_ctx_leave(usb_app_ctx_t *ctx)

Called by a worker as the last thing before it deletes itself.

参数:

ctx -- App lifecycle state

返回值:

None --

static inline void usb_app_ctx_end(usb_app_ctx_t *ctx)

Finish a teardown: free the join semaphore and go back to IDLE.

参数:

ctx -- App lifecycle state

返回值:

None --

static inline int usb_app_ctx_wait_idle(usb_app_ctx_t *ctx)

Stop entry for an app that is not the teardown owner.

备注

A worker owning a teardown (dead stack) finishes it on its own; wait for that.

参数:

ctx -- App lifecycle state

返回值:

RTK_SUCCESS -- once idle, -RTK_ERR_TIMEOUT if the owner did not finish in time

USB Common Misc Functions

Helpers for the shared USB definitions

static inline u32 usb_get_dword_aligned_mps(u32 mps)

Get the per-packet stride of an OUT transfer, adjusted to the DWORD boundary.

备注

DWC OTG Programming Guide, Application Requirements of the OUT data transfers: the transfer size programmed into DOEPTSIZn.XferSize shall be a multiple of the MPS adjusted to the DWORD boundary, because in DMA mode the controller always starts a received packet on a DWORD boundary and pads a max-packet-size packet up to the end of the DWORD. if ((mps mod 4) == 0) stride = mps else stride = mps + 4 - (mps mod 4)

参数:

mps -- Max packet size of the endpoint, in bytes

返回值:

Per-packet -- stride in bytes

static inline u32 usb_get_dma_len(u32 xfer_len, u32 mps)

Get the DMA window length of an OUT transfer.

备注

The controller receives whole packets only, so it is programmed with XFRSIZ = usb_get_dword_aligned_mps(MPS) * PKTCNT, refer to usbd_hal_ep_start_transfer. The RX buffer shall be able to hold this length, and the cache maintenance before the transfer shall cover it.

参数:
  • xfer_len -- Requested transfer length, in bytes

  • mps -- Max packet size of the endpoint, in bytes

返回值:

DMA -- window length in bytes, xfer_len if mps is invalid

static inline u32 usb_get_max_payload_len(u32 buf_len, u32 mps)

Get the largest OUT transfer length whose DMA window still fits in a given buffer.

备注

This is the inverse of usb_get_dma_len: it answers how long a transfer may be requested before the window the core derives from it overflows the buffer. Solving usb_get_dma_len(len, mps) <= buf_len gives n = buf_len / usb_get_dword_aligned_mps(mps) whole packet slots that fit len = n * mps payload carried by those n packets The divisor is the DWORD adjusted MPS because that is what a packet costs in memory, while the multiplier is the raw MPS because that is what a packet carries on the wire. Bounding the payload by buf_len instead is NOT enough: one extra payload byte costs a whole extra padded packet, e.g. with MPS 1023 and a 1024 byte buffer a 1024 byte request needs 2 packets, so a 2048 byte window.

参数:
  • buf_len -- Capacity of the transfer buffer, in bytes

  • mps -- Max packet size of the endpoint, in bytes

返回值:

Largest -- requestable transfer length in bytes, 0 if the buffer cannot hold one packet, buf_len if mps is invalid

USB Diag Functions

ISR-side recording entry point of the USB diagnostics facility

void usb_diag(usb_diag_layer_t layer, usb_diag_event_t event, u8 id)

Record a USB diagnostic event into the diag ring buffer.

警告

For internal use inside USB interrupt handlers ONLY. It exists to capture diagnostic events from ISR context without printing there. Do NOT call it from task/thread context or any other code path: the ring buffer write is a non-atomic read-modify-write on a shared index, with no locking (locking is intentionally avoided to keep ISR latency minimal). A caller racing with the USB ISR writer will corrupt the buffer state. Use it exclusively within the USB ISR.

参数:
USB_DIAG(layer, event, id)

Record a USB diagnostics event, compiled out when the OS is absent.

USB OS Functions

Memory, lock, semaphore, queue and timing wrappers of the USB OS abstraction

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_mem_sync(void)

Issues a full memory barrier.

Every memory access before the call completes before any access after it, as seen by other cores and bus masters. Use it to publish data shared between task and ISR contexts that may run on different SMP cores.

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

Enters the USB critical section (disables interrupts, and takes the USB spinlock under SMP).

备注

Usable in task and ISR context. Nests on the same core: calling it again while already inside, e.g. from a class callback of an ISR running with isr_in_critical, only counts the nesting.

返回:

0 on success, non-zero on failure

int usb_os_exit_critical(void)

Exits the USB critical section, restoring interrupts on the outermost level only.

返回:

0 on success, non-zero on failure

u8 usb_os_is_in_interrupt(void)

Tells whether the caller runs in interrupt context.

返回:

1 in interrupt context, 0 in task context.

void usb_os_atomic_inc(volatile u32 *cnt)

Atomically increments a counter shared across cores and contexts.

备注

Lock free and usable from any context, without the interrupt latency of usb_os_enter_critical(). Full barrier on both sides.

参数:

cnt -- [inout] Counter to increment.

void usb_os_atomic_dec(volatile u32 *cnt)

Atomically decrements a counter shared across cores and contexts.

备注

See usb_os_atomic_inc().

参数:

cnt -- [inout] Counter to decrement.

u32 usb_os_atomic_load(volatile const u32 *cnt)

Atomically reads a counter shared across cores and contexts.

备注

Full barrier: the stores the other core made before its last update are visible.

参数:

cnt -- [in] Counter to read.

返回:

Current value.

int usb_os_sema_create(usb_os_sema_t *sema)

Creates a new binary semaphore, initially empty.

参数:

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

返回:

0 on success, non-zero on failure

int usb_os_sema_create_with_count(usb_os_sema_t *sema, u32 init_count, u32 max_count)

Creates a new counting semaphore.

The handle is released and used with the same calls as a binary semaphore: usb_os_sema_delete, usb_os_sema_take and usb_os_sema_give.

参数:
  • sema -- [out] Pointer to the semaphore handle to be created.

  • init_count -- [in] Initial count, no greater than max_count.

  • max_count -- [in] Maximum count, at least 1.

返回:

0 on success, -RTK_ERR_BADARG on invalid counts, -RTK_ERR_NOMEM if it cannot be created.

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 Ring Buffer Functions

Lifecycle and enqueue/dequeue operations of the block-based USB ring buffer

int usb_ringbuf_manager_init(usb_ringbuf_manager_t *handle, u8 count, u16 size, u8 cache_align)

Initializes the USB ring buffer manager.

Allocates necessary memory resources for the node metadata and the raw data buffer. It also resets the read/write indices.

参数:
  • handle -- [inout] Pointer to the manager structure to initialize.

  • count -- [in] Capacity of the ring buffer (number of discrete nodes).

  • size -- [in] Maximum size in bytes for each data node.

  • cache_align -- [in] Memory alignment requirement (in bytes). Useful for DMA or cache line alignment.

返回:

  • 0: Success.

  • Non-zero: Error (e.g., memory allocation failed).

int usb_ringbuf_manager_deinit(usb_ringbuf_manager_t *handle)

De-initializes the ring buffer manager.

Frees all allocated memory resources associated with the handle and resets internal states.

参数:

handle -- [inout] Pointer to the manager structure to de-initialize.

返回:

0 on success.

int usb_ringbuf_reset(usb_ringbuf_manager_t *handle)

Resets the ring buffer state.

Clears the buffer logically by resetting the head and tail pointers to zero. This function does not free memory; it simply discards all existing data.

参数:

handle -- [inout] Pointer to the manager structure.

返回:

0 on success.

u8 *usb_ringbuf_peek_head(usb_ringbuf_manager_t *handle, u32 *len)

Gets the head packet in place, without removing it.

Consumer side only. The returned node stays owned by the consumer, and the producer cannot overwrite it, until usb_ringbuf_pop_head() is called.

参数:
  • handle -- [in] Pointer to the manager structure.

  • len -- [out] Length of the packet, only valid when the return value is not NULL.

返回:

Pointer to the packet data, or NULL if the buffer is empty.

void usb_ringbuf_pop_head(usb_ringbuf_manager_t *handle)

Removes the head packet previously read by usb_ringbuf_peek_head().

Consumer side only.

参数:

handle -- [inout] Pointer to the manager structure.

void usb_ringbuf_drop_all(usb_ringbuf_manager_t *handle)

Discards every queued packet from the consumer side.

Unlike usb_ringbuf_reset(), only the head pointer is moved (to the tail), so it is safe against a producer concurrently calling usb_ringbuf_add_tail() on another core.

参数:

handle -- [inout] Pointer to the manager structure.

u8 usb_ringbuf_get_count(usb_ringbuf_manager_t *handle)

Retrieves the number of valid data nodes currently in the buffer.

参数:

handle -- [in] Pointer to the manager structure.

返回:

The count of occupied nodes waiting to be read.

int usb_ringbuf_is_empty(usb_ringbuf_manager_t *handle)

Checks if the ring buffer is empty.

参数:

handle -- [in] Pointer to the manager structure.

返回:

  • 1: Buffer is empty (Head == Tail).

  • 0: Buffer contains data.

int usb_ringbuf_is_full(usb_ringbuf_manager_t *handle)

Checks if the ring buffer is full.

参数:

handle -- [in] Pointer to the manager structure.

返回:

  • 1: Buffer is full.

  • 0: Buffer has space for new nodes.

int usb_ringbuf_add_tail(usb_ringbuf_manager_t *handle, const u8 *buf, u32 size, u8 valid)

Writes a data packet to the tail of the buffer.

Copies data from the source buffer into the current write slot (tail) and advances the tail pointer.

参数:
  • handle -- [inout] Pointer to the manager structure.

  • buf -- [in] Pointer to the source data to copy.

  • size -- [in] Length of the data to copy (must be <= node_size).

  • valid -- [in] Validity flag to set for this node (1 = Valid, 0 = Invalid).

返回:

  • 0: Success.

  • Non-zero: Error (e.g., buffer is full).

u32 usb_ringbuf_remove_head(usb_ringbuf_manager_t *handle, u8 *buffer, u32 size, u8 *valid)

Reads and removes a data packet from the head of the buffer.

Copies data from the current read slot (head) into the destination buffer and advances the head pointer.

参数:
  • handle -- [inout] Pointer to the manager structure.

  • buffer -- [out] Pointer to the destination buffer where data will be copied.

  • size -- [in] Maximum capacity of the destination buffer (safety check).

  • valid -- [out] Pointer to store the validity flag of the retrieved node (optional, can be NULL).

返回:

The actual number of bytes read/copied. Returns 0 if buffer was empty.

USB Common Constants

USB App Constants

Start/stop lifecycle of a switchable USB application, used by the usb_drd example

USB_APP_ROLE_DEVICE
USB_APP_ROLE_HOST
USB_APP_STATE_IDLE
USB_APP_STATE_RUNNING
USB_APP_STATE_STOPPING
USB_APP_JOIN_TIMEOUT_MS

USB CDC ACM Constants (PSTN 1.2)

Abstract Control Model definitions shared by the USBD and USBH CDC ACM drivers

USB_CDC_SUBCLASS_ACM

CDC Subclass Code: Abstract Control Model (ACM)

USB_CDC_CTRL_PROTOCOL_COMMON_AT_COMMAND

CDC Protocol Code: AT command

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_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 CDC Constants (CDC 1.2)

Communications Device Class definitions shared by the USBD and USBH CDC drivers

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_CTRL_PROTOCOL_NO_CLASS_SPECIFIC

CDC Protocol Code: No class specific protocol

USB_CDC_CTRL_PROTOCOL_VENDOR_SPECIFIC

CDC Protocol Code: Vendor specific

USB_CDC_DATA_PROTOCOL_NO_CLASS_SPECIFIC

CDC Data Protocol: No class specific protocol

USB_CDC_DATA_PROTOCOL_NETWORK_TRANSFER_BLOCK

CDC Data Protocol: Network Transfer Block

USB_CDC_CS_INTERFACE

Class-Specific Interface Descriptor Type

USB_CDC_CS_ENDPOINT

Class-Specific Endpoint Descriptor Type

USB_CDC_FUNC_DESC_HEADER

Header Functional Descriptor

USB_CDC_FUNC_DESC_CALL_MGMT

Call Management Functional Descriptor

USB_CDC_FUNC_DESC_UNION

Union Functional Descriptor

USB_CDC_FUNC_DESC_ETHERNET_NETWORKING

Ethernet Networking Functional Descriptor

USB_CDC_UNION_FUNC_DESC_MIN_SIZE

Union Functional Descriptor minimum size

USB_CDC_SET_ETHERNET_MULTICAST_FILTERS

Set Ethernet multicast address filters

USB_CDC_SET_ETHERNET_POWER_MANAGEMENT

Set device power management pattern filter

USB_CDC_GET_ETHERNET_POWER_MANAGEMENT

Get device power management pattern filter

USB_CDC_SET_ETHERNET_PACKET_FILTER

Set Ethernet packet filter bitmap

USB_CDC_GET_ETHERNET_STATISTIC

Retrieve Ethernet device statistics

USB_CDC_ETHERNET_STATISTIC_RESPONSE_LEN

GET_ETHERNET_STATISTIC response size

USB_CDC_ETHERNET_POWER_MANAGEMENT_RESPONSE_LEN

GET_ETHERNET_POWER_MANAGEMENT response size

USB_CDC_NOTIFY_NETWORK_CONNECTION

Network Connection Notification

USB_CDC_NOTIFY_RESPONSE_AVAILABLE

Response Available Notification

USB_CDC_NOTIFY_CONNECTION_SPEED_CHANGE

Connection Speed Change Notification

USB_CDC_NOTIFY_HDR_LEN
USB_CDC_CONNECTION_BITRATE_HS

High Speed: 480 Mbit/s

USB_CDC_CONNECTION_BITRATE_FS

Full Speed: 12 Mbit/s

USB CDC ECM Constants (ECM 1.2)

Ethernet Control Model definitions shared by the USBD and USBH CDC ECM drivers

USB_CDC_ECM_SUBCLASS_ECM

CDC Subclass Code: Ethernet Control Model (ECM)

USB_CDC_ECM_PACKET_TYPE_PROMISCUOUS

Promiscuous mode

USB_CDC_ECM_PACKET_TYPE_ALL_MULTICAST

All multicast packets

USB_CDC_ECM_PACKET_TYPE_DIRECTED

Directed packets

USB_CDC_ECM_PACKET_TYPE_BROADCAST

Broadcast packets

USB_CDC_ECM_PACKET_TYPE_MULTICAST

Filtered multicast packets

USB_CDC_ECM_STAT_XMIT_OK

Frames transmitted without errors

USB_CDC_ECM_STAT_RCV_OK

Frames received without errors

USB_CDC_ECM_STAT_XMIT_ERROR

Frames not transmitted due to errors

USB_CDC_ECM_STAT_RCV_ERROR

Frames received with errors

USB_CDC_ECM_STAT_RCV_NO_BUFFER

Frames missed due to no buffer

USB_CDC_ECM_STAT_DIRECTED_BYTES_XMIT

Directed bytes transmitted without errors

USB_CDC_ECM_STAT_DIRECTED_FRAMES_XMIT

Directed frames transmitted without errors

USB_CDC_ECM_STAT_MULTICAST_BYTES_XMIT

Multicast bytes transmitted without errors

USB_CDC_ECM_STAT_MULTICAST_FRAMES_XMIT

Multicast frames transmitted without errors

USB_CDC_ECM_STAT_BROADCAST_BYTES_XMIT

Broadcast bytes transmitted without errors

USB_CDC_ECM_STAT_BROADCAST_FRAMES_XMIT

Broadcast frames transmitted without errors

USB_CDC_ECM_STAT_DIRECTED_BYTES_RCV

Directed bytes received without errors

USB_CDC_ECM_STAT_DIRECTED_FRAMES_RCV

Directed frames received without errors

USB_CDC_ECM_STAT_MULTICAST_BYTES_RCV

Multicast bytes received without errors

USB_CDC_ECM_STAT_MULTICAST_FRAMES_RCV

Multicast frames received without errors

USB_CDC_ECM_STAT_BROADCAST_BYTES_RCV

Broadcast bytes received without errors

USB_CDC_ECM_STAT_BROADCAST_FRAMES_RCV

Broadcast frames received without errors

USB_CDC_ECM_STAT_RCV_CRC_ERROR

Frames received with CRC errors

USB_CDC_ECM_STAT_TRANSMIT_QUEUE_LENGTH

Length of transmit queue

USB_CDC_ECM_STAT_RCV_ERROR_ALIGNMENT

Frames received with alignment errors

USB_CDC_ECM_STAT_XMIT_ONE_COLLISION

Frames transmitted with one collision

USB_CDC_ECM_STAT_XMIT_MORE_COLLISIONS

Frames transmitted with more than one collision

USB_CDC_ECM_STAT_XMIT_DEFERRED

Frames transmitted after deferral

USB_CDC_ECM_STAT_XMIT_MAX_COLLISIONS

Frames not transmitted due to collisions

USB_CDC_ECM_STAT_RCV_OVERRUN

Frames not received due to overrun

USB_CDC_ECM_STAT_XMIT_UNDERRUN

Frames not transmitted due to underrun

USB_CDC_ECM_STAT_XMIT_HEARTBEAT_FAILURE

Frames transmitted with heartbeat failure

USB_CDC_ECM_STAT_XMIT_TIMES_CRS_LOST

Times carrier sense signal lost during transmission

USB_CDC_ECM_STAT_XMIT_LATE_COLLISIONS

Late collisions detected

USB_CDC_ECM_INTR_IN_PACKET_SIZE

Maximum packet size for Interrupt IN endpoint

USB_CDC_ECM_NETWORK_CONNECTION_SIZE

Network Connection notification size

USB_CDC_ECM_CONNECTION_SPEED_CHANGE_SIZE

Connection Speed Change notification size (8 byte header + 8 byte data)

USB_CDC_ECM_ETHERNET_FUNC_DESC_SIZE

Ethernet Networking Functional Descriptor size

USB_CDC_ECM_MAX_SEGMENT_SIZE

Maximum Ethernet frame size (default)

USB_CDC_ECM_MAC_STRING_SIZE

MAC address string length (12 Unicode characters)

USB CDC NCM Constants (NCM 1.0)

Network Control Model definitions shared by the USBD and USBH CDC NCM drivers

USB_CDC_NCM_SUBCLASS_CODE

CDC Subclass Code: Network Control Model (NCM)

USB_CDC_NCM_FUNC_DESC

NCM Functional Descriptor

USB_CDC_NCM_GET_NTB_PARAMETERS

Get NTB parameters

USB_CDC_NCM_GET_NET_ADDRESS

Get network address (obsolete)

USB_CDC_NCM_SET_NET_ADDRESS

Set network address (obsolete)

USB_CDC_NCM_GET_NTB_FORMAT

Get NTB format (16-bit vs 32-bit)

USB_CDC_NCM_SET_NTB_FORMAT

Set NTB format

USB_CDC_NCM_GET_NTB_INPUT_SIZE

Get max NTB input size

USB_CDC_NCM_SET_NTB_INPUT_SIZE

Set max NTB input size

USB_CDC_NCM_GET_MAX_DATAGRAM_SIZE

Get max datagram size

USB_CDC_NCM_SET_MAX_DATAGRAM_SIZE

Set max datagram size

USB_CDC_NCM_GET_CRC_MODE

Get CRC mode

USB_CDC_NCM_SET_CRC_MODE

Set CRC mode

USB_CDC_NCM_NET_ADDRESS_RSP_LEN

GET_NET_ADDRESS response size

USB_CDC_NCM_CRC_MODE_RSP_LEN

GET_CRC_MODE response size

USB_CDC_NCM_NTH16_SIGNATURE

"NCMH" - NTB16 header signature

USB_CDC_NCM_NDP16_NOCRC_SIGNATURE

"NCM0" - NTB16 datagram pointer signature (no CRC)

USB_CDC_NCM_NDP16_CRC_SIGNATURE

"NCM1" - NTB16 datagram pointer signature (CRC)

USB_CDC_NCM_NTH32_SIGNATURE

"ncmh" - NTB32 header signature

USB_CDC_NCM_NDP32_NOCRC_SIGNATURE

"ncm0" - NTB32 datagram pointer signature (no CRC)

USB_CDC_NCM_NDP32_CRC_SIGNATURE

"ncm1" - NTB32 datagram pointer signature (CRC)

USB_CDC_NCM_CRC_MODE_NONE

No CRC

USB_CDC_NCM_CRC_MODE_CRC32

CRC32

USB_CDC_NCM_NTB16_SUPPORTED

NTB16 format supported

USB_CDC_NCM_NTB32_SUPPORTED

NTB32 format supported

USB_CDC_NCM_DEFAULT_NTB_INPUT_SIZE

Default NTB input size

USB_CDC_NCM_MIN_NTB_INPUT_SIZE

Minimum dwNtbInMaxSize the host may negotiate for NTB-16. Ref NCM 1.0 Table 6-3: a device shall accept any value down to 2048 bytes for the 16-bit NTB format.

USB_CDC_NCM_MAX_NTB_INPUT_SIZE

Maximum NTB input size (16-bit limit)

USB_CDC_NCM_NTH16_LENGTH

NTH16 header length

USB_CDC_NCM_NDP16_HEADER_LENGTH

NDP16 header length, i.e. offset of aEntry[0] (dwSignature + wLength + wNextFpIndex)

USB_CDC_NCM_NDP16_MIN_LENGTH

Minimum NDP16 length (header + 1 datagram entry + terminator entry)

USB_CDC_NCM_NDP16_ENTRY_LENGTH

Each NDP16 datagram entry length

USB_CDC_NCM_DATAGRAM_ALIGN

Default datagram alignment

USB_CDC_NCM_MAX_DATAGRAMS_DEFAULT

Default max datagrams per NTB

USB_CDC_NCM_MAX_ETHERNET_FRAME_SIZE

Maximum Ethernet frame size

USB Ch9 Constants

Chapter 9 standard descriptor, request and status definitions

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_LEN_DESC_HEADER

Length of the common descriptor header (bLength + bDescriptorType). Ref USB 2.0 9.6.

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

Request recipient is another element.

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_CS_INTERFACE

Class-Specific Interface descriptor type (USB Spec Table 9-5).

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_TEST_MODE_J

Test_J, the first defined selector.

USB_TEST_MODE_K

Test_K.

USB_TEST_MODE_SE0_NAK

Test_SE0_NAK.

USB_TEST_MODE_PACKET

Test_Packet.

USB_TEST_MODE_FORCE_EN

Test_Force_Enable, the last defined 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_EP_BINTERVAL_EXP_MIN

Legal bInterval ranges of an endpoint descriptor (USB 2.0 9.6.6).

bInterval is the period of a periodic endpoint, and the spec encodes it in two different ways depending on speed and transfer type. Mixing them up misreads the service interval by up to 2^15, so pick the pair matching the endpoint:

  • Isochronous, full and high speed, and Interrupt at high speed: a exponent, where the period is 2^(bInterval-1) frames (full speed) or microframes (high speed). Range 1..16; a value above 16 is malformed and, used as a shift count, would be undefined behaviour.

  • Interrupt at full/low speed: a linear count of frames, range 1..255. Bulk and Control endpoints have no period; bInterval is reserved and must be ignored.

Note that these bounds only make a descriptor well formed, not usable: the longest legal exponent (16, i.e. 2^15 frames/microframes) is a period of several seconds, which many derived rate computations cannot represent. Range-check with these macros, then still validate whatever rate or size is computed from the value. Min bInterval where the period is 2^(bInterval-1).

USB_EP_BINTERVAL_EXP_MAX

Max bInterval where the period is 2^(bInterval-1).

USB_EP_BINTERVAL_LINEAR_MIN

Min bInterval where the period is bInterval frames.

USB_EP_BINTERVAL_LINEAR_MAX

Max bInterval where the period is bInterval frames.

USB_ISOC_FS_BINTERVAL_MIN

FS Isochronous: 2^(n-1) frames.

USB_ISOC_FS_BINTERVAL_MAX

FS Isochronous: 2^(n-1) frames.

USB_ISOC_HS_BINTERVAL_MIN

HS Isochronous: 2^(n-1) microframes.

USB_ISOC_HS_BINTERVAL_MAX

HS Isochronous: 2^(n-1) microframes.

USB_INTR_FS_BINTERVAL_MIN

FS Interrupt: bInterval frames.

USB_INTR_FS_BINTERVAL_MAX

FS Interrupt: bInterval frames.

USB_INTR_HS_BINTERVAL_MIN

HS Interrupt: 2^(n-1) microframes.

USB_INTR_HS_BINTERVAL_MAX

HS Interrupt: 2^(n-1) microframes.

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

Offset to bcdDevice in device descriptor.

USB_DEV_DESC_OFFSET_IMFG

Offset to iManufacturer in device descriptor.

USB_DEV_DESC_OFFSET_IPROD

Offset to iProduct in device descriptor.

USB_DEV_DESC_OFFSET_ISN

Offset to iSerialNumber in device descriptor.

USB_DEV_DESC_OFFSET_NUM_CFG

Offset to bNumConfigurations in device descriptor.

USB_DEV_QUALIFIER_DESC_OFFSET_NUM_CFG

Offset to bNumConfigurations in device qualifier 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_MAX_POWER

Offset to bMaxPower 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 Ch9 Macros

Endpoint address helper macros of Chapter 9

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 Common Misc Constants

Speed, status and error code definitions shared across the USB stack

USB_FRAME_NUM_MASK

Mask of a USB frame/microframe number.

备注

Ref USB 2.0 spec 8.4.3 and the DWC OTG HFNUM/DSTS.FNSOF fields: the frame number is an 11-bit frame plus a 3-bit microframe index, i.e. a 14-bit counter that wraps back to 0 after 0x3FFF. Frame arithmetic shall stay unsigned and be masked with this value so it survives the wrap, e.g. ((cur - start) & USB_FRAME_NUM_MASK).

USB_FRAME_NUM_MAX

Largest USB frame/microframe number, the value the counter wraps at.

备注

Same 14-bit range as USB_FRAME_NUM_MASK, spelled for the places that compute a wrapped distance as (USB_FRAME_NUM_MAX - start + 1 + cur) instead of masking.

USB DFU Constants (DFU 1.1)

Common protocol definitions shared by USBD and USBH DFU drivers

USB_DFU_CLASS_CODE

Application-Specific class code

USB_DFU_SUBCLASS_CODE

DFU subclass code

USB_DFU_PROTOCOL_RUNTIME

Run-Time protocol (application running)

USB_DFU_PROTOCOL_DFU

DFU mode protocol

USB_DFU_FUNC_DESC_TYPE

DFU Functional Descriptor type

USB_DFU_FUNC_DESC_SIZE

DFU Functional Descriptor size (bytes)

USB_DFU_ATTR_CAN_DNLOAD

Device supports DFU_DNLOAD

USB_DFU_ATTR_CAN_UPLOAD

Device supports DFU_UPLOAD

USB_DFU_ATTR_MANIFEST_TOL

Device is manifestation tolerant

USB_DFU_ATTR_WILL_DETACH

Device will detach after DFU_DETACH

USB_DFU_REQ_DETACH

DFU_DETACH request

USB_DFU_REQ_DNLOAD

DFU_DNLOAD request

USB_DFU_REQ_UPLOAD

DFU_UPLOAD request

USB_DFU_REQ_GETSTATUS

DFU_GETSTATUS request

USB_DFU_REQ_CLRSTATUS

DFU_CLRSTATUS request

USB_DFU_REQ_GETSTATE

DFU_GETSTATE request

USB_DFU_REQ_ABORT

DFU_ABORT request

USB_DFU_STATUS_PKT_SIZE

GETSTATUS response is always 6 bytes

USB_DFU_BCD_VERSION

BCD-encoded DFU specification version

USB Diag Constants

Default sizing of the USB diagnostics ring buffer and dumper task

USB_DIAG_DEFAULT_DEPTH

Default ring buffer depth for USB diag entries, used when diag_depth is 0 in the config.

USB_DIAG_DEFAULT_POLL_MS

Default diag task polling interval in ms, used when diag_poll_ms is 0 in the config.

USB HID Constants (HID 1.11)

Common protocol definitions shared by the USBD and USBH HID drivers

USB_HID_CLASS_CODE

HID interface class code.

USB_HID_SUBCLASS_NONE

No subclass.

USB_HID_PROTOCOL_NONE

No protocol (boot IF not used).

USB_HID_PROTOCOL_KEYBOARD

Keyboard boot protocol.

USB_HID_PROTOCOL_MOUSE

Mouse boot protocol.

USB MSC Constants (BOT 1.0)

Common protocol definitions shared by the USBD and USBH MSC drivers

USB_MSC_CLASS_CODE

Mass Storage Class code.

USB_MSC_SUBCLASS_SCSI

SCSI transparent command set.

USB_MSC_PROTOCOL_BOT

Bulk-Only Transport protocol.

USB_MSC_REQUEST_BOT_RESET

Bulk-Only Mass Storage Reset request.

USB_MSC_REQUEST_GET_MAX_LUN

Get Max LUN request.

USB_MSC_CBW_SIGN

Standard dCBWSignature, spells out USBC

USB_MSC_CSW_SIGN

Standard dCSWSignature, spells out 'USBS'

USB_MSC_CBW_LEN

Standard CBW length in bytes.

USB_MSC_CSW_LEN

Standard CSW length in bytes.

USB_BOT_CBW_TAG

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

USB OS Constants

Timeout and alignment definitions of the USB OS abstraction

USB_OS_SEMA_TIMEOUT

Defines the maximum timeout value for semaphore operations.

USB_OS_WAIT_FOREVER

Timeout value making a queue or semaphore wait block until it is served.

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 SCSI Constants (SPC)

SCSI opcodes, data lengths and sense codes shared by the USBD and USBH MSC drivers

SCSI_TEST_UNIT_READY

TEST UNIT READY opcode (SPC-3).

SCSI_REQUEST_SENSE

REQUEST SENSE opcode (SPC-3).

SCSI_FORMAT_UNIT

FORMAT UNIT opcode (SBC-2).

SCSI_INQUIRY

INQUIRY opcode (SPC-3).

SCSI_START_STOP_UNIT

START STOP UNIT opcode (SBC-2).

SCSI_MODE_SELECT6

MODE SELECT(6) opcode (SPC-3).

SCSI_MODE_SELECT10

MODE SELECT(10) opcode (SPC-3).

SCSI_MODE_SENSE6

MODE SENSE(6) opcode (SPC-3).

SCSI_MODE_SENSE10

MODE SENSE(10) opcode (SPC-3).

SCSI_ALLOW_MEDIUM_REMOVAL

PREVENT ALLOW MEDIUM REMOVAL opcode (SPC-3).

SCSI_READ6

READ(6) opcode (SBC-2).

SCSI_READ10

READ(10) opcode (SBC-2).

SCSI_READ12

READ(12) opcode (SBC-2).

SCSI_READ16

READ(16) opcode (SBC-2).

SCSI_READ_CAPACITY10

READ CAPACITY(10) opcode (SBC-2).

SCSI_READ_CAPACITY16

SERVICE ACTION IN(16) opcode, carrying READ CAPACITY(16) (SBC-2).

SCSI_WRITE6

WRITE(6) opcode (SBC-2).

SCSI_WRITE10

WRITE(10) opcode (SBC-2).

SCSI_WRITE12

WRITE(12) opcode (SBC-2).

SCSI_WRITE16

WRITE(16) opcode (SBC-2).

SCSI_VERIFY10

VERIFY(10) opcode (SBC-2).

SCSI_VERIFY12

VERIFY(12) opcode (SBC-2).

SCSI_VERIFY16

VERIFY(16) opcode (SBC-2).

SCSI_SEND_DIAGNOSTIC

SEND DIAGNOSTIC opcode (SPC-3).

SCSI_READ_FORMAT_CAPACITIES

READ FORMAT CAPACITIES opcode (MMC-2, used by UFI hosts).

TEST_UNIT_READY_LEN

TEST UNIT READY carries no data stage.

READ_CAPACITY10_DATA_LEN

READ CAPACITY(10) response length: last LBA + block length.

INQUIRY_DATA_LEN

Standard INQUIRY response length requested by this stack.

REQUEST_SENSE_DATA_LEN

Fixed-format sense data length.

READ_FORMAT_CAPACITY_DATA_LEN

READ FORMAT CAPACITIES response length: list header + one descriptor.

MODE_SENSE10_DATA_LEN

MODE SENSE(10) response length: mode parameter header only.

MODE_SENSE6_DATA_LEN

MODE SENSE(6) response length: mode parameter header only.

PAGE00_INQUIRY_DATA_LEN

INQUIRY VPD page 00h (supported pages) response length.

PAGE80_INQUIRY_DATA_LEN

INQUIRY VPD page 80h (unit serial number) response length.

CBW_CB_LENGTH

Size of the CBWCB field of a CBW (BOT 5.1).

CBW_LENGTH

bCBWCBLength used for 10-byte command blocks.

CBW_LENGTH_SIX_BYTE_COMMAND

bCBWCBLength used for 6-byte command blocks.

SCSI_SENSE_KEY_NO_SENSE

Sense key: no specific sense information.

SCSI_SENSE_KEY_RECOVERED_ERROR

Sense key: command completed after recovery.

SCSI_SENSE_KEY_NOT_READY

Sense key: logical unit not accessible.

SCSI_SENSE_KEY_MEDIUM_ERROR

Sense key: non-recoverable medium error.

SCSI_SENSE_KEY_HARDWARE_ERROR

Sense key: non-recoverable hardware failure.

SCSI_SENSE_KEY_ILLEGAL_REQUEST

Sense key: illegal parameter in the command.

SCSI_SENSE_KEY_UNIT_ATTENTION

Sense key: unit attention, e.g. medium changed or reset.

SCSI_SENSE_KEY_DATA_PROTECT

Sense key: access to a protected block.

SCSI_SENSE_KEY_BLANK_CHECK

Sense key: blank or end-of-data condition.

SCSI_SENSE_KEY_VENDOR_SPECIFIC

Sense key: vendor specific condition.

SCSI_SENSE_KEY_COPY_ABORTED

Sense key: copy command aborted.

SCSI_SENSE_KEY_ABORTED_COMMAND

Sense key: command aborted by the device.

SCSI_SENSE_KEY_VOLUME_OVERFLOW

Sense key: end of medium reached with data left.

SCSI_SENSE_KEY_MISCOMPARE

Sense key: source data did not match medium data.

SCSI_ASC_NO_ADDITIONAL_SENSE_INFORMATION

ASC: no additional sense information.

SCSI_ASC_WRITE_FAULT

ASC: peripheral device write fault.

SCSI_ASC_LOGICAL_UNIT_NOT_READY

ASC: logical unit not ready.

SCSI_ASC_UNRECOVERED_READ_ERROR

ASC: unrecovered read error.

SCSI_ASC_PARAMETER_LIST_LENGTH_ERROR

ASC: parameter list length error.

SCSI_ASC_INVALID_COMMAND_OPERATION_CODE

ASC: invalid command operation code.

SCSI_ASC_ADDRESS_OUT_OF_RANGE

ASC: logical block address out of range.

SCSI_ASC_INVALID_FIELD_IN_CDB

ASC: invalid field in CDB.

SCSI_ASC_INVALID_FIELD_IN_PARAMETER_LIST

ASC: invalid field in parameter list.

SCSI_ASC_WRITE_PROTECTED

ASC: write protected.

SCSI_ASC_MEDIUM_HAVE_CHANGED

ASC: not ready to ready change, medium may have changed.

SCSI_ASC_NOT_READY_TO_READY_CHANGE

ASC: not ready to ready change (same code as SCSI_ASC_MEDIUM_HAVE_CHANGED).

SCSI_ASC_FORMAT_ERROR

ASC: medium format corrupted.

SCSI_ASC_MEDIUM_NOT_PRESENT

ASC: medium not present.

SCSI_ASC_MEDIUM_REMOVAL_PREVENTED

ASC: medium removal prevented, with SCSI_ASCQ_MEDIUM_REMOVAL_PREVENTED.

SCSI_ASCQ_MEDIUM_REMOVAL_PREVENTED

ASCQ paired with SCSI_ASC_MEDIUM_REMOVAL_PREVENTED.

SCSI_ASCQ_FORMAT_COMMAND_FAILED

ASCQ with ASC 0x31: format command failed.

SCSI_ASCQ_INITIALIZING_COMMAND_REQUIRED

ASCQ with ASC 0x04: initializing command required.

SCSI_ASCQ_OPERATION_IN_PROGRESS

ASCQ with ASC 0x04: operation in progress.

USB UAC Constants

Audio Class definitions shared by UAC 1.0/2.0 and by the USBD and USBH UAC drivers

USB_UAC_CLASS_CODE
USB_UAC_IF_CLASS_AUDIO
USB_UAC_IP_VERSION_1
USB_UAC_IP_VERSION_2
USB_UAC_SUBCLASS_AUDIOCONTROL
USB_UAC_SUBCLASS_AUDIOSTREAMING
USB_UAC_CS_INTERFACE
USB_UAC_CS_ENDPOINT
USB_UAC_IAD_DESCRIPTOR_TYPE
USB_UAC_AC_HEADER
USB_UAC_AC_INPUT_TERMINAL
USB_UAC_AC_OUTPUT_TERMINAL
USB_UAC_AC_FEATURE_UNIT
USB_UAC_AS_GENERAL
USB_UAC_AS_FORMAT_TYPE
USB_UAC_AS_EP_GENERAL
USB_UAC_REQ_CUR
USB_UAC_REQ_RANGE
USB_UAC_CS_SAM_FREQ_CONTROL
USB_UAC_FU_MUTE
USB_UAC_FU_VOLUME
USB_UAC_FU_BASS
USB_UAC_FU_MID
USB_UAC_FU_TREBLE
USB_UAC_FU_GRAPHIC_EQUALIZER
USB_UAC_FU_AUTOMATIC_GAIN
USB_UAC_FU_DELAY
USB_UAC_FU_BASS_BOOST
USB_UAC_FU_LOUDNESS
USB_UAC_FU_INPUT_GAIN
USB_UAC_FU_INPUT_GAIN_PAD
USB_UAC_FU_PHASE_INVERTER
USB_UAC_FU_UNDERFLOW
USB_UAC_FU_OVERFLOW
USB_UAC_FU_LATENCY

USB UAC1 Constants (UAC 1.0)

UAC 1.0 descriptor, request and terminal definitions shared by the USBD and USBH UAC drivers

USB_UAC1_VERSION_01_00
USB_UAC1_IF_IDX_AC_HEADSET
USB_UAC1_IF_IDX_AS_HEADSET_HEADPHONES
USB_UAC1_CONTROL_MUTE
USB_UAC1_CONTROL_VOLUME
USB_UAC1_CONTROL_BASS
USB_UAC1_CONTROL_MID
USB_UAC1_CONTROL_TREBLE
USB_UAC1_MIXER_UNIT
USB_UAC1_SELECTOR_UNIT
USB_UAC1_PROCESSING_UNIT
USB_UAC1_EXTENSION_UNIT
USB_UAC1_FORMAT_SPECIFIC
USB_UAC1_PROCESS_UNDEFINED
USB_UAC1_PROCESS_UP_DOWNMIX
USB_UAC1_PROCESS_DOLBY_PROLOGIC
USB_UAC1_PROCESS_STEREO_EXTENDER
USB_UAC1_PROCESS_REVERB
USB_UAC1_PROCESS_CHORUS
USB_UAC1_PROCESS_DYN_RANGE_COMP
USB_UAC1_SET_CUR
USB_UAC1_GET_CUR
USB_UAC1_SET_MIN
USB_UAC1_GET_MIN
USB_UAC1_SET_MAX
USB_UAC1_GET_MAX
USB_UAC1_SET_RES
USB_UAC1_GET_RES
USB_UAC1_SET_MEM
USB_UAC1_GET_MEM
USB_UAC1_GET_STAT
USB_UAC1_AC_IF_HEADER_LEN
USB_UAC1_AC_IN_TTY_DESC_LEN
USB_UAC1_AC_OUT_TTY_DESC_LEN
USB_UAC1_AC_FUNC_UNIT_DESC_LEN
USB_UAC1_AS_IF_DESC_LEN
USB_UAC1_AS_FRT_TYPE_DESC_LEN
USB_UAC1_EP_DESC_LEN
USB_UAC1_AUDIO_DATA_EP_DESC_LEN
USB_UAC1_EP_ATTR_SAMPLING_FREQ_CONTROL
USB_UAC1_INPUT_TERMINAL_UNDEFINED
USB_UAC1_INPUT_TERMINAL_MICROPHONE
USB_UAC1_INPUT_TERMINAL_DESKTOP_MICROPHONE
USB_UAC1_INPUT_TERMINAL_PERSONAL_MICROPHONE
USB_UAC1_INPUT_TERMINAL_OMNI_DIR_MICROPHONE
USB_UAC1_INPUT_TERMINAL_MICROPHONE_ARRAY
USB_UAC1_INPUT_TERMINAL_PROC_MICROPHONE_ARRAY
USB_UAC1_OUTPUT_TERMINAL_UNDEFINED
USB_UAC1_OUTPUT_TERMINAL_SPEAKER
USB_UAC1_OUTPUT_TERMINAL_HEADPHONES
USB_UAC1_OUTPUT_TERMINAL_HEAD_MOUNTED_DISPLAY_AUDIO
USB_UAC1_OUTPUT_TERMINAL_DESKTOP_SPEAKER
USB_UAC1_OUTPUT_TERMINAL_ROOM_SPEAKER
USB_UAC1_OUTPUT_TERMINAL_COMMUNICATION_SPEAKER
USB_UAC1_OUTPUT_TERMINAL_LOW_FREQ_EFFECTS_SPEAKER
USB_UAC1_FORMAT_TYPE_I_UNDEFINED
USB_UAC1_FORMAT_TYPE_I_PCM
USB_UAC1_FORMAT_TYPE_I_PCM8
USB_UAC1_FORMAT_TYPE_I_IEEE_FLOAT
USB_UAC1_FORMAT_TYPE_I_ALAW
USB_UAC1_FORMAT_TYPE_I_MULAW
USB_UAC1_FORMAT_TYPE_UNDEFINED
USB_UAC1_FORMAT_TYPE_I
USB_UAC1_FORMAT_TYPE_II
USB_UAC1_FORMAT_TYPE_III
USB_UAC1_EXT_FORMAT_TYPE_I
USB_UAC1_EXT_FORMAT_TYPE_II
USB_UAC1_EXT_FORMAT_TYPE_III
struct usb_ac_itf_desc_header_t
#include <usb_uac1.h>

Public Members

uint8_t bLength
uint8_t bDescriptorType
uint8_t bDescriptorSubtype
struct usb_uac1_as_ep_desc_t
#include <usb_uac1.h>

Public Members

uint8_t bLength
uint8_t bDescriptorType
uint8_t bDescriptorSubtype
uint8_t bmAttributes
uint8_t bLockDelayUnits
uint16_t wLockDelay
struct usb_uac1_format_type_i_discrete_descriptor
#include <usb_uac1.h>

Public Members

uint8_t bLength
uint8_t bDescriptorType
uint8_t bDescriptorSubtype
uint8_t bFormatType
uint8_t bNrChannels
uint8_t bSubframeSize
uint8_t bBitResolution
uint8_t bSamFreqType
uint8_t tSamFreq[3][3]

USB UAC2 Constants (UAC 2.0)

UAC 2.0 descriptor, request and control definitions shared by the USBD and USBH UAC drivers

USB_UAC2_LEN_CTRL_IF_HEADER

Defines UAC 2.0 descriptor lengths. UAC Audio Control Interface Header Descriptor 2.0.

USB_UAC2_LEN_CLK_SRC_DESC

UAC Audio Control Clock Source Unit Descriptor 2.0.

USB_UAC2_LEN_AC_IN_TTY_DESC

UAC Audio Control Input Terminal Descriptor 2.0.

USB_UAC2_LEN_FUNC_UNIT_DESC

UAC Audio Control Feature Unit Descriptor 2.0.

USB_UAC2_LEN_AC_OUT_TTY_DESC

UAC Audio Control Output Terminal Descriptor 2.0.

USB_UAC2_LEN_AS_IF_ALT_SET_DESC

UAC Audio Streaming Interface Descriptor 2.0.

USB_UAC2_LEN_AS_FRT_TYPE_ALT_SET_DESC

UAC Audio Streaming Format Type Descriptor 2.0.

USB_UAC2_LEN_DATA_EP_DESC

UAC Audio Data Endpoint Descriptor.

USB_UAC2_IF_IDX_AC_HEADSET

UAC Audio Control Interface Index.

USB_UAC2_IF_IDX_AS_HEADSET_HEADPHONES

UAC Audio Streaming Headphone Interface Index.

USB_UAC2_IF_IDX_AS_HEADSET_MICROPHONE

UAC Audio Streaming Microphone Interface Index.

USB_UAC2_FUNC_CATEGORY_CODE_DESKTOP_UNDEFINED

UAC Audio Function Undefined type.

USB_UAC2_FUNC_CATEGORY_CODE_DESKTOP_SPEAKER

UAC Audio Function Speaker.

USB_UAC2_FUNC_CATEGORY_CODE_DESKTOP_HEADSET

UAC Audio Function Headset.

USB_UAC2_AC_IF_DESC_SUBTYPE_CLOCK_SOURCE

UAC Clock Source Descriptor subtype.

USB_UAC2_CS_CLK_VALID_CONTROL

UAC Audio Clock Source Clock Valid Control.

USB_UAC2_TE_CONNECTOR_CONTROL

UAC Audio Terminal Control Selectors CONNECTOR.

USB Video Constants (UVC 1.5)

Common protocol definitions shared by the USBD and USBH UVC drivers

USB_VIDEO_CLASS_CODE

Video interface class code.

USB_VIDEO_SUBCLASS_VIDEOCONTROL

Video Control (VC) interface.

USB_VIDEO_SUBCLASS_VIDEOSTREAMING

Video Streaming (VS) interface.

USB_VIDEO_SUBCLASS_INTERFACE_COLLECTION

Video Interface Collection (IAD).

USB_VIDEO_PROTOCOL_UNDEFINED

No protocol / undefined.

USB Common Types

USB App Types

struct usb_app_t
#include <usb_app.h>

Public Members

const char *name
int (*start)(void)
int (*stop)(void)
u8 role
struct usb_app_ctx_t
#include <usb_app.h>

Public Members

usb_os_sema_t join_sema
u8 state
u8 quit

USB CDC ACM Types (PSTN 1.2)

Abstract Control Model types shared by the USBD and USBH CDC ACM drivers

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

union usb_cdc_acm_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_acm_line_coding_t::[anonymous] b

Structured member access

USB CDC ECM Types (ECM 1.2)

Ethernet Control Model types shared by the USBD and USBH CDC ECM drivers

struct usb_cdc_ecm_ethernet_function_desc_t
#include <usb_cdc_ecm.h>

CDC Ethernet Networking Functional Descriptor.

Public Members

u8 bFunctionLength

Size of this descriptor in bytes (13)

u8 bDescriptorType

CS_INTERFACE descriptor type

u8 bDescriptorSubtype

Ethernet Networking functional descriptor subtype

u8 iMACAddress

Index of string descriptor containing MAC address

u32 bmEthernetStatistics

Bitmap of supported Ethernet statistics capabilities

u16 wMaxSegmentSize

Maximum segment size device can support

u16 wNumberMCFilters

Number of multicast filters that can be configured

u8 bNumberPowerFilters

Number of pattern filters available for wake-up

struct usb_cdc_ecm_union_func_desc_t
#include <usb_cdc_ecm.h>

CDC Union Functional Descriptor.

Public Members

u8 bFunctionLength

Size of this descriptor in bytes (5)

u8 bDescriptorType

CS_INTERFACE descriptor type

u8 bDescriptorSubtype

Union functional descriptor subtype

u8 bControlInterface

Interface number of the control interface

u8 bSubordinateInterface0

Interface number of the first subordinate (data) interface

struct usb_cdc_ecm_speed_change_data_t
#include <usb_cdc_ecm.h>

Connection Speed Change Notification Data.

Public Members

u32 DLBitRate

Downstream bit rate in bits per second

u32 ULBitRate

Upstream bit rate in bits per second

struct usb_cdc_ecm_notify_t
#include <usb_cdc_ecm.h>

Connection Notification.

Public Members

u8 bmRequestType

Request type

u8 bNotificationCode

NETWORK_CONNECTION or CONNECTION_SPEED_CHANGE

u16 wValue

Connection status or Reserved (0)

u16 wIndex

Interface number

u16 wLength

Data length: 0 for NETWORK_CONNECTION, 8 for CONNECTION_SPEED_CHANGE

usb_cdc_ecm_speed_change_data_t data

Speed change data

USB CDC NCM Types (NCM 1.0)

Network Control Model types shared by the USBD and USBH CDC NCM drivers

struct usb_cdc_ncm_ethernet_function_desc_t
#include <usb_cdc_ncm.h>

CDC Ethernet Networking Functional Descriptor (used by NCM for MAC address extraction)

Public Members

u8 bFunctionLength

Size of this descriptor in bytes (13)

u8 bDescriptorType

CS_INTERFACE descriptor type

u8 bDescriptorSubtype

Ethernet Networking functional descriptor subtype

u8 iMACAddress

Index of string descriptor containing MAC address

u32 bmEthernetStatistics

Bitmap of supported Ethernet statistics capabilities

u16 wMaxSegmentSize

Maximum segment size device can support

u16 wNumberMCFilters

Number of multicast filters that can be configured

u8 bNumberPowerFilters

Number of pattern filters available for wake-up

struct usb_cdc_ncm_speed_change_data_t
#include <usb_cdc_ncm.h>

Connection Speed Change Notification Data.

Public Members

u32 DLBitRate

Downstream bit rate in bits per second

u32 ULBitRate

Upstream bit rate in bits per second

struct usb_cdc_ncm_notify_t
#include <usb_cdc_ncm.h>

NCM Connection Notification.

Public Members

u8 bmRequestType

Request type

u8 bNotificationCode

Notification code

u16 wValue

Connection status

u16 wIndex

Interface number

u16 wLength

Data length

struct usb_cdc_ncm_function_desc_t
#include <usb_cdc_ncm.h>

CDC NCM Functional Descriptor.

Public Members

u8 bFunctionLength

Size of this descriptor in bytes

u8 bDescriptorType

CS_INTERFACE descriptor type (0x24)

u8 bDescriptorSubtype

NCM functional descriptor subtype (0x1A)

u16 bcdNcmVersion

NCM specification version (BCD)

u8 bmNetworkCapabilities

Bitmap of network capabilities

struct usb_cdc_ncm_ntb_parameters_t
#include <usb_cdc_ncm.h>

NCM NTB Parameters structure (returned by GET_NTB_PARAMETERS)

Public Members

u16 wLength

Size of this structure in bytes (28)

u16 bmNtbFormatsSupported

Bitmap of supported NTB formats (bit0=NTB16, bit1=NTB32)

u32 dwNtbInMaxSize

Max NTB the device may send to the host (IN, device-to-host)

u16 wNdbInDivisor

Datagram divisor for device-to-host (IN) NTBs

u16 wNdbInPayloadRemainder

Datagram payload remainder for device-to-host (IN) NTBs

u16 wNdbInAlignment

NDP alignment for device-to-host (IN) NTBs

u16 wReserved1

Reserved (offset 14, set to 0) per NCM 1.0 Table 6-3

u32 dwNtbOutMaxSize

Max NTB the host may send to the device (OUT, host-to-device)

u16 wNdbOutDivisor

Datagram divisor for host-to-device (OUT) NTBs

u16 wNdbOutPayloadRemainder

Datagram payload remainder for host-to-device (OUT) NTBs

u16 wNdbOutAlignment

NDP alignment for host-to-device (OUT) NTBs

u16 wNtbOutMaxDatagrams

Max datagrams per host-to-device (OUT) NTB (0 = no limit)

struct usb_cdc_ncm_nth16_t
#include <usb_cdc_ncm.h>

NTB16 Transfer Header.

Public Members

u32 dwSignature

Signature: "NCMH" (0x484D434E)

u16 wHeaderLength

Header length (12 bytes)

u16 wSequence

Sequence number

u16 wBlockLength

Total NTB block length

u16 wFpIndex

Frame pointer index (offset to NDP from NTH start, 0 if none)

struct usb_cdc_ncm_ndp16_entry_t
#include <usb_cdc_ncm.h>

NTB16 Datagram Pointer Entry.

Public Members

u16 wDatagramIndex

Offset to datagram from NTH start

u16 wDatagramLength

Length of datagram

struct usb_cdc_ncm_ndp16_t
#include <usb_cdc_ncm.h>

NTB16 Datagram Pointer (NDP)

Public Members

u32 dwSignature

Signature: "NCM0" (0x304D434E)

u16 wLength

Length of this NDP including all entries

u16 wNextFpIndex

Offset to next NDP (0 if last)

usb_cdc_ncm_ndp16_entry_t aEntry[2]

First 2 entries (one real + terminator with index=0)

USB Ch9 Types

Chapter 9 standard descriptor and setup packet types

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.

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 Common Misc Types

Speed and status types shared across the USB stack

enum usb_speed_type_t

Defines the operational speeds for the USB controller.

备注

This is a controller operating mode rather than a Chapter 9 definition: USB_SPEED_HIGH_IN_FULL has no counterpart on the bus, it describes a High-Speed capable PHY driven in Full-Speed mode.

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

struct usb_ep_info_t
#include <usb_def.h>

USB endpoint information structure.

Contains basic endpoint configuration: interval, address, max packet size, and type.

Public Members

u16 interval

Endpoint polling interval in ticks, High-speed means 2^(binterval-1).

u16 mps

Maximum Packet Size for this endpoint (0-1024).

u16 type

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

u8 binterval

Polling interval for the endpoint. Full Speed: 1-255, High Speed: 1-16

u8 addr

Endpoint address (includes direction).

USB DFU Types (DFU 1.1)

DFU state and status types shared by the USBD and USBH DFU drivers

USB Diag Types

Layer and event identifiers recorded in a USB diagnostics entry

enum usb_diag_layer_t

Stack layer that reported a diagnostics event.

Values:

enumerator USB_LAYER_CORE

Core, HCD or PCD.

enumerator USB_LAYER_CLASS

Class driver.

enumerator USB_LAYER_APP

Example or application.

enum usb_diag_event_t

Event recorded in a USB diagnostics entry.

Values:

enumerator USB_EVT_DEFAULT

Unclassified event.

enumerator USB_EVT_LINK

Link event (connect or disconnect).

enumerator USB_EVT_ERR_SETUP

Setup callback error.

enumerator USB_EVT_ERR_GET_DESC

Get descriptor callback error.

enumerator USB_EVT_ERR_XFER

Transfer error.

enumerator USB_EVT_MAX

Maximum event value that fits the entry bit-field.

USB MSC Types (BOT 1.0)

Common protocol types shared by the USBD and USBH MSC drivers

enum usb_msc_bot_csw_state_t

BOT CSW status enumeration.

Values:

enumerator BOT_CSW_CMD_PASSED

The pass status of the command execution

enumerator BOT_CSW_CMD_FAILED

The fail status of the command execution

enumerator BOT_CSW_PHASE_ERROR

The phase error status of the command execution

union usb_msc_bot_cbw_t
#include <usb_msc.h>

Command Block Wrapper (CBW) structure.

This structure defines the format of a command sent from the host to the device.

Public Members

u32 dCBWSignature

CBW Signature, must be 'USBC' (0x43425355).

u32 dCBWTag

A unique tag sent by the host, returned in the CSW.

u32 dCBWDataTransferLength

Number of bytes of data the host expects to transfer.

u8 bmCBWFlags

Data transfer direction (bit 7: 0=OUT, 1=IN).

u8 bCBWLUN

The Logical Unit Number (LUN) to which the command is addressed.

u8 bCBWCBLength

The length of the command block (CBWCB) in bytes (1-16).

u8 CBWCB[16]

The SCSI command block to be executed by the device.

struct usb_msc_bot_cbw_t::[anonymous] field
u8 data[31]

Byte array access to the entire CBW structure.

union usb_msc_bot_csw_t
#include <usb_msc.h>

Bulk-Only Transport (BOT) Command Status Wrapper (CSW) structure.

Public Members

u32 dCSWSignature

CSW Signature, must be 'USBS' (0x53425355).

u32 dCSWTag

The device shall set this to the value from the associated CBW's dCBWTag.

u32 dCSWDataResidue

The difference between the amount of data expected and the actual data processed.

u8 bCSWStatus

The status of the command execution (0=Pass, 1=Fail, 2=Phase Error), see USBD_MSC_CSW_XX.

struct usb_msc_bot_csw_t::[anonymous] field
u8 data[13]

Byte array access to the entire CSW structure.

struct usb_msc_scsi_sense_data_t
#include <usb_msc.h>

SCSI Sense Data structure.

This structure holds sense data used to report errors for SCSI commands.

Public Members

u8 key

Sense Key.

u8 asc

Additional Sense Code.

u8 ascq

Additional Sense Code Qualifier.

USB OS Types

Abstracted OS object types of the USB OS abstraction

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.

USB Ring Buffer Types

Node and manager types of the block-based USB ring buffer

struct usb_ringbuf_t
#include <usb_ringbuf.h>

Individual data node within the ring buffer. Represents a single block of memory within the managed buffer pool.

Public Members

u8 *buf

Pointer to the actual data storage area for this node.

u16 buf_len

Length of valid data currently stored in this node (bytes).

u8 data_valid

Data validity flag. 1 indicates valid payload; 0 indicates empty/invalid.

struct usb_ringbuf_manager_t
#include <usb_ringbuf.h>

Ring Buffer Manager Control Structure. Main structure used to manage the state, memory, and pointers of the circular buffer.

Public Members

usb_ringbuf_t *list_node

Array of metadata nodes. Size equals 'capacity'.

u8 *buffer

Base address of the contiguous memory pool. Total size = capacity * node_size.

u16 node_size

Maximum data size (in bytes) for a single node.

u8 head

Read index (Consumer). Points to the next node to be dequeued.

u8 tail

Write index (Producer). Points to the next slot for enqueuing.

u8 capacity

Maximum number of nodes (blocks) the buffer can hold.

USB UAC2 Types (UAC 2.0)

UAC 2.0 descriptor, request and control definitions shared by the USBD and USBH UAC drivers

struct usb_uac2_ac_connect_ctrl_t
#include <usb_uac2.h>

Public Members

u8 bNrChannels
u32 bmChannelConfig
u8 iChannelNames
struct usb_uac2_ctrl_range_layout2_struct
#include <usb_uac2.h>

Structure to define the volume range attribute.

This structure holds the volume range attribute, such as max, min and res.

Public Members

u16 wNumSubRanges
u16 wMIN
u16 wMAX
u16 wRES
struct usb_uac2_freq_t
#include <usb_uac2.h>

One subrange of a Layout 3 RANGE parameter block.

A RANGE response is wNumSubRanges followed by wNumSubRanges of these subranges, e.g. for the Sampling Frequency Control of a Clock Source.

Public Members

u32 dMIN
u32 dMAX
u32 dRES

USB Device API

USB Device Functions

Device CDC ACM Functions

int usbd_cdc_acm_init(const usbd_cdc_acm_cb_t *cb, const usbd_cdc_acm_config_t *cfg)

Initializes class driver as a standalone device.

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

  • cfg -- [in] Pointer to the class configuration. See usbd_cdc_acm_config_t.

返回:

0 on success, non-zero on failure.

int usbd_composite_cdc_acm_init(const usbd_cdc_acm_cb_t *cb, const usbd_cdc_acm_config_t *cfg)

Initializes class driver as part of a composite device.

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

  • cfg -- [in] Pointer to the class configuration. See usbd_cdc_acm_config_t.

返回:

0 on success, non-zero on failure.

void usbd_cdc_acm_deinit(void)

De-initializes the CDC ACM class driver.

备注

Call it in task context, once no other task is inside usbd_cdc_acm_transmit() or usbd_cdc_acm_notify_serial_state(): the TX buffers they write to are released here.

备注

Composite mode: call it after usbd_composite_deinit. Before that the class is still reachable from the USB ISR, so the call returns at once and releases nothing.

返回:

None. This is a teardown path: apart from the composite case above, the class is always unregistered and every resource it owns released, nothing for the caller to recover from.

int usbd_cdc_acm_transmit(const u8 *buf, u32 len)

Transmits data to the host over the BULK IN endpoint.

备注

At most usbd_cdc_acm_config_t::bulk_in_xfer_size bytes are sent per call, a longer len is cut to that size.

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

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

返回:

0 on success, -RTK_ERR_BUSY while the previous transfer is in flight, -RTK_ERR_IO when the device is not configured, other non-zero on failure.

int usbd_cdc_acm_notify_serial_state(u16 serial_state)

Sets new line coding properties over the INTR IN endpoint.

备注

Requires usbd_cdc_acm_config_t::notify_en, otherwise the class owns no INTR IN endpoint and the call fails.

参数:

serial_state -- [in] New line coding properties.

返回:

0 on success, -RTK_ERR_BUSY while the previous notification is in flight, -RTK_ERR_IO when the device is not configured, other non-zero on failure.

Device CDC ECM Functions

int usbd_cdc_ecm_init(const usbd_cdc_ecm_cb_t *cb, const usbd_cdc_ecm_config_t *cfg)

Initializes class driver with application callback handler.

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

  • cfg -- [in] Pointer to the class configuration. See usbd_cdc_ecm_config_t.

返回:

0 on success, non-zero on failure.

int usbd_composite_cdc_ecm_init(const usbd_cdc_ecm_cb_t *cb, const usbd_cdc_ecm_config_t *cfg)

Initializes class driver as part of a composite device.

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

  • cfg -- [in] Pointer to the class configuration. See usbd_cdc_ecm_config_t.

返回:

0 on success, non-zero on failure.

void usbd_cdc_ecm_deinit(void)

De-initializes the CDC ECM class driver.

备注

Call it in task context and never from a task that calls usbd_cdc_ecm_transmit(): it waits, without a bound, for every task inside usbd_cdc_ecm_transmit() to leave before the TX resources are released, so such a caller would wait for itself.

备注

Composite mode: call it after usbd_composite_deinit. Before that the class is still reachable from the USB ISR, so the call returns at once and releases nothing.

返回:

None. This is a teardown path: apart from the composite case above, the class is always unregistered and every resource it owns released, nothing for the caller to recover from.

int usbd_cdc_ecm_transmit(const u8 *buf, u32 len, u8 block)

Transmits data to the host over the BULK IN endpoint.

备注

The frame is only queued here; the USB ISR (SOF and BULK IN completion) starts the transfer, so USBD_SOF_INTR must be set in usbd_config_t::ext_intr_enable. Task context only, a call in interrupt context is rejected. It may run concurrently with usbd_cdc_ecm_deinit(), which waits for it to leave before releasing resources.

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

  • len -- [in] Length of the data in bytes, at most USB_CDC_ECM_MAX_SEGMENT_SIZE (no FCS).

  • block -- [in] Blocking mode flag (0 for non-blocking, else block up to usbd_cdc_ecm_config_t::bulk_tx_timeout_ms).

返回:

0 on success, non-zero on failure.

Gets the link state last reported to the host.

返回:

1: Link is up, i.e. the host activated the data interface and the uplink is up. 0: Link is down.

Reports the upper-layer network link state to the host (edge-triggered).

The host is notified with NETWORK_CONNECTION only when the reported state actually changes; calling repeatedly with the same value is a no-op. Call from the layer that owns the real uplink (e.g. Wi-Fi / cellular) on link up/down events. The uplink starts down at every usbd_cdc_ecm_init, so call this after each init once the uplink is up.

参数:

link_up -- [in] Non-zero when the link is up, zero when it is down.

返回:

0 on success.

Device CDC NCM Functions

int usbd_cdc_ncm_init(const usbd_cdc_ncm_cb_t *cb, const usbd_cdc_ncm_config_t *cfg)

Initializes class driver with application callback handler.

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

  • cfg -- [in] Pointer to the class configuration. See usbd_cdc_ncm_config_t.

返回:

0 on success, non-zero on failure.

int usbd_composite_cdc_ncm_init(const usbd_cdc_ncm_cb_t *cb, const usbd_cdc_ncm_config_t *cfg)

Initializes class driver as part of a composite device.

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

  • cfg -- [in] Pointer to the class configuration. See usbd_cdc_ncm_config_t.

返回:

0 on success, non-zero on failure.

void usbd_cdc_ncm_deinit(void)

De-initializes the CDC NCM class driver.

备注

Call it in task context and never from a task that calls usbd_cdc_ncm_transmit(): it waits, without a bound, for every task inside usbd_cdc_ncm_transmit() to leave before the TX resources are released, so such a caller would wait for itself.

备注

Composite mode: call it after usbd_composite_deinit. Before that the class is still reachable from the USB ISR, so the call returns at once and releases nothing.

返回:

None. This is a teardown path: apart from the composite case above, the class is always unregistered and every resource it owns released, nothing for the caller to recover from.

int usbd_cdc_ncm_transmit(const u8 *buf, u32 len, u8 block)

Transmits an ethernet frame to the host wrapped in an NTB16.

备注

Task context only, a call in interrupt context is rejected. It may run concurrently with usbd_cdc_ncm_deinit(), which waits for it to leave before releasing resources.

参数:
  • buf -- [in] Pointer to the ethernet frame buffer to be transmitted.

  • len -- [in] Length of the ethernet frame in bytes.

  • block -- [in] When non-zero, block for a bounded time waiting for TX room, then drop the frame and return -RTK_ERR_BUSY. When zero, drop immediately.

返回:

0 on success, non-zero on failure.

Gets the link state last reported to the host.

返回:

1: Link is up, i.e. the host activated the data interface and the uplink is up. 0: Link is down.

Reports the upper-layer network link state to the host (edge-triggered).

The host is notified with NETWORK_CONNECTION only when the reported state actually changes; calling repeatedly with the same value is a no-op. Call from the layer that owns the real uplink (e.g. Wi-Fi / cellular) on link up/down events. The uplink starts down at every usbd_cdc_ncm_init, so call this after each init once the uplink is up.

参数:

link_up -- [in] Non-zero when the link is up, zero when it is down.

返回:

0 on success.

Device Core Functions For Applications

int usbd_init(const usbd_config_t *cfg)

Initialize USB device core driver with configuration.

参数:

cfg -- [in] USB device configuration.

返回:

0 on success, non-zero on failure.

void usbd_deinit(void)

Deinitialize USB device core driver.

备注

Teardown always completes: every software resource owned by the core (EP0 transfer buffer, PCD context, diag task, interrupt registration) is released even when the controller refuses to stop, which is reported through the log only. The device can therefore always be re-initialized with usbd_init afterwards. Task context only: a call in interrupt context is rejected with an error log and leaves the stack untouched.

返回:

None. Nothing is left for the caller to recover from, so no status is reported.

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.

void usbd_cg_register(void)

Register the sleep callbacks for USB device Clock Gating (CG).

Registers the PMU sleep callbacks so the USB device can be suspended/resumed when the AP enters/exits the low-power clock gated state. Wakelock operations and wake event configuration are handled by the caller, not inside this function.

void usbd_cg_unregister(void)

Unregister the sleep callbacks for USB device Clock Gating (CG).

备注

Wakelock operations are handled by the caller, not inside this function.

int usbd_wake_host(void)

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

备注

Task context only: this call blocks for about 8ms as required by the USB spec. It fails unless the bus is suspended (USB 2.0 7.1.7.7).

备注

USB 2.0 9.4.5 only allows a remote wakeup once the host has enabled it by SET_FEATURE(DEVICE_REMOTE_WAKEUP). This call is kept permissive and still signals when the host has not enabled it, only logging a warning, as some hosts never enable the feature. A strictly compliant application shall not call it in that case.

返回:

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.

备注

Task context only, same rule as usbd_deinit.

返回:

RTK_SUCCESS once the class is detached and the device driven to the detached state, also when no class was registered. -RTK_ERR_BADARG when called in interrupt context: nothing was done, the class is still reachable from the USB ISR, so the caller shall not release anything.

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.

void 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. Tolerates an endpoint that was never initialized, so a class may release its whole endpoint set unconditionally.

参数:
  • dev -- [in] USB device.

  • ep -- [in] USB endpoint.

返回:

None. This is a teardown path: the endpoint state is always released and an invalid endpoint address is reported through the log.

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.

  • The hardware always receives in whole packets, so the DMA window is xfer_len rounded up to a multiple of the DWORD aligned endpoint MPS (one such MPS when xfer_len is 0), refer to usb_get_dma_len() and usb_get_max_payload_len(). The class shall provide a usbd_ep_t::xfer_buf of at least that capacity and report it via usbd_ep_t::xfer_buf_len, otherwise a host sending a longer packet than expected overflows the buffer. Requests violating this are rejected when xfer_buf_len is set.

参数:
  • dev -- [in] USB device.

  • ep -- [in] USB endpoint.

返回:

0 on success, non-zero on failure.

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

返回:

None. A stall is unconditional on an endpoint opened by the current configuration. An invalid or unopened endpoint is a class programming error and is reported through the log.

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

返回:

None. See usbd_ep_set_stall.

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.

u8 usbd_add_string(const char *str)

Register a string descriptor and get the index naming it.

Lets a class or an application publish a string without knowing which indices the other functions of the device already use, which is what the composite framework needs. The returned index shall be emitted in the descriptor field naming the string (iInterface, CDC ECM/NCM iMACAddress, ...); the core answers GET_DESCRIPTOR(String, index) itself, so the class has nothing more to do. The table holds USBD_MAX_STR_NUM entries, all available to the classes and the application: the device-global strings are answered from usbd_dev_info_t and take no slot.

备注

The string is stored by pointer, not copied, so it shall remain valid until usbd_deinit. Registering the same pointer twice returns the same index and consumes no extra slot. Shall be called from task context, after usbd_init.

参数:

str -- [in] Pointer to the null-terminated UTF-8 string.

返回:

The string index on success, 0 when str is NULL or the table is full. Index 0 is reserved for the LANGID string descriptor and therefore doubles as the error value.

usbd_dev_info_t *usbd_get_dev_info(void)

Get the device-global descriptor parameters, for a class that has to override them.

Returns the resolved copy the core answers descriptor requests from, so a class holding values latched in hardware may overwrite any field. usbd_whc does so with its OTP parameters. An application configures these through usbd_config_t::info instead and has no need for this.

备注

Shall be called from task context, after usbd_init and before the device is enumerated. String pointers are stored, not copied, so a string assigned here shall remain valid until usbd_deinit.

返回:

Pointer to the device-global parameters, never NULL.

u8 usbd_get_uuid_sn(char *sn, u8 len)

Build a serial number string from the chip UUID.

Writes USBD_SN_STR_LEN uppercase hex characters plus a terminator: UUID[0] in the first 8, UUID[1] in the last 8. An unprogrammed OTP falls back to a fixed value and logs a warning, so the result is always a valid string.

备注

Reading the chip UUID costs several kilobytes of stack on some SoCs, which is why the core does not do it by itself. Call this from task context with enough stack, e.g. the application init thread, and assign the buffer to usbd_dev_info_t::sn_str. The buffer is referenced by pointer, so it shall remain valid until usbd_deinit.

参数:
  • sn -- [out] Destination buffer.

  • len -- [in] Capacity of sn in bytes, shall be greater than USBD_SN_STR_LEN.

返回:

Number of characters written, 0 when sn is NULL or len is too small.

u16 usbd_get_str_descriptor(const char *str, u8 *desc, u16 desc_len)

Converts UTF-8 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). Nothing is written when the descriptor does not fit, or when its length would exceed the 255-byte bLength field. Only the Basic Multilingual Plane is supported: a code point above U+FFFF, which UTF-16 would have to encode as a surrogate pair, is rejected.

参数:
  • str -- [in] Pointer to the null-terminated source UTF-8 string.

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

  • desc_len -- [in] Capacity of desc in bytes.

返回:

The total length of the generated descriptor in bytes, or 0 on error.

Device DFU Functions

Standalone and composite initialization, teardown and state query of the DFU class

int usbd_dfu_init(const usbd_dfu_cb_t *cb, const usbd_dfu_config_t *cfg)

Initialize and register the DFU device class driver (standalone).

参数:
  • cb -- Pointer to user callback structure.

  • cfg -- Pointer to the DFU configuration, carrying the flash parameters.

返回值:

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

int usbd_composite_dfu_init(const usbd_dfu_cb_t *cb, const usbd_dfu_config_t *cfg)

Initialize DFU as part of a composite device (driver registration is handled by composite).

参数:
  • cb -- Pointer to user callback structure.

  • cfg -- Pointer to the DFU configuration, carrying the flash parameters.

返回值:

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

void usbd_dfu_deinit(void)

Unregister the DFU device class driver and release resources.

备注

Composite mode: call it after usbd_composite_deinit. Before that the class is still reachable from the USB ISR, so the call returns at once and releases nothing.

返回值:

None. -- This is a teardown path: apart from the composite case above, the class is always unregistered and every resource it owns released, nothing for the caller to recover from.

void usbd_dfu_set_write_poll_ms(u32 poll_ms)

Set the poll timeout reported to the host in bwPollTimeout while the device is busy writing a firmware block (dfuDNBUSY state). Call this before usbd_dfu_init() or at any time before the first DNLOAD block arrives.

参数:

poll_ms -- Expected worst-case write time in milliseconds (e.g., flash sector erase + program time). 0 means the host polls immediately (default).

void usbd_dfu_set_manifest_poll_ms(u32 poll_ms)

Set the poll timeout (ms) reported to the host in bwPollTimeout during the MANIFEST state — the "Status poll timeout" period. After this interval the device transitions out of MANIFEST.

参数:

poll_ms -- Expected manifestation time in milliseconds. Default is 100 ms.

u8 usbd_dfu_get_state(void)

Read the current DFU device state.

返回值:

Current -- usb_dfu_state_t value (e.g. USB_DFU_STATE_DFU_IDLE).

Device HID Functions

int usbd_hid_init(const usbd_hid_usr_cb_t *cb, const usbd_hid_config_t *cfg)

Initializes class driver as a standalone device.

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

  • cfg -- [in] Pointer to the class configuration. See usbd_hid_config_t.

返回:

0 on success, non-zero on failure.

int usbd_composite_hid_init(const usbd_hid_usr_cb_t *cb, const usbd_hid_config_t *cfg)

Initializes class driver as part of a composite device.

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

  • cfg -- [in] Pointer to the class configuration. See usbd_hid_config_t.

返回:

0 on success, non-zero on failure.

void usbd_hid_deinit(void)

DeInitialize HID device.

备注

Call it in task context, once no other task is inside usbd_hid_send_data(), usbd_hid_volume_ctrl() or usbd_hid_power_ctrl(): the TX buffers they write to are released here.

备注

Composite mode: call it after usbd_composite_deinit. Before that the class is still reachable from the USB ISR, so the call returns at once and releases nothing.

返回:

None. This is a teardown path: apart from the composite case above, the class is always unregistered and every resource it owns released, nothing for the caller to recover from.

int usbd_hid_send_data(const 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(const usbd_msc_cb_t *cb, const usbd_msc_config_t *cfg)

Initializes the MSC device class driver (standalone).

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

  • cfg -- [in] Pointer to the class configuration. See usbd_msc_config_t.

返回:

0 on success, non-zero on failure.

int usbd_composite_msc_init(const usbd_msc_cb_t *cb, const usbd_msc_config_t *cfg)

Initializes MSC as part of a composite device.

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

  • cfg -- [in] Pointer to the class configuration. See usbd_msc_config_t.

返回:

0 on success, non-zero on failure.

void usbd_msc_deinit(void)

De-initializes the MSC device class driver.

备注

Composite mode: call it after usbd_composite_deinit. Before that the class is still reachable from the USB ISR, so the call returns at once and releases nothing.

int usbd_msc_disk_init(void)

Initializes the underlying storage disk.

返回:

0 on success, non-zero on failure.

void usbd_msc_disk_deinit(void)

De-initializes the underlying storage disk.

返回:

None. This is a teardown path: a backend that cannot unmount cleanly is reported through the log, and the caller has no way to recover from it anyway.

Device SCSI Functions

SCSI command execution and BOT transfer helpers, internal to the MSC class

int usbd_scsi_process_cmd(usbd_msc_dev_t *cdev, u8 *cmd)

Execute a SCSI command received in a CBW.

参数:
  • cdev -- MSC device instance.

  • cmd -- SCSI command block.

返回:

RTK_SUCCESS on success, a RTK error code otherwise.

void usbd_scsi_sense_code(usbd_msc_dev_t *cdev, u8 key, u8 asc)

Record a sense key and additional sense code for the next REQUEST SENSE.

参数:
  • cdev -- MSC device instance.

  • key -- Sense key.

  • asc -- Additional sense code.

返回:

None

u8 usbd_scsi_out_data_pending(const usbd_msc_dev_t *cdev)

Check whether the host still has OUT data to send after the WRITE chunk being processed.

参数:

cdev -- Device instance.

返回:

1 if more OUT data follows the current chunk, 0 otherwise.

int usbd_msc_bulk_transmit(usb_dev_t *dev, u8 *buf, u32 len)

Transmit data on the MSC bulk IN endpoint.

参数:
  • dev -- USB device instance.

  • buf -- Data to transmit.

  • len -- Data length in bytes.

返回:

RTK_SUCCESS on success, a RTK error code otherwise.

int usbd_msc_bulk_receive(usb_dev_t *dev, u8 *buf, u32 len, u32 buf_len)

Arm a receive on the MSC bulk OUT endpoint.

参数:
  • dev -- USB device instance.

  • buf -- Buffer receiving the data.

  • len -- Number of bytes to receive.

  • buf_len -- Buffer capacity, which shall cover the DMA window; refer to usbd_ep_receive().

返回:

RTK_SUCCESS on success, a RTK error code otherwise.

void usbd_msc_send_csw(usb_dev_t *dev, u8 status)

Send the Command Status Wrapper closing the current command.

参数:
返回:

None

Device UAC Functions

int usbd_uac_init(const usbd_uac_cb_t *cb, const usbd_uac_config_t *cfg)

Initializes class driver as a standalone device.

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

  • cfg -- [in] Pointer to endpoint address configuration, or NULL for defaults.

返回:

0 on success, non-zero on failure.

int usbd_composite_uac_init(const usbd_uac_cb_t *cb, const usbd_uac_config_t *cfg)

Initializes class driver as part of a composite device.

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

  • cfg -- [in] Pointer to endpoint address configuration, or NULL for defaults.

返回:

0 on success, non-zero on failure.

void usbd_uac_deinit(void)

DeInitialize UAC device.

备注

Call it in task context, without holding the USB critical section, and never from a task that calls usbd_uac_read() or usbd_uac_transmit_data(): it waits, without a bound, for every task inside them to leave before the ring buffers are released, so such a task calling it would wait for itself. Stop them first (usbd_uac_stop_play() / usbd_uac_stop_record() or an application lock held across the loop), as the examples do. Never delete a task while it is inside usbd_uac_read() or usbd_uac_transmit_data(): it would never leave, and this call would wait forever, reporting it once per second. Same rule for usbd_uac_config().

备注

Composite mode: call it after usbd_composite_deinit. Before that the class is still reachable from the USB ISR, so the call returns at once and releases nothing.

返回:

None. This is a teardown path: apart from the composite case above, the class is always unregistered and every resource it owns released, nothing for the caller to recover from.

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

Set audio configuration to the UAC class.

Validates the format against the declared ones and makes it the current one. The ISOC ring of the direction is sized for the largest declared format at the connection speed, so it is allocated by the first call after enumeration and only reallocated when the speed changed: a format switch requested by the host never reallocates it.

备注

Task context only, same rules as usbd_uac_deinit.

参数:
  • 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.

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

int usbd_uac_start_record(void)

USB audio start record.

返回值:

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

void usbd_uac_stop_record(void)

USB audio stop record.

int usbd_uac_transmit_data(const u8 *buf, u32 len)

Queue record (ISOC IN) PCM data for transmission to the host.

The stream is cut into one packet per (micro)frame of the nominal size for the record format, the class adding one audio frame now and then when the rate is not a multiple of the packet rate (e.g. 44.1kHz), ref UAC 2.0 2.3.1.1. Any length is accepted, typically 1ms of audio per call: nothing is truncated, and a tail shorter than a packet is kept for the next call. When the ring is full the oldest packet is dropped. UAC 2.0 only.

备注

Task context only, from a single producer task, same rules as usbd_uac_deinit. Pass whole audio frames (ch_cnt * byte_width bytes) so that packets stay frame aligned.

参数:
  • buf -- [in] pointer to the PCM data.

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

返回值:

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

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

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.

  • zero_pkt_flag -- [out] bitmap of zero-length filler packets returned in this read. Bit N is set if the N-th packet copied out was a ZLP inserted by the SOF underrun handler. May be NULL if the caller does not care.

返回值:

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

u32 usbd_uac_get_read_frame_time_in_us(void)

Get the time duration of currently queued audio frames in microseconds.

返回值:

frame_cnt -- * bInterval_us

Device UVC Functions

Lifecycle, event dispatch and state query of the UVC class

void usbd_uvc_events_process(usbd_uvc_dev_t *dev, usbd_uvc_req_data_t *uvc_event)

Dispatch a UVC event (SETUP / DATA / STREAMON / STREAMOFF) to the event handlers.

参数:
  • dev -- [in] UVC device context.

  • uvc_event -- [in] Event container (type + setup request or data payload).

usbd_uvc_dev_t *get_private_usbd_uvcd(void)

Return a pointer to the internal UVC device context.

备注

Caller must not free the returned pointer.

返回值:

Pointer -- to the singleton usbd_uvc_dev_t; never NULL after usbd_uvc_init().

void usbd_uvc_video_put_out_stream_queue(usbd_uvc_buffer_t *payload)

Return a completed video buffer to the output (free) queue.

参数:

payload -- [in] Buffer to return; must have been obtained from usbd_uvc_video_out_stream_queue().

void usbd_uvc_video_put_in_stream_queue(usbd_uvc_buffer_t *payload)

Submit a filled video buffer to the input (ready-to-send) queue.

参数:

payload -- [in] Buffer containing a complete video frame; mem and bytesused must be set.

usbd_uvc_buffer_t *usbd_uvc_video_out_stream_queue(void)

Dequeue one buffer from the output (free) queue.

返回值:

Pointer -- to a free usbd_uvc_buffer_t, or NULL if the queue is empty.

void usbd_uvc_wait_frame_down(void)

Block until the current video frame has been fully queued into the ring.

备注

Must not be called from ISR context.

int usbd_uvc_get_status(void)

Query whether UVC streaming is currently active.

返回值:

1 -- if streaming is running, 0 otherwise.

int usbd_uvc_init(const usbd_uvc_ep_cfg_t *ep_cfg)

Initialize the UVC device class (standalone) and start its worker tasks.

参数:

ep_cfg -- [in] Endpoint configuration; NULL selects the class defaults.

返回值:

RTK_SUCCESS -- on success, negative error code on failure.

int usbd_composite_uvc_init(const usbd_uvc_ep_cfg_t *ep_cfg)

Initialize UVC as part of a composite device, where driver registration is handled by the composite framework.

参数:

ep_cfg -- [in] Endpoint configuration assigned by the top-level application.

返回值:

RTK_SUCCESS -- on success, negative error code on failure.

int usbd_uvc_parameter_init(void)

Initialize UVC processing-unit and extension-unit control parameters.

返回值:

RTK_SUCCESS -- on success.

void usbd_uvc_deinit(void)

Tear down the UVC device class: stop tasks, delete OS objects, free ring.

备注

Composite mode: call it after usbd_composite_deinit. Before that the class is still reachable from the USB ISR, so the call returns at once and releases nothing.

void usbd_uvc_set_change_parm_cb(int cb)

Register a callback invoked when the host commits new streaming parameters.

备注

The callback is invoked in ISR context — must not block.

参数:

cb -- [in] Function pointer cast to int; signature: void (*)(void *uvc_format_ptr).

usbd_uvc_format_t *usbd_uvc_get_format(void)

Return a pointer to the active UVC format descriptor.

备注

Do not free the returned pointer.

返回值:

Pointer -- to the internal usbd_uvc_format_t; valid after usbd_uvc_init().

Device Vendor Functions

int usbd_vendor_init(const usbd_vendor_cb_t *cb, const usbd_vendor_config_t *cfg)

Initializes class driver with application callback handler.

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

  • cfg -- [in] Pointer to the class configuration. See usbd_vendor_config_t.

返回:

0 on success, non-zero on failure.

int usbd_composite_vendor_init(const usbd_vendor_cb_t *cb, const usbd_vendor_config_t *cfg)

Initializes class driver as part of a composite device.

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

  • cfg -- [in] Pointer to the class configuration. See usbd_vendor_config_t.

返回:

0 on success, non-zero on failure.

void usbd_vendor_deinit(void)

De-initializes the Vendor class driver.

备注

Call it in task context, once no other task is inside usbd_vendor_transmit_bulk_data(), usbd_vendor_transmit_intr_data() or usbd_vendor_transmit_isoc_data(): the TX buffers they write to are released here.

备注

Composite mode: call it after usbd_composite_deinit. Before that the class is still reachable from the USB ISR, so the call returns at once and releases nothing.

返回:

None. This is a teardown path: apart from the composite case above, the class is always unregistered and every resource it owns released, nothing for the caller to recover from.

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_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_transmit_isoc_data(u8 *buf, u32 len)

Transmits data to the host over the ISOC IN endpoint.

备注

ISOC keeps no in-flight state: each call copies into the single ISOC IN buffer and arms it at once, so a packet still pending is overwritten. Call it at most once per service interval, e.g. from the isoc_transmitted callback, to keep every packet intact.

参数:
  • 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 WHC Functions

Lifecycle and transfer operations of the WHC class

int usbd_whc_init(const usbd_whc_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.

void usbd_whc_deinit(void)

DeInitialize HID device.

返回:

None. This is a teardown path: the class is always unregistered and every resource it owns released, so there is nothing for the caller to recover from.

int usbd_whc_transmit_ctrl_data(u8 *buf, u16 len)

Transmits control IN data.

参数:
  • 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_whc_transmit_data(u8 ep_addr, u8 *buf, u32 len, void *userdata)

Transmits data to the host.

参数:
  • ep_addr -- [in] Endpoint address.

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

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

  • userdata -- [in] userdata from application for each endpoint.

返回:

0 on success, non-zero on failure.

int usbd_whc_receive_data(u8 ep_addr, u8 *buf, u32 len, void *userdata)

Prepares to receive non-control OUT data.

备注

The controller writes whole packets, so the DMA window is usb_get_dma_len(len, MPS), which exceeds len when len is not a multiple of the MPS. The buffer shall hold that window: the class does not report its capacity, so the core cannot reject or clamp an oversized OUT transfer and a host sending more than len bytes overruns a smaller buffer.

参数:
  • ep_addr -- [in] Endpoint address.

  • buf -- [in] Pointer to the data buffer, at least usb_get_dma_len(len, MPS) bytes.

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

  • userdata -- [in] userdata from application for each endpoint.

返回:

0 on success, non-zero on failure.

u8 usbd_whc_is_bt_en(void)

Checks whether the BT is enbaled.

返回:

  • 1: BT is enbaled.

  • 0: BT is disabled.

Device WHC OTP Functions

Reading the OTP-latched device identity, internal to the WHC class

int usbd_otp_init(usbd_otp_t *otp)

Read the device identity and parameters from OTP.

备注

Allocates the identity string buffers; release them with usbd_otp_deinit. On a partial failure the already allocated buffers are freed before returning.

参数:

otp -- OTP parameter block to fill in.

返回:

RTK_SUCCESS on success, -RTK_ERR_NOMEM when a buffer cannot be allocated.

void usbd_otp_deinit(usbd_otp_t *otp)

Free the buffers allocated by usbd_otp_init.

参数:

otp -- OTP parameter block to release.

返回:

None

USB Device Constants

Device CDC ACM Constants

USBD_CDC_ACM_DEFAULT_INTR_IN_INTERVAL

Default INTR IN bInterval, used when the configuration leaves it 0.

Device CDC ECM Constants

USBD_CDC_ECM_MAC_STR_LEN

Length of the MAC address in bytes.

USBD_CDC_ECM_DEFAULT_INTR_IN_INTERVAL

Default INTR IN bInterval.

USBD_CDC_ECM_DEFAULT_BULK_TX_QUEUE_DEPTH

Default TX ring buffer slot count.

USBD_CDC_ECM_DEFAULT_BULK_TX_TIMEOUT_MS

Default blocking-transmit timeout in ms.

USBD_CDC_ECM_DEFAULT_RX_TASK_STACK_SIZE

Default RX delivery task stack size in bytes.

USBD_CDC_ECM_DEFAULT_RX_TASK_PRIORITY

Default RX delivery task priority.

USBD_CDC_ECM_STATE_TRACE_ENABLE
USBD_CDC_ECM_COMM_INTERFACE_NUM

Communication interface

USBD_CDC_ECM_DATA_INTERFACE_NUM

Data interface

USBD_CDC_ECM_RX_BUF_NUM

Device CDC NCM Constants

USBD_CDC_NCM_MAC_STR_LEN

Length of the MAC address in bytes.

USBD_CDC_NCM_DEFAULT_INTR_IN_INTERVAL

Default INTR IN bInterval.

USBD_CDC_NCM_DEFAULT_NTB_IN_SIZE

Default dwNtbInMaxSize.

USBD_CDC_NCM_DEFAULT_NTB_OUT_SIZE

Default dwNtbOutMaxSize.

USBD_CDC_NCM_DEFAULT_NTB_OUT_MAX_DATAGRAMS

Default wNtbOutMaxDatagrams.

USBD_CDC_NCM_DEFAULT_BULK_TX_TIMEOUT_MS

Default blocking-transmit timeout in ms.

USBD_CDC_NCM_DEFAULT_RX_TASK_STACK_SIZE

Default RX delivery task stack size in bytes.

USBD_CDC_NCM_DEFAULT_RX_TASK_PRIORITY

Default RX delivery task priority.

USBD_CDC_NCM_DEFAULT_TX_NTB_DEPTH

Default TX NTB ring slot count.

USBD_CDC_NCM_DEFAULT_NTB_IN_MAX_DATAGRAMS

Datagrams per IN NTB; always 1 without aggregation.

USBD_CDC_NCM_MIN_TX_NTB_DEPTH
USBD_CDC_NCM_STATE_TRACE_ENABLE
USBD_CDC_NCM_RX_BUF_NUM

Device Composite Constants

USBD_COMP_MAX_FUNCS

Maximum number of sub-functions in one composite device.

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_TP_TRACE_DEBUG

This define is used to trace transfer performance

USBD_MAX_NUM_INTERFACES
USBD_MAX_NUM_CONFIGURATION
USBD_MIN_CTRL_BUF_LEN

Minimum EP0 control transfer buffer length in bytes.

Used when usbd_config_t::ctrl_xfer_buf_len is 0 or smaller. Shall be >= USBD_MIN_CTRL_BUF_LEN to handle standard enumeration.

USBD_MAX_STR_NUM

Number of class/application string descriptors held by the core string table.

The table covers the strings registered through usbd_add_string only, whose indices start right above USBD_IDX_SERIAL_STR. The device-global strings (LANGID, manufacturer, product, serial number) occupy the fixed indices below and are answered straight from usbd_dev_info_t, so they consume no slot.

USBD_CLASS_STR_IDX_BASE

First string index handed out by usbd_add_string.

USBD_SN_STR_LEN

Length in characters of the serial number usbd_get_uuid_sn builds, without the terminator.

备注

This sizes the buffer for that helper only. A serial number assigned to usbd_dev_info_t::sn_str is referenced by pointer, so it may be of any length that still fits a string descriptor, refer to usbd_get_str_descriptor.

Device DFU Constants

Descriptor layout, request codes and flash parameters of the DFU class

USBD_DFU_DEFAULT_XFER_SIZE

Default maximum firmware block transfer size per DNLOAD/UPLOAD request.

USBD_DFU_DEFAULT_DETACH_TIMEOUT

Default DFU detach timeout (ms), reported as wDetachTimeOut.

USBD_DFU_DEFAULT_IFACE_STRING

Default iInterface string.

USBD_DFU_DEFAULT_WRITE_TASK_STACK
USBD_DFU_DEFAULT_WRITE_TASK_PRIORITY
USBD_DFU_DEFAULT_WRITE_POLL_MS

Default ms reported in bwPollTimeout during DNLOAD; 0 lets the host poll immediately.

USBD_DFU_DEFAULT_MANIFEST_TASK_STACK
USBD_DFU_DEFAULT_MANIFEST_TASK_PRIORITY
USBD_DFU_DEFAULT_MANIFEST_POLL_MS

Default ms reported as bwPollTimeout during MANIFEST.

USBD_DFU_CFG_IF_PROTOCOL_OFFSET
USBD_DFU_CFG_IF_ISTR_OFFSET
USBD_DFU_CFG_DETACH_TIMEOUT_OFFSET
USBD_DFU_CFG_XFER_SIZE_OFFSET
USBD_DFU_DEFAULT_REENUM_TASK_STACK
USBD_DFU_DEFAULT_REENUM_TASK_PRIORITY
USBD_DFU_DEFAULT_DETACH_STATUS_DELAY_MS

Default delay (ms) after DFU_DETACH so its control status stage completes before detach.

Device HID Constants

USBD_HID_INTR_IN_BUF_SIZE

Default INTR IN transfer buffer size.

USBD_HID_INTR_OUT_BUF_SIZE

Default INTR OUT transfer buffer size, one max packet: the keyboard LED report is a single byte.

USBD_HID_DEFAULT_FS_INTR_INTERVAL

Default INTR bInterval at Full Speed.

USBD_HID_DEFAULT_HS_INTR_INTERVAL

Default INTR bInterval at High Speed.

USBD_HID_HS_INT_MAX_PACKET_SIZE

High speed INTR maximum packet size

USBD_HID_FS_INT_MAX_PACKET_SIZE

Full speed INTR maximum packet size

USBD_HID_DESC_SIZE

HID descriptor size.

USBD_HID_DESC_ITEM_LENGTH_OFFSET

Offset of report desc wItemLength in the HID descriptor.

USBD_HID_CFG_DESC_ITEM_LENGTH_OFFSET

Offset of report desc wItemLength in the config descriptor.

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_DEFAULT_TX_TASK_PRIORITY

Default TX task priority.

USBD_MSC_DEFAULT_RX_TASK_PRIORITY

Default RX task priority.

USBD_MSC_DEFAULT_TRX_TASK_STACK_SIZE

Default TX/RX task stack size in bytes.

USBD_MSC_DEFAULT_BUF_SIZE

Default size of the internal data buffer.

USBD_MSC_INQUIRY_VENDOR_LEN

Vendor identification field length.

USBD_MSC_INQUIRY_PRODUCT_LEN

Product identification field length.

USBD_MSC_INQUIRY_REVISION_LEN

Product revision level field length.

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

Size of the CBW buffer.

备注

The BULK OUT DMA window is always a multiple of the endpoint max packet size, so the buffer used to receive the 31-byte CBW shall be able to hold a full max packet.

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

Device UAC Constants

USBD_UAC_DEBUG

Enable/Disable UAC debug feature.

USBD_UAC_ISOC_RX_APPEND_ZLP_DIFF_MAX

SOF-to-data desync threshold before the OUT ISR helper starts appending ZLP filler nodes. Prevents readers from stalling when the host silences the ISOC stream (e.g. switching tracks).

USBD_UAC_POW2(n)

2^(n) shorthand used across UAC MPS/ring/interval scaling.

USBD_UAC_DEFAULT_RX_BUF_CNT

Default RX ring buffer slot count.

USBD_UAC_DEFAULT_TX_BUF_CNT

Default TX ring buffer slot count.

USBD_UAC_RING_NODE_COUNT_MAX

Ring buffer node limit, the ring manager counts nodes in a u8.

USBD_UAC_BUFFER_COUNT_MAX

Largest UAC 2.0 rx/tx_buf_cnt: high speed uses 8 nodes per slot.

USBD_UAC_DEFAULT_VOLUME_MIN

Default minimum volume.

USBD_UAC_DEFAULT_VOLUME_MAX

Default maximum volume.

USBD_UAC_DEFAULT_VOLUME

Default initial volume.

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_SAMPLING_FREQ_8K

Audio 8000 sample frequency.

USBD_UAC_SAMPLING_FREQ_16K

Audio 16000 sample frequency.

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.

USBD_UAC_DEFAULT_CH_CNT

Playback max channel count.

USBD_UAC_DEFAULT_BYTE_WIDTH

Playback byte width.

USBD_UAC_OUT_MAX_SAMPLING_FREQ

Playback max sampling frequency.

USBD_UAC_IN_DEFAULT_CH_CNT

Default microphone channel count.

USBD_UAC_IN_DEFAULT_BYTE_WIDTH

Default microphone byte width.

USBD_UAC_IN_DEFAULT_SAMPLING_FREQ

Default microphone sampling frequency.

Device UVC Constants

Interface indices, event codes and descriptor lengths of the UVC class

USBD_UVC_INTF_CONTROL
USBD_UVC_INTF_STREAMING
USBD_UVC_EVENT_FIRST
USBD_UVC_EVENT_CONNECT
USBD_UVC_EVENT_DISCONNECT
USBD_UVC_EVENT_STREAMON
USBD_UVC_EVENT_STREAMOFF
USBD_UVC_EVENT_SETUP
USBD_UVC_EVENT_DATA
USBD_UVC_EVENT_LAST
USBD_UVC_CMD_THREAD_PRIORITY
USBD_UVC_NUM_REQUESTS
USBD_UVC_MAX_REQUEST_SIZE
USBD_UVC_MAX_EVENTS
USBD_TUNING_MODE
USBD_TUNING_W
USBD_TUNING_H
USBD_UVC_WEBCAM_VENDOR_ID
USBD_UVC_WEBCAM_PRODUCT_ID
USBD_UVC_WEBCAM_DEVICE_BCD
USBD_UVC_MFG_HS_STRING
USBD_UVC_MFG_FS_STRING
USBD_UVC_MAKE_SUBCMD(data, dir, subcmd)
USBD_UVC_STRING_CONTROL_IDX
USBD_UVC_STRING_STREAMING_IDX
USBD_UVC_INTF_VIDEO_CONTROL
USBD_UVC_INTF_VIDEO_STREAMING
USBD_UVC_STATUS_MAX_PACKET_SIZE
USBD_UVC_ISO_IN_EP
USBD_UVC_IN_BUF_SIZE
USBD_UVC_IN_SLOT_CNT
USBD_UVC_PAYLOAD_HEADER_LEN
USBD_UVC_STALL_SOF_MAX
USBD_UVC_DUMP_INTERVAL_MS
USBD_UVC_ISOC_EP_MPS
USBD_UVC_ISOC_EP_BINTERVAL
USBD_UVC_ISOC_EP_TRANS_CNT
USBD_UVC_ISOC_EP_MPKT
USBD_UVC_PROBE_BMHINT
USBD_UVC_YUY2_BPP
USBD_UVC_NV12_SIZE_NUM
USBD_UVC_NV12_SIZE_DEN
USBD_UVC_FRAME_INTERVAL_UNIT
USBD_UVC_GET_LEN_RESP_SIZE
USBD_UVC_GET_INFO_CAPS
USBD_UVC_FRAME_INTERVAL_CNT
USBD_UVC_BMREQTYPE_DIR_IN
USBD_UVC_CLOCK_FREQUENCY
USBD_UVC_KEYFRAME_GATE_FRAMES
USBD_UVC_DEBUG
USBD_UVC_USE_EXTENSION_UNIT
USBD_UVC_XU_DESC_LEN
USBD_UVC_OT_SOURCE_ID
USBD_UVC_VC_INTR_EP_DESC_LEN

Device Vendor Constants

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

Default INTR/ISOC bInterval, both speeds.

Device Video Constants

UVC descriptor subtypes, control selectors and request codes used by the UVC class

USBD_UVC_SC_UNDEFINED
USBD_UVC_SC_VIDEOCONTROL
USBD_UVC_SC_VIDEOSTREAMING
USBD_UVC_SC_VIDEO_INTERFACE_COLLECTION
USBD_UVC_PC_PROTOCOL_UNDEFINED
USBD_UVC_VC_DESCRIPTOR_UNDEFINED
USBD_UVC_VC_HEADER
USBD_UVC_VC_INPUT_TERMINAL
USBD_UVC_VC_OUTPUT_TERMINAL
USBD_UVC_VC_SELECTOR_UNIT
USBD_UVC_VC_PROCESSING_UNIT
USBD_UVC_VC_EXTENSION_UNIT
USBD_UVC_VS_UNDEFINED
USBD_UVC_VS_INPUT_HEADER
USBD_UVC_VS_OUTPUT_HEADER
USBD_UVC_VS_STILL_IMAGE_FRAME
USBD_UVC_VS_FORMAT_UNCOMPRESSED
USBD_UVC_VS_FRAME_UNCOMPRESSED
USBD_UVC_VS_FORMAT_MJPEG
USBD_UVC_VS_FRAME_MJPEG
USBD_UVC_VS_FORMAT_MPEG2TS
USBD_UVC_VS_FORMAT_DV
USBD_UVC_VS_COLORFORMAT
USBD_UVC_VS_FORMAT_FRAME_BASED
USBD_UVC_VS_FRAME_FRAME_BASED
USBD_UVC_VS_FORMAT_STREAM_BASED
USBD_UVC_EP_UNDEFINED
USBD_UVC_EP_GENERAL
USBD_UVC_EP_ENDPOINT
USBD_UVC_EP_INTERRUPT
USBD_UVC_RC_UNDEFINED
USBD_UVC_SET_CUR
USBD_UVC_GET_CUR
USBD_UVC_GET_MIN
USBD_UVC_GET_MAX
USBD_UVC_GET_RES
USBD_UVC_GET_LEN
USBD_UVC_GET_INFO
USBD_UVC_GET_DEF
USBD_UVC_VC_CONTROL_UNDEFINED
USBD_UVC_VC_VIDEO_POWER_MODE_CONTROL
USBD_UVC_VC_REQUEST_ERROR_CODE_CONTROL
USBD_UVC_TE_CONTROL_UNDEFINED
USBD_UVC_SU_CONTROL_UNDEFINED
USBD_UVC_SU_INPUT_SELECT_CONTROL
USBD_UVC_CT_CONTROL_UNDEFINED
USBD_UVC_CT_SCANNING_MODE_CONTROL
USBD_UVC_CT_AE_MODE_CONTROL
USBD_UVC_CT_AE_PRIORITY_CONTROL
USBD_UVC_CT_EXPOSURE_TIME_ABSOLUTE_CONTROL
USBD_UVC_CT_EXPOSURE_TIME_RELATIVE_CONTROL
USBD_UVC_CT_FOCUS_ABSOLUTE_CONTROL
USBD_UVC_CT_FOCUS_RELATIVE_CONTROL
USBD_UVC_CT_FOCUS_AUTO_CONTROL
USBD_UVC_CT_IRIS_ABSOLUTE_CONTROL
USBD_UVC_CT_IRIS_RELATIVE_CONTROL
USBD_UVC_CT_ZOOM_ABSOLUTE_CONTROL
USBD_UVC_CT_ZOOM_RELATIVE_CONTROL
USBD_UVC_CT_PANTILT_ABSOLUTE_CONTROL
USBD_UVC_CT_PANTILT_RELATIVE_CONTROL
USBD_UVC_CT_ROLL_ABSOLUTE_CONTROL
USBD_UVC_CT_ROLL_RELATIVE_CONTROL
USBD_UVC_CT_PRIVACY_CONTROL
USBD_UVC_PU_CONTROL_UNDEFINED
USBD_UVC_PU_BACKLIGHT_COMPENSATION_CONTROL
USBD_UVC_PU_BRIGHTNESS_CONTROL
USBD_UVC_PU_CONTRAST_CONTROL
USBD_UVC_PU_GAIN_CONTROL
USBD_UVC_PU_POWER_LINE_FREQUENCY_CONTROL
USBD_UVC_PU_HUE_CONTROL
USBD_UVC_PU_SATURATION_CONTROL
USBD_UVC_PU_SHARPNESS_CONTROL
USBD_UVC_PU_GAMMA_CONTROL
USBD_UVC_PU_WHITE_BALANCE_TEMPERATURE_CONTROL
USBD_UVC_PU_WHITE_BALANCE_TEMPERATURE_AUTO_CONTROL
USBD_UVC_PU_WHITE_BALANCE_COMPONENT_CONTROL
USBD_UVC_PU_WHITE_BALANCE_COMPONENT_AUTO_CONTROL
USBD_UVC_PU_DIGITAL_MULTIPLIER_CONTROL
USBD_UVC_PU_DIGITAL_MULTIPLIER_LIMIT_CONTROL
USBD_UVC_PU_HUE_AUTO_CONTROL
USBD_UVC_PU_ANALOG_VIDEO_STANDARD_CONTROL
USBD_UVC_PU_ANALOG_LOCK_STATUS_CONTROL
USBD_UVC_VS_CONTROL_UNDEFINED
USBD_UVC_VS_PROBE_CONTROL
USBD_UVC_VS_COMMIT_CONTROL
USBD_UVC_VS_STILL_PROBE_CONTROL
USBD_UVC_VS_STILL_COMMIT_CONTROL
USBD_UVC_VS_STILL_IMAGE_TRIGGER_CONTROL
USBD_UVC_VS_STREAM_ERROR_CODE_CONTROL
USBD_UVC_VS_GENERATE_KEY_FRAME_CONTROL
USBD_UVC_VS_UPDATE_FRAME_SEGMENT_CONTROL
USBD_UVC_VS_SYNC_DELAY_CONTROL
USBD_UVC_TT_VENDOR_SPECIFIC
USBD_UVC_TT_STREAMING
USBD_UVC_ITT_VENDOR_SPECIFIC
USBD_UVC_ITT_CAMERA
USBD_UVC_ITT_MEDIA_TRANSPORT_INPUT
USBD_UVC_OTT_VENDOR_SPECIFIC
USBD_UVC_OTT_DISPLAY
USBD_UVC_OTT_MEDIA_TRANSPORT_OUTPUT
USBD_UVC_EXTERNAL_VENDOR_SPECIFIC
USBD_UVC_COMPOSITE_CONNECTOR
USBD_UVC_SVIDEO_CONNECTOR
USBD_UVC_COMPONENT_CONNECTOR
USBD_UVC_STATUS_TYPE_CONTROL
USBD_UVC_STATUS_TYPE_STREAMING
USBD_UVC_STREAM_EOH
USBD_UVC_STREAM_ERR
USBD_UVC_STREAM_STI
USBD_UVC_STREAM_RES
USBD_UVC_STREAM_SCR
USBD_UVC_STREAM_PTS
USBD_UVC_STREAM_EOF
USBD_UVC_STREAM_FID
USBD_UVC_CONTROL_CAP_GET
USBD_UVC_CONTROL_CAP_SET
USBD_UVC_CONTROL_CAP_DISABLED
USBD_UVC_CONTROL_CAP_AUTOUPDATE
USBD_UVC_CONTROL_CAP_ASYNCHRONOUS
USBD_UVC_FORMAT_TYPE_YUY2
USBD_UVC_FORMAT_TYPE_NV12
USBD_UVC_FORMAT_TYPE_MJPEG
USBD_UVC_FORMAT_TYPE_H264
USBD_UVC_FORMAT_TYPE_H265
USBD_UVC_FRAME_WIDTH
USBD_UVC_FRAME_HEIGHT
USBD_UVC_JPEG_FRAME_WIDTH
USBD_UVC_JPEG_FRAME_HEIGHT

Device Video Macros

Frame-rate and little-endian helper macros of the UVC protocol

USBD_UVC_FPS(fps)
USBD_UVC_WBVAL(x)

Device WHC Constants

Identity defaults, endpoint sizing and firmware type codes of the WHC class

USBD_WHC_VID
USBD_WHC_PID
USBD_NIC_PID

NIC mode PID (used to patch device descriptor at runtime).

USBD_WHC_MFG_STRING

Manufacturer string.

USBD_WHC_PROD_STRING

Product string.

USBD_WHC_SN_STRING

Serial number string.

USBD_WHC_BT_STRING

Bluetooth interface string.

USBD_WHC_HS_BULK_MPS
USBD_WHC_FS_BULK_MPS
USBD_WHC_HS_INTR_MPS
USBD_WHC_FS_INTR_MPS
USBD_WHC_BT_EP_INTR_IN
USBD_WHC_BT_EP_BULK_OUT
USBD_WHC_BT_EP_BULK_IN
USBD_WHC_BT_EP_ISOC_IN
USBD_WHC_BT_EP_ISOC_OUT
USBD_WHC_WIFI_EP_BULK_IN
USBD_WHC_WIFI_EP_BULK_OUT_1
USBD_WHC_WIFI_EP_BULK_OUT_2
USBD_WHC_WIFI_EP_BULK_OUT_3
USBD_WHC_WIFI_BULK_OUT_EP_NUM
USBD_WHC_BT_ITF_CLASS
USBD_WHC_BT_ITF_SUBCLASS
USBD_WHC_BT_ITF_PROTOCOL
USBD_WHC_WIFI_ITF_CLASS
USBD_WHC_WIFI_ITF_SUBCLASS
USBD_WHC_WIFI_ITF_PROTOCOL
USBD_WHC_ETH_ITF_CLASS
USBD_WHC_ETH_ITF_SUBCLASS
USBD_WHC_ETH_ITF_PROTOCOL
USBD_WHC_VENDOR_REQ_BT_HCI_CMD
USBD_WHC_VENDOR_REQ_FW_DOWNLOAD
USBD_WHC_VENDOR_QUERY_CMD
USBD_WHC_VENDOR_QUERY_ACK
USBD_WHC_VENDOR_RESET_CMD
USBD_WHC_VENDOR_RESET_ACK
USBD_WHC_FW_TYPE_APPLICATION

Device WHC OTP Constants

String length limits of the OTP-latched device identity

USBD_OTP_MAX_STR_LEN

Maximum length in bytes of an OTP-stored identity string.

USB Device Types

Device CDC ACM Types

struct usbd_cdc_acm_config_t
#include <usbd_cdc_acm.h>

Configuration for the CDC ACM class.

Carries every CDC ACM option: the endpoint allocation, which the top-level application owns, plus the class feature switches. Used by both standalone and composite modes. Device-global parameters (VID/PID, strings, power attributes) live in usbd_dev_info_t instead, and application-level options such as hotplug or task priorities belong in the example's own configuration structure.

备注

The structure is stored by pointer, not copied, so it shall remain valid until usbd_cdc_acm_deinit.

Public Members

u32 bulk_in_xfer_size

BULK IN transfer buffer size.

u32 bulk_out_xfer_size

BULK OUT transfer buffer size.

const char *itf_str

iInterface string of the communication interface, NULL for none.

u8 bulk_in_addr

BULK IN endpoint address (e.g. 0x81).

u8 bulk_out_addr

BULK OUT endpoint address (e.g. 0x01).

u8 intr_in_addr

INTERRUPT IN endpoint address (e.g. 0x83). Ignored unless notify_en is set.

u8 intr_in_interval_hs

INTR IN bInterval at High Speed, 0 uses USBD_CDC_ACM_DEFAULT_INTR_IN_INTERVAL.

u8 intr_in_interval_fs

INTR IN bInterval at Full Speed, 0 uses USBD_CDC_ACM_DEFAULT_INTR_IN_INTERVAL.

u8 notify_en

Enable the INTR IN notification endpoint (0: Disable, 1: Enable).

When disabled the class exposes no INTR IN endpoint, the communication interface reports bNumEndpoints 0, and usbd_cdc_acm_notify_serial_state fails. Saves one endpoint and its TxFIFO for a host that never reads SERIAL_STATE.

u8 bulk_in_zero_copy

Transmit directly from the caller's buffer instead of copying (0: Disable, 1: Enable).

Avoids one memcpy per BULK IN transfer, but the caller's buffer shall be USB_DMA_ALIGNED and shall stay valid and unmodified until the transmitted callback reports completion.

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.

备注

This function is called within an interrupt service routine (ISR) context; time-consuming operations (e.g., malloc, rtos_sema_take) are not permitted.

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.

备注

This function is called within an interrupt service routine (ISR) context; time-consuming operations (e.g., malloc, rtos_sema_take) are not permitted.

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)(int status)

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

备注

This function is called within an interrupt service routine (ISR) context; time-consuming operations (e.g., malloc, rtos_sema_take) are not permitted.

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.

备注

This function is called within an interrupt service routine (ISR) context; time-consuming operations (e.g., malloc, rtos_sema_take) are not permitted.

Param old_status:

[in] The previous attach status.

Param status:

[in] The new attach status.

void (*wakeup)(void)

Called when the USB device resumes from suspend (wakeup).

Indicates that the USB bus is active again and the upper layer can resume normal TRX.

备注

This function is called within an interrupt service routine (ISR) context; time-consuming operations (e.g., malloc, rtos_sema_take) are not permitted.

struct usbd_cdc_acm_dev_t
#include <usbd_cdc_acm.h>

Structure representing the CDC ACM device instance.

Public Members

const usbd_cdc_acm_config_t *cfg

Pointer to the class configuration (set by init).

const usbd_cdc_acm_cb_t *cb

Pointer to the user-defined callback structure.

usb_dev_t *dev

Pointer to the USB device instance.

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_setup_req_t ctrl_req

Stores the current control request (byte-packed).

u8 ctrl_req_pending

1 if ctrl_req is waiting for its EP0 OUT data stage.

u8 from_composite

Flag indicating if part of a composite device.

u8 if_base

First interface number of this class; 0 in standalone mode unless the composite framework rebases it via set_interface_base().

u8 itf_str_idx

iInterface string index from usbd_add_string(), 0 for none.

Device CDC ECM Types

struct usbd_cdc_ecm_config_t
#include <usbd_cdc_ecm.h>

Configuration for the CDC ECM class.

Carries every CDC ECM option: the endpoint allocation, which the top-level application owns, plus the MAC address and the TX/RX resource sizing. Used by both standalone and composite modes. Device-global parameters (VID/PID, strings, power attributes) live in usbd_dev_info_t instead, and application-level options such as hotplug or the network configuration belong in the example's own configuration structure.

备注

The structure is stored by pointer, not copied, so it shall remain valid until usbd_cdc_ecm_deinit.

Public Members

const u8 *mac

MAC address reported to the host, 6 bytes, NULL for the class default.

Copied into the class at init and formatted into the iMACAddress string, so the buffer itself needs not outlive the init call.

const char *itf_str

iInterface string of the communication interface, NULL for none.

u16 bulk_tx_timeout_ms

Blocking-transmit timeout in ms, 0 uses USBD_CDC_ECM_DEFAULT_BULK_TX_TIMEOUT_MS.

u16 rx_task_stack_size

RX delivery task stack size in bytes, 0 uses USBD_CDC_ECM_DEFAULT_RX_TASK_STACK_SIZE.

u8 bulk_in_addr

BULK IN endpoint address (e.g. 0x81).

u8 bulk_out_addr

BULK OUT endpoint address (e.g. 0x01).

u8 intr_in_addr

INTERRUPT IN endpoint address (e.g. 0x83).

u8 intr_in_interval_hs

INTR IN bInterval at High Speed, 0 uses USBD_CDC_ECM_DEFAULT_INTR_IN_INTERVAL.

u8 intr_in_interval_fs

INTR IN bInterval at Full Speed, 0 uses USBD_CDC_ECM_DEFAULT_INTR_IN_INTERVAL.

u8 bulk_tx_queue_depth

Number of Ethernet frames the TX ring buffer can hold, 0 uses USBD_CDC_ECM_DEFAULT_BULK_TX_QUEUE_DEPTH.

Each slot costs one max-size segment of heap, and deeper queues absorb longer bursts before usbd_cdc_ecm_transmit has to block or drop.

u8 rx_task_priority

RX delivery task priority, 0 uses USBD_CDC_ECM_DEFAULT_RX_TASK_PRIORITY.

struct usbd_cdc_ecm_cb_t
#include <usbd_cdc_ecm.h>

Structure containing callback functions for the CDC ECM class.

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

Public Members

int (*init)(void)

Called during CDC ECM class driver initialization to set up application resources.

Return:

0 on success, non-zero on failure.

int (*deinit)(void)

Called when the CDC ECM 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.

备注

This function is called within an interrupt service routine (ISR) context; time-consuming operations (e.g., malloc, rtos_sema_take) are not permitted.

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 (*status_changed)(u8 old_status, u8 status)

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

备注

This function is called within an interrupt service routine (ISR) context; time-consuming operations (e.g., malloc, rtos_sema_take) are not permitted.

Param old_status:

[in] The previous attach status.

Param status:

[in] The new attach status.

struct usbd_cdc_ecm_dev_t
#include <usbd_cdc_ecm.h>

Structure representing the CDC ECM device instance.

Public Members

const usbd_cdc_ecm_config_t *cfg

Pointer to the class configuration (set by init).

const usbd_cdc_ecm_cb_t *cb

User-defined callback structure.

usb_dev_t *dev

USB device instance.

u8 data_alt_setting

Alternate setting currently selected for the DATA interface: 0 = default setting, no endpoints; 1 = BULK IN/OUT initialised. Ref CDC ECM 1.2 3.2.2 / USB 2.0 9.4.10: alt 0 has bNumEndpoints = 0, so the BULK pipes exist only in alt 1. Written only by usbd_ecm_data_alt_start()/_stop(), which keep it in lockstep with the real endpoint state. It therefore serves both purposes at once: the value GET_INTERFACE reports, and the "BULK endpoints are alive" predicate guarding every TX/RX submission. Deliberately distinct from connect_status, which is the link state reported to the host and also depends on the uplink state. The communication interface has alt 0 only, so it needs no field - GET_INTERFACE answers it with a literal 0. ISR writes (setup/clear_config/status_changed); task reads (transmit), hence volatile.

u8 connect_status

Link state last reported to the host by NETWORK_CONNECTION: 1 only while the data interface is in alt 1 and the uplink is up. Written only in USB ISR context (setup/SOF/clear_config/ status_changed); tasks only read it. Must be volatile.

Upper-layer (uplink) link state set by usbd_cdc_ecm_set_link_status(), 1=up, 0=down. Written only by that task-context API, only read by the USB ISR, so it needs no lock. Starts at 0 on every init.

u8 notify_state

Active notification type. Written only in USB ISR context.

u8 notify_retry

1 when a notification send failed or is queued; SOF handler (ISR) retries it. Must be volatile.

u8 ctrl_req_pending

1 if ctrl_req is waiting for its EP0 OUT data stage.

u8 from_composite

Flag indicating if part of a composite device.

u8 if_base

First interface number of this class; 0 in standalone mode unless the composite framework rebases it via set_interface_base().

u8 *bulk_tx_dma_buf

DMA source for BULK IN. A frame is copied here from the ring buffer head before each transfer, so the DMA never reads ring buffer memory directly. Size = USBD_CDC_ECM_BULK_BUF_MAX_SIZE.

usb_os_sema_t bulk_tx_slot_sema

ISR -> tcpip: given each time a ring buffer slot is freed.

usb_ringbuf_manager_t bulk_tx_rb

TX ring buffer: queues frames while a DMA is in flight.

u8 is_closing

Set by deinit: transmit() rejects new callers before the TX resources are released. Written under the USB critical section.

u8 xfer_users

Number of tasks inside usbd_cdc_ecm_transmit(); deinit waits for it to drop to 0. Updated under the USB critical section.

usb_os_sema_t rx_data_ready_sema

ISR -> thread: signals a buffer holds a frame.

usb_os_task_t rx_task

RX delivery thread handle.

u8 *rx_buf[USBD_CDC_ECM_RX_BUF_NUM]

Ping-pong RX buffers (ISR and RxThread).

u8 *rx_msg_buf

Buffer pointer handed to the RX thread for current frame.

u32 rx_msg_len

Frame length handed to the RX thread.

u32 rx_pending_len

Deferred frame length waiting in rx_buf[rx_xfer_idx]. ISR writes, task reads.

u8 rx_xfer_idx

Index of the buffer currently armed for USB OUT (0 or 1).

u8 rx_buf_free

thread->ISR: 1=buffer available, 0=held by RX thread.

u8 rx_thread_running

RX thread loop guard; cleared to 0 to request exit.

usbd_ep_t ep_bulk_in

BULK IN endpoint.

usbd_ep_t ep_bulk_out

BULK OUT endpoint.

usbd_ep_t ep_intr_in

INTERRUPT IN endpoint.

usb_setup_req_t ctrl_req

Saved control request for EP0 OUT data phase.

u8 mac[USBD_CDC_ECM_MAC_STR_LEN]

Device MAC address (6 bytes).

char mac_str[(USBD_CDC_ECM_MAC_STR_LEN * 2U) + 1U]

MAC address as the 12 uppercase hex characters the iMACAddress string reports.

Registered with the core by pointer, so it has to outlive enumeration rather than being formatted into a local buffer on each request.

u8 mac_str_idx

iMACAddress string index from usbd_add_string(), 0 for none.

u8 itf_str_idx

Communication interface iInterface string index from usbd_add_string(), 0 for none.

Device CDC NCM Types

struct usbd_cdc_ncm_config_t
#include <usbd_cdc_ncm.h>

Configuration for the CDC NCM class.

Carries every CDC NCM option: the endpoint allocation, which the top-level application owns, plus the MAC address, the advertised NTB parameters and the TX/RX resource sizing. Used by both standalone and composite modes. Device-global parameters (VID/PID, strings, power attributes) live in usbd_dev_info_t instead, and application-level options such as hotplug or the network configuration belong in the example's own configuration structure.

备注

The structure is stored by pointer, not copied, so it shall remain valid until usbd_cdc_ncm_deinit.

Public Members

const u8 *mac

MAC address reported to the host, 6 bytes, NULL for the class default.

Copied into the class at init and formatted into the iMACAddress string, so the buffer itself needs not outlive the init call.

const char *itf_str

iInterface string of the communication interface, NULL for none.

u32 ntb_in_max_size

dwNtbInMaxSize advertised in GET_NTB_PARAMETERS, 0 uses USBD_CDC_NCM_DEFAULT_NTB_IN_SIZE.

Upper bound on what SET_NTB_INPUT_SIZE may negotiate, so it shall be at least USB_CDC_NCM_MIN_NTB_INPUT_SIZE. It may exceed what one TX slot buffer holds: a device may always emit NTBs smaller than the maximum it advertises, and the class clamps every NTB to the slot capacity that ntb_in_max_datagrams sets.

u32 ntb_out_max_size

dwNtbOutMaxSize advertised in GET_NTB_PARAMETERS, 0 uses USBD_CDC_NCM_DEFAULT_NTB_OUT_SIZE.

Also sizes the two ping-pong RX buffers, because the device shall be able to receive a whole max-size OUT NTB in one transfer.

u16 bulk_tx_timeout_ms

Blocking-transmit timeout in ms, 0 uses USBD_CDC_NCM_DEFAULT_BULK_TX_TIMEOUT_MS.

u16 rx_task_stack_size

RX delivery task stack size in bytes, 0 uses USBD_CDC_NCM_DEFAULT_RX_TASK_STACK_SIZE.

u16 tx_task_stack_size

TX aggregation task stack size in bytes, 0 uses USBD_CDC_NCM_DEFAULT_TX_TASK_STACK_SIZE. Ignored unless CONFIG_USBD_CDC_NCM_TX_AGGREGATION.

u16 tx_sema_timeout_ms

TX aggregation task safety-net wake-up period in ms, 0 uses USBD_CDC_NCM_DEFAULT_TX_SEMA_TIMEOUT_MS. Ignored unless CONFIG_USBD_CDC_NCM_TX_AGGREGATION.

u8 bulk_in_addr

BULK IN endpoint address (e.g. 0x81).

u8 bulk_out_addr

BULK OUT endpoint address (e.g. 0x01).

u8 intr_in_addr

INTERRUPT IN endpoint address (e.g. 0x83).

u8 intr_in_interval_hs

INTR IN bInterval at High Speed, 0 uses USBD_CDC_NCM_DEFAULT_INTR_IN_INTERVAL.

u8 intr_in_interval_fs

INTR IN bInterval at Full Speed, 0 uses USBD_CDC_NCM_DEFAULT_INTR_IN_INTERVAL.

u8 tx_ntb_depth

Number of TX NTB ring slots, 0 uses USBD_CDC_NCM_DEFAULT_TX_NTB_DEPTH.

The SPSC ring keeps one empty gap between the write and the read index, so the usable depth is one less than this and the minimum accepted value is USBD_CDC_NCM_MIN_TX_NTB_DEPTH. Each slot owns one NTB buffer, whose size ntb_in_max_datagrams determines.

u8 ntb_in_max_datagrams

Ethernet frames aggregated into one device-to-host (IN) NTB, 0 uses USBD_CDC_NCM_DEFAULT_NTB_IN_MAX_DATAGRAMS.

"IN" is the USB direction (Ref NCM 1.0: IN = device-to-host), so this is purely a property of what the device emits; it is not the ntb_out_max_datagrams limit advertised for the opposite direction.

It sizes both the NDP16 directory a slot reserves, 8 + (value + 1) * 4 bytes, and the slot buffer itself, which holds that directory plus value max-size frames. A higher value lowers the per-frame NTB overhead and the number of USB transfers a small-packet burst costs, at a linearly growing heap cost: ~3 KB per slot at 2, ~6 KB at 4. Ignored unless CONFIG_USBD_CDC_NCM_TX_AGGREGATION: without it the lwIP task builds one-frame NTBs and the class forces 1.

u8 ntb_out_max_datagrams

wNtbOutMaxDatagrams advertised in GET_NTB_PARAMETERS, 0 uses USBD_CDC_NCM_DEFAULT_NTB_OUT_MAX_DATAGRAMS.

How many datagrams the host may pack into one host-to-device (OUT) NTB (Ref NCM 1.0 Table 6-3). Purely advertised: the RX parser walks every NDP entry and bounds-checks each datagram, so the real limit is ntb_out_max_size.

u8 tx_raw_queue_depth

Raw frame queue depth (lwIP -> TX task), 0 uses USBD_CDC_NCM_DEFAULT_TX_RAW_QUEUE_DEPTH. Ignored unless CONFIG_USBD_CDC_NCM_TX_AGGREGATION.

u8 rx_task_priority

RX delivery task priority, 0 uses USBD_CDC_NCM_DEFAULT_RX_TASK_PRIORITY.

u8 tx_task_priority

TX aggregation task priority, 0 uses USBD_CDC_NCM_DEFAULT_TX_TASK_PRIORITY. Ignored unless CONFIG_USBD_CDC_NCM_TX_AGGREGATION.

struct ncm_tx_ntb_t
#include <usbd_cdc_ncm.h>

One TX NTB buffer slot in the SPSC ring.

Each slot owns its own DMA-aligned NTB scratch buffer. The single producer (lwIP task) fills slot[tx_wd] with NTH16+NDP16+frame and advances tx_wd; the single consumer (USB ISR: SOF and XFRC run serially in interrupt context, never concurrently) sends slot[tx_rd] and advances tx_rd after XFRC. Because producer touches only the tx_wd slot and consumer touches only the tx_rd slot, and the ring keeps at least one empty gap between them, no lock is needed &#8212; tx_wd / tx_rd index isolation provides the mutual exclusion.

Public Members

u8 *buf

DMA-aligned NTB scratch buffer (size usbd_cdc_ncm_dev_t::ntb_tx_buf_size).

u32 data_offset

Total NTB length (bytes) once finalised; DMA transfer length.

u16 sequence

NTH16 wSequence value for this NTB.

u8 frame_count

Datagrams aggregated into this NTB so far.

struct usbd_cdc_ncm_cb_t
#include <usbd_cdc_ncm.h>

Structure containing callback functions for the CDC NCM class.

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

Public Members

int (*init)(void)

Pointer to the USB CDC NCM private data structure.

Called during CDC NCM class driver initialization to set up application resources.

Return:

0 on success, non-zero on failure.

int (*deinit)(void)

Called when the CDC NCM 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.

备注

This function is called within an interrupt service routine (ISR) context; time-consuming operations (e.g., malloc, rtos_sema_take) are not permitted.

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 (*status_changed)(u8 old_status, u8 status)

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

备注

This function is called within an interrupt service routine (ISR) context; time-consuming operations (e.g., malloc, rtos_sema_take) are not permitted.

备注

A bus suspend is also reported as USBD_ATTACH_STATUS_DETACHED, and the class then drops the data interface back to alt 0. A host resuming without re-enumeration finds the data path stopped, so the application shall reinitialize the class (usbd_cdc_ncm_deinit/usbd_deinit, then usbd_init/usbd_cdc_ncm_init) on DETACHED.

Param old_status:

[in] The previous attach status.

Param status:

[in] The new attach status.

struct usbd_cdc_ncm_dev_t
#include <usbd_cdc_ncm.h>

Structure representing the CDC NCM device instance.

Public Members

const usbd_cdc_ncm_config_t *cfg

Pointer to the class configuration (set by init).

const usbd_cdc_ncm_cb_t *cb

User-defined callback structure.

usb_dev_t *dev

USB device instance.

u8 data_alt_setting

Alternate setting currently selected for the DATA interface: 0 = default setting, no endpoints; 1 = BULK IN/OUT initialised. Ref NCM 1.0 3.1 / USB 2.0 9.4.10: alt 0 has bNumEndpoints = 0, so the BULK pipes exist only in alt 1. Written only by usbd_cdc_ncm_data_alt_start()/_stop(), which keep it in lockstep with the real endpoint state. It therefore serves both purposes at once: the value GET_INTERFACE reports, and the "BULK endpoints are alive" predicate guarding every TX/RX submission. Deliberately distinct from connect_status, which is the link state reported to the host and also depends on the uplink state. The communication interface has alt 0 only, so it needs no field - GET_INTERFACE answers it with a literal 0. ISR writes (setup/clear_config/status_changed); the lwIP and TX aggregation tasks read it, hence volatile.

u8 connect_status

Link state last reported to the host by NETWORK_CONNECTION: 1 only while the data interface is in alt 1 and the uplink is up. Written only in USB ISR context (setup/SOF/clear_config/ status_changed); tasks only read it. Must be volatile.

Upper-layer (uplink) link state set by usbd_cdc_ncm_set_link_status(), 1=up, 0=down. Written only by that task-context API, only read by the USB ISR, so it needs no lock. Starts at 0 on every init.

u8 notify_state

Active notification type. Written only in USB ISR context.

u8 notify_retry

1 when a notification send failed or is queued; SOF handler (ISR) retries it. Must be volatile.

u8 ctrl_req_pending

1 if ctrl_req is waiting for its EP0 OUT data stage.

u8 from_composite

Flag indicating if part of a composite device.

u8 if_base

First interface number of this class; 0 in standalone mode unless the composite framework rebases it via set_interface_base().

ncm_tx_ntb_t *tx_slot

SPSC TX NTB ring, tx_ntb_depth slots allocated at init.

usb_os_sema_t tx_buf_free_sema

ISR -> producer: given each XFRC when a slot is freed.

u8 tx_wd

Producer write index (TX task / lwIP task only advances this).

u8 tx_rd

Consumer read index (USB ISR only advances this).

u8 tx_inflight

1 = slot[tx_rd] is currently being DMA'd; only USB ISR touches it.

u8 tx_ntb_depth

Resolved TX NTB ring slot count (tx_slot[] length).

u8 is_closing

Set by deinit: transmit() rejects new callers before the TX resources are released. Written under the USB critical section.

u8 xfer_users

Number of tasks inside usbd_cdc_ncm_transmit(); deinit waits for it to drop to 0. Updated under the USB critical section.

u32 agg_data_offset

Offset of the first datagram in a slot, i.e. NTH16 + NDP16 directory rounded up to the datagram alignment.

u32 ntb_tx_buf_size

Allocated size of one slot buffer: agg_data_offset plus ntb_in_max_datagrams aligned max-size frames.

u16 sequence

NTB sequence number, incremented per transmitted NTB.

u8 ntb_in_max_datagrams

Resolved datagrams per IN NTB; always 1 without aggregation.

usb_os_sema_t rx_data_ready_sema

ISR -> thread: signals a buffer holds data.

usb_os_task_t rx_task

RX delivery thread handle.

u8 *rx_buf[USBD_CDC_NCM_RX_BUF_NUM]

Ping-pong RX buffers (ISR and RxThread).

u8 *rx_msg_buf

Buffer pointer handed to the RX thread for current data.

u32 rx_msg_len

Data length handed to the RX thread.

u32 rx_pending_len

Deferred data length waiting in rx_buf[rx_xfer_idx].

u32 rx_buf_size

Allocated size of one RX ping-pong buffer: a whole max-size OUT NTB, rounded up to a whole number of HS bulk packets.

u8 rx_xfer_idx

Index of the buffer currently armed for USB OUT (0 or 1).

u8 rx_buf_free

thread->ISR: 1=buffer available, 0=held by RX thread.

u8 rx_thread_running

RX thread loop guard; cleared to 0 to request exit.

u32 ntb_in_max_size

Max NTB the device may send to the host (IN), negotiated via SET_NTB_INPUT_SIZE. Also caps the TX aggregation length.

u32 ntb_out_max_size

Max NTB the host may send to the device (OUT).

u32 ntb_in_max_size_cap

dwNtbInMaxSize the device advertises, i.e. the resolved usbd_cdc_ncm_config_t::ntb_in_max_size.

Ref NCM 1.0 6.2.1: GET_NTB_PARAMETERS reports the device's fixed capability, not the value last negotiated by SET_NTB_INPUT_SIZE, so this is kept separate from ntb_in_max_size and also serves as the upper bound that request accepts.

u8 ntb_format

NTB format: 0=NTB16, currently only NTB16 supported.

u8 crc_mode

CRC mode: 0=none, currently only no-CRC supported.

usbd_ep_t ep_bulk_in

BULK IN endpoint.

usbd_ep_t ep_bulk_out

BULK OUT endpoint.

usbd_ep_t ep_intr_in

INTERRUPT IN endpoint.

usb_setup_req_t ctrl_req

Saved control request for EP0 OUT data phase.

u8 mac[USBD_CDC_NCM_MAC_STR_LEN]

Device MAC address (6 bytes).

char mac_str[(USBD_CDC_NCM_MAC_STR_LEN * 2U) + 1U]

MAC address as the 12 uppercase hex characters the iMACAddress string reports.

Registered with the core by pointer, so it has to outlive enumeration rather than being formatted into a local buffer on each request.

u8 mac_str_idx

iMACAddress string index from usbd_add_string(), 0 for none.

u8 itf_str_idx

Communication interface iInterface string index from usbd_add_string(), 0 for none.

Device Composite Types

struct usbd_composite_cb_t
#include <usbd_composite.h>

Composite user callback structure.

Public Members

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

USB attach status change callback.

struct usbd_composite_dev_t
#include <usbd_composite.h>

Composite device structure (internal).

Public Members

const usbd_class_driver_t *drivers[USBD_COMP_MAX_FUNCS]

Registered class driver array.

const usbd_composite_cb_t *cb

User callback.

u8 func_count

Number of registered sub-functions.

u8 if_counts[USBD_COMP_MAX_FUNCS]

Interface count for each sub-function (parsed from desc).

u8 active_func

Index of sub-function handling the current setup with data OUT, 0xFF if none.

u8 active_func_in

Index of sub-function handling the current setup with data IN, 0xFF if none.

u8 registered

1 between usbd_composite_init and usbd_composite_deinit.

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.

u32 xfer_len

Total length of the data to transfer.

u32 xfer_buf_len

Capacity of the class transfer buffer, 0 if unknown. For OUT endpoints it shall cover the whole DMA window, refer to usbd_ep_receive.

usb_ep_info_t info

Endpoint information: addr, mps, type, binterval, interval.

u8 xfer_state

Current state of the class transfer.

u8 tx_zlp

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

u8 is_busy

Flag indicating if the endpoint is currently busy.

u8 dis_zlp

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

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.

struct usbd_dev_info_t
#include <usbd.h>

Defines the device-global descriptor parameters shared by every class.

The core rewrites the fields below into the device and configuration descriptors returned by the class driver, so a class never has to know them. Every field is optional: a zero value keeps the class template default, which makes the whole structure omissible for an application happy with the defaults. String pointers are stored, not copied, so they shall remain valid until usbd_deinit.

备注

usbd_init copies this structure into usb_dev_t::info and resolves every default there, and the descriptor paths read that copy on each request rather than snapshotting it. A class holding values latched in hardware may therefore overwrite any field of dev->info after usbd_init and before enumeration, and the core reports the overwritten value. usbd_whc does so with its OTP parameters.

Public Members

const char *mfg_str

iManufacturer string, NULL uses "Realtek".

const char *prod_str

iProduct string, NULL uses "Realtek USB Device".

const char *sn_str

iSerialNumber string, NULL or empty reports no serial number.

备注

There is deliberately no default: reading the chip UUID costs several kilobytes of stack on some SoCs, which usbd_init cannot impose on its caller. An application wanting a UUID-derived serial number calls usbd_get_uuid_sn from a context with enough stack and assigns the result here.

u16 vid

idVendor, 0 uses USB_VID.

u16 pid

idProduct, 0 uses USB_PID.

u16 bcd_device

bcdDevice, 0 keeps the class template value.

u16 lang_id

wLANGID of the LANGID string descriptor, 0 uses 0x0409 (English US).

u8 max_power

bMaxPower in 2mA units, 0 keeps the class template value.

u8 speed

USB device speed mode. See usb_speed_type_t.

  • USB_SPEED_HIGH: USB 2.0 High-Speed PHY, the default (value 0).

  • USB_SPEED_HIGH_IN_FULL: USB 2.0 PHY driven in Full-Speed mode, for a low bandwidth application such as UAC 1.0 that has to run Full Speed on an HS-capable SoC.

  • USB_SPEED_FULL: USB 1.1 Full-Speed transceiver.

备注

An application normally leaves this 0 and lets the core pick: on an FS-only SoC (CONFIG_SUPPORT_USB_FS_ONLY) usbd_init clamps any High-Speed request down to USB_SPEED_FULL, so only a class that must down-shift a capable PHY by itself needs to set it.

u8 self_powered

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

u8 remote_wakeup_en

Advertise remote wakeup capability (0: Disable, 1: Enable).

struct usbd_config_t
#include <usbd.h>

Defines the core driver configuration parameters for the USB device.

Public Members

u16 rx_fifo_depth

RxFIFO depth in dwords, min value 16, 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. Each used TxFIFO must be at least 16 dwords.

  • For SoCs with dedicated USB FIFO, when an ISOC IN packet is too large for its TxFIFO, enable the ISOC TX threshold so the core can transmit before a whole packet is buffered. ISOC used TxFIFO must be <= MPS.

u16 ctrl_xfer_buf_len

Control transfer buffer length in bytes for EP0 IN/OUT.

Defines the size of the shared EP0 transfer buffer allocated in usbd_init. If set to 0 or less than USBD_MIN_CTRL_BUF_LEN, USBD_MIN_CTRL_BUF_LEN is used. Set this parameter to an appropriate value especially when defining a large device descriptor for a composite device.

u16 ext_intr_enable

Enables extra interrupts.

Optional USB interrupt enable flags:

  • USBD_SOF_INTR: For SOF-based timing synchronization.

u16 diag_depth

Diag ring buffer depth in entries; 0 uses USB_DIAG_DEFAULT_DEPTH. Requires diag_enable.

u16 diag_poll_ms

Diag task polling interval in ms; 0 uses USB_DIAG_DEFAULT_POLL_MS. Requires diag_enable.

usbd_dev_info_t info

Device-global descriptor parameters. See usbd_dev_info_t.

u8 isr_priority

Priority of the USB interrupt.

u8 isr_in_critical

Process the whole USB ISR, class callbacks included, inside the USB critical section (0: Disable, 1: Enable).

When enabled:

  • The callbacks run with interrupts disabled, and with the USB spinlock held under SMP: keep them short. Under SMP a USB API called on the other core spins with its interrupts disabled until the ISR has left.

  • A callback shall not take the critical section of another component, and no code shall call a USB API while holding one. Under SMP either order against the ISR on the other core deadlocks both cores.

u8 diag_enable

Enable USB diag ring buffer and polling task (0: Disable, 1: Enable). When disabled, error diagnostic information is silently lost. Enable this to capture USB error events for debugging.

u8 isoc_use_ptx_threshold

Use TX threshold (DTHRCTL) for ISOC IN transfers (Dedicated FIFO mode only).

struct usb_dev_t
#include <usbd.h>

Defines the main USB device structure.

Public Members

const struct _usbd_class_driver_t *driver

Pointer to the active class driver.

void *pcd

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

u8 dev_state

Current device state. See usbd_state_t.

u8 dev_old_state

Previous device state. See usbd_state_t.

u8 dev_attach_status

Current device attach status. See usbd_attach_status_t.

u8 dev_old_attach_status

Previous device attach status. See usbd_attach_status_t.

u8 is_ready

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

u8 is_connected

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

u8 dev_config

Current device configuration index.

u8 test_mode

Flag indicating if the device is in a test mode.

u8 dev_speed

Current device speed. See usb_speed_type_t.

u8 remote_wakeup

Remote wakeup authorized by the host (0: not authorized, 1: authorized).

Distinct from usbd_dev_info_t::remote_wakeup_en, which only advertises the capability: this one tracks whether the host has actually enabled it through SET_FEATURE(DEVICE_REMOTE_WAKEUP).

u8 str_cnt

Number of entries used in str_tbl.

const char *str_tbl[USBD_MAX_STR_NUM]

Class/application string table, string index n is held by slot n - USBD_CLASS_STR_IDX_BASE.

Holds the strings registered through usbd_add_string, which stores pointers only. The device-global indices below USBD_CLASS_STR_IDX_BASE are answered from info instead and take no slot here.

usbd_ep_t ep0_in

Control endpoint 0 IN.

usbd_ep_t ep0_out

Control endpoint 0 OUT.

usbd_dev_info_t info

Device-global descriptor parameters, with every default already resolved.

Copied from usbd_config_t::info by usbd_init, which substitutes the defaults once so that the descriptor and string paths, both running in ISR context, never have to test for one.

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, u16 buf_len)

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

备注

This callback is called within an interrupt service routine (ISR) context; time-consuming operations (e.g., malloc, rtos_sema_take) are not permitted. The class driver must return the descriptor data buffer and length against 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: Not handled by the class: the core answers the language ID and the device strings from usbd_dev_info_t, and the strings a class registers through usbd_add_string. Only an index the core does not own (e.g. the 0xEE MS OS string) is forwarded here, return 0 if unsupported.

备注

buf_len describes the physical capacity of buf only. It must not be used to truncate a descriptor: a partial configuration descriptor whose wTotalLength disagrees with the returned bytes is illegal per USB 2.0 section 9.4.3. If the descriptor does not fit, the class driver shall return 0 so that the core stalls EP0. Short reads requested by the host through wLength are handled by the core, not here; the class driver always reports the full descriptor length.

Param dev:

[in] USB device.

Param req:

[in] USB setup request.

Param buf:

[out] Buffer to store the requested descriptor.

Param buf_len:

[in] Capacity of buf in bytes. The class driver shall not write beyond it.

Return:

The actual length of the descriptor, or 0 on error / insufficient buffer.

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

Callback to set the device configuration.

备注

This callback is called within an interrupt service routine (ISR) context; time-consuming operations (e.g., malloc, rtos_sema_take) are not permitted. Called upon SET_CONFIGURATION request in ADDRESSED state. The device class driver must:

Param dev:

[in] USB device.

Param config:

[in] The configuration index to be set.

Return:

0 on success, non-zero on failure.

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

Callback to clear the device configuration.

备注

This callback is called within an interrupt service routine (ISR) context; time-consuming operations (e.g., malloc, rtos_sema_take) are not permitted. 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:

None. This is a teardown path, the bus is already gone or the configuration must drop to zero, so the core cannot act on a failure. Release best effort.

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). Ref USB 2.0 §9.4.10: on SET_INTERFACE the endpoints of the interface addressed by wIndex return to their default state, not halted and data toggle DATA0. The class shall call usbd_ep_clear_stall for them, or re-initialize them if the new alternate setting differs. This also applies to an interface having the default setting only, hosts do send SET_INTERFACE(0) to such an interface.

  • Standard endpoint requests SET_FEATURE/CLEAR_FEATURE with ENDPOINT_HALT, which the core offers to the class before handling them itself. Handle one only if the endpoint address in the low byte of wIndex belongs to this class, and only if halting or unhalting requires class bookkeeping the core cannot do, e.g. re-arming an OUT transfer or resetting a protocol state machine. Return 0 to state that the halt state change is done, any non-zero value keeps the default core handling. The core has already validated the request and completes the status stage in both cases. A class which keeps its OUT endpoint armed while halted needs none of this.

  • Class-specific requests per relevant class specifications.

  • Vendor-defined requests for custom devices.

备注

This callback is called within an interrupt service routine (ISR) context; time-consuming operations (e.g., malloc, rtos_sema_take) are not permitted.

Param dev:

[in] USB device.

Param req:

[in] USB setup request.

Return:

0 on success, non-zero on failure.

void (*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).

备注

This callback is called within an interrupt service routine (ISR) context; time-consuming operations (e.g., malloc, rtos_sema_take) are not permitted.

Param dev:

[in] USB device.

Return:

None. Ref USB 2.0 8.4.3: the SOF token has no data or handshake phase, so the device has no way to report a failure to the host.

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

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

备注

This callback is called within an interrupt service routine (ISR) context; time-consuming operations (e.g., malloc, rtos_sema_take) are not permitted.

Param dev:

[in] USB device.

Param status:

[in] Status of the completed transfer.

Return:

0 if this class owns the endpoint, non-zero otherwise. Used by the composite dispatcher to keep iterating to the owning sub-function. The core itself ignores it: the data has already been ACKed by the host and cannot be recalled.

int (*ep0_data_out)(usb_dev_t *dev)

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

备注

This callback is called within an interrupt service routine (ISR) context; time-consuming operations (e.g., malloc, rtos_sema_take) are not permitted. 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. Ref USB 2.0 8.5.3.1: the status stage carries the outcome of a control write, so a non-zero value makes the core protocol-stall EP0 instead of acknowledging the request.

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

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

备注

This callback is called within an interrupt service routine (ISR) context; time-consuming operations (e.g., malloc, rtos_sema_take) are not permitted. 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 if this class owns the endpoint, non-zero otherwise. Used by the composite dispatcher to keep iterating to the owning sub-function. The core itself ignores it: ref USB 2.0 8.4.6, leaving the endpoint unarmed already makes the controller NAK the next IN token, which is the correct "no data yet" response.

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.

备注

This callback is called within an interrupt service routine (ISR) context; time-consuming operations (e.g., malloc, rtos_sema_take) are not permitted. 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 if this class owns the endpoint, non-zero otherwise. Used by the composite dispatcher to keep iterating to the owning sub-function. The core itself ignores it: ref USB 2.0 8.4.6, leaving the endpoint unarmed already makes the controller NAK the next OUT token, which is the correct flow-control response, and a functional stall would break the class protocol instead.

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)

备注

This callback is called within an interrupt service routine (ISR) context; time-consuming operations (e.g., malloc, rtos_sema_take) are not permitted.

Param dev:

[in] USB device.

Param old_status:

[in] Previous status of USB device.

Param status:

[in] Current status of USB device.

void (*wakeup)(usb_dev_t *dev)

Callback invoked when the device resumes from USB suspend (wakeup).

Called upon resume from suspend (WKUINT or SOF detection), indicating that the USB bus is active and the upper layer can resume normal TRX.

备注

This callback is called within an interrupt service routine (ISR) context; time-consuming operations (e.g., malloc, rtos_sema_take) are not permitted.

Param dev:

[in] USB device.

void (*set_interface_base)(u8 base)

Callback to inform the class of its interface number base.

备注

Optional, used by the composite framework only; never called in standalone mode, where the base is implicitly 0. The composite framework renumbers every sub-function's interfaces to base..base+bNumInterfaces-1. A class implementing this callback shall add base to every interface number it emits OUTSIDE the standard Interface and IAD descriptors, which the framework rebases itself, namely:

  • class-specific descriptor fields cross-referencing its own interfaces (CDC Union bMasterInterface/bSlaveInterface0, CDC Call Management bDataInterface, UAC1 AC Header baInterfaceNr[], UVC VC Header baInterfaceNr[]);

  • interface numbers carried in class notification payloads (Ref CDC 1.2 6.3). A class shall NOT add base to wIndex of an incoming setup request: the framework already rebases interface-recipient requests to the class-local interface number. A class whose descriptors carry no cross-interface reference and which sends no notification naming an interface leaves this callback NULL. Called before every configuration descriptor build and on set_config, always with the same base, so the class only has to store it.

Param base:

[in] First interface number assigned to this class.

Device DFU Types

Descriptor, state and device context types of the DFU class

enum usbd_dfu_status_t

DFU status codes (DFU 1.1 spec Table 3-2)

Values:

enumerator USBD_DFU_STATUS_OK
enumerator USBD_DFU_STATUS_ERR_TARGET
enumerator USBD_DFU_STATUS_ERR_FILE
enumerator USBD_DFU_STATUS_ERR_WRITE
enumerator USBD_DFU_STATUS_ERR_ERASE
enumerator USBD_DFU_STATUS_ERR_CHECK_ERASED
enumerator USBD_DFU_STATUS_ERR_PROG
enumerator USBD_DFU_STATUS_ERR_VERIFY
enumerator USBD_DFU_STATUS_ERR_ADDRESS
enumerator USBD_DFU_STATUS_ERR_NOTDONE
enumerator USBD_DFU_STATUS_ERR_FIRMWARE
enumerator USBD_DFU_STATUS_ERR_VENDOR
enumerator USBD_DFU_STATUS_ERR_USBR
enumerator USBD_DFU_STATUS_ERR_POR
enumerator USBD_DFU_STATUS_ERR_UNKNOWN
enumerator USBD_DFU_STATUS_ERR_STALLEDPKT
struct usbd_dfu_config_t
#include <usbd_dfu.h>

Configuration for the DFU class.

Carries every DFU option. This class is EP0-only (DFU 1.1: no class endpoints), so there is no endpoint allocation to pass in; what remains is the advertised transfer size and timeouts plus the sizing of the three asynchronous tasks. Device-global parameters (VID/PID, strings, power attributes) live in usbd_dev_info_t instead. The bmAttributes feature bits are compile-time Kconfig options, not fields here, because they select which code and which device members exist at all.

备注

The structure is stored by pointer, not copied, so it shall remain valid until usbd_dfu_deinit.

Public Members

u32 xfer_size

Maximum firmware block per DNLOAD/UPLOAD, 0 uses USBD_DFU_DEFAULT_XFER_SIZE.

Advertised as wTransferSize, so the host honours it, and it also sizes the class buffer that temporarily replaces the core's EP0 buffer. It therefore has to be DMA-alignable and within what the EP0 path can carry; init validates the allocation and rejects a size it cannot serve.

u32 detach_timeout_ms

Detach timeout in ms, 0 uses USBD_DFU_DEFAULT_DETACH_TIMEOUT.

Reported as wDetachTimeOut and, when CONFIG_USBD_DFU_WILL_DETACH is not set, used as the real detach-timer period, so one value drives both and the device cannot promise the host a window it does not honour.

u32 write_poll_ms

bwPollTimeout during DNLOAD, 0 uses USBD_DFU_DEFAULT_WRITE_POLL_MS. Overridable later via usbd_dfu_set_write_poll_ms.

u32 manifest_poll_ms

bwPollTimeout during MANIFEST, 0 uses USBD_DFU_DEFAULT_MANIFEST_POLL_MS. Overridable later via usbd_dfu_set_manifest_poll_ms.

const char *itf_str

iInterface string, NULL uses USBD_DFU_DEFAULT_IFACE_STRING.

u16 write_task_stack_size

Write task stack in bytes, 0 uses USBD_DFU_DEFAULT_WRITE_TASK_STACK.

u16 manifest_task_stack_size

Manifest task stack in bytes, 0 uses USBD_DFU_DEFAULT_MANIFEST_TASK_STACK.

u16 reenum_task_stack_size

Reconfiguration task stack in bytes, 0 uses USBD_DFU_DEFAULT_REENUM_TASK_STACK.

u16 detach_status_delay_ms

Delay after DFU_DETACH before the bus detach, 0 uses USBD_DFU_DEFAULT_DETACH_STATUS_DELAY_MS.

u8 write_task_priority

Write task priority, 0 uses USBD_DFU_DEFAULT_WRITE_TASK_PRIORITY.

u8 manifest_task_priority

Manifest task priority, 0 uses USBD_DFU_DEFAULT_MANIFEST_TASK_PRIORITY.

u8 reenum_task_priority

Reconfiguration task priority, 0 uses USBD_DFU_DEFAULT_REENUM_TASK_PRIORITY.

struct usbd_dfu_cb_t
#include <usbd_dfu.h>

User application callbacks for the DFU device class driver.

备注

write() and manifest() are called from dedicated task contexts and may block (e.g., flash erase/program, OTA activation). All other callbacks — setup, read, detach, status_changed — are called from ISR context and must not block.

Public Members

int (*init)(void)

Allocate resources, called once before USB enumeration begins.

Retval 0:

on success, non-zero on failure.

int (*deinit)(void)

Release resources, called on deinitialization.

Retval 0:

on success, non-zero on failure.

int (*write)(u16 block_num, u8 *buf, u32 len)

Write one downloaded firmware block.

备注

Called from a dedicated task context — blocking operations such as flash erase/program are permitted.

Param block_num:

wBlockNum from the DFU_DNLOAD request.

Param buf:

Data buffer (usbd_dfu_config_t::xfer_size bytes max).

Param len:

Actual byte count in this block.

Retval 0:

on success. Non-zero triggers dfuERROR with ERR_WRITE.

int (*read)(u16 block_num, u8 *buf, u32 max_len)

Read one firmware block for host upload (synchronous).

Param block_num:

wBlockNum from the DFU_UPLOAD request.

Param buf:

Output buffer.

Param max_len:

Maximum bytes to return (equals wLength).

Retval Bytes:

placed in buf (< max_len signals end-of-image), or <0 on error.

void (*manifest)(void)

Activate newly downloaded firmware. Called after all blocks received (zero-length DFU_DNLOAD). Device may trigger a reset inside this callback.

void (*detach)(void)

DFU_DETACH received while in application runtime mode.

void (*reconf)(void)

Called from reconf_task when the device needs to re-enumerate in DFU mode (CONFIG_USBD_DFU_WILL_DETACH=y only). dfu->mode is already USBD_DFU_PROTOCOL_DFU when this fires. The application must respond from a separate task: call usbd_dfu_deinit(), usbd_deinit(), usbd_init(), then usbd_dfu_init() to force re-enumeration. usbd_dfu_deinit() waits for reconf_task to exit, so calling it from this callback would never return. May be NULL if re-enumeration is handled another way.

u32 (*get_write_poll_ms)(u16 block_num)

Return the expected write time (ms) for the block about to be written. Called from ISR — must not block. May be NULL; driver falls back to the static write_poll_ms value set via usbd_dfu_set_write_poll_ms().

Param block_num:

wBlockNum of the incoming DNLOAD block.

Retval Expected:

milliseconds for this specific block.

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

USB cable attach/detach status changed.

Param old_status:

Previous usbd_attach_status_t value.

Param status:

Current usbd_attach_status_t value.

struct usbd_dfu_dev_t
#include <usbd_dfu.h>

Internal DFU device instance (opaque to application).

Public Members

usb_dev_t *dev
const usbd_dfu_cb_t *cb
const usbd_dfu_config_t *cfg

Pointer to the class configuration (set by init).

usb_dfu_state_t state
usbd_dfu_status_t status
u8 mode
u8 alt_setting
u8 from_composite

Flag indicating if part of a composite device.

u8 itf_str_idx

iInterface string index from usbd_add_string(), 0 for none.

u8 write_state
u8 manifest_done
u8 reconf_pending
u8 write_stop
u8 manifest_stop
u8 reconf_stop
u8 *xfer_buf
u32 xfer_size

Allocated size of xfer_buf, i.e. the resolved usbd_dfu_config_t::xfer_size.

u8 *ep0_default_buf
u32 ep0_default_buf_len
u16 block_num
u16 block_len
u8 ep0_in_owned
usb_os_sema_t write_sema
usb_os_task_t write_task
u32 write_poll_ms
usb_os_sema_t manifest_sema
usb_os_task_t manifest_task
rtos_timer_t manifest_timer
u32 manifest_poll_ms
usb_os_sema_t reconf_sema
usb_os_task_t reconf_task
u32 detach_timeout_ms

Resolved usbd_dfu_config_t::detach_timeout_ms; drives both the advertised wDetachTimeOut and the detach timer.

u16 detach_status_delay_ms

Resolved usbd_dfu_config_t::detach_status_delay_ms.

rtos_timer_t detach_timer
u16 detach_wait_ms

Device HID Types

struct usbd_hid_config_t
#include <usbd_hid.h>

HID endpoint configuration structure.

Allows the user to override default endpoint addresses and buffer sizes. Keyboard variant needs INTR OUT (LED report). Vendor variant needs INTR OUT (raw OUT report) and a second INTR IN (Vendor: Volume/Power).

Public Members

u32 intr_in_xfer_size

INTR IN transfer buffer size, 0 uses USBD_HID_INTR_IN_BUF_SIZE.

u32 intr_out_xfer_size

INTR OUT transfer buffer size, 0 uses USBD_HID_INTR_OUT_BUF_SIZE. Ignored unless the keyboard variant is built.

const char *itf_str

iInterface string of the HID interface, NULL for none.

u8 intr_in_addr

INTR IN endpoint address.

u8 intr_out_addr

INTR OUT endpoint address.

Ignored unless CONFIG_USBD_HID_KEYBOARD (LED report) or CONFIG_USBD_HID_VENDOR (raw OUT report) is built.

u8 vendor_intr_in_addr

Vendor INTR IN endpoint address.

Ignored unless CONFIG_USBD_HID_VENDOR is built.

u8 intr_interval_hs

INTR bInterval at High Speed, 0 uses USBD_HID_DEFAULT_HS_INTR_INTERVAL.

u8 intr_interval_fs

INTR bInterval at Full Speed, 0 uses USBD_HID_DEFAULT_FS_INTR_INTERVAL.

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.

备注

This function is called within an interrupt service routine (ISR) context; time-consuming operations (e.g., malloc, rtos_sema_take) are not permitted.

void (*transmitted)(int status)

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

备注

This function is called within an interrupt service routine (ISR) context; time-consuming operations (e.g., malloc, rtos_sema_take) are not permitted.

Param status:

[in] The status of the transmission.

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

Called when new data is received from the host on the INTR OUT endpoint (or via SET_REPORT on EP0). Keyboard: LED-state report; Vendor: raw OUT report (also queued into ring buffer for blocking usbd_hid_read).

备注

This function is called within an interrupt service routine (ISR) context; time-consuming operations (e.g., malloc, rtos_sema_take) are not permitted.

Param buf:

[in] Pointer to the received data buffer.

Param len:

[in] Length of the received data in bytes.

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

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

备注

This function is called within an interrupt service routine (ISR) context; time-consuming operations (e.g., malloc, rtos_sema_take) are not permitted.

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.

备注

This function is called within an interrupt service routine (ISR) context; time-consuming operations (e.g., malloc, rtos_sema_take) are not permitted.

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_config_t
#include <usbd_uac.h>

Configuration for the UAC class.

Carries every UAC option: the endpoint allocation, which the top-level application owns, the audio format of each direction, and the ISOC buffer sizing and class-control ranges. Used by both standalone and composite modes. Device-global parameters (VID/PID, strings, power attributes) live in usbd_dev_info_t instead.

备注

The structure is stored by pointer, not copied, so it shall remain valid until usbd_uac_deinit.

备注

The advertised sample rates, channel counts and bit widths are baked into the const descriptor tables at build time from the menuconfig formats, refer to USBD_UAC_DEFAULT_CH_CNT, USBD_UAC_DEFAULT_BYTE_WIDTH and USBD_UAC_OUT_MAX_SAMPLING_FREQ; usbd_uac_config rejects a playback format the descriptors do not declare.

备注

The record format (in, UAC 2.0 only) is the single one the mic reports, its descriptors are built from it at run time: 1 or 2 channels, 2, 3 or 4 bytes per sample, 8 kHz to 192 kHz, and one Full-Speed packet (1023 bytes per ms) at most. usbd_uac_init rejects any other.

Public Members

const char *itf_str

iInterface string of the audio control interface, NULL for none.

usbd_audio_cfg_t in

Audio format for record (device to host).

usbd_audio_cfg_t out

Audio format for playback (host to device).

u16 volume_min

Minimum volume reported to the host, 0 uses USBD_UAC_DEFAULT_VOLUME_MIN. Keep the range within the defaults: a SET_CUR outside them is STALLed.

u16 volume_max

Maximum volume reported to the host, 0 uses USBD_UAC_DEFAULT_VOLUME_MAX.

u16 volume_default

Initial volume, 0 uses USBD_UAC_DEFAULT_VOLUME.

u8 mute_default

Initial mute state (0: unmuted, 1: muted).

u8 isoc_in_addr

ISOC IN endpoint address

u8 isoc_out_addr

ISOC OUT endpoint address

u8 rx_buf_cnt

RX ring buffer slot count, 0 uses USBD_UAC_DEFAULT_RX_BUF_CNT. UAC 2.0: at most USBD_UAC_BUFFER_COUNT_MAX, init fails otherwise.

u8 tx_buf_cnt

TX (record) ring buffer slot count, 0 uses USBD_UAC_DEFAULT_TX_BUF_CNT. UAC 2.0 only, UAC 1.0 has no record. At most USBD_UAC_BUFFER_COUNT_MAX, init fails otherwise.

struct usbd_uac_cb_t
#include <usbd_uac.h>

Public Members

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.

备注

This function is called within an interrupt service routine (ISR) context; time-consuming operations (e.g., malloc, rtos_sema_take) are not permitted.

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.

备注

This function is called within an interrupt service routine (ISR) context; time-consuming operations (e.g., malloc, rtos_sema_take) are not permitted.

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.

备注

This function is called within an interrupt service routine (ISR) context; time-consuming operations (e.g., malloc, rtos_sema_take) are not permitted.

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.

备注

This function is called within an interrupt service routine (ISR) context; time-consuming operations (e.g., malloc, rtos_sema_take) are not permitted.

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.

备注

This function is called within an interrupt service routine (ISR) context; time-consuming operations (e.g., malloc, rtos_sema_take) are not permitted.

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.

备注

This function is called within an interrupt service routine (ISR) context; time-consuming operations (e.g., malloc, rtos_sema_take) are not permitted.

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.

备注

This function is called within an interrupt service routine (ISR) context; time-consuming operations (e.g., malloc, rtos_sema_take) are not permitted.

struct usbd_uac_buf_ctrl_t
#include <usbd_uac.h>

Public Members

rtos_sema_t uac_isoc_sema

ISOC sema.

u32 sof_idx
u32 data_idx
u32 xfer_cnt

Xfer valid count

u16 last_xfer_len

Last xfer length, used to size appended ZLP

u16 isoc_mps

ISOC maximum packet size.

usb_ringbuf_manager_t buf_list

Ring buffer manager for ISOC packets.

u8 buf_list_cnt

Ring buffer node count.

u8 binterval

bInterval used for MPS/ring sizing.

u8 uac_sema_valid

ISOC sema created.

u8 read_wait_sema

The sema is waiting.

u8 next_xfer

Audio transfer continue flag.

u8 is_closing

Set by the buffer teardown: usbd_uac_read() (OUT ring) or usbd_uac_transmit_data() (IN ring) rejects new callers. Written under the USB critical section.

u8 xfer_users

Number of tasks inside those APIs on this ring; the buffer teardown waits for it to drop to 0. Updated under the USB critical section.

Device UVC Types

Endpoint configuration, streaming control and device context types of the UVC class

struct usbd_uvc_ep_cfg_t
#include <usbd_uvc.h>

UVC endpoint configuration structure.

Used to configure endpoint addresses at runtime.

Public Members

u32 iso_in_xfer_size

ISOC IN transfer buffer size (0 = use default).

u8 iso_in_addr

ISOC IN endpoint address for video streaming

struct usbd_uvc_frame_info_t
#include <usbd_uvc.h>

UVC frame information structure.

Describes a single video frame size and its supported frame intervals.

Public Members

u32 width
u32 height
u32 intervals[4]
struct usbd_uvc_format_info_t
#include <usbd_uvc.h>

UVC video format information.

Defines a video format and its supported frame resolutions.

Public Members

u32 fcc
usbd_uvc_frame_info_t *frames
struct usbd_uvc_vendorcmd_t
#include <usbd_uvc.h>

UVC vendor-specific command structure.

Used for vendor-defined control or data transfer commands over USB.

Public Members

u8 cmd
u8 subcmd
u16 address
u16 length
u16 reserved
u8 buffer[8]
struct usbd_uvc_process_unit_t
#include <usbd_uvc.h>

UVC Processing Unit control data.

Stores control values returned by standard UVC GET requests (e.g. brightness, contrast, saturation).

Public Members

int cur
int min
int max
int res
int len
int info
int def
struct usbd_uvc_isp_usbd_cmd_data_t
#include <usbd_uvc.h>

ISP USB device command data structure.

Used for communication between USB and ISP firmware logic.

Public Members

u32 offset
u16 cmdcode
u16 param
u16 addr
u8 buf[0x40]
u8 index
u8 length
struct usbd_uvc_request_data_t
#include <usbd_uvc.h>

UVC request payload data.

Used to store data associated with a UVC control request.

Public Members

u8 data[64]
int length
struct usbd_uvc_buffer_t
#include <usbd_uvc.h>

USB UVC video buffer structure.

Represents a single video buffer used for streaming.

Public Members

const u8 *mem
u32 bytesused
void *exbuf
int index
struct list_head buffer_list
struct usbd_uvc_req_data_t
#include <usbd_uvc.h>

UVC request data container.

Wraps USB setup requests and UVC-specific request payloads.

Public Members

u32 type
usb_setup_req_t req
usbd_uvc_request_data_t uvc_data
u8 buf[64]
union usbd_uvc_req_data_t::[anonymous] [anonymous]
struct list_head list
struct usbd_uvc_video_t
#include <usbd_uvc.h>

UVC video streaming context.

Holds all runtime information related to UVC video streaming, including format, buffers, payload handling, and synchronization.

Public Members

int stream_index
u32 fcc
u32 width
u32 height
u32 imagesize
u32 frm_type
u8 format
u8 bpp
u8 fid
u8 end_flag
u32 req_size
u32 payload_size
u32 max_payload_size
u32 buf_used
u32 cur_pts

PTS (48MHz units) captured at frame start; constant for the whole frame.

u16 sof_count

Software SOF counter (11-bit) maintained in .sof; used as SCR SOF token.

u8 armed

1 = an ISOC IN xfer is in flight (set/cleared only in ISR).

u8 stall_sof

SOF count since arm; watchdog for incompISOIN recovery.

u8 wait_keyframe

1 = streaming just started; drop payloads until a key frame.

u8 keyframe_gate_left

Frames the key-frame gate may still drop before giving up.

usb_ringbuf_manager_t in_rb

Payload ring; TX DMA reads node->buf in place (zero-copy).

usb_os_sema_t in_rb_space_sema

Given by ISR when a node is consumed; producer waits on it when ring is full.

usb_os_lock_t input_lock
struct list_head input_queue
usb_os_lock_t output_lock
struct list_head output_queue
usb_os_sema_t output_queue_sema
usb_os_sema_t output_frame_sema
usbd_uvc_buffer_t uvc_buffer
u32 tx_payloads

Total microframe payloads transmitted (XFRC).

u32 tx_frames

Total UVC frames fully queued into ring by producer.

u32 incomp_cnt

incompISOIN recoveries: SOF watchdog triggered.

u32 underrun_cnt

Ring underrun: try_arm found empty ring.

struct usbd_uvc_dev_t
#include <usbd_uvc.h>

UVC device context structure.

Represents the complete UVC device state, including control, streaming, USB endpoints, and synchronization primitives.

Public Members

usb_dev_t *dev
const usbd_uvc_ep_cfg_t *ep_cfg
usbd_uvc_format_t *uvc_format_ptr
void (*change_parm_cb)(void*)

Called when UVC streaming parameters are committed/changed by the host.

备注

This function is called within an interrupt service routine (ISR) context; time-consuming operations (e.g., malloc, rtos_sema_take) are not permitted.

Param uvc_format_ptr:

[in] Pointer to the active UVC format descriptor.

u8 running
u8 init_done
u8 res_created
u8 frame_task_alive
u8 frame_done
u8 config
u8 ctrl_req_pending

1 if ctrl_req is waiting for its EP0 OUT data stage.

u8 from_composite

Flag indicating if part of a composite device.

u8 if_base

First interface number of this class; 0 in standalone mode unless the composite framework rebases it via set_interface_base().

usbd_uvc_video_t video
usbd_ep_t ep_isoc_in
int control
int command_interface
int command_entity
u32 event_setup_out
u16 event_length
u16 interface_number
u8 ctrl_req
u8 ctrl_data_len
u8 uvc_cmd_blocked
usbd_uvc_req_data_t req_data
u8 result[64]
usbd_uvc_streaming_control_t probe
usbd_uvc_streaming_control_t commit
usb_os_sema_t uvc_cmd_wakeup_sema
usb_os_lock_t bod_mutex
struct list_head bod_list
usb_os_lock_t lock

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.

备注

This function is called within an interrupt service routine (ISR) context; time-consuming operations (e.g., malloc, rtos_sema_take) are not permitted.

备注

The handler shall validate every field of the request and return non-zero for any request it does not support, which makes the core STALL EP0.

Param req:

[in] Pointer to the setup request packet.

Param buf:

[out] Pointer to a buffer for data stage of control transfers. For a D2H request it is the zero-initialized response window, min(wLength, EP0 buffer size) bytes, and all of it is sent to the host when the handler returns 0. For an H2D request it holds the received payload, and it is NULL if the request has no data stage.

Return:

0 on success, non-zero on failure.

int (*set_config)(void)

Called when the USB device is configured.

备注

This function is called within an interrupt service routine (ISR) context; time-consuming operations (e.g., malloc, rtos_sema_take) are not permitted.

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.

备注

This function is called within an interrupt service routine (ISR) context; time-consuming operations (e.g., malloc, rtos_sema_take) are not permitted.

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.

备注

This function is called within an interrupt service routine (ISR) context; time-consuming operations (e.g., malloc, rtos_sema_take) are not permitted.

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.

备注

This function is called within an interrupt service routine (ISR) context; time-consuming operations (e.g., malloc, rtos_sema_take) are not permitted.

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)(int status)

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

备注

This function is called within an interrupt service routine (ISR) context; time-consuming operations (e.g., malloc, rtos_sema_take) are not permitted.

Param status:

[in] The status of the transmission.

void (*intr_transmitted)(int status)

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

备注

This function is called within an interrupt service routine (ISR) context; time-consuming operations (e.g., malloc, rtos_sema_take) are not permitted.

Param status:

[in] The status of the transmission.

void (*isoc_transmitted)(int status)

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

备注

This function is called within an interrupt service routine (ISR) context; time-consuming operations (e.g., malloc, rtos_sema_take) are not permitted.

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.

备注

This function is called within an interrupt service routine (ISR) context; time-consuming operations (e.g., malloc, rtos_sema_take) are not permitted.

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

const usbd_vendor_config_t *cfg

Pointer to the class configuration (set by init).

const usbd_vendor_cb_t *cb

Pointer to the user-defined callback structure

usb_dev_t *dev

Pointer to the USB device instance

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_setup_req_t ctrl_req

Stores the current control request (byte-packed)

u8 alt_setting

Alternate setting number of the current interface

u8 ctrl_req_pending

1 if ctrl_req is waiting for its EP0 OUT data stage

u8 from_composite

Flag indicating if part of a composite device.

u8 itf_str_idx

iInterface string index from usbd_add_string(), 0 for none.

Device Video Types

Streaming control and probe/commit types of the UVC protocol

struct usbd_uvc_streaming_control_t
#include <usbd_video.h>

UVC Streaming Control structure.

This structure defines the parameters used to control video streaming behavior in USB Video Class (UVC) devices, including format selection, frame interval, bandwidth requirements, and payload size.

Public Members

u16 bmHint
u8 bFormatIndex
u8 bFrameIndex
u32 dwFrameInterval
u16 wKeyFrameRate
u16 wPFrameRate
u16 wCompQuality
u16 wCompWindowSize
u16 wDelay
u32 dwMaxVideoFrameSize
u32 dwMaxPayloadTransferSize
u32 dwClockFrequency
u8 bmFramingInfo
u8 bPreferedVersion
u8 bMinVersion
u8 bMaxVersion
struct usbd_uvc_format_t
#include <usbd_video.h>

UVC Video Format Configuration structure.

This structure defines the current video format and ISP-related settings used by the USB Video Class (UVC) device. It includes resolution, frame rate, pixel format, and image processing options, as well as synchronization and initialization state control.

The structure is typically updated during UVC negotiation or runtime reconfiguration, and is accessed by both control and streaming paths.

Public Members

u32 width
u32 height
u32 format
u32 fps
u32 state
u32 bayer_type
usb_os_sema_t uvcd_change_sema
u8 isp_format
u8 ldc
u8 init

Device WHC OTP Types

Device identity and capability parameters read from OTP

struct usbd_otp_t
#include <usbd_whc_otp.h>

Device identity and capability parameters latched from OTP.

Public Members

u8 *mfg_str

Manufacturer string, heap-allocated by usbd_otp_init.

u8 *prod_str

Product string, heap-allocated by usbd_otp_init.

u8 *sn_str

Serial number string, heap-allocated by usbd_otp_init.

u16 vid

Vendor ID read from OTP.

u16 pid

Product ID read from OTP.

u8 otp_sn

1 when OTP supplied a valid serial number.

u8 otp_param

1 when OTP supplied valid device parameters.

u8 self_powered

1 when the device reports itself as self-powered.

u8 remote_wakeup_en

1 when remote wakeup is enabled.

u8 bt_en

1 when the Bluetooth function is enabled in OTP.

Device WHC Types

Packet header, endpoint, callback and device context types of the WHC class

struct usbd_whc_query_packet_t
#include <usbd_whc.h>

Public Members

u32 data_len
u32 data_offset
u32 data_checksum
u32 pkt_type
u32 xfer_status
u32 rl_version
u32 dev_mode
u32 mem_addr
u32 mem_size
u32 d32
u16 d16[2]
u8 d8[4]
union usbd_whc_query_packet_t::[anonymous] value
u32 reserved
struct usbd_whc_ep_t
#include <usbd_whc.h>

One WHC endpoint and the application context bound to it.

Public Members

void *userdata
usbd_ep_t ep

Core endpoint descriptor.

struct usbd_whc_cb_t
#include <usbd_whc.h>

WHC user callback structure.

Application callbacks of the WHC class. All of them run in interrupt context.

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

Public Members

int (*init)(void)

Called during class driver initialization for application resource setup.

Return:

0 on success, non-zero on failure.

int (*deinit)(void)

Called during class driver deinitialization for resource cleanup.

Return:

0 on success, non-zero on failure.

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

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

备注

This function is called within an interrupt service routine (ISR) context; time-consuming operations (e.g., malloc, rtos_sema_take) are not permitted.

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)

Notifies application layer when WHC driver becomes operational.

备注

This function is called within an interrupt service routine (ISR) context; time-consuming operations (e.g., malloc, rtos_sema_take) are not permitted.

Return:

0 on success, non-zero on failure.

int (*clear_config)(void)

Notifies application layer when WHC driver becomes non-operational.

备注

This function is called within an interrupt service routine (ISR) context; time-consuming operations (e.g., malloc, rtos_sema_take) are not permitted.

Return:

0 on success, non-zero on failure.

void (*transmitted)(usbd_whc_ep_t *in_ep, int status)

Called when non-control IN transfer done, for asynchronous non-control IN transfer status notification.

备注

This function is called within an interrupt service routine (ISR) context; time-consuming operations (e.g., malloc, rtos_sema_take) are not permitted.

Param in_ep:

[in] Pointer to the WHC IN endpoint.

Param status:

[in] The status of the transmission.

int (*received)(usbd_whc_ep_t *out_ep, u32 len)

Called when non-control OUT transfer done, for application to handle the received host command/data.

备注

This function is called within an interrupt service routine (ISR) context; time-consuming operations (e.g., malloc, rtos_sema_take) are not permitted.

Param out_ep:

[in] Pointer to the WHC OUT endpoint.

Param len:

[in] Length of the received data in bytes.

Return:

0 on success, non-zero on failure.

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

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

备注

This function is called within an interrupt service routine (ISR) context; time-consuming operations (e.g., malloc, rtos_sema_take) are not permitted.

Param old_status:

[in] The previous USB device status.

Param status:

[in] The new USB device status.

void (*wakeup)(void)

Called when the USB device resumes from suspend (wakeup).

Indicates that the USB bus is active again and the upper layer can resume normal TRX.

备注

This function is called within an interrupt service routine (ISR) context; time-consuming operations (e.g., malloc, rtos_sema_take) are not permitted.

struct usbd_whc_dev_t
#include <usbd_whc.h>

Public Members

usb_dev_t *dev
const usbd_whc_cb_t *cb
rtos_task_t reset_task
rtos_sema_t reset_sema
usbd_whc_ep_t in_ep[USB_MAX_ENDPOINTS]
usbd_whc_ep_t out_ep[USB_MAX_ENDPOINTS]
usbd_otp_t otp
usb_setup_req_t ctrl_req
u8 ctrl_req_pending
u8 bt_str_idx
u8 bt_sco_alt

USB Host API

USB Host Functions

Host CDC ACM Functions

int usbh_cdc_acm_init(const usbh_cdc_acm_cb_t *cb, const usbh_cdc_acm_config_t *cfg)

Initializes the CDC ACM host class driver.

备注

The class relies on the SOF interrupt to re-drive a NAKed BULK transfer and to re-arm the INTR IN poll, so the host shall run with usbh_config_t::tick_source = USBH_SOF_TICK, or with USBH_SOF_INTR set in usbh_config_t::ext_intr_enable.

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

  • cfg -- [in] Pointer to the class configuration. See usbh_cdc_acm_config_t.

返回:

0 on success, non-zero on failure.

void usbh_cdc_acm_deinit(void)

De-initializes the CDC ACM host class driver.

int usbh_cdc_acm_set_line_coding(usb_cdc_acm_line_coding_t *lc)

Sets the line coding parameters for the device.

参数:

lc -- [in] Pointer to the line coding structure, checked against PSTN 1.2 Table 17.

返回:

0 on success, -RTK_ERR_BUSY while a previous class request is still in flight, other non-zero on failure.

int usbh_cdc_acm_get_line_coding(usb_cdc_acm_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, -RTK_ERR_BUSY before the class setup has read it or while SET/GET_LINE_CODING is still in flight, other non-zero on failure.

int usbh_cdc_acm_set_control_line_state(u16 bitmap)

Sets the control line state (PSTN §6.3.12 SET_CONTROL_LINE_STATE).

参数:

bitmap -- [in] Control Signal Bitmap written to wValue. D0=DTR, D1=RTS; all other bits reserved and shall be zero.

返回:

0 on success, -RTK_ERR_BUSY while a previous class request is still in flight, other non-zero on failure.

int usbh_cdc_acm_send_break(u16 duration_ms)

Sends a break signal to the device (PSTN §6.3.13).

参数:

duration_ms -- [in] Break duration in milliseconds. 0xFFFF = continuous break; 0x0000 = end break.

返回:

0 on success, -RTK_ERR_BUSY while a previous class request is still in flight, other non-zero on failure.

int usbh_cdc_acm_transmit(u8 *buf, u32 len)

Transmits data to the device over the BULK OUT pipe.

备注

The pipe stays busy until the transmitted callback, and buf must stay valid until then. buf is accessed by DMA and must be cache line aligned (e.g. declared with USB_DMA_ALIGNED).

参数:
  • 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.

备注

The pipe stays busy until the received callback, and buf must stay valid until then. buf is accessed by DMA and must be cache line aligned (e.g. declared with USB_DMA_ALIGNED). The controller receives whole packets, so the request is cut down to the packets that fit in len: use a multiple of the BULK IN MPS to have it used in full.

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

  • len -- [in] Length of the buffer in bytes, at least one BULK IN MPS.

返回:

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.

备注

Requires CONFIG_USBH_CDC_ACM_NOTIFY, otherwise the class owns no INTR IN pipe and this function is not built. The pipe stays busy until the notify callback, and buf must stay valid until then. One call receives one INTR IN packet. A device whose INTR IN MPS is below the 10-byte SERIAL_STATE splits it over two packets, which is not supported yet: such a notification is reported as notify(NULL, 0), and attach logs a warning. buf is accessed by DMA and must be cache line aligned (e.g. declared with USB_DMA_ALIGNED).

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

  • len -- [in] Length of the buffer in bytes, at least the INTR IN MPS: the controller may fill a whole packet.

返回:

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(const usbh_cdc_ecm_state_cb_t *cb, const usbh_cdc_ecm_config_t *cfg)

Initializes the CDC ECM host class driver.

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

  • cfg -- [in] Pointer to the class configuration, NULL to take every default. See usbh_cdc_ecm_config_t.

返回:

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

void usbh_cdc_ecm_deinit(void)

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

int usbh_cdc_ecm_choose_config(usb_host_t *host)

Selects the appropriate configuration index for the device.

参数:

host -- [in] USB Host Handle.

返回:

0 (RTK_SUCCESS) 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 (RTK_SUCCESS) 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.

void usbh_cdc_ecm_prepare_done(void)

Signal that the upper layer has finished all pre-transfer preparation (e.g. 4G dongle AT configuration) and Ethernet data transfer may start. Until this is called, SOF withholds bulk/intr transfer scheduling.

int usbh_cdc_ecm_send_data(u8 *buf, u32 len, u8 block)

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

备注

Task context only, one sender at a time. Safe against a concurrent deinit of the class: returns -RTK_ERR_IO while the class is not initialized or is being de-initialized. A blocking send waits until the transfer completes, so it shall not be called inside a critical section or the PMU suspend flow, where the task can not block.

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

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

  • block -- [in] Blocking mode flag (e.g., 0 for non-blocking, else for blocking).

返回:

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

Gets the current network link state (uplink status).

返回:

1: Network link is up (connected to uplink). 0: Network link is down (disconnected, or USB not yet enumerated).

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.

u16 usbh_cdc_ecm_get_device_vid(void)

Gets the Vendor ID of the attached CDC ECM device.

返回:

VID on success, 0 if no device is attached.

u16 usbh_cdc_ecm_get_device_pid(void)

Gets the Product ID of the attached CDC ECM device.

返回:

PID on success, 0 if no device is attached.

Host CDC NCM Functions

int usbh_cdc_ncm_init(const usbh_cdc_ncm_state_cb_t *cb, const usbh_cdc_ncm_config_t *cfg)

Initializes the CDC NCM host class driver.

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

  • cfg -- [in] Pointer to the class configuration, NULL to take every default. See usbh_cdc_ncm_config_t.

返回:

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

void usbh_cdc_ncm_deinit(void)

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

int usbh_cdc_ncm_choose_config(usb_host_t *host)

Selects the appropriate configuration index for the device.

参数:

host -- [in] USB Host Handle.

返回:

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

int usbh_cdc_ncm_check_config_desc(usb_host_t *host)

Validates the device configuration descriptor for CDC NCM support.

备注

Applies the same rules as attach: the NCM Communication Interface with one INTR IN endpoint and the NCM Data Interface (protocol 0x01) it names in its Union, with one BULK IN/OUT pair.

参数:

host -- [in] USB Host Handle.

返回:

RTK_SUCCESS if both NCM interfaces are found, -RTK_ERR_BADARG otherwise.

u8 usbh_cdc_ncm_is_configured(void)

Checks if the CDC NCM device is enumerated and configured on the USB bus.

返回:

1: USB configured (ready for control/bulk transfer). 0: Device not enumerated or not yet configured.

int usbh_cdc_ncm_transmit(u8 *buf, u32 len, u8 block)

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

备注

Task context only, one sender at a time. Safe against a concurrent deinit of the class: returns -RTK_ERR_IO while the class is not initialized or is being de-initialized. A blocking send waits until the transfer completes, so it shall not be called inside a critical section or the PMU suspend flow, where the task can not block.

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

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

  • block -- [in] Blocking mode flag (e.g., 0 for non-blocking, else for blocking).

返回:

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

Checks if the Ethernet link is up (USB enumerated + link active).

返回:

1: Device enumerated and Ethernet link is up. 0: Device not enumerated or Ethernet link is down.

const u8 *usbh_cdc_ncm_get_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(const usbh_config_t *cfg, const 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.

void usbh_deinit(void)

Deinitialize USB host core driver.

int usbh_reenumerate(void)

Request a reset and a fresh enumeration of the attached device.

The host task detaches every class driver, reports USBH_MSG_RESET to the application, resets the root port and enumerates the device again from address 0, so the same class drivers re-bind to a device in its power-on state. Typical uses are the last recovery step of a class whose own recovery failed (e.g. MSC after a failed BOT Reset Recovery, as Linux usb_reset_device() is for its class drivers), and picking up a device that changed its descriptors on the fly (e.g. a DFU run-time -> DFU-mode switch on a device that does not detach itself). A hub on the root port is reset with the device behind it.

备注

Asynchronous: only records the request and wakes the host task, so it may be called from any context, including a class process() or ISR-context callback. After it returns RTK_SUCCESS a class must not use its pipes; its detach() runs from the host task.

备注

At most USBH_REENUMERATE_MAX_CNT resets are allowed. Once they are spent the request is escalated to usbh_power_cycle() if usbh_user_cb_t::set_vbus is registered, as the Linux hub driver power cycles a port whose resets fail. Otherwise, or once the power cycles are spent as well, the request is refused: USBH_MSG_ERROR is reported, every class is detached and the device is left alone until it is replugged. A real unplug renews the budgets, and so does a device that has stayed set up for USBH_RESET_BUDGET_RENEW_MS.

警告

Requires an initialized core: call only after a successful usbh_init(), and never after usbh_deinit().

返回:

RTK_SUCCESS if the reset was scheduled, -RTK_ERR_BUSY if one is already pending or running, -RTK_ERR_BADARG if no device is attached, -RTK_ERR_IO if the reset budget is spent.

int usbh_power_cycle(void)

Request a VBUS power cycle of the attached device, skipping the port resets.

The host task detaches every class driver, reports USBH_MSG_POWER_CYCLE, cuts VBUS through usbh_user_cb_t::set_vbus, waits USBH_VBUS_OFF_MS for the device to discharge, supplies VBUS again and enumerates the device from scratch once it reconnects. USBH_MSG_ERROR is reported if VBUS cannot be switched or the device does not reconnect within USBH_VBUS_RECONNECT_TIMEOUT_MS. Also picks up a device the core has given up after USBH_MSG_ERROR, as long as it is still plugged in.

备注

For the application only, e.g. when its own watchdog finds the device dead. A class driver calls usbh_reenumerate() instead: a power-on reset is not the bus reset a class protocol asks for (e.g. DFU 1.1 appDETACH falls back to appIDLE on a power-on reset), and the core escalates to a power cycle by itself when the resets fail.

备注

Every device on the root port loses power, a hub with all the devices behind it. A self-powered device only detaches, its firmware is not restarted.

备注

Asynchronous: only records the request and wakes the host task, so it may be called from any context. At most USBH_POWER_CYCLE_MAX_CNT power cycles are allowed, renewed as the budget of usbh_reenumerate().

警告

Requires an initialized core: call only after a successful usbh_init(), and never after usbh_deinit().

返回:

RTK_SUCCESS if the power cycle was scheduled, -RTK_ERR_BUSY if a reset is already pending or running, -RTK_ERR_BADARG if no device is attached or no usbh_user_cb_t::set_vbus is registered (nothing is done then), -RTK_ERR_IO if the power cycle budget is spent.

int usbh_sync_isr(u32 timeout_ms)

Wait until no class sof()/completed() callback runs on any core.

The core enters a class ISR callback only while its slot is attached, but a callback another core entered just before a gate closed may still be running. The core already waits this way whenever it closes a slot gate itself: before a class detach() and inside usbh_unregister_class(), so a class deinit() that unregisters before freeing needs no call. A class that tears down ISR data under its own gate while still attached (e.g. on an alt setting change) closes that gate, then calls this, then frees: any callback entered after the gate closed sees it closed. A full barrier here and one in the IRQ handler between its counter increment and its gate reads make the handshake hold on weak-order SMP, so a plain store is enough for the gate.

备注

Task context only, it sleeps between polls. Returns at once in the usual case, and never while a callback still runs: the caller frees right after, so an early return would be the use after free this guards against. An IRQ handler that does not end is a fault, reported with an ERROR log every USBH_TEARDOWN_WAIT_LOG_MS, but waited out.

参数:

timeout_ms -- [in] Wait after which an ERROR is logged; the wait itself goes on until the callback leaves. A callback normally ends within microseconds.

返回:

RTK_SUCCESS if no callback ran past timeout_ms, -RTK_ERR_TIMEOUT if one did (it has left all the same), -RTK_ERR_BADARG in ISR context or without an initialized core.

u32 usbh_get_dev_address(void)

Get the USB address currently assigned to the attached device.

Returns the address the host handed out with SET_ADDRESS during enumeration, i.e. the value carried in the token of every subsequent transfer. Mainly useful for diagnostics, bus-trace correlation, and compliance/verification tooling; normal class code never needs it because the core fills the address into each transfer itself.

备注

Returns 0 when no device is enumerated yet, when enumeration has not reached SET_ADDRESS, and when the core is not initialized - 0 is the USB default address, so it can never be a live device's address and needs no separate error code.

返回:

Device address (1..127), or 0 if no device is addressed.

void usbh_suspend(void)

USB Host enter suspend.

void usbh_resume(void)

USB Host exit suspend.

void usbh_cg_register(void)

Register the sleep callbacks for USB host Clock Gating (CG).

Registers the PMU sleep callbacks so the USB host can be suspended/resumed when the AP enters/exits the low-power clock gated state. Wakelock operations and wake event configuration are handled by the caller, not inside this function.

void usbh_cg_unregister(void)

Unregister the sleep callbacks for USB host Clock Gating (CG).

备注

Wakelock operations are handled by the caller, not inside this function.

int usbh_select_test_mode(u8 mode)

USB Host Port Test Control, for CTS test.

参数:

mode -- [in] Test mode.

返回:

0 on success, non-zero on failure.

Host Core Functions For Classes

int usbh_register_class(const usbh_class_driver_t *driver)

Register a host class driver, called in class initialization function. Only records the driver in class_driver[]; USB TRX is NOT started here. Call usbh_start() once after all class drivers are registered.

参数:

driver -- [in] USB class driver.

返回:

0 on success, non-zero on failure.

int usbh_unregister_class(const usbh_class_driver_t *driver)

Un-register a class, called in class de-initialization function. Removes ONLY the matching driver from class_driver[]; does not stop hardware (usbh_stop()) or release core resources (usbh_deinit()). A driver that was never registered is silently ignored.

The slot is released by the host task between two driver messages, so on a RTK_SUCCESS return none of attach(), setup(), process() or detach() of this driver runs, none will run again, and an EP0 request it left in flight is halted with its buffer dropped. Its sof()/completed() are waited out as well (usbh_sync_isr()). So a class deinit() calls this first and may then free everything those callbacks touch. A class data pipe is not covered: close it with usbh_close_pipe().

备注

Task context only, and not from the host task: no class callback and no usbh_user_cb_t process() may deinit a class, as the release waits for the host task, which is the caller then. The wait has no upper bound, since freeing before the host task is out of the driver is a use after free; a wait past USBH_TEARDOWN_WAIT_LOG_MS is reported with an ERROR log at that period. The caller must therefore not hold a lock that a callback of any class takes.

参数:

driver -- [in] USB class driver.

返回:

RTK_SUCCESS once the driver is out (also when it was not registered or the core is not initialized), -RTK_ERR_BADARG in ISR context or on the host task, where nothing was released and the caller must not free anything.

int usbh_start(void)

Start USB host TRX: drive VBUS and enable global interrupts.

Must be invoked ONCE after usbh_init() and after every class driver you need has been registered via its *_init() (which internally calls usbh_register_class()). Enumeration for an already-plugged device begins the moment this returns, and Phase-1 driver match iterates over class_driver[] as it is at that instant - classes registered later can still bind on subsequent hot-plugs, but will miss the initial device. Idempotent (guarded by hcd->started); repeated calls are safe.

返回:

0 on success, non-zero on failure.

void usbh_stop(void)

Stop USB host TRX: disable global interrupts.

Symmetric counterpart of usbh_start() - the interrupt half it enabled. Halts USB ISR-driven TRX. VBUS is not dropped here; that is done by usbh_deinit(). Does not remove class drivers (usbh_unregister_class()). Safe to call when already stopped or when the core was never initialized.

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

Open a pipe.

参数:
  • host -- [in] Host Handle.

  • pipe -- [in] Pipe struct handle.

  • ep_desc -- [in] Endpoint descriptor handle.

  • owner -- [in] The class driver that owns the pipe.

返回:

0 on success, non-zero on failure.

void usbh_close_pipe(usb_host_t *host, usbh_pipe_t *pipe)

Close a pipe.

Halts the channel, drops its transfer buffer and waits out a completion ISR another core entered before, so on return neither the controller nor the ISR touches the buffer of the last transfer and the caller may free it.

备注

Task context only.

参数:
  • host -- [in] Host Handle.

  • pipe -- [in] Pipe struct handle.

u8 usbh_get_configuration(usb_host_t *host, usbh_dev_id_t *id)

Get the config idx by device 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 device 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.

void usbh_notify(usb_host_t *host, u8 pipe_num, const usbh_class_driver_t *owner)

Post a USBH_DRV_MSG_CLASS message to schedule the caller's process().

Called by a class driver when it wants its own process() invoked (e.g. after setup, on a state transition, or after handling a pipe completion in its ISR callback). The message is routed by owner (resolved to its class_slot index), NOT by pipe_num - many callers pass pipe_num=0 for non-pipe-bound state changes, and pipe 0 (control EP0) has no class owner anyway. See usbh_notify() in usbh.c for the full routing rationale.

Note: pipe completion / state-changed messages posted from the ISR use a separate routing path (hc[pipe_num].driver_idx), so this API is only for class-originated USBH_DRV_MSG_CLASS messages.

备注

The only failure mode is a full message queue, which the core counts for the main task to report and the caller cannot recover from, so no status is returned.

参数:
  • host -- [in] Host Handle.

  • pipe_num -- [in] Optional context, carried through to msg.pipe_num; 0 when the message is not tied to a specific pipe. Not used for routing.

  • owner -- [in] Originating class driver. Required for routing. NULL falls back defensively to slot 0.

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.

返回:

-RTK_ERR_BUSY while in progress, the owner is driven again; RTK_SUCCESS on success; -RTK_ERR_BADARG on STALL or a torn down host; RTK_FAIL once the retry budget or the control timeout is spent. A failure is reported only by this value, never by a USBH_MSG_*.

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.

返回:

-RTK_ERR_BUSY while in progress, the owner is driven again; RTK_SUCCESS on success; -RTK_ERR_BADARG on STALL or a torn down host; RTK_FAIL once the retry budget or the control timeout is spent. A failure is reported only by this value, never by a USBH_MSG_*.

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.

返回:

-RTK_ERR_BUSY while in progress, the owner is driven again; RTK_SUCCESS on success; -RTK_ERR_BADARG on STALL or a torn down host; RTK_FAIL once the retry budget or the control timeout is spent. A failure is reported only by this value, never by a USBH_MSG_*.

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

Send control request to device.

备注

For a D2H request the controller reserves whole EP0 packets, so buf shall hold usb_get_dma_len(wLength, USB_MAX_EP0_SIZE) bytes, i.e. wLength rounded up to 64, even though no more than wLength is ever reported as received.

参数:
  • host -- [in] Host Handle.

  • req -- [in] Control request.

  • buf -- [in] Data buffer.

返回:

-RTK_ERR_BUSY while in progress, the owner is driven again; RTK_SUCCESS on success; -RTK_ERR_BADARG on STALL or a torn down host; RTK_FAIL once the retry budget or the control timeout is spent. A failure is reported only by this value, never by a USBH_MSG_*.

int usbh_transfer_data(usb_host_t *host, usbh_pipe_t *pipe)

Start one data transfer.

备注

An IN transfer reserves whole packets of ep_mps bytes, each adjusted to the DWORD boundary, so the device may fill up to usb_get_dma_len(xfer_len, ep_mps) bytes of xfer_buf; the received length may exceed xfer_len by the tail of the last packet. Set xfer_buf_len to have such a request rejected when the buffer cannot hold it.

参数:
  • 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 actual number of bytes received in the last D2H transfer of specific pipe.

参数:
  • host -- [in] Host Handle.

  • pipe -- [in] Pipe struct handle.

返回:

Last transfer data size in bytes

u32 usbh_get_last_ctrl_in_size(usb_host_t *host)

Get the actual number of bytes received in the last D2H control transfer (EP0 IN data phase).

参数:

host -- [in] Host Handle.

返回:

Bytes received; 0 if a ZLP was received.

u16 usbh_get_lang_id(usb_host_t *host)

Get the LANGID to use as wIndex of a GET_DESCRIPTOR(STRING) request.

Learned from string descriptor 0 of the attached device during enumeration, US English (0x0409) when listed or when the device reports none. Ref USB 2.0 9.6.7.

参数:

host -- [in] Host Handle.

返回:

LANGID of the attached device.

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.

Host DFU Functions

int usbh_dfu_init(const usbh_dfu_cb_t *cb, const usbh_dfu_config_t *cfg)

Initializes the DFU host class driver.

参数:
  • cb -- [in] Pointer to the user-supplied callback structure.

  • cfg -- [in] Pointer to the class configuration. See usbh_dfu_config_t.

返回:

RTK_SUCCESS on success, -RTK_ERR_BADARG if cb/cfg is invalid, -RTK_ERR_NOMEM on allocation failure.

void usbh_dfu_deinit(void)

De-initializes the DFU host class driver and frees all resources.

int usbh_dfu_download(void)

Starts a DFU firmware download (host → device).

Transitions the state machine to USBH_DFU_STATE_GET_STATUS and triggers the first process() call. The driver will call cb->get_block() repeatedly until it returns 0 (EOF), then sends the final zero-length DFU_DNLOAD and polls for manifestation. Every accepted download ends with exactly one download_done(), also when the device is detached or the transfer is aborted (RTK_FAIL then).

返回:

RTK_SUCCESS if the operation was accepted, RTK_FAIL if no device is connected or a transfer or abort is already in progress.

int usbh_dfu_upload(void)

Starts a DFU firmware upload (device → host).

Transitions the state machine to USBH_DFU_STATE_UPLOAD_BLOCK and triggers the first process() call. The driver calls cb->recv_block() for every block received. The upload ends when the device returns a short (or zero-length) block. Every accepted upload ends with exactly one upload_done(), also when the device is detached, the transfer is aborted or recv_block() refuses a block (RTK_FAIL then).

返回:

RTK_SUCCESS if the operation was accepted, RTK_FAIL if no device is connected or a transfer or abort is already in progress.

int usbh_dfu_abort(void)

Requests DFU_ABORT and returns the host state to IDLE.

Asynchronous: DFU_ABORT is sent once the request currently in flight, and any bwPollTimeout the device asked for, have completed. A download or upload in progress then ends with its done callback reporting RTK_FAIL.

返回:

RTK_SUCCESS if the abort was accepted, RTK_FAIL if no DFU-mode device is connected.

u8 usbh_dfu_get_attr(void)

Get the DFU device's bmAttributes from the functional descriptor.

返回:

bmAttributes byte, or 0 if no device is connected.

Host HID Functions

int usbh_hid_init(const usbh_hid_usr_cb_t *cb)

Initialize the HID host class.

参数:

cb -- Pointer to user callback structure.

返回:

0 on success, non-zero on failure.

void usbh_hid_deinit(void)

De-Initialize the HID host class.

int usbh_hid_send_report(u8 *buf, u32 len)

Send an output report to the HID device via the Interrupt OUT pipe.

备注

Only available when the HID interface exposes an Interrupt OUT endpoint.

参数:
  • buf -- Pointer to the report data buffer. The controller reads it by DMA, so it must start on a cache line boundary (declare it with USB_DMA_ALIGNED, or take it from the heap) and stay valid and unchanged until the transfer completes.

  • len -- Length of the report data in bytes.

返回:

0 (RTK_SUCCESS) on success, -RTK_ERR_BADARG if no OUT pipe is available or buf is NULL or not cache line aligned, -RTK_ERR_BUSY if a transfer is already in progress.

Host MSC Functions

int usbh_msc_init(const usbh_msc_cb_t *cb, const usbh_msc_config_t *cfg)

Initializes the MSC class driver with application callback handler.

参数:
  • cb -- [in] Pointer to a user callback structure.

  • cfg -- [in] Pointer to the class configuration. See usbh_msc_config_t.

返回:

RTK_SUCCESS on success, -RTK_ERR_BADARG if cb/cfg is invalid, another RTK error code otherwise.

void usbh_msc_deinit(void)

De-initializes the MSC class driver.

int usbh_msc_bot_process(usb_host_t *host, u8 lun)

Main processing function for the MSC BOT state machine.

参数:
  • host -- [in] Pointer to the parent USB host structure.

  • lun -- [in] The logical unit number to process.

返回:

0 on success, non-zero on failure.

int usbh_msc_is_ready(void)

Checks if the MSC device is ready for I/O operations.

返回:

1 if ready, 0 otherwise.

u32 usbh_msc_get_max_lun(void)

Gets the number of logical units (LUNs) in use.

返回:

The LUN count, i.e. the GET MAX LUN result + 1 clamped to USBH_MSC_MAX_LUN, so valid LUN indexes are 0 to count - 1. 0 if no device is attached, 0xFFFFFFFF while the class is still bringing the LUNs up or a command is in flight.

int usbh_msc_unit_is_ready(u8 lun)

Checks if a specific logical unit (LUN) is ready.

参数:

lun -- [in] The LUN to check.

返回:

1 if the unit is ready, 0 otherwise.

int usbh_msc_get_lun_info(u8 lun, usbh_msc_lun_t *info)

Retrieves information about a specific LUN, like capacity and block size.

参数:
  • lun -- [in] The LUN to query.

  • info -- [out] Pointer to a usbh_msc_lun_t structure to store the information.

返回:

0 on success, non-zero on failure.

int usbh_msc_read(u8 lun, u32 address, u8 *pbuf, u32 length)

Reads data from the MSC device.

备注

Blocks the calling thread until the command ends; the BOT transfer itself runs in the host task. Hence it must not be called from any MSC or host callback (they run in that task), not even indirectly through FatFs, e.g. a file operation in the callback set by fatfs_set_hotplug_usr_cb(). Callers on several threads, as well as usbh_msc_deinit(), must be serialized by the application.

参数:
  • lun -- [in] The logical unit number to read from.

  • address -- [in] The starting logical block address.

  • pbuf -- [out] Pointer to the buffer where data will be stored.

  • length -- [in] The number of logical blocks to read.

返回:

RTK_SUCCESS on success, -RTK_ERR_TIMEOUT if the command was abandoned, another RTK error code otherwise.

int usbh_msc_write(u8 lun, u32 address, const u8 *pbuf, u32 length)

Writes data to the MSC device.

备注

Same blocking and serialization rules as usbh_msc_read().

参数:
  • lun -- [in] The logical unit number to write to.

  • address -- [in] The starting logical block address.

  • pbuf -- [in] Pointer to the buffer containing the data to write.

  • length -- [in] The number of logical blocks to write.

返回:

RTK_SUCCESS on success, -RTK_ERR_TIMEOUT if the command was abandoned, another RTK error code otherwise.

Host MSC SCSI Functions

SCSI commands issued over Bulk-Only Transport, internal to the MSC class

int usbh_scsi_test_unit_ready(usbh_msc_host_t *msc, u8 lun)

Issue the TEST UNIT READY command.

参数:
  • msc -- MSC host handle.

  • lun -- Logical Unit Number.

返回:

RTK_SUCCESS on success, a RTK error code otherwise.

int usbh_scsi_read_capacity(usbh_msc_host_t *msc, u8 lun, usbh_scsi_capacity_t *capacity)

Issue the READ CAPACITY (10) command.

参数:
  • msc -- MSC host handle.

  • lun -- Logical Unit Number.

  • capacity -- Output, receives the block count and block size.

返回:

RTK_SUCCESS on success, a RTK error code otherwise.

int usbh_scsi_inquiry(usbh_msc_host_t *msc, u8 lun, usbh_scsi_inquiry_t *inquiry)

Issue the INQUIRY command.

参数:
  • msc -- MSC host handle.

  • lun -- Logical Unit Number.

  • inquiry -- Output, receives the standard INQUIRY response.

返回:

RTK_SUCCESS on success, a RTK error code otherwise.

int usbh_scsi_request_sense(usbh_msc_host_t *msc, u8 lun, usb_msc_scsi_sense_data_t *sense_data)

Issue the REQUEST SENSE command.

参数:
  • msc -- MSC host handle.

  • lun -- Logical Unit Number.

  • sense_data -- Output, receives the sense key, ASC and ASCQ.

返回:

RTK_SUCCESS on success, a RTK error code otherwise.

int usbh_scsi_write(usbh_msc_host_t *msc, u8 lun, u32 address, const u8 *pbuf, u32 length)

Issue the WRITE (10) command.

参数:
  • msc -- MSC host handle.

  • lun -- Logical Unit Number.

  • address -- Start sector address.

  • pbuf -- Data to write.

  • length -- Number of sectors to write, at most one bounce buffer.

返回:

RTK_SUCCESS on success, a RTK error code otherwise.

int usbh_scsi_read(usbh_msc_host_t *msc, u8 lun, u32 address, u8 *pbuf, u32 length)

Issue the READ (10) command.

参数:
  • msc -- MSC host handle.

  • lun -- Logical Unit Number.

  • address -- Start sector address.

  • pbuf -- Buffer receiving the data read.

  • length -- Number of sectors to read, at most one bounce buffer.

返回:

RTK_SUCCESS on success, a RTK error code otherwise.

Host UAC Functions

int usbh_uac_init(const usbh_uac_cb_t *cb, const usbh_uac_config_t *cfg)

Initialize the UAC Class Driver.

参数:
  • cb -- Pointer to the user callback structure.

  • cfg -- Pointer to the class configuration. See usbh_uac_config_t.

返回:

0 on success, non-zero on failure.

void usbh_uac_deinit(void)

De-initialize the UAC Class Driver and release resources.

u8 usbh_uac_support_playback(void)

Check if UAC supports playback (speaker output).

返回:

1 if playback is supported, 0 otherwise.

u8 usbh_uac_support_record(void)

Check if UAC supports recording (microphone input).

返回:

1 if recording is supported, 0 otherwise.

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.

返回:

0 on success, non-zero on failure.

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

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

备注

The array stays addressable until usbh_uac_deinit(), but its content describes the device only until the detached callback; stop using it from then on.

参数:
  • 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, NULL if the direction is not available.

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_get_mute(u8 dir, u8 ch, u8 *mute)

Synchronously read the current mute state from the device. Issues a UAC1 GET_CUR(MUTE) on the selected channel and blocks until the response arrives or a 6 s timeout elapses.

参数:
  • dir -- Direction (USBH_UAC_ISOC_OUT_DIR or USBH_UAC_ISOC_IN_DIR).

  • ch -- Channel index (0 = master, 1..N = individual channels).

  • mute -- Output pointer that receives the device's mute state.

返回:

0 on success, non-zero on failure.

int usbh_uac_set_mute(u8 mute, u8 dir)

Set the mute state.

参数:
  • mute -- 1 to mute, 0 to unmute.

  • dir -- Direction.

返回:

0 on success, non-zero on failure.

int usbh_uac_get_volume(u8 dir, u8 ch, s16 *volume, s16 *vol_min, s16 *vol_max)

Synchronously read the current volume from the device. Issues a UAC1 GET_CUR(VOLUME) on the selected channel and blocks until the response arrives or a 6 s timeout elapses. The min/max range is returned from the cache populated at attach time.

参数:
  • dir -- Direction (USBH_UAC_ISOC_OUT_DIR or USBH_UAC_ISOC_IN_DIR).

  • ch -- Channel index (0 = master, 1..N = individual channels).

  • volume -- Output pointer that receives the current volume in raw dB units.

  • vol_min -- Output pointer for minimum volume; may be NULL.

  • vol_max -- Output pointer for maximum volume; may be NULL.

返回:

0 on success, non-zero on failure.

int usbh_uac_set_volume(u8 volume, u8 dir)

Set the volume level percentage.

备注

A channel whose volume range could not be read at attach is skipped with a warning.

参数:
  • volume -- Volume level (0-100).

  • dir -- Direction.

返回:

0 on success, non-zero on failure.

const usbh_uac_fu_info_t *usbh_uac_get_volume_ctrl_info(u8 dir)

Get the parsed Feature Unit info for the active streaming direction. The returned struct exposes bma_controls<a href="mirroring the UAC1 bmaControls layout: index 0 = master,

indices 1..num_channels = per-channel".

>0..num_channels, so callers can iterate uniformly and filter against any UAC1 control bit (USB_UAC1_CONTROL_VOLUME, USB_UAC1_CONTROL_MUTE, ...). set_volume() and set_mute() walk this same structure, so callers can reuse the iteration pattern to verify exactly what was written.

参数:

dir -- Direction (USBH_UAC_ISOC_OUT_DIR or USBH_UAC_ISOC_IN_DIR).

返回:

Pointer to the FU info, or NULL if the device has no Feature Unit on this direction. Valid until the device is detached.

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.

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

Write audio data to the UAC driver ring buffer.

备注

Single writer: call it from one thread at a time.

参数:
  • buffer -- Pointer to the PCM data buffer.

  • size -- Size of data to write (in bytes), at most 0x7FFFFFFF.

  • timeout_ms -- Maximum wait in milliseconds each time the buffer is full; 0 for non-blocking. The call returns once all data is queued, or when no space frees up within timeout_ms, so it may block longer than timeout_ms while playback progresses.

返回:

> 0: bytes queued, less than size when the buffer stayed full or the stream ended midway; 0: the stream runs but the buffer stayed full, nothing was queued; -RTK_ERR_BADARG: invalid argument or no playback interface; -RTK_ERR_BUSY: playback is not started; -RTK_ERR_IO: the device is not connected.

void usbh_uac_start_capture(void)

Start the audio capture process (microphone recording). Enables SOF handling and prepares for data reception.

void usbh_uac_stop_capture(void)

Stop the audio capture process.

int usbh_uac_read(u8 *buffer, u32 size, u32 time_out_ms)

Read audio data from UAC IN (microphone)

参数:
  • buffer -- Pointer to the data buffer to store read data

  • size -- Size of data to read (in bytes)

  • time_out_ms -- Total budget in milliseconds this call may spend waiting for data, not a per-packet allowance; 0 for non-blocking. May return fewer than size bytes when the budget runs out.

返回:

> 0: bytes read; 0: the stream runs but no data arrived within time_out_ms; -RTK_ERR_BADARG: invalid argument or no record interface; -RTK_ERR_BUSY: capture is not started; -RTK_ERR_IO: the device is not connected.

Host UVC Class Functions

Registration and teardown of the UVC host class driver, internal to the UVC class

int usbh_uvc_class_init(void)

Register the UVC class driver with the host core.

返回:

RTK_SUCCESS on success, a RTK error code otherwise.

int usbh_uvc_class_deinit(void)

Unregister the UVC class driver from the host core.

返回:

Result of usbh_unregister_class(): on anything but RTK_SUCCESS nothing was released.

Host UVC Functions

int usbh_uvc_init(const usbh_uvc_cb_t *cb, const usbh_uvc_config_t *cfg)

Initializes the UVC host class driver. Registers the application callback handler and global context, and allocates all per-stream runtime resources (frame buffers, frame lists, semaphores, mutexes and worker threads / HW channels) for every stream, moving them to the READY state. The per-stream frame buffer size is taken from cfg->frame_buf_size. This does NOT begin data transfer.

备注

The public API has a single data-flow axis: usbh_uvc_start() <-> usbh_uvc_stop() Lifecycle order: usbh_uvc_init() (resources ready here) -> usbh_uvc_set_param() -> usbh_uvc_start() (transfer begins here) -> usbh_uvc_get_frame() / usbh_uvc_put_frame() -> usbh_uvc_stop(). Resources are released by usbh_uvc_deinit().

备注

usbh_uvc_init()/usbh_uvc_deinit() take no stream_index: they prepare/release ALL streams at once (count = USBH_UVC_VS_DESC_MAX_NUM). A specific stream is then selected by the stream_index argument on the data-flow APIs. For a single-stream camera (USBH_UVC_VS_DESC_MAX_NUM = 1) stream_index must be 0; a dual-stream camera (= 2) accepts stream_index 0 or 1.

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

  • cfg -- [in] Pointer to the class configuration. See usbh_uvc_config_t.

返回:

0 on success, non-zero on failure.

int usbh_uvc_set_param(usbh_uvc_s_ctx_t *para, u8 stream_index)

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

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

  • stream_index -- [in] VideoStreaming stream index, range 0 .. USBH_UVC_VS_DESC_MAX_NUM-1 (must be 0 for a single-stream camera).

返回:

0 on success, non-zero on failure.

int usbh_uvc_start(u8 stream_index)

Start video streaming and kick off isochronous data transfer. Data-flow-axis entry; the stream resources are ready after usbh_uvc_init() and must be negotiated (usbh_uvc_set_param) first. Pair with usbh_uvc_stop().

参数:

stream_index -- [in] VideoStreaming stream index, range 0 .. USBH_UVC_VS_DESC_MAX_NUM-1 (must be 0 for a single-stream camera).

返回:

0 on success, non-zero on failure.

usbh_uvc_frame_t *usbh_uvc_get_frame(u8 stream_index)

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

备注

One consumer thread per stream: usbh_uvc_stop() and usbh_uvc_deinit() wait for the call in progress to return, so they must not be called from inside it.

参数:

stream_index -- [in] VideoStreaming stream index, range 0 .. USBH_UVC_VS_DESC_MAX_NUM-1 (must be 0 for a single-stream camera).

返回:

Pointer to a valid usbh_uvc_frame_t if available, otherwise NULL.

int usbh_uvc_put_frame(usbh_uvc_frame_t *frame, u8 stream_index)

Returns a processed frame back to the driver's free pool. Must be called after the application finishes using the frame, and for every frame got before usbh_uvc_stop(): usbh_uvc_start() refuses to restart the HW decoder while one is still held.

备注

Same single consumer thread per stream as usbh_uvc_get_frame().

参数:
  • frame -- [in] Pointer to the frame to be released. Must be obtained via usbh_uvc_get_frame().

  • stream_index -- [in] VideoStreaming stream index, range 0 .. USBH_UVC_VS_DESC_MAX_NUM-1 (must be 0 for a single-stream camera).

返回:

0 on success, -RTK_ERR_BADARG on invalid parameters, -RTK_ERR_IO if the frame lock failed.

int usbh_uvc_stop(u8 stream_index)

Stop video streaming and return to the ready state (resources retained). Data-flow-axis exit; the stream stays ready and can be re-started with usbh_uvc_start() without re-init. Pair with usbh_uvc_start().

参数:

stream_index -- [in] VideoStreaming stream index, range 0 .. USBH_UVC_VS_DESC_MAX_NUM-1 (must be 0 for a single-stream camera).

返回:

0 on success, non-zero on failure.

void usbh_uvc_deinit(void)

De-initializes the UVC host class driver and releases resources. Releases everything allocated by usbh_uvc_init() (frame buffers, frame lists, semaphores, mutexes and worker threads / HW channels) for every stream and wakes up any thread blocked in usbh_uvc_get_frame().

Host UVC Parse Functions

UVC descriptor parsing and format lookup, internal to the UVC class

int usbh_uvc_parse_cfgdesc(usb_host_t *host)

Parse the configuration descriptor into the UVC descriptor tree.

参数:

host -- Host handle.

返回:

RTK_SUCCESS on success, a RTK error code otherwise.

int usbh_uvc_desc_find_format_frame(usbh_uvc_stream_t *stream, usbh_uvc_s_ctx_t *context, u8 *format_idx, u8 *frame_idx)

Find the format and frame index matching a requested resolution and format type.

参数:
  • stream -- UVC streaming interface to search.

  • context -- Requested configuration, carrying width, height and format type.

  • format_idx -- Output, receives the matching format index.

  • frame_idx -- Output, receives the matching frame index.

返回:

RTK_SUCCESS on success, a RTK error code when nothing matches.

int usbh_uvc_desc_find_frame_rate(usbh_uvc_stream_t *stream, usbh_uvc_s_ctx_t *context, u32 *interval, u8 *format_idx, u8 *frame_idx)

Find the frame interval matching a requested frame rate.

参数:
  • stream -- UVC streaming interface to search.

  • context -- Requested configuration, carrying the frame rate.

  • interval -- Output, receives the matching frame interval.

  • format_idx -- Output, receives the matching format index.

  • frame_idx -- Output, receives the matching frame index.

返回:

RTK_SUCCESS on success, a RTK error code when nothing matches.

int usbh_uvc_desc_init(void)

Allocate the UVC descriptor parser state.

返回:

RTK_SUCCESS on success, a RTK error code otherwise.

void usbh_uvc_desc_deinit(void)

Free the UVC descriptor parser state.

返回:

None

u16 usbh_uvc_get_ctrl_len_by_version(u16 bcdUVC)

Get the Probe/Commit control wLength for a UVC release number.

备注

Ref UVC 1.5 Table 4-75.

参数:

bcdUVC -- UVC device release number, such as 0x0100, 0x0110 or 0x0150.

返回:

26 for UVC 1.0, 34 for UVC 1.1, 48 for UVC 1.5.

Host UVC Stream Functions

Stream negotiation, lifecycle and data path of the UVC class, internal to it

int usbh_uvc_stream_ctrl_set_video(usbh_uvc_stream_t *stream, u8 probe)

Send a SET_CUR request on the Probe or Commit control.

参数:
  • stream -- UVC streaming interface.

  • probe -- 1 to address the Probe control, 0 for the Commit control.

返回:

RTK_SUCCESS on success, a RTK error code otherwise.

int usbh_uvc_stream_ctrl_get_video(usbh_uvc_stream_t *stream, u8 probe, u16 request)

Send a GET request, such as GET_CUR or GET_DEF, on the Probe or Commit control.

参数:
  • stream -- UVC streaming interface.

  • probe -- 1 to address the Probe control, 0 for the Commit control.

  • request -- Request code to issue.

返回:

RTK_SUCCESS on success, a RTK error code otherwise.

int usbh_uvc_stream_open(usbh_uvc_stream_t *stream)

Allocate and initialize all runtime resources of a UVC stream.

参数:

stream -- UVC streaming interface.

返回:

RTK_SUCCESS on success, a RTK error code otherwise.

void usbh_uvc_stream_close(usbh_uvc_stream_t *stream)

Release all runtime resources of a UVC stream.

参数:

stream -- UVC streaming interface.

返回:

None

int usbh_uvc_stream_start(usbh_uvc_stream_t *stream)

Start the data path of a UVC stream, moving it from READY to ACTIVE.

参数:

stream -- UVC streaming interface.

返回:

RTK_SUCCESS on success or if the stream is already active, a RTK error code otherwise.

int usbh_uvc_stream_stop(usbh_uvc_stream_t *stream)

Stop the data path of a UVC stream, moving it from ACTIVE to READY.

参数:

stream -- UVC streaming interface.

返回:

RTK_SUCCESS on success or if the stream is not currently active, a RTK error code otherwise.

void usbh_uvc_stream_flush(usbh_uvc_stream_t *stream)

Synchronously flush all per-round runtime state of a UVC stream.

参数:

stream -- UVC streaming interface.

返回:

None

void usbh_uvc_stream_free_urb_buffer(usbh_uvc_stream_t *stream)

Free the URB buffers, which are sized for the previous alternate setting MPS.

参数:

stream -- UVC streaming interface.

返回:

None

int usbh_uvc_stream_alloc_urb_buffer(usbh_uvc_stream_t *stream)

Allocate the URB buffers sized to the pipe's current transfer length.

参数:

stream -- UVC streaming interface.

返回:

RTK_SUCCESS on success, a RTK error code otherwise.

void usbh_uvc_stream_process_sof(usb_host_t *host)

Process a Start Of Frame event and resubmit the isochronous IN URBs.

备注

ISR context: must not block or allocate.

参数:

host -- Host handle.

返回:

None

int usbh_uvc_stream_process_completed(usb_host_t *host, u8 pipe_num)

Process a completed isochronous IN transfer and assemble the frame payload.

备注

ISR context: must not block or allocate.

参数:
  • host -- Host handle.

  • pipe_num -- Pipe number that completed.

返回:

RTK_SUCCESS on success, a RTK error code otherwise.

Host Vendor Functions

int usbh_vendor_init(const usbh_vendor_cb_t *cb)

Initialize the Vendor Class driver.

参数:

cb -- Pointer to the application callback structure.

返回:

0 on success, non-zero on failure.

void usbh_vendor_deinit(void)

De-Initialize the Vendor Class driver.

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

USBH_CDC_ACM_DEBUG

Enable/Disable debug dump (pipe/descriptor info). Set to 1 for debug.

USBH_CDC_ACM_DEFAULT_DTE_RATE

Default dwDteRate.

USBH_CDC_ACM_DEFAULT_DATA_BITS

Default bDataBits.

CONFIG_USBH_CDC_ACM_4G_DONGLE

Enable optional 4G LTE dongle support (Quectel / Fibocom, ECM mode). When enabled, the driver accepts a VID/PID parameter table via usbh_cdc_acm_config_t::dongle_param and handles vendor-specific ACM topologies (param-driven AT-command interface index, single vendor interface carrying INTR+BULK+BULK, SET_INTERFACE alternate setting).

备注

When enabled, only a device listed in dongle_param is attached: a plain CDC ACM device whose VID/PID is not in the table fails to attach.

USBH_CDC_ACM_QUECTEL_DONGLE_VID
USBH_CDC_ACM_QUECTEL_DONGLE_EG915_PID
USBH_CDC_ACM_QUECTEL_DONGLE_EG91_PID
USBH_CDC_ACM_FIBOCOM_DONGLE_LE271_VID
USBH_CDC_ACM_FIBOCOM_DONGLE_LE271_PID
USBH_CDC_ACM_SIMCOM_DONGLE_SIM767X_VID
USBH_CDC_ACM_SIMCOM_DONGLE_SIM767X_PID

Host CDC ECM Constants

USBH_CDC_ECM_STATE_TRACE_ENABLE

Enable or disable CDC ECM state trace logging.

USBH_CDC_ECM_MAC_STR_LEN

Length of the MAC address in bytes.

USBH_CDC_ECM_CTRL_REG_BUF_LEN

Length of the ECM dongle control register buffer.

USBH_CDC_ECM_MULTICAST_FILTER_STR_LEN

Length of the ECM multicast filter control buffer.

Host CDC NCM Constants

USBH_CDC_NCM_STATE_TRACE_ENABLE

Enable or disable NCM state trace logging.

CDC_NCM_MAC_STR_LEN

Length of the MAC address in bytes.

CDC_NCM_CTRL_REG_BUF_LEN

Length of the NCM dongle control register buffer.

USBH_CDC_NCM_TX_AGG_MAX_DATAGRAMS

Max frames coalesced per NTB.

USBH_CDC_NCM_TX_AGG_NUM_BUF

Ping-pong buffer count (fixed at 2).

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_HUB_PORT
USBH_CLASS_ISR_SYNC_TIMEOUT_MS

Default usbh_sync_isr() bound for a class tearing down after its slot gate closed

USBH_TEARDOWN_WAIT_FIRST_LOG_MS

A teardown wait that has no upper bound logs an ERROR once it has waited this long

USBH_TEARDOWN_WAIT_LOG_MS

... and repeats it at this period from then on

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

Host DFU Constants

USBH_DFU_DEFAULT_XFER_SIZE

Default maximum transfer size for a single DFU block transfer (bytes).

Applied when usbh_dfu_config_t::xfer_size is left 0.

USBH_DFU_MAX_RETRY
USBH_DFU_MAX_POLL_TIMEOUT
USBH_DFU_POLL_SLICE_MS
USBH_DFU_POLL_MIN_MS
USBH_DFU_MAX_DNLOAD_POLL
USBH_DFU_DNLOAD_POLL_BUDGET_MS
USBH_DFU_MAX_MANIFEST_RETRY

Host HID Constants

USBH_CLASS_HID

USB HID Class Code

USBH_HID_DESC

HID Descriptor Type

USBH_HID_REPORT_TYPE

HID Report Descriptor Type

USBH_HID_ITEM_TYPE_MAIN

Main Item Type

USBH_HID_ITEM_TYPE_GLOBAL

Global Item Type

USBH_HID_ITEM_TYPE_LOCAL

Local Item Type

USBH_HID_MAIN_ITEM_TAG_INPUT

Input Tag

USBH_HID_MAIN_ITEM_TAG_OUTPUT

Output Tag

USBH_HID_MAIN_ITEM_TAG_COLLECTION

Collection Tag

USBH_HID_MAIN_ITEM_TAG_FEATURE

Feature Tag

USBH_HID_MAIN_ITEM_TAG_END_COLLECTION

End Collection Tag

USBH_HID_ITEM_DATA_CONSTANT

0: Data, 1: Constant(padding)

USBH_HID_ITEM_DATA_VARIABLE

0: Array, 1: Variable

USBH_HID_GLOBAL_ITEM_TAG_USAGE_PAGE

Usage Page Tag

USBH_HID_GLOBAL_ITEM_TAG_LOGICAL_MINIMUM

Logical Minimum Tag

USBH_HID_GLOBAL_ITEM_TAG_LOGICAL_MAXIMUM

Logical Maximum Tag

USBH_HID_GLOBAL_ITEM_TAG_REPORT_SIZE

Report Size Tag

USBH_HID_GLOBAL_ITEM_TAG_REPORT_ID

Report ID Tag

USBH_HID_GLOBAL_ITEM_TAG_REPORT_COUNT

Report Count Tag

USBH_HID_LOCAL_ITEM_TAG_USAGE

Usage Tag

USBH_HID_LOCAL_ITEM_TAG_USAGE_MIN

Usage Minimum Tag

USBH_HID_LOCAL_ITEM_TAG_USAGE_MAX

Usage Maximum Tag

USBH_HID_UP_CONSUMER

Consumer Usage Page

USBH_HID_CONSUMER_VOLUME_UP

Volume Increment

USBH_HID_CONSUMER_VOLUME_DOWN

Volume Decrement

USBH_HID_CONSUMER_MUTE

Mute

USBH_HID_CONSUMER_PLAY_PAUSE

Play/Pause

USBH_HID_CONSUMER_STOP

Stop

USBH_HID_BIT_NONE

Control is not declared in the report descriptor

USBH_HID_TRACK_VOLUME_UP

Tracked usage slot: Volume Up

USBH_HID_TRACK_VOLUME_DOWN

Tracked usage slot: Volume Down

USBH_HID_TRACK_MUTE

Tracked usage slot: Mute

USBH_HID_TRACK_PLAY_PAUSE

Tracked usage slot: Play/Pause

USBH_HID_TRACK_STOP

Tracked usage slot: Stop

USBH_HID_TRACK_USAGE_CNT

Tracked usages: volume up/down/mute, play-pause, stop

USBH_HID_ARRAY_ELEM_CNT

Max usage codes decoded from one Array field

USBH_HID_REPORT_MAX_LEN

Largest FS/LS INTR IN report kept per ring node (Ref USB 2.0 5.7.3)

USBH_HID_DESC_LEN

HID descriptor length with one class descriptor, Ref HID 1.11 6.2.1

USBH_HID_HALT_RETRY_MAX_CNT

CLEAR_FEATURE(ENDPOINT_HALT) attempts before the device is re-enumerated

Host MSC Constants

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_DATA_LENGTH

Generic data buffer length for small transfers, one HS bulk packet.

USBH_BOT_CSW_BUF_LENGTH

CSW buffer length, one HS bulk packet.

USBH_MSC_MAX_LUN

Maximum number of logical units (LUNs) supported.

USBH_MSC_MIN_BLOCK_SIZE

Minimum accepted logical block size reported by READ CAPACITY(10).

USBH_MSC_MAX_BLOCK_SIZE

Maximum accepted logical block size reported by READ CAPACITY(10).

USBH_MSC_DEFAULT_BUF_SIZE

Default size of the READ(10)/WRITE(10) bounce buffer.

USBH_MSC_MAX_BUF_SIZE

Maximum size of the READ(10)/WRITE(10) bounce buffer.

Host MSC Disk Constants

Retry policy of the FatFs disk I/O glue of the MSC class

USBH_MSC_RETRY_ENABLE

Set to 1 to retry failed sector I/O, used for the USB EMC test.

USBH_MSC_RETRY_CNT

Number of retries per sector when USBH_MSC_RETRY_ENABLE is 1.

Host UAC Constants

USBH_UAC_DEBUG

UAC debug switch. Set to 1 to enable verbose UAC logging and the periodic status dump thread; 0 to compile them out.

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_UNIT_MAX_CNT

Maximum number of intermediate Units (Mixer/Selector/Processing/Extension) tracked for topology walks

USBH_UAC_UNIT_SRC_MAX_CNT

Maximum number of bSourceID entries tracked per intermediate Unit

USBH_UAC_TOPO_DEPTH_MAX

Maximum topology hops walked from an Output Terminal back to a Feature Unit

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

USBH_UAC_FMT_MAX

Maximum number of formats listed per AS interface

USBH_UAC_ISOC_OUT_DIR

Isochronous OUT endpoint (Playback)

USBH_UAC_ISOC_IN_DIR

Isochronous IN endpoint (Recording)

Host UVC Constants

USBH_UVC_USE_HW

Disable usage of UVC hardware decoder.

USBH_UVC_FORMAT_MJPEG

Motion-JPEG format.

USBH_UVC_FORMAT_YUV

Uncompressed YUV format.

USBH_UVC_FORMAT_H264

H.264 (frame-based) format.

USBH_UVC_FORMAT_H265

H.265/HEVC (frame-based) format (driver-private selector).

USBH_UVC_VS_DESC_MAX_NUM
USBH_UVC_VS_ALTS_MAX_NUM
USBH_UVC_GET_FRAME_TIMEOUT

Timeout for getting a frame in ms.

USBH_UVC_VIDEO_FRAME_NUMS

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

USBH_UVC_SET_ALT_RETRY_MAX

Max retries for SET_ALT (SET_INTERFACE) failures.

USBH_UVC_URB_NUMS

Ring depth: number of single-packet URB slots (usable = NUMS-1).

USBH_UVC_URB_WATERMARK

ISR wakes combine thread when ready URB count >= this. Must be < USBH_UVC_URB_NUMS.

USBH_UVC_URB_PACKET_NUM

Payload packets per URB slot; also the packet_info[] entry count.

USBH_UVC_COMBINE_TASK_STACK

Stack size for the combine task in bytes.

USBH_UVC_COMBINE_TASK_PRIORITY

Priority of the combine task.

USBH_UVC_DEBUG

Host UVC Descriptor Constants

Class-specific descriptor type and subtype codes of the UVC specification

USBH_UVC_VC_DESCRIPTOR_UNDEFINED
USBH_UVC_VC_HEADER
USBH_UVC_VC_INPUT_TERMINAL
USBH_UVC_VC_OUTPUT_TERMINAL
USBH_UVC_VC_SELECTOR_UNIT
USBH_UVC_VC_PROCESSING_UNIT
USBH_UVC_VC_EXTENSION_UNIT
USBH_UVC_VC_ENCODING_UNIT
USBH_UVC_VS_UNDEFINED
USBH_UVC_VS_INPUT_HEADER
USBH_UVC_VS_OUTPUT_HEADER
USBH_UVC_VS_STILL_IMAGE_FRAME
USBH_UVC_VS_FORMAT_UNCOMPRESSED
USBH_UVC_VS_FRAME_UNCOMPRESSED
USBH_UVC_VS_FORMAT_MJPEG
USBH_UVC_VS_FRAME_MJPEG
USBH_UVC_VS_FORMAT_MPEG2TS
USBH_UVC_VS_FORMAT_DV
USBH_UVC_VS_COLORFORMAT
USBH_UVC_VS_FORMAT_FRAME_BASED
USBH_UVC_VS_FRAME_FRAME_BASED
USBH_UVC_VS_FORMAT_STREAM_BASED
USBH_UVC_EP_UNDEFINED
USBH_UVC_EP_GENERAL
USBH_UVC_EP_ENDPOINT
USBH_UVC_EP_INTERRUPT
USBH_UVC_RC_UNDEFINED
USBH_UVC_SET_CUR
USBH_UVC_GET_CUR
USBH_UVC_GET_MIN
USBH_UVC_GET_MAX
USBH_UVC_GET_RES
USBH_UVC_GET_LEN
USBH_UVC_GET_INFO
USBH_UVC_GET_DEF
USBH_UVC_VS_PROBE_CONTROL
USBH_UVC_VS_COMMIT_CONTROL
USBH_UVC_DESC_TYPE_CS_INTERFACE
USBH_UVC_DESC_TYPE_CS_ENDPOINT
USBH_UVC_PH_FID
USBH_UVC_PH_EOF
USBH_UVC_PH_PTS
USBH_UVC_PH_SCR
USBH_UVC_PH_RES
USBH_UVC_PH_STI
USBH_UVC_PH_ERR
USBH_UVC_PH_EOH

Host UVC Parse Constants

Unit conversion constants of the UVC descriptor parser

USBH_UVC_FRAME_INTERVAL_UNIT_NS

UVC frame interval base unit: 100ns (10^7 * 100ns = 1s).

Host Vendor Constants

USBH_VENDOR_DEBUG

Enable the ISOC test finish log and buffer dump.

备注

Set to 1 for manual debugging only: the dump is test_cnt/10 UART lines, which costs tens of ms at 115200 baud. It is emitted from usbh_vendor_process (task context), never from the SOF ISR, but it still delays the host task while it runs.

VENDOR_CLASS_CODE

Vendor Specific Class Code

VENDOR_SUBCLASS_CODE

Vendor Specific SubClass Code

VENDOR_PROTOCOL

Vendor Specific Protocol Code

USB Host Types

Host CDC ACM Types

enum usbh_cdc_acm_state_t

CDC ACM EP0 class request state machine.

Tracks the control pipe only. The BULK and INTR pipes are independent of EP0 (Ref USB 2.0 5.3.2), so a data transfer has no state here and never waits for, or is blocked by, a class request.

Values:

enumerator USBH_CDC_ACM_STATE_IDLE

State IDLE: EP0 free for a new class request.

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_SEND_BREAK

State SEND_BREAK: Sending break signal (PSTN §6.3.13).

enumerator USBH_CDC_ACM_STATE_ERROR

State ERROR: Error occurred.

struct usbh_cdc_acm_param_t
#include <usbh_cdc_acm.h>

4G dongle VID/PID parameter entry.

A NULL-terminated array (vid==0 sentinel) supplied through usbh_cdc_acm_config_t::dongle_param lets the driver recognise specific LTE dongles and locate their AT-command interface. Only consulted when CONFIG_USBH_CDC_ACM_4G_DONGLE is enabled.

Public Members

u16 vid

Dongle Vendor ID.

u16 pid

Dongle Product ID.

u8 at_line_idx

Dongle AT-command interface index (used as SET/GET_LINE_CODING wIndex and comm interface number).

struct usbh_cdc_acm_config_t
#include <usbh_cdc_acm.h>

Configuration for the CDC ACM host class.

Carries every CDC ACM host option: the initial line coding and control line state the driver applies to the attached device, plus the optional 4G-dongle identification table. Host-global parameters (speed, FIFO depths, main task stack and priority, ISR priority) live in usbh_config_t instead, and application-level options such as hotplug or worker task priorities belong in the application's own configuration.

备注

The structure is stored by pointer, not copied, so it shall remain valid until usbh_cdc_acm_deinit.

Public Members

const usbh_cdc_acm_param_t *dongle_param

Optional 4G-dongle VID/PID table, NULL-terminated (vid == 0 sentinel).

NULL for a plain CDC ACM device. Ignored unless CONFIG_USBH_CDC_ACM_4G_DONGLE is enabled.

u32 dte_rate

dwDteRate, 0 uses USBH_CDC_ACM_DEFAULT_DTE_RATE (Ref PSTN 1.2 6.3.11).

u8 data_bits

bDataBits, 0 uses USBH_CDC_ACM_DEFAULT_DATA_BITS.

u8 char_format

bCharFormat, one of the LINE_CODING_CHAR_FORMAT_* values.

0 is the valid encoding for 1 stop bit, so it is used as given rather than being treated as "take the default".

u8 parity_type

bParityType, one of the LINE_CODING_PARITY_* values.

0 is the valid encoding for no parity, so it is used as given.

u8 ctrl_line_state

Initial SET_CONTROL_LINE_STATE bitmap: D0 = DTR, D1 = RTS (Ref PSTN 1.2 6.3.12).

0 is a valid state (both lines deasserted), so it is used as given.

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

Public Members

int (*init)(void)

Called when the CDC ACM host driver initialization.

Return:

0 on success, non-zero on failure.

void (*deinit)(void)

Called when the CDC ACM host driver de-initialization.

void (*attached)(void)

Called when a CDC ACM device is attached.

void (*detached)(void)

Called when a CDC ACM device is detached.

void (*setup)(void)

Called to handle class-specific SETUP requests completion.

void (*notify)(u8 *buf, u32 len, int 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.

void (*received)(u8 *buf, u32 len, int 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.

void (*transmitted)(int status)

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

Param status:

[in] The status of the transmission.

void (*line_coding_changed)(usb_cdc_acm_line_coding_t *line_coding)

Called after the device reported its line coding, which may differ from the one requested.

Param line_coding:

[in] Pointer to the new line coding structure.

struct usbh_cdc_acm_host_t
#include <usbh_cdc_acm.h>

Structure representing the CDC ACM host instance.

Public Members

usb_host_t *host

Pointer to the USB host instance.

const usbh_cdc_acm_cb_t *cb

Pointer to the user-defined callback structure.

const usbh_cdc_acm_config_t *cfg

Pointer to the class configuration (set by init).

u8 state

EP0 class request state, usbh_cdc_acm_state_t.

u8 comm_itf_num

bInterfaceNumber of Communication Interface, used as wIndex in class requests (SET_CONTROL_LINE_STATE / SEND_BREAK).

u8 bulk_in_busy

BULK IN submitted and its completion not yet reported.

u8 bulk_out_busy

BULK OUT submitted and its completion not yet reported.

u8 intr_in_busy

INTR IN submitted and its completion not yet reported.

u8 line_coding_valid

line_coding filled by setup(), from the device or the default.

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_cdc_acm_line_coding_t *line_coding

Current line coding of the device.

usb_cdc_acm_line_coding_t *user_line_coding

User requested line coding.

u16 ctrl_line_state

Control Signal Bitmap sent in SET_CONTROL_LINE_STATE wValue: D0=DTR, D1=RTS (PSTN §6.3.12).

u16 break_duration

Duration for SEND_BREAK in milliseconds; 0xFFFF = continuous break.

Host CDC ECM Types

struct usbh_cdc_ecm_config_t
#include <usbh_cdc_ecm.h>

Configuration for the CDC ECM host class.

Carries every CDC ECM host option: the MAC address to program into a Realtek dongle and the dongle LED pattern. Host-global parameters (speed, FIFO depths, main task stack and priority, ISR priority) live in usbh_config_t instead.

备注

The structure is stored by pointer, but both arrays are copied at init, so the arrays themselves need not outlive the init call.

Public Members

const u16 *led_array

LED state array, NULL for none; each u16 element is one LED state.

const u8 *mac_value

MAC address to program, 6 bytes, NULL to keep the dongle default.

u8 led_cnt

Number of valid elements in led_array; 0 disables LED setup.

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.

void (*deinit)(void)

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

void (*attached)(void)

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

void (*detached)(void)

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

void (*setup)(void)

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

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

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

备注

Runs in the USB host task. buf is valid only until the callback returns: the class re-arms the same buffer right after, so copy the frame out before returning, never keep the pointer.

Param buf:

[in] Pointer to the buffer containing received data.

Param len:

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

struct usbh_cdc_ecm_pipe_info_t
#include <usbh_cdc_ecm.h>

Public Members

usbh_pipe_t pipe

USB Host pipe handle.

usbh_ep_desc_t ep_desc

Endpoint descriptor (byte-packed).

u8 valid

Validity flag for this pipe info.

Host CDC NCM Types

struct usbh_cdc_ncm_config_t
#include <usbh_cdc_ncm.h>

Configuration for the CDC NCM host class.

Carries every CDC NCM host option. Host-global parameters (speed, FIFO depths, main task stack and priority, ISR priority) live in usbh_config_t instead.

备注

The structure is stored by pointer, but the MAC is copied at init, so the buffer itself need not outlive the init call.

Public Members

const u8 *mac_value

MAC address to program, 6 bytes, NULL to keep the dongle default.

struct usbh_cdc_ncm_state_cb_t
#include <usbh_cdc_ncm.h>

Public Members

int (*init)(void)

Callback invoked during NCM class driver initialization.

Return:

0 on success, non-zero on failure.

void (*deinit)(void)

Callback invoked during NCM class driver de-initialization.

void (*attached)(void)

Callback invoked when a device is attached.

void (*detached)(void)

Callback invoked when a device is detached.

void (*setup)(void)

Callback invoked when the device setup phase is complete.

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

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

备注

Runs in the USB host task, once per datagram of the NTB. buf is valid only until the callback returns: the class re-arms the NTB buffer right after, so copy the frame out before returning.

Param buf:

[in] Pointer to the buffer containing received data.

Param len:

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

struct usbh_cdc_ncm_pipe_info_t
#include <usbh_cdc_ncm.h>

Public Members

usbh_pipe_t pipe

USB Host pipe handle.

usbh_ep_desc_t ep_desc

Endpoint descriptor (byte-packed).

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_type_t

Defines application message types for user process callbacks of usbh_user_cb_t.

备注

Naming convention in the host stack: everything the core hands to an upper layer is a message, distinguished by recipient. An application message (usbh_msg_type_t, USBH_MSG_*) is a notification code passed synchronously to the application's usbh_user_cb_t process() callback and is never queued. A driver message (usbh_drv_msg_t, usbh_drv_msg_type_t, USBH_DRV_MSG_*) is an item of the HCD message queue, consumed by the host main task and dispatched to class drivers. The two families are unrelated; do not mix them. The unprefixed USBH_MSG_* family is the application-facing one, kept unprefixed for API compatibility.

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_WAKEUP

Message indicating the host has been woken from suspend by a device-initiated remote wakeup.

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 the core gave the attached device up: enumeration aborted, a usbh_reenumerate() / usbh_power_cycle() request refused, or a VBUS power cycle failed or the device did not come back from it. The device is left alone until replugged. A failed control request is reported only to its requester, by return value.

enumerator USBH_MSG_RESET

Message indicating a class-requested reset of the attached device is starting. Reported before the class detach callbacks it causes, which are therefore not an unplug; the device is then enumerated again and the classes re-attach. No USBH_MSG_DISCONNECTED / USBH_MSG_CONNECTED pair is reported for it.

enumerator USBH_MSG_POWER_CYCLE

Message indicating a VBUS power cycle of the attached device is starting, see usbh_power_cycle(). Reported before the class detach callbacks it causes; the device then drops off the bus, is powered again and enumerated from scratch. No USBH_MSG_DISCONNECTED / USBH_MSG_CONNECTED pair is reported for it.

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

Error state for tick source.

typedef struct _usbh_itf_data_t usbh_itf_data_t

Holds all parsed information for one unique bInterfaceNumber.

The USB framework organises interfaces along two axes:

  1. Same bInterfaceNumber, different bAlternateSetting -> stored inside this node as itf_desc_array[0..alt_setting_cnt-1]. Example: CDC-ACM data interface has alt=0 (no endpoints, default) and alt=1 (BULK IN + BULK OUT, active).

  2. Different bInterfaceNumber, same class/subclass/protocol -> chained via the next pointer. Example: a composite device with 3 CDC-ACM produces three separate nodes (one per ACM ctrl interface) linked as: [itf1/ACM#1] -> [itf2/ACM#2] -> [itf3/ACM#3] -> NULL

usbh_get_interface_descriptor() returns the head of the matching chain. The caller walks ->next to reach every interface of the same class.

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 0, each interface specifies its own class code. If 0xFF, the class code is vendor specified. Otherwise, this field is a 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>

Holds all parsed information for one unique bInterfaceNumber.

The USB framework organises interfaces along two axes:

  1. Same bInterfaceNumber, different bAlternateSetting -> stored inside this node as itf_desc_array[0..alt_setting_cnt-1]. Example: CDC-ACM data interface has alt=0 (no endpoints, default) and alt=1 (BULK IN + BULK OUT, active).

  2. Different bInterfaceNumber, same class/subclass/protocol -> chained via the next pointer. Example: a composite device with 3 CDC-ACM produces three separate nodes (one per ACM ctrl interface) linked as: [itf1/ACM#1] -> [itf2/ACM#2] -> [itf3/ACM#3] -> NULL

usbh_get_interface_descriptor() returns the head of the matching chain. The caller walks ->next to reach every interface of the same class.

Public Members

struct _usbh_itf_data_t *next

Next node with a different bInterfaceNumber but identical class/subclass/protocol; NULL if this is the last in the chain.

usbh_itf_desc_t *itf_desc_array

Array of alt-setting descriptors for this interface number, indexed [0..alt_setting_cnt-1] by bAlternateSetting order.

u8 *raw_data

Start of the raw descriptor bytes for this interface; used by class drivers to parse class-specific (CS) descriptors that the generic framework does not decode.

u16 raw_data_len

Byte length of the raw_data region (covers all alt settings and their CS/endpoint descriptors).

u8 alt_setting_cnt

Number of alternate settings; equals the length of itf_desc_array.

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 identified 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 bDescLength

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.

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_drv_msg_t
#include <usbh.h>

Packed structure for an item of the HCD driver message queue.

Public Members

u32 data

Message private data. For USBH_DRV_MSG_CLASS this carries the originating class driver's slot index (0..config.class_num-1); CLASS_READY dispatch uses it to index class_slot[] and route the message to exactly that driver, so per-class process() handlers no longer need an owner filter guard.

u16 tick

Tick count when the message was raised.

u8 pipe_num

Pipe number associated with the message.

u8 type

Driver message type, corresponds to usbh_drv_msg_type_t.

struct usbh_config_t
#include <usbh.h>

USB host user configuration structure.

Public Members

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

u16 main_task_stack_size

USB main task stack size.

u16 diag_depth

Diag ring buffer depth in entries; 0 uses USB_DIAG_DEFAULT_DEPTH. Requires diag_enable.

u16 diag_poll_ms

Diag task polling interval in ms; 0 uses USB_DIAG_DEFAULT_POLL_MS. Requires diag_enable.

u8 main_task_priority

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

u8 isr_priority

USB ISR priority.

u8 xfer_retry_max_cnt

Maximum number of retries for a failed transfer.

u8 class_num

Maximum number of class drivers that can be registered.

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 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 applications like UAC).

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

u8 isr_in_critical

Process the whole USB ISR, class callbacks included, inside the USB critical section (0: Disable, 1: Enable).

When enabled:

  • The callbacks run with interrupts disabled, and with the USB spinlock held under SMP: keep them short. Under SMP a USB API called on the other core spins with its interrupts disabled until the ISR has left.

  • A callback shall not take the critical section of another component, and no code shall call a USB API while holding one. Under SMP either order against the ISR on the other core deadlocks both cores.

备注

Ignored and forced to 1 on an SMP build (RTOS_NUM_CORES > 1): the USB IRQ runs on another core than the task, which is only excluded from the ISR register and state updates if the ISR holds the USB lock as well. The rules above then always apply to the class sof()/completed() callbacks.

u8 hub_support

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

u8 diag_enable

Enable USB diag ring buffer and polling task (0: Disable, 1: Enable). When disabled, error diagnostic information is silently lost. Enable this to capture USB error events for debugging.

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 xfer_buf_len

Capacity of xfer_buf in bytes, 0 to skip the check. An IN transfer reserves whole packets, so usbh_transfer_data() rejects one whose usb_get_dma_len(xfer_len, ep_mps) exceeds it.

u32 tick

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

u16 frame_num

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

u16 max_timeout_tick

Maximum wait timeout in ticks for this transfer, a tick being 125 us at HS and 1 ms at FS/LS; 0 for 100 ms.

u16 ep_interval

Endpoint polling interval in ticks.

u16 ep_mps

Endpoint Maximum Packet Size in bytes.

  • FS: max 64 (CTRL/BULK/INTR), max 1023 (ISOC)

  • HS: max 64 (CTRL), max 512 (BULK), max 1024 (INTR/ISOC)

u8 xfer_state

Current transfer state. See usbh_ep_xfer_state_t.

u8 ep_addr

Endpoint address (including direction bit).

u8 pipe_num

Host pipe/channel number assigned to this endpoint.

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.

u8 ep_trans

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

u8 ep_type

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

u8 ep_is_in

Endpoint direction: 1 for IN, 0 for OUT.

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

Match mask.

u16 idVendor

Vendor ID.

u16 idProduct

Product ID.

u8 bDeviceClass

Device class.

u8 bDeviceSubClass

Device subclass.

u8 bDeviceProtocol

Device protocol.

u8 bInterfaceClass

Interface class.

u8 bInterfaceSubClass

Interface subclass.

u8 bInterfaceProtocol

Interface protocol.

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.

void (*detach)(struct _usb_host_t *host)

Called when a supported device is detached.

Param host:

[in] USB host.

int (*setup)(struct _usb_host_t *host)

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

Invoked repeatedly by the host core from USBH_CLASS_REQUEST and must be implemented as a non-blocking state machine: each call advances the class initialisation by at most one control transfer and returns immediately. Classes are set up strictly in registration order, so the returned status gates the progress of every later class of a composite device.

The status is interpreted in exactly three ways, and a class must not conflate them: RTK_SUCCESS: this class is fully set up. The core advances to the next class and, once all are done, enters CLASS_READY. -RTK_ERR_BUSY: still in progress, call me again. This is the only status that requests a retry, and it must be returned whenever the class intends to make further attempts - including when an optional request failed but the sequence continues to its next step. A class that stays BUSY without advancing for longer than USBH_CLASS_SETUP_TIMEOUT_MS is detached and skipped by the core's progress watchdog.

  • any other status: terminal failure. The core calls this class's detach(), drops it and continues with the remaining classes; if no class is left, the device is failed with USBH_MSG_ATTACH_FAIL. Return an error only when retrying genuinely cannot help - e.g. the device STALLed a request the class requires, since a STALL means "will not do" rather than "retry later" (USB 2.0 8.5.3.4). When a refused request is optional, fall back to a default and keep going instead of failing the class.

Param host:

[in] USB host.

Return:

RTK_SUCCESS when setup is complete, -RTK_ERR_BUSY while in progress, another status to abandon this class.

void (*process)(struct _usb_host_t *host, usbh_drv_msg_t *msg)

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

The core dispatches each driver message to exactly one class driver (by class slot for USBH_DRV_MSG_CLASS, by the pipe's owning driver otherwise), so a driver never sees a foreign message and has no result to report back to the core.

Param host:

[in] USB host.

Param msg:

[in] usbh_drv_msg_t.

void (*sof)(struct _usb_host_t *host)

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

备注

This callback is called within an interrupt service routine (ISR) context; time-consuming operations (e.g., malloc, rtos_sema_take) are not permitted.

Param host:

[in] USB host.

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

Called when a transfer on a specific pipe completes.

备注

This callback is called within an interrupt service routine (ISR) context; time-consuming operations (e.g., malloc, rtos_sema_take) are not permitted.

备注

The core routes the completion to the pipe's owning driver only (recorded from the owner passed to usbh_open_pipe), so this callback is never invoked for a foreign pipe and has no result to report back to the core.

Param host:

[in] USB host.

Param pipe:

[in] Pipe number.

struct usbh_user_cb_t
#include <usbh.h>

Structure defining user-level callbacks.

Public Members

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

Callback to handle class-independent notifications in the application.

Pure notification: the core ignores any result, so the application cannot influence the host state machine from here.

Param host:

[in] USB host.

Param msg:

[in] Application message type, usbh_msg_type_t.

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 RTK_SUCCESS, the enum process will use this device as the target device, else return !RTK_SUCCESS, 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.

int (*set_vbus)(struct _usb_host_t *host, u8 on)

Optional callback to switch the board VBUS supply of the root port, e.g. a GPIO driven load switch.

Lets the core power cycle a device that no longer answers a port reset, see usbh_power_cycle(). Once registered the core owns VBUS: it is supplied by usbh_start(), cut by usbh_deinit(), and switched off and on again by a power cycle. Leave NULL when VBUS is not switchable.

备注

Called from the host task or from the caller of usbh_start()/usbh_deinit(), never from an ISR or inside the USB critical section. Keep it short: the host task is blocked while it runs. The discharge wait after cutting VBUS is done by the core, see USBH_VBUS_OFF_MS.

备注

A hub on the root port loses power with every device behind it.

Param host:

[in] USB host.

Param on:

[in] 1 to supply VBUS, 0 to cut it.

Return:

0 on success, non-zero on failure.

struct _usb_host_t
#include <usbh.h>

USB host.

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.

const usbh_user_cb_t *cb

Pointer to the user-provided callbacks.

void *hcd

Pointer to the HCD handle.

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 DFU Types

enum usbh_dfu_state_t

DFU host-side state machine states.

Values:

enumerator USBH_DFU_STATE_IDLE

Idle; waiting for a download or upload request.

enumerator USBH_DFU_STATE_GET_STATUS

Issuing DFU_GETSTATUS to query device state.

enumerator USBH_DFU_STATE_CLR_STATUS

Issuing DFU_CLRSTATUS to clear an error.

enumerator USBH_DFU_STATE_DNLOAD_BLOCK

Fetching a block from the application and sending DFU_DNLOAD.

enumerator USBH_DFU_STATE_DNLOAD_POLL

Waiting the device-reported poll timeout before retrying.

enumerator USBH_DFU_STATE_DNLOAD_FINAL

Sending the zero-length DFU_DNLOAD to signal end-of-firmware.

enumerator USBH_DFU_STATE_MANIFEST_POLL

Polling via GETSTATUS until the device finishes manifesting.

enumerator USBH_DFU_STATE_UPLOAD_BLOCK

Issuing DFU_UPLOAD to receive one block from the device.

enumerator USBH_DFU_STATE_DONE

Transfer complete; about to invoke the completion callback.

enumerator USBH_DFU_STATE_ERROR

Error occurred; about to invoke the error callback.

enumerator USBH_DFU_STATE_RECONFIGURE

Run-Time device: sending DFU_DETACH to trigger re-enumeration.

enumerator USBH_DFU_STATE_ABORT

Issuing DFU_ABORT to cancel an in-progress transfer.

enumerator USBH_DFU_STATE_RECOVER

Issuing DFU_ABORT to return a device left mid-transfer to dfuIDLE.

struct usbh_dfu_cb_t
#include <usbh_dfu.h>

User-supplied callbacks for the DFU host class driver.

Public Members

int (*init)(void)

Called during usbh_dfu_init() for any application-side initialization.

Return:

RTK_SUCCESS on success, non-zero on failure.

void (*deinit)(void)

Called during usbh_dfu_deinit() for application-side cleanup.

void (*attached)(void)

Called when a DFU device is attached and enumerated.

Typically used to give a semaphore so the application thread can proceed.

void (*detached)(void)

Called when the DFU device is detached.

Typically used to give a semaphore so the application thread can react.

int (*get_block)(u16 block_num, u8 *buf, u32 max_len)

Called once per DFU_DNLOAD block to obtain firmware data.

Param block_num:

[in] Zero-based block index, the wBlockNum sent to the device. It wraps from 65535 to 0 (DFU 1.1 6.1.1), so an image of more than 65536 blocks needs its own block count to locate the data.

Param buf:

[out] Buffer to fill (at most max_len bytes).

Param max_len:

[in] Maximum bytes the driver can accept (wTransferSize from device).

Return:

Number of bytes written to buf; 0 signals end-of-firmware.

void (*download_done)(int status)

Called when the download operation completes (or fails).

Param status:

[in] RTK_SUCCESS on success, RTK_FAIL on failure.

int (*recv_block)(u16 block_num, u8 *buf, u32 len)

Called after each DFU_UPLOAD block is received from the device.

Param block_num:

[in] Zero-based block index, wraps from 65535 to 0 as in get_block.

Param buf:

[in] Buffer containing the received data.

Param len:

[in] Number of bytes in buf.

Return:

RTK_SUCCESS to continue uploading; any other value aborts the upload.

void (*upload_done)(int status)

Called when the upload operation completes (or fails).

Param status:

[in] RTK_SUCCESS on success, RTK_FAIL on failure.

struct usbh_dfu_config_t
#include <usbh_dfu.h>

Configuration for the DFU host class.

Carries every DFU host option. Host-global parameters (speed, FIFO depths, main task stack and priority, ISR priority) live in usbh_config_t instead.

备注

The structure is stored by pointer, not copied, so it shall remain valid until usbh_dfu_deinit.

Public Members

u32 xfer_size

Largest DFU block this host will transfer, 0 uses USBH_DFU_DEFAULT_XFER_SIZE.

Sizes the internal DMA transfer buffer and therefore caps what the host can accept: a device advertising a larger wTransferSize in its DFU Functional Descriptor is clamped down to this value. Raising it lets a device use bigger blocks at the cost of heap.

struct usbh_dfu_host_t
#include <usbh_dfu.h>

Internal DFU host instance context.

Allocated statically; one instance shared across attach/detach cycles.

Public Members

usb_host_t *host

Pointer to the USB host handle (set on attach).

const usbh_dfu_cb_t *cb

Pointer to the user-supplied callback table.

const usbh_dfu_config_t *cfg

Pointer to the class configuration (set by init).

usbh_dfu_state_t state

Current host-side DFU state machine state.

u8 dev_state

Latest device-side bState from GETSTATUS.

u8 dev_status

Latest device-side bStatus from GETSTATUS.

u8 itf_num

Matched DFU interface number (set on attach; used as wIndex for all DFU class requests).

u8 is_download

1 = download operation in progress; 0 = upload.

u8 is_runtime

1 = device attached in Run-Time mode (Protocol=0x01).

u8 reconf_pending

1 = attached in Run-Time mode and cb->attached() has not been delivered; suppresses cb->detached() until the device re-enumerates in DFU mode.

u8 ctrl_pending

1 while a DFU class request is in flight on EP0.

u8 xfer_active

1 from usbh_dfu_download()/upload() until its done callback.

u8 abort_req

1 = usbh_dfu_abort() asked, served once no request is in flight.

u8 starting

1 until the first GETSTATUS of a transfer has found the device in dfuIDLE.

usb_dfu_func_desc_t func_desc

Parsed DFU Functional Descriptor fields (byte-packed).

u8 *xfer_buf

DMA-aligned transfer buffer (xfer_size bytes).

u32 xfer_size

Allocated size of xfer_buf, i.e. the resolved usbh_dfu_config_t::xfer_size.

u16 block_num

Current block number for DNLOAD or UPLOAD.

u16 last_good_block

Block last confirmed written (dfuDNLOAD-IDLE). Initialised to 0xFFFF (no block confirmed yet); CLR_STATUS resumes from last_good_block + 1.

u16 xfer_len

Byte count of the block currently being downloaded; saved before the ctrl transfer starts so the DMA buffer is not re-filled while the transfer is live.

u8 upload_phase

Sub-phase inside UPLOAD_BLOCK: 0 = DFU_UPLOAD ctrl transfer in progress; 1 = follow-up DFU_GETSTATUS in progress.

u8 retry_cnt

Consecutive write failures at the same block; reset to 0 on each confirmed write.

u32 poll_timeout

Poll timeout in ms from bwPollTimeout field.

u32 poll_remain

Length (ms) of the current bwPollTimeout wait, counted from poll_start_ms; 0 = no wait pending.

u32 poll_start_ms

Timestamp (ms) at which the current bwPollTimeout wait was armed.

u32 dnload_poll_ms

Timestamp (ms) at which the current block's DNBUSY poll started, bounding it against the wall-clock budget; 0 = not started yet.

u16 dnload_poll_cnt

GETSTATUS polls spent on the current block while the device reports dfuDNBUSY/dfuDNLOAD-SYNC.

u8 manifest_retry_cnt

GETSTATUS polls while device reports dfuMANIFEST; independent of write retry_cnt.

Host HID Types

enum usbh_hid_get_report_desc_t

HID Report Descriptor State Machine states.

Values:

enumerator USBH_HID_REPORT_IDLE

Idle state

enumerator USBH_HID_REPORT_SET_ALT

Setting Interface Alternate Setting

enumerator USBH_HID_REPORT_GET_DESC

Getting Report Descriptor

enumerator USBH_HID_REPORT_MAX

Max state guard

enum usbh_hid_event_type_t

HID Event Types. Abstracted events generated from HID reports.

Values:

enumerator VOLUME_EVENT_NONE

No event

enumerator VOLUME_EVENT_CONSUMER_UP

Volume Up pressed

enumerator VOLUME_EVENT_CONSUMER_DOWN

Volume Down pressed

enumerator VOLUME_EVENT_CONSUMER_MUTE

Mute pressed

enumerator VOLUME_EVENT_CONSUMER_PLAY_PAUSE

Play/Pause pressed

enumerator VOLUME_EVENT_CONSUMER_STOP

Stop pressed

struct usbh_dev_hid_desc_t
#include <usbh_hid.h>

USB Standard HID Descriptor structure.

Public Members

u8 bLength

Size of this descriptor in bytes, fixed is 9

u8 bDescriptorType

Descriptor Type (USBH_HID_DESC)

u16 bcdHID

HID Class Specification release number (BCD: 0x0100)

u8 bCountryCode

Hardware target country

u8 bNumDescriptors

Number of class descriptors to follow, usually is 1

u8 bReportDescriptorType

Report descriptor type (USBH_HID_REPORT_DESC)

u16 wDescriptorLength

Total length of Report descriptor

struct usbh_hid_event_t
#include <usbh_hid.h>

HID Event Structure.

备注

Reported once per INTR IN report, also for a report repeating the previous one. Only presses are decoded: a tracked control set in the report gives its type with is_press 1, a report with no tracked control set, a key release included, gives VOLUME_EVENT_NONE with is_press 0.

Public Members

usbh_hid_event_type_t type

Event type, VOLUME_EVENT_NONE when no tracked control is set

u8 is_press

1 if a tracked control is pressed, 0 for VOLUME_EVENT_NONE

struct usbh_hid_item_t
#include <usbh_hid.h>

HID Report Item structure. Used during parsing of the HID Report Descriptor.

Public Members

u32 data

Item Data

u8 type

Item Type (Main, Global, Local)

u8 tag

Item Tag

u8 size

Item Size

struct usbh_hid_ctrl_caps_t
#include <usbh_hid.h>

HID Control Capabilities structure. Stores supported features found during parsing (Volume, Media).

备注

A control declared by a Variable field of Report Size 1 is located by its absolute bit position (bitmap form). A control declared by an Array field is not a bit at all: the field carries usage codes, so it is described by consumer_array instead. Ref HID 1.11 6.2.2.5.

Public Members

u16 up_bit

Absolute bit of Volume Up, USBH_HID_BIT_NONE if not declared

u16 down_bit

Absolute bit of Volume Down, USBH_HID_BIT_NONE if not declared

u16 mute_bit

Absolute bit of Mute, USBH_HID_BIT_NONE if not declared

u8 report_id

Report ID for volume

Report ID for media

Report ID holding the array field

bool supported

Is volume control declared as a bitmap

Is media control declared as a bitmap

Is a consumer array field present

struct usbh_hid_ctrl_caps_t::[anonymous] volume
u16 play_pause_bit

Absolute bit of Play/Pause, USBH_HID_BIT_NONE if not declared

u16 stop_bit

Absolute bit of Stop, USBH_HID_BIT_NONE if not declared

struct usbh_hid_ctrl_caps_t::[anonymous] media
u16 bit_offset

Absolute bit of the first array element

u8 elem_bits

Bits per element, i.e. Report Size

u8 elem_cnt

Elements to decode, clamped to USBH_HID_ARRAY_ELEM_CNT

struct usbh_hid_ctrl_caps_t::[anonymous] consumer_array
u8 report_id_count

Number of report IDs found

u8 report_id_zero

The descriptor declares the reserved Report ID 0, so its reports can not be framed

struct usbh_hid_parse_state
#include <usbh_hid.h>

HID Parser State structure. Maintains the context while parsing the HID Report Descriptor.

备注

Input, Output and Feature fields live in separate reports, so each one needs its own bit cursor. Ref HID 1.11 5.6 / 8.

Public Members

usbh_hid_ctrl_caps_t *device_info

Pointer to capabilities struct to populate

int logical_min

Current Logical Minimum

int logical_max

Current Logical Maximum

u32 in_bit_offset

Bits consumed by previous Input fields of the current report

u32 out_bit_offset

Bits consumed by previous Output fields of the current report

u32 feat_bit_offset

Bits consumed by previous Feature fields of the current report

u32 usage_cnt

Usages declared so far for the pending Main item

u32 usage_min

Pending Usage Minimum

u16 track_ord[USBH_HID_TRACK_USAGE_CNT]

Ordinal of each tracked usage in the pending field

u16 usage_page

Current Usage Page

u16 report_size

Current Report Size (bits)

u16 report_count

Current Report Count

u8 track_mask

Bitmask of tracked usages declared in the pending field

u8 report_id

Current Report ID

u8 usage_min_valid

A Usage Minimum is pending a Usage Maximum

u8 collection_depth

Current depth of Collection nesting

struct usbh_hid_usr_cb_t
#include <usbh_hid.h>

User Callback Structure for HID Host Driver.

Public Members

int (*init)(void)

Called on initialization

void (*deinit)(void)

Called on de-initialization

void (*attached)(void)

Called when device is attached

void (*detached)(void)

Called when device is detached

void (*setup)(void)

Called during setup phase

void (*report)(usbh_hid_event_t *event)

Called for every INTR IN report received, see usbh_hid_event_t

struct usbh_hid_t
#include <usbh_hid.h>

Public Members

usb_host_t *host

USB host handle (stored at attach)

const usbh_hid_usr_cb_t *cb

User callback pointers

u8 hid_ctrl

HID control state

u8 report_desc_status

Status of report descriptor retrieval

u8 itf_idx

Interface Index

u8 itf_alt_idx

Interface Alternate Setting Index

u8 alt_setting_count

Number of alternate settings on this HID interface

u8 halt_pending

INTR IN STALLed, CLEAR_FEATURE(ENDPOINT_HALT) to be sent

u8 halt_retry_cnt

Failed CLEAR_FEATURE(ENDPOINT_HALT) attempts

usbh_dev_hid_desc_t hid_desc

HID Descriptor

usbh_ep_desc_t ep_desc_in

Interrupt IN Endpoint Descriptor

usbh_ep_desc_t ep_desc_out

Interrupt OUT Endpoint Descriptor, optional

u8 *report_desc

Alias pointer into hid_ctrl_buf (zero-copy). Valid only until setup() ends: hid_ctrl_buf then becomes the INTR IN buffer and is overwritten by reports.

usbh_hid_ctrl_caps_t vol_caps

Volume capabilities detected; written with hid_ctrl under the USB critical section, read by the parse thread through caps_snap

usbh_pipe_t pipe_in

Interrupt IN pipe handle

usbh_pipe_t pipe_out

Interrupt OUT pipe handle (optional)

u8 *hid_ctrl_buf

General-purpose control transfer buffer (512 B); backs report_desc during setup(), then serves as the INTR IN transfer buffer.

rtos_task_t msg_parse_task

Task handle for parsing messages

usb_os_sema_t report_sema

Wakes the parse thread when a report is queued

usb_ringbuf_manager_t report_msg

Ring buffer for report data

usbh_hid_event_t report_event

HID report event

u8 parse_task_alive

Flag to indicate parse task is alive

u8 parse_task_exit

Flag to indicate signal parse task is exit

u8 report_buf[USBH_HID_REPORT_MAX_LEN]

Parse thread copy of one report, kept off its 768 B stack

usbh_hid_ctrl_caps_t caps_snap

Parse thread copy of vol_caps for one report, taken under the lock

usbh_hid_ctrl_caps_t caps_build

Main task scratch the report descriptor is parsed into before publish

Host MSC Types

enum usbh_bot_cmd_state_t

BOT command state enumeration.

Values:

enumerator BOT_CMD_IDLE

BOT command layer is idle.

enumerator BOT_CMD_SEND

BOT is sending a command.

enumerator BOT_CMD_BUSY

BOT is busy processing a command.

enum usbh_bot_state_t

BOT state machine enumeration for data transfer phases.

Values:

enumerator BOT_SEND_CBW

Sending Command Block Wrapper (CBW).

enumerator BOT_DATA_IN

Data-In phase (Device to Host).

enumerator BOT_DATA_OUT

Data-Out phase (Host to Device).

enumerator BOT_RECEIVE_CSW

Receiving Command Status Wrapper (CSW).

enumerator BOT_ERROR_IN

Error occurred during Data-In phase.

enumerator BOT_ERROR_OUT

Error occurred during Data-Out phase.

enumerator BOT_UNRECOVERED_ERROR

Unrecoverable BOT protocol error.

enum usbh_msc_state_t

MSC state machine enumeration.

Values:

enumerator MSC_INIT

Initialization state.

enumerator MSC_IDLE

Idle state, waiting for user commands.

enumerator MSC_TEST_UNIT_READY

Processing TEST UNIT READY command.

enumerator MSC_READ_CAPACITY10

Processing READ CAPACITY(10) command.

enumerator MSC_READ_INQUIRY

Processing INQUIRY command.

enumerator MSC_REQUEST_SENSE

Processing REQUEST SENSE command.

enumerator MSC_READ

Processing READ command.

enumerator MSC_WRITE

Processing WRITE command.

enumerator MSC_UNRECOVERED_ERROR

Unrecoverable error state.

enumerator MSC_PERIODIC_CHECK

Periodic check state for device status.

enumerator MSC_ABORT

A timed-out READ/WRITE is being abandoned through BOT Reset Recovery.

enum usbh_msc_error_t

MSC status enumeration.

Values:

enumerator MSC_OK

Command successful.

enumerator MSC_NOT_READY

Device or unit is not ready.

enumerator MSC_ERROR

A general error occurred.

enum usbh_msc_req_state_t

MSC control request state machine enumeration.

Values:

enumerator MSC_REQ_IDLE

No control request active.

enumerator MSC_REQ_RESET

Processing a Bulk-Only Mass Storage Reset request.

enumerator MSC_REQ_GET_MAX_LUN

Processing a Get Max LUN request.

enumerator MSC_REQ_ERROR

An error occurred during a control request.

struct usbh_bot_handle_t
#include <usbh_msc.h>

BOT protocol handler structure.

Manages the state and buffers for a single BOT transaction.

Public Members

usb_msc_bot_cbw_t *cbw

Pointer to the Command Block Wrapper.

usb_msc_bot_csw_t *csw

Pointer to the Command Status Wrapper.

usb_os_sema_t cmd_done_sema

Given once by the host task when the in-flight READ/WRITE ends, waking its caller.

u32 rx_data_len

Bytes actually sent by the device in the Data-In phase (BOT §6.7 case 5).

u32 cmd_address

LBA of the in-flight READ/WRITE, re-used to re-issue the same CBW (BOT §6.3.3).

u32 cmd_block_count

Block count of the in-flight READ/WRITE, re-used on the retry path.

u32 cmd_done_count

Blocks of the in-flight READ/WRITE already moved; the next chunk starts here.

u8 *cmd_rx_buf

User buffer of the in-flight READ, receiving the data.

const u8 *cmd_tx_buf

User buffer of the in-flight WRITE, holding the data to send.

u8 *pbuf

Data buffer of the current command: data, or bounce_buf for READ(10)/WRITE(10).

u8 *data

A general-purpose data buffer.

u8 *bounce_buf

READ(10)/WRITE(10) bounce buffer, one chunk of a READ/WRITE.

u32 bounce_len

Size of bounce_buf, the resolved usbh_msc_config_t::buf_size.

u32 tag_counter

Per-CBW tag; incremented before each CBW send (BOT §6.3.1).

int cmd_result

Final RTK status of the last READ/WRITE (RTK_SUCCESS, -RTK_ERR_TIMEOUT, ...), valid once cmd_done_sema is given. Unlike cmd_state, it is an outcome, not a progress state.

u8 state

Current state of the BOT state machine, usbh_bot_state_t.

u8 reset_recovery

Set during BOT Reset Recovery, so the endpoint-halt clearing ends in BOT_SEND_CBW.

u8 csw_retried

1 once the CSW of the current command was re-read after a Bulk-In clear (BOT 6.7.2).

u8 cmd_state

Progress of the BOT command layer (send / busy), usbh_bot_cmd_state_t. Not a result.

struct usbh_scsi_capacity_t
#include <usbh_msc.h>

SCSI capacity data structure.

Holds the result from a READ CAPACITY command.

Public Members

u32 block_nbr

Total number of logical blocks on the medium.

u32 block_size

Size of each logical block in bytes.

struct usbh_scsi_inquiry_t
#include <usbh_msc.h>

SCSI standard INQUIRY data structure.

Fields decoded from the standard INQUIRY response (SPC-3 6.4.2). The ID strings are space-padded ASCII and are not NUL-terminated.

Public Members

u8 vendor_id[8]

T10 VENDOR IDENTIFICATION, response bytes 8..15.

u8 product_id[16]

PRODUCT IDENTIFICATION, response bytes 16..31.

u8 revision_id[4]

PRODUCT REVISION LEVEL, response bytes 32..35.

u8 peripheral_qualifier

PERIPHERAL QUALIFIER, bits 7..5 of response byte 0.

u8 device_type

PERIPHERAL DEVICE TYPE, bits 4..0 of response byte 0 (0x00 = direct access block device).

u8 removable_media

1 if the RMB bit (bit 7 of response byte 1) marks the medium removable, else 0.

struct usbh_msc_lun_t
#include <usbh_msc.h>

Logical unit (LUN) structure.

Holds what the driver learned about one logical unit during enumeration, and the per-unit state of the command currently addressed to it.

Public Members

usbh_scsi_capacity_t capacity

Geometry reported by READ CAPACITY(10).

usb_msc_scsi_sense_data_t sense

Sense data of the last failed command, from REQUEST SENSE.

usbh_scsi_inquiry_t inquiry

Identity reported by INQUIRY.

u8 state

Current state of the per-unit state machine, usbh_msc_state_t.

u8 error

Stores the last occurred error, usbh_msc_error_t.

u8 prev_ready

1 if the previous TEST UNIT READY passed, used to detect a ready-state change.

u8 state_changed

1 if the last TEST UNIT READY changed the ready state, else 0.

u8 retired

1 once a timed-out init or a failed Reset Recovery left the unit unusable; READ/WRITE are refused until re-attach. Unlike error, a single failed command never sets it.

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 notifications like device attachment and detachment.

Public Members

void (*attached)(void)

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

void (*detached)(void)

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

void (*setup)(void)

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

struct usbh_msc_config_t
#include <usbh_msc.h>

Configuration for the MSC host class.

备注

Read by usbh_msc_init() only, so it need not outlive that call.

Public Members

u32 buf_size

Size of the READ(10)/WRITE(10) bounce buffer, 0 uses USBH_MSC_DEFAULT_BUF_SIZE.

Allocated once by usbh_msc_init(). A READ/WRITE larger than it is moved in chunks of this size, one READ(10)/WRITE(10) each, so it trades throughput against heap. Shall be a multiple of USBH_MSC_MAX_BLOCK_SIZE not above USBH_MSC_MAX_BUF_SIZE.

struct usbh_msc_host_t
#include <usbh_msc.h>

MSC host structure.

This structure holds all the state and context for the MSC host driver.

Public Members

const usbh_msc_cb_t *cb

Pointer to the user-registered callback structure.

usb_host_t *host

Pointer to the parent USB host structure.

u8 state

Current state of the main MSC state machine, usbh_msc_state_t.

u8 req_state

Current state of the MSC control request state machine, usbh_msc_req_state_t.

u8 current_lun

The currently active logical unit number.

u8 max_lun

Number of LUNs in use: GET MAX LUN + 1, clamped to USBH_MSC_MAX_LUN.

u8 itf_num

MSC interface number; used as wIndex in class requests (BOT §3.1).

u8 init_diag_done

1 once the stuck LUN init diagnostic has been printed for this attach.

u8 init_recovery

Recovery steps a stuck LUN init has used this attach: 1 after BOT Reset Recovery.

usbh_bot_handle_t hbot

Handle for the BOT protocol layer.

usbh_pipe_t bulk_in

Pipe handle for the Bulk IN endpoint.

usbh_pipe_t bulk_out

Pipe handle for the Bulk OUT endpoint.

u8 *max_lun_buf

Buffer to hold the result of GET MAX LUN request.

u32 sof_tick

Host tick of the last SOF wakeup of the BOT FSM, see usbh_msc_sof().

u32 lun_ms

OS time in ms when the current LUN init step began, base of its budget.

u32 init_ms

OS time in ms at attach, diagnostic base for a stuck LUN init.

usbh_msc_lun_t unit[USBH_MSC_MAX_LUN]

Array to hold information for each LUN.

Host UAC Types

struct usbh_uac_term_info_t
#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_unit_info_t
#include <usbh_uac1.h>

UAC 1.0 intermediate Unit (Mixer/Selector/Processing/Extension) link information. Only the ID and the bSourceID list are kept: enough to walk an Output Terminal's chain back to the Feature Unit that feeds it (UAC1 4.3.2).

Public Members

u8 unit_id

bUnitID of this Unit

u8 source_cnt

Number of valid entries in source_ids[]

u8 source_ids[USBH_UAC_UNIT_SRC_MAX_CNT]

bSourceID list of the entities feeding this Unit

struct usbh_uac_fu_info_t
#include <usbh_uac1.h>

UAC 1.0 Feature Unit (Volume Control) Information structure. match to the bmaControls layout from UAC1 spec: index 0 is the Master Channel (logical channel 0); indices 1..num_channels are per-channel logical channels 1..N.

Public Members

u16 bma_controls[1 + USBH_UAC_MAX_CHANNEL]

Bitmap of supported fu_controls logical channels: [0]=master, [1..num_channels]=ch1..N

u16 sink_type

Terminal Type of the sink connected to this Feature Unit (used to classify OUT/IN direction)

u8 unit_id

ID of this Feature Unit

u8 source_id

ID of the source entity connected to this Feature Unit

u8 sink_id

ID of the sink Terminal connected to this Feature Unit

u8 num_channels

Number of logical audio channels (excludes master)

u8 control_size

Size in bytes of each bmaControls field in the descriptor (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 Feature Units within the AC interface.

Public Members

usbh_uac_fu_info_t fu_controls[USBH_UAC_FU_MAX_CNT]

Parsed Feature Units, indexed 0..volume_ctrl_count-1

usbh_uac_term_info_t terminals[USBH_UAC_TERM_MAX_CNT]

Parsed Terminals, indexed 0..terminal_count-1

usbh_uac_unit_info_t units[USBH_UAC_UNIT_MAX_CNT]

Parsed intermediate Units, indexed 0..unit_count-1

u8 volume_ctrl_count

Number of valid entries in fu_controls[]

u8 terminal_count

Number of valid entries in terminals[]

u8 unit_count

Number of valid entries in units[]

u8 in_best_idx

Index into fu_controls[] for the best IN/Record Feature Unit; (u8)-1 if none

u8 out_best_idx

Index into fu_controls[] for the best OUT/Playback Feature Unit; (u8)-1 if none

u8 ac_itf_idx

Interface number of the Audio Control interface (used as wIndex in control requests)

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

rtos_sema_t isoc_sema

Semaphore signaled when a ring buffer slot becomes available

u32 sample_freq

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

u32 sample_rem

Remainder of (sample_freq % pkt_per_second), used for fractional packet sizing

u32 sample_accum

Accumulated remainder across frames; when >= pkt_per_second, one extra sample is added

u32 last_sample_accum

Saved accumulator value after the last committed packet, restored on ring-buffer full

u16 packet_rate

Number of USB packets per second (max: 8000 for HS ISOC)

u16 written

Bytes accumulated in ringbuf_partial_write_buf for the current packet under construction

u16 mps

Endpoint Maximum Packet Size in bytes

u16 node_size

Ring buffer node size in bytes, i.e. the largest packet a node can hold. Equals mps for a single-transaction endpoint and the full packet size for a high-bandwidth one (USB 2.0 5.6.3), so it is what the read path must reserve room for rather than mps

usb_ringbuf_manager_t buf_manager

Ring buffer manager for isochronous data

u8 sema_valid

1 when isoc_sema has been created and is safe to use

u8 wait_sema

1 while a write/read thread is blocked on isoc_sema (used for safe teardown)

u8 next_xfer

1 to allow isochronous transfers; cleared by stop_play/stop_capture

u8 frame_cnt

Ring buffer depth in frames; set from cb->isoc_out/in_frm_cnt before ep_buf_ctrl_init

struct usbh_uac_volume_info_t
#include <usbh_uac1.h>

Audio Volume Status Information.

Public Members

s16 volume

Current volume in device units (1/256 dB steps; 0x8000 = silence)

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)

u8 range_valid

1 once vol_min/vol_max have been successfully read at attach

struct usbh_uac_format_cfg_t
#include <usbh_uac1.h>

Audio Format Configuration Descriptor Information.

Public Members

u32 freq[USBH_UAC_FREQ_FORMAT_MAX]

Supported discrete sampling frequencies in Hz

u8 bit_width

Bit resolution per sample (e.g., 16, 24, 32)

u8 channels

Number of audio channels

u8 freq_cnt

Number of valid entries in freq[]

u8 freq_continuous

1 when bSamFreqType==0: freq[0]/freq[1] are the lower/upper bounds of a continuous range

u8 subframe_size

Bytes one sample occupies on the bus (bSubframeSize), e.g. 4 for 24-bit audio in a 32-bit container

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 alternate setting

usbh_ep_desc_t ep_desc

Isochronous endpoint descriptor for this alternate setting (byte-packed)

u8 alt_setting

USB Alternate Setting number as reported in the descriptor

u8 freq_ctrl_supported

1 if the CS AS endpoint descriptor's bmAttributes advertises Sampling Frequency Control

struct usbh_uac_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 per sample

u8 ch_cnt

Channel count

u8 subframe_size

Bytes one sample occupies in the PCM stream, may exceed bit_width / 8 (Audio Formats 1.0 2.2.5)

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

u16 packet_size_small

Bytes per packet when the sample accumulator does not overflow

u16 packet_size_large

Bytes per packet when the sample accumulator overflows (one extra sample)

usbh_uac_as_itf_alt_info_t interface_array[USBH_UAC_ALT_SETTING_MAX]

Valid alternate settings (Alt 0 skipped; index 0 = Alt 1)

usbh_pipe_t pipe

USB pipe for this AS interface

u8 as_itf_num

USB interface number of this AS interface

u8 alt_setting_cnt

Number of valid entries in interface_array[]

u8 fmt_array_cnt

Number of entries in fmt_array[]

u8 choose_alt_idx

Index into interface_array[] for the currently active alternate setting

usbh_uac_audio_fmt_t fmt_array[USBH_UAC_FMT_MAX]

Flattened list of all supported audio formats

struct usbh_uac_cb_t
#include <usbh_uac1.h>

UAC User Callback Interface.

Public Members

int (*init)(void)

Called once when the UAC driver is initialized

void (*deinit)(void)

Called once when the UAC driver is de-initialized

void (*attached)(void)

Called when a UAC device is enumerated and pipes are opened

void (*detached)(void)

Called when a UAC device is removed

void (*setup)(void)

Called on each USB Setup-stage transaction

void (*transmitted)(usbh_urb_state_t state)

Reserved: registered by application but not currently invoked by the driver

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

Reserved: registered by application but not currently invoked by the driver

struct usbh_uac_config_t
#include <usbh_uac1.h>

Configuration for the UAC host class.

Carries every UAC host option: how deep each direction's ISOC ring buffer is, which also selects whether that direction is supported at all. Host-global parameters (speed, FIFO depths, main task stack and priority, ISR priority) live in usbh_config_t instead.

备注

The structure is stored by pointer, not copied, so it shall remain valid until usbh_uac_deinit.

备注

Unlike most configuration fields in this stack, 0 here does NOT mean "take the

default": it disables that direction. At least one of the two shall be non-zero.

Public Members

u8 isoc_in_frm_cnt

Ring buffer depth in frames for the IN/record path; 0 disables record.

u8 isoc_out_frm_cnt

Ring buffer depth in frames for the OUT/playback path; 0 disables playback.

struct usbh_uac_channel_t
#include <usbh_uac1.h>

Public Members

usbh_uac_as_itf_info_t *as_itf

AS interface bound for this direction; NULL when the device offers none or it is detached

usbh_uac_as_itf_info_t *as_itf_mem

Storage as_itf binds to: allocated in usbh_uac_init() when the direction is enabled and freed only in usbh_uac_deinit(), so a pointer taken from it stays valid across detach

u8 *xfer_buf

DMA-safe transfer buffer passed to usbh_transfer_data

usbh_uac_buf_ctrl_t buf_ctrl

Isochronous buffer and packet-size control

usbh_uac_volume_info_t volume_info[1 + USBH_UAC_MAX_CHANNEL]

Volume info per channel: [0]=master, [1..N]=per-channel

struct usbh_uac_t
#include <usbh_uac1.h>

Main UAC Host Class Driver Handle.

Public Members

const usbh_uac_cb_t *cb

User callback structure registered via usbh_uac_init

usb_host_t *host

Pointer to the USB host handle, saved at attach

u8 *audio_ctrl_buf

Shared buffer for all USB control transfer payloads

u8 *ringbuf_partial_write_buf

Staging buffer that accumulates partial writes until a full packet is ready

u8 xfer_state

Isochronous data transfer state (UAC_STATE_IDLE / UAC_STATE_TRANSFER)

u8 ctrl_state

USB control transfer state machine state (UAC_STATE_CTRL_IDLE, SET_ALT, SET_FREQ, ...)

u8 init_state

Initialization sequence state (UAC_INIT_OUT_GET_FU -> UAC_INIT_IN_GET_FU -> UAC_INIT_OUT_SET_ITF -> UAC_INIT_DONE)

u8 cur_dir

Direction being operated on by the current ctrl_state sequence

rtos_mutex_t alt_set_mutex

Serializes concurrent usbh_uac_set_alt_setting calls

rtos_sema_t ctrl_done_sema

Signaled by ctrl_setting when SET_ALT + SET_FREQ sequence completes

int ctrl_status

RTK status reported back to the current sync ctrl op (set/get) callers

s16 get_volume_result

Volume word parsed by UAC_STATE_GET_VOLUME; consumed by get_volume()

u8 get_mute_result

Mute byte parsed by UAC_STATE_GET_MUTE; consumed by get_mute()

u8 get_ch

Channel argument for the active UAC_STATE_GET_* on-demand query

u8 ch_idx

Channel index driving the current iterative SET_VOLUME/SET_MUTE loop (0 = master)

u8 mute_value

Mute state (1: Mute, 0: Unmute) dispatched to process_set_ch_mute

u8 volume_value

Volume value dispatched to process_set_ch_volume

u8 ctrl_waiting

1 when a sync waiter is blocked on ctrl_done_sema. Mutual exclusion among set_alt_setting/get_mute/get_volume is guaranteed by alt_set_mutex held across the entire wait, so at most one waiter exists at any time. ctrl_done_sema is drained before each take to absorb any stale give left by the previous round's timeout/ctrl_finish race.

usbh_uac_channel_t isoc_out

OUT channel state (Playback/Speaker)

usbh_uac_channel_t isoc_in

IN channel state (Record/Microphone)

usbh_uac_ac_itf_info_t ac_isoc_desc

Audio Control interface topology (Feature Units + Terminals)

Host UVC Descriptor Types

Packed class-specific descriptor layouts of the UVC specification

struct usbh_uvc_stream_control_t
#include <usbh_uvc_desc.h>

UVC Probe and Commit Control (UVC spec Table 4-75)

备注

Covers UVC 1.0 (26 bytes) and UVC 1.1 (34 bytes, up to bMaxVersion). UVC 1.5 adds 14 bytes at offset 34 (bUsage..bmLayoutPerStream); not supported.

Public Members

u16 bmHint
u8 bFormatIndex
u8 bFrameIndex
u32 dwFrameInterval
u16 wKeyFrameRate
u16 wPFrameRate
u16 wCompQuality
u16 wCompWindowSize
u16 wDelay
u32 dwMaxVideoFrameSize
u32 dwMaxPayloadTransferSize
u32 dwClockFrequency
u8 bmFramingInfo
u8 bPreferredVersion
u8 bMinVersion
u8 bMaxVersion
struct usbh_uvc_vs_payload_header_t
#include <usbh_uvc_desc.h>

Public Members

u8 bHeaderLength
u8 bmHeaderInfo
struct usbh_uvc_vc_intr_ep_desc_t
#include <usbh_uvc_desc.h>

Public Members

u8 bLength
u8 bDescriptorType
u8 bDescriptorSubType
u16 wMaxTransferSize
struct usbh_uvc_vc_header_desc_t
#include <usbh_uvc_desc.h>

Public Members

u8 bLength
u8 bDescriptorType
u8 bDescriptorSubtype
u16 bcdUVC
u16 wTotalLength
u32 dwClockFrequency
u8 bInCollection
struct usbh_uvc_vc_it_desc_t
#include <usbh_uvc_desc.h>

Public Members

u8 bLength
u8 bDescriptorType
u8 bDescriptorSubtype
u8 bTerminalID
u8 wTerminalType[2]
u8 bAssocTerminal
u8 iTerminal
u8 wObjectiveFocalLengthMin[2]
u8 wObjectiveFocalLengthMax[2]
u8 wOcularFocalLength[2]
u8 bControlSize
u8 bmControls[3]
struct usbh_uvc_vc_ot_desc_t
#include <usbh_uvc_desc.h>

Public Members

u8 bLength
u8 bDescriptorType
u8 bDescriptorSubtype
u8 bTerminalID
u8 wTerminalType[2]
u8 bAssocTerminal
u8 bSourceID
u8 iTerminal
struct usbh_uvc_vc_ct_desc_t
#include <usbh_uvc_desc.h>

Public Members

u8 bLength
u8 bDescriptorType
u8 bDescriptorSubtype
u8 bTerminalID
u8 wTerminalType[2]
u8 bAssocTerminal
u8 iTerminal
u8 wObjectiveFocalLengthMin[2]
u8 wObjectiveFocalLengthMax[2]
u8 wOcularFocalLength[2]
u8 bControlSize
u8 bmControls[3]
struct usbh_uvc_vc_pu_desc_t
#include <usbh_uvc_desc.h>

Public Members

u8 bLength
u8 bDescriptorType
u8 bDescriptorSubtype
u8 bUnitID
u8 bSourceID
u8 wMaxMultiplier[2]
u8 bControlSize
u8 bmControls[3]
u8 iProcessing
u8 bmVideoStandards
struct usbh_uvc_vc_su_desc_t
#include <usbh_uvc_desc.h>

Public Members

u8 bLength
u8 bDescriptorType
u8 bDescriptorSubtype
u8 bUnitID
u8 bNrInPins
u8 bSourceID
u8 iSelector
struct usbh_uvc_vc_xu_desc_t
#include <usbh_uvc_desc.h>

Public Members

u8 bLength
u8 bDescriptorType
u8 bDescriptorSubtype
u8 bUnitID
u8 guidExtensionCode[16]
u8 bNumControls
u8 bNrInPins
struct usbh_uvc_vc_eu_desc_t
#include <usbh_uvc_desc.h>

Public Members

u8 bLength
u8 bDescriptorType
u8 bDescriptorSubtype
u8 bUnitID
u8 bNrInPins
u8 bSourceID0
u8 iSelector
struct usbh_uvc_vs_input_header_desc_t
#include <usbh_uvc_desc.h>

Public Members

u8 bLength
u8 bDescriptorType
u8 bDescriptorSubtype
u8 bNumFormats
u16 wTotalLength
u8 bEndPointAddress
u8 bmInfo
u8 bTerminalLink
u8 bStillCaptureMethod
u8 bTriggerSupport
u8 bTriggerUsage
u8 bControlSize
struct usbh_uvc_vs_output_header_desc_t
#include <usbh_uvc_desc.h>

Public Members

u8 bLength
u8 bDescriptorType
u8 bDescriptorSubtype
u8 bNumFormats
u8 wTotalLength[2]
u8 bEndPointAddress
u8 bTerminalLink
u8 bControlSize
struct usbh_uvc_entity_t
#include <usbh_uvc_desc.h>

Public Members

u8 *p
const u8 *source
struct list_head list
u8 type
u8 id
u8 source_num

Host UVC Types

enum usbh_uvc_streaming_state_t

UVC Streaming State.

Values:

enumerator UVC_STREAM_OFF

No streaming resources: before stream_on / after stream_off.

enumerator UVC_STREAM_READY

Resources ready, idle: after stream_on / after stream_stop.

enumerator UVC_STREAM_ACTIVE

Actively transferring: after stream_start.

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

UVC Stream Context / Parameters.

Public Members

u32 frame_buf_size

Size of a single video frame buffer in bytes.

u16 width

Video frame width in pixels.

u16 height

Video frame height in pixels.

u8 frame_rate

Video frame rate (fps).

u8 fmt_type

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

struct usbh_uvc_config_t
#include <usbh_uvc.h>

Configuration for the UVC host class.

Carries every UVC host option: the per-stream frame buffer size and, on SoCs with the hardware decoder, its ISR priority. Host-global parameters (speed, FIFO depths, main task stack and priority, ISR priority) live in usbh_config_t instead.

备注

The structure is stored by pointer, not copied, so it shall remain valid until usbh_uvc_deinit.

Public Members

u32 frame_buf_size

Size of a single video frame buffer in bytes (applied to every stream at init).

struct usbh_uvc_cb_t
#include <usbh_uvc.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.

void (*deinit)(void)

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

void (*attached)(void)

Callback invoked when a UVC device is attached.

void (*detached)(void)

Callback invoked when a UVC device is detached.

void (*setup)(void)

Callback invoked when the device setup phase is complete.

void (*set_param)(int status)

Callback invoked when the UVC parameter-setting sequence (Probe/Commit/SET_INTERFACE) completes; status is RTK_SUCCESS on success, -RTK_ERR_NOMEM if the streaming buffers cannot be allocated, or -RTK_ERR_IO on any other failure.

struct usbh_uvc_frame_t
#include <usbh_uvc.h>

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

Public Members

u8 *buf

Pointer to the data buffer containing the frame.

u32 byteused

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

u32 timestamp

Presentation timestamp of the frame.

struct list_head list

Linked list node for queue management.

u8 err

Error flags associated with this frame.

u8 state

Current state of this frame buffer, usbh_uvc_frame_state_t.

Host Vendor Types

enum usbh_vendor_state_t

States for Vendor State Machine.

Values:

enumerator VENDOR_STATE_IDLE

No device attached, the data pipes are closed

enumerator VENDOR_STATE_XFER

Device attached, the data pipes may be used

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.

void (*deinit)(void)

Called when the host driver de-initialization.

void (*attached)(void)

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

void (*detached)(void)

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

void (*setup)(void)

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

void (*received)(u8 ep_type, u8 *buf, u32 len, int status)

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

备注

This function may be called within an interrupt service routine (ISR) context (e.g., on the SOF path); time-consuming operations (e.g., RTK_LOG,rtos_sema_take) are not permitted.

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

void (*transmitted)(u8 ep_type)

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

备注

This function may be called within an interrupt service routine (ISR) context (e.g., on the SOF path); time-consuming operations (e.g., RTK_LOG,rtos_sema_take) are not permitted.

Param ep_type:

Endpoint type(BULK/INTR/ISOC)..

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

u32 xfer_max_len

Max length of a single transfer

u32 xfer_cnt

Current transfer count (for test loops), same width as the test_cnt API argument

u32 xfer_max_cnt

Target transfer count (for test loops), same width as the test_cnt API argument

u16 cur_frame

Current frame number (for ISOC synchronization), 14-bit HFNUM value

u8 busy

Transfer claimed by the API and its completion not yet reported

struct usbh_vendor_host_t
#include <usbh_vendor.h>

Vendor Host Class Structure.

Public Members

const usbh_vendor_cb_t *cb

Pointer to user callback structure

usb_host_t *host

Pointer to USB Host core handle

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

u8 state

Current class state machine state, usbh_vendor_state_t.