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.
- 参数:
layer -- [in] usb_diag_layer_t
event -- [in] usb_diag_event_t
id -- [in] endpoint addr / pipe number / parameter (bits[7:0])
-
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
wValuefield 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
bmRequestTypefield 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
wPortStatusfield 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
wPortChangefield 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>
-
struct usb_uac1_as_ep_desc_t
- #include <usb_uac1.h>
-
struct usb_uac1_format_type_i_discrete_descriptor
- #include <usb_uac1.h>
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>
-
struct usb_app_ctx_t
- #include <usb_app.h>
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
-
enumerator LINE_CODING_PARITY_NO
-
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
-
enumerator LINE_CODING_CHAR_FORMAT_1_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
-
u8 d8[USB_CDC_ACM_LINE_CODING_SIZE]
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
-
u8 bFunctionLength
-
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
-
u8 bFunctionLength
-
struct usb_cdc_ecm_speed_change_data_t
- #include <usb_cdc_ecm.h>
Connection Speed Change Notification Data.
-
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
-
u8 bmRequestType
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
-
u8 bFunctionLength
-
struct usb_cdc_ncm_speed_change_data_t
- #include <usb_cdc_ncm.h>
Connection Speed Change Notification Data.
-
struct usb_cdc_ncm_notify_t
- #include <usb_cdc_ncm.h>
NCM Connection Notification.
-
struct usb_cdc_ncm_function_desc_t
- #include <usb_cdc_ncm.h>
CDC NCM Functional Descriptor.
-
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)
-
u16 wLength
-
struct usb_cdc_ncm_nth16_t
- #include <usb_cdc_ncm.h>
NTB16 Transfer Header.
-
struct usb_cdc_ncm_ndp16_entry_t
- #include <usb_cdc_ncm.h>
NTB16 Datagram Pointer Entry.
-
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)
-
u32 dwSignature
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
bmAttributesfield 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.
-
enumerator USB_CH_EP_TYPE_CTRL
-
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.
-
u8 bmRequestType
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_FULLhas 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).
-
enumerator USB_SPEED_HIGH
-
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).
-
u16 interval
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.
-
enumerator USB_LAYER_CORE
-
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.
-
enumerator USB_EVT_DEFAULT
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
passstatus of the command execution
-
enumerator BOT_CSW_CMD_FAILED
The
failstatus of the command execution
-
enumerator BOT_CSW_PHASE_ERROR
The
phase errorstatus of the command execution
-
enumerator BOT_CSW_CMD_PASSED
-
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.
-
u32 dCBWSignature
-
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.
-
u32 dCSWSignature
-
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.
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.
-
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_ringbuf_t *list_node
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>
-
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.
-
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.
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.
-
int usbd_cdc_ecm_get_link_status(void)
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.
-
int usbd_cdc_ecm_set_link_status(u8 link_up)
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.
-
int usbd_cdc_ncm_get_link_status(void)
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.
-
int usbd_cdc_ncm_set_link_status(u8 link_up)
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_lenrounded up to a multiple of the DWORD aligned endpoint MPS (one such MPS whenxfer_lenis 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 whenxfer_buf_lenis 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/NCMiMACAddress, ...); the core answersGET_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
stris 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_whcdoes 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
snin bytes, shall be greater than USBD_SN_STR_LEN.
- 返回:
Number of characters written, 0 when
snis NULL orlenis 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
bLengthfield. 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
descin 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.
- 参数:
dev -- USB device instance.
status -- CSW status, see usb_msc_bot_csw_state_t.
- 返回:
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_enis 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
transmittedcallback reports completion.
-
u32 bulk_in_xfer_size
-
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.
-
u8 bmRequestType
-
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.
-
int (*init)(void)
-
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_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.
-
const usbd_cdc_acm_config_t *cfg
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.
-
const u8 *mac
-
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.
-
int (*init)(void)
-
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.
-
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.
-
u8 uplink_status
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.
-
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.
-
const usbd_cdc_ecm_config_t *cfg
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_datagramssets.
-
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_datagramsdetermines.
-
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_datagramslimit 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
valuemax-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 unlessCONFIG_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.
-
const u8 *mac
-
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 — 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.
-
u8 *buf
-
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.
-
int (*init)(void)
-
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.
-
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.
-
u8 uplink_status
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.
-
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.
-
const usbd_cdc_ncm_config_t *cfg
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.
-
void (*status_changed)(u8 old_status, u8 new_status)
-
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.
-
const usbd_class_driver_t *drivers[USBD_COMP_MAX_FUNCS]
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.
-
enumerator USBD_STATE_INIT
-
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.
-
enumerator USBD_ATTACH_STATUS_INIT
-
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_Cleanin TRX API and it will be called in class.
-
u8 skip_dcache_post_invalidate
Skip
DCache_Invalidatewhen RX complete and it will be called in class.
-
u8 *xfer_buf
-
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->infoafter usbd_init and before enumeration, and the core reports the overwritten value.usbd_whcdoes 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 toUSB_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).
-
const char *mfg_str
-
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).
-
u16 rx_fifo_depth
-
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
infoinstead and take no slot here.
-
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.
-
const struct _usbd_class_driver_t *driver
-
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 thewValuevalue 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_lendescribes the physical capacity ofbufonly. It must not be used to truncate a descriptor: a partial configuration descriptor whosewTotalLengthdisagrees 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 throughwLengthare 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
bufin 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 uponSET_CONFIGURATIONrequest in ADDRESSED state. The device class driver must:Initialize endpoints via usbd_ep_init.
Prepare first OUT transfer via usbd_ep_receive.
- Param dev:
[in] USB device.
- Param config:
[in] The configuration index to be set.
- Return:
0 on success, non-zero on failure.
-
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_CONFIGURATIONcontrol request in CONFIGURED state and needs to switch configuration.Core driver receives
SET_CONFIGURATIONcontrol 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: onSET_INTERFACEthe 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 sendSET_INTERFACE(0)to such an interface.Standard endpoint requests
SET_FEATURE/CLEAR_FEATUREwithENDPOINT_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.
-
u16 (*get_descriptor)(usb_dev_t *dev, usb_setup_req_t *req, u8 *buf, u16 buf_len)
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
-
enumerator USBD_DFU_STATUS_OK
-
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_DETACHis 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.
-
u32 xfer_size
-
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.
-
int (*init)(void)
-
struct usbd_dfu_dev_t
- #include <usbd_dfu.h>
Internal DFU device instance (opaque to application).
Public Members
-
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
-
rtos_timer_t detach_timer
-
u16 detach_wait_ms
-
const usbd_dfu_cb_t *cb
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) orCONFIG_USBD_HID_VENDOR(raw OUT report) is built.
-
u8 vendor_intr_in_addr
Vendor INTR IN endpoint address.
Ignored unless
CONFIG_USBD_HID_VENDORis 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.
-
u32 intr_in_xfer_size
-
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.
-
void (*init)(void)
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.
-
void (*status_changed)(u8 old_status, u8 status)
Device UAC Types
-
struct usbd_audio_cfg_t
- #include <usbd_uac.h>
-
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
constdescriptor tables at build time from the menuconfig formats, refer toUSBD_UAC_DEFAULT_CH_CNT,USBD_UAC_DEFAULT_BYTE_WIDTHandUSBD_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.
-
const char *itf_str
-
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.
-
int (*init)(void)
-
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.
-
rtos_sema_t uac_isoc_sema
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.
-
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.
-
struct usbd_uvc_format_info_t
- #include <usbd_uvc.h>
UVC video format information.
Defines a video format and its supported frame resolutions.
-
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.
-
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).
-
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.
-
struct usbd_uvc_request_data_t
- #include <usbd_uvc.h>
UVC request payload data.
Used to store data associated with a UVC control request.
-
struct usbd_uvc_buffer_t
- #include <usbd_uvc.h>
USB UVC video buffer structure.
Represents a single video buffer used for streaming.
-
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
-
u32 type
-
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.
-
int stream_index
-
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
-
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
-
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]
-
usb_os_sema_t uvc_cmd_wakeup_sema
-
usb_os_lock_t bod_mutex
-
struct list_head bod_list
-
usb_os_lock_t lock
-
const usbd_uvc_ep_cfg_t *ep_cfg
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.
-
int (*init)(void)
-
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_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.
-
const usbd_vendor_config_t *cfg
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
-
u16 bmHint
-
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.
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.
-
u8 *mfg_str
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>
-
struct usbd_whc_ep_t
- #include <usbd_whc.h>
One WHC endpoint and the application context bound to it.
-
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.
-
int (*init)(void)
-
struct usbd_whc_dev_t
- #include <usbd_whc.h>
Public Members
-
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
-
const usbd_whc_cb_t *cb
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.
-
int usbh_cdc_ecm_get_link_status(void)
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.
-
u8 usbh_cdc_ncm_get_link_status(void)
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 bypipe_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_INTERFACEstandard 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_FEATUREstandard 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_FEATUREstandard 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_tstructure 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
sizebytes 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_tif 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 Transportinterface protocol code.
-
USBH_MSC_TRANSPARENT
MSC
SCSI Transparent Command Setinterface 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.
-
enumerator USBH_CDC_ACM_STATE_IDLE
-
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_DONGLEis enabled.
-
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_DONGLEis 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.
-
const usbh_cdc_acm_param_t *dongle_param
-
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.
-
int (*init)(void)
-
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.
-
usb_host_t *host
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.
-
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.
-
int (*init)(void)
-
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.
-
usbh_pipe_t pipe
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.
-
const u8 *mac_value
-
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.
-
int (*init)(void)
-
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.
-
usbh_pipe_t pipe
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.
-
enumerator USBH_EP_XFER_IDLE
-
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.
-
enumerator USBH_STATE_IDLE
-
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.
-
enumerator USBH_URB_IDLE
-
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 unprefixedUSBH_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.
-
enumerator USBH_MSG_USER_SET_CONFIG
-
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.
-
enumerator USBH_SW_TICK
-
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:
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).
Different bInterfaceNumber, same class/subclass/protocol -> chained via the
nextpointer. 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.
-
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.
-
u8 bLength
-
struct usbh_dev_bos_t
- #include <usbh.h>
USB standard Binary Device Object Store (BOS) descriptor structure.
-
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.
-
u8 bLength
-
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
-
u8 bLength
-
struct _usbh_itf_data_t
- #include <usbh.h>
Holds all parsed information for one unique bInterfaceNumber.
The USB framework organises interfaces along two axes:
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).
Different bInterfaceNumber, same class/subclass/protocol -> chained via the
nextpointer. 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...
-
u8 bLength
-
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.
-
u8 bDescLength
-
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.
-
u32 d32[2]
-
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.
-
u32 data
-
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.
-
u16 ext_intr_enable
-
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.
-
u8 *xfer_buf
-
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.
-
u16 mMatchFlags
-
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_CONFIGURATIONrequest 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
ownerpassed 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.
-
const usbh_dev_id_t *id_table
-
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.
-
void (*process)(struct _usb_host_t *host, u8 msg)
-
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.
-
const usbh_dev_id_t *dev_id
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.
-
enumerator USBH_DFU_STATE_IDLE
-
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_lenbytes).- 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.
-
int (*init)(void)
-
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.
-
u32 xfer_size
-
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.
-
usb_host_t *host
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
-
enumerator USBH_HID_REPORT_IDLE
-
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
-
enumerator VOLUME_EVENT_NONE
-
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
-
u8 bLength
-
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
-
usbh_hid_event_type_t type
-
struct usbh_hid_item_t
- #include <usbh_hid.h>
HID Report Item structure. Used during parsing of the HID Report Descriptor.
-
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
-
u16 up_bit
-
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
-
usbh_hid_ctrl_caps_t *device_info
-
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
-
int (*init)(void)
-
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
-
usb_host_t *host
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.
-
enumerator BOT_CMD_IDLE
-
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.
-
enumerator BOT_SEND_CBW
-
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.
-
enumerator MSC_INIT
-
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.
-
enumerator MSC_OK
-
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.
-
enumerator MSC_REQ_IDLE
-
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.
-
usb_msc_bot_cbw_t *cbw
-
struct usbh_scsi_capacity_t
- #include <usbh_msc.h>
SCSI capacity data structure.
Holds the result from a READ CAPACITY command.
-
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.
-
u8 vendor_id[8]
-
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.
-
usbh_scsi_capacity_t capacity
-
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.
-
void (*attached)(void)
-
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.
-
u32 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.
-
const usbh_msc_cb_t *cb
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.
-
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).
-
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)
-
u16 bma_controls[1 + USBH_UAC_MAX_CHANNEL]
-
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)
-
usbh_uac_fu_info_t fu_controls[USBH_UAC_FU_MAX_CNT]
-
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
-
rtos_sema_t isoc_sema
-
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
-
s16 volume
-
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
-
u32 freq[USBH_UAC_FREQ_FORMAT_MAX]
-
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
-
usbh_uac_format_cfg_t format_info
-
struct usbh_uac_audio_fmt_t
- #include <usbh_uac1.h>
Generic Audio Format Structure (Used for API interaction).
-
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
-
u16 packet_size_small
-
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
-
int (*init)(void)
-
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.
-
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
-
usbh_uac_as_itf_info_t *as_itf
-
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)
-
const usbh_uac_cb_t *cb
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
-
u16 bmHint
-
struct usbh_uvc_vs_payload_header_t
- #include <usbh_uvc_desc.h>
-
struct usbh_uvc_vc_intr_ep_desc_t
- #include <usbh_uvc_desc.h>
-
struct usbh_uvc_vc_header_desc_t
- #include <usbh_uvc_desc.h>
-
struct usbh_uvc_vc_it_desc_t
- #include <usbh_uvc_desc.h>
-
struct usbh_uvc_vc_ot_desc_t
- #include <usbh_uvc_desc.h>
-
struct usbh_uvc_vc_ct_desc_t
- #include <usbh_uvc_desc.h>
-
struct usbh_uvc_vc_pu_desc_t
- #include <usbh_uvc_desc.h>
-
struct usbh_uvc_vc_su_desc_t
- #include <usbh_uvc_desc.h>
-
struct usbh_uvc_vc_xu_desc_t
- #include <usbh_uvc_desc.h>
-
struct usbh_uvc_vc_eu_desc_t
- #include <usbh_uvc_desc.h>
-
struct usbh_uvc_vs_input_header_desc_t
- #include <usbh_uvc_desc.h>
-
struct usbh_uvc_vs_output_header_desc_t
- #include <usbh_uvc_desc.h>
-
struct usbh_uvc_entity_t
- #include <usbh_uvc_desc.h>
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.
-
enumerator UVC_STREAM_OFF
-
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.
-
enumerator UVC_FRAME_INIT
-
struct usbh_uvc_s_ctx_t
- #include <usbh_uvc.h>
UVC Stream Context / Parameters.
-
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).
-
u32 frame_buf_size
-
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.
-
int (*init)(void)
-
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.
-
u8 *buf
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
-
enumerator VENDOR_STATE_IDLE
-
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)..
-
int (*init)(void)
-
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
-
usbh_pipe_t pipe
-
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.
-
const usbh_vendor_cb_t *cb