HAL Driver

Overview

USB HAL driver implements ​​SoC-specific USB power management, interrupt handling and phy calibration interfaces, defines system-level preprocessor constants, exposes unified HAL API to upper-layer drivers.

USB HAL API

USB HAL driver is defined with usb_hal_driver_t type:

typedef struct {
   int(* init)(u8 mode);
   int(* deinit)(void);
   void(* enable_interrupt)(u8 priority);
   void(* disable_interrupt)(void);
   void(* register_irq_handler)(void *handler, u8 priority);
   void(* unregister_irq_handler)(void);
   usb_cal_data_t *(* get_cal_data)(u8 mode);
   void (*cg)(u32 ms);
} usb_hal_driver_t;

API	Description
init	SoC-specific USB initialization
deinit	SoC-specific USB deinitialization
enable_interrupt	Enable USB interrupt
disable_interrupt	Disable USB interrupt
register_irq_handler	Register USB interrupt handler
unregister_irq_handler	Unregister USB interrupt handler
get_cal_data	Get SoC-specific USB PHY calibration data
cg	Clock gate process for USB power test

And USB HAL driver defines following preprocessor constants used in upper-layer drivers:

Definition	Description
USB_REG_BASE	Base address of USB registers
USB_ADDON_REG_BASE	Base address of USB AddOn registers
USB_MAX_ENDPOINTS	Max number of endpoints supported in USB device mode
USB_MAX_PIPES	Max number of pipes supported in USB host mode
USB_VID	Realtek USB VID
USB_PID	Realtek USB PID

Note

• USB HAL driver is built into USB host/device/DRD core library as default and customization is not allowed.

• USB PHY calibration data is determined by Realtek during manufacturing and developer-side re-calibration is not allowed, for suspected calibration-related compatibility issues (e.g., USB enumeration failures, intermittent disconnection/reconnection issues), contact Realtek FAE for help.

Host Driver

Host Core Driver API Overview

USB host core driver API definition header file: {SDK}/component/usb/host/core/usbh.h

API for Host Class Drivers

API	Description
usbh_register_class	Register a class driver, the class driver is defined by type usbh_class_driver_t. Refer to Class callback for details.
usbh_unregister_class	Un-register a class driver.
usbh_alloc_pipe	Allocate a pipe for the specified endpoint address.
usbh_free_pipe	Free a pipe.
usbh_open_pipe	Open a pipe as per specified pipe number and endpoint info.
usbh_close_pipe	Close a pipe.
usbh_reactivate_pipe	Reactivate the request in a specific pipe.
usbh_get_configuration	Get the configuration index against specific subclass.
usbh_set_configuration	Set the configuration index for bNumConfigurations>1 in device descriptor.
usbh_get_interface	Get the interface index as per the specific class, subclass and protocol.
usbh_set_interface	Set activate interface index.
usbh_get_interface_descriptor	Get the interface descriptor as per specific interface index and alternate setting.
usbh_get_active_raw_configuration_descriptor	Get current active raw configuration descriptor data.
usbh_get_raw_configuration_descriptor	Get the raw configuration descriptor data by config index.
usbh_get_device_descriptor	Get device descriptor.
usbh_get_interval	Get the actual interval value as per endpoint type and bInterval.
usbh_set_toggle	Set PID toggle for specific pipe.
usbh_get_toggle	Get the current PID toggle of specific pipe.
usbh_get_ep_type	Get the endpoint type of specific pipe.
usbh_get_urb_state	Get the current URB state of specific pipe.
usbh_notify_class_state_change	Notify host core that class state has been changed.
usbh_notify_urb_state_change	Notify host core that URB state has been changed.
usbh_ctrl_set_interface	Send SET_INTERFACE standard request to device.
usbh_ctrl_set_feature	Send SET_FEATURE standard request to device.
usbh_ctrl_clear_feature	Send CLEAR_FEATURE standard request to device.
usbh_ctrl_request	Send control request to device.
usbh_bulk_receive_data	Receive BULK IN data from device.
usbh_bulk_send_data	Send BULK OUT data to device.
usbh_intr_receive_data	Receive INTR IN data from device.
usbh_intr_send_data	Send INTR OUT data to device.
usbh_isoc_receive_data	Receive ISOC IN data from device.
usbh_isoc_send_data	Send ISOC OUT data to device.
usbh_get_current_frame	Get the current frame number.
usbh_get_last_transfer_size	Get the last transfer data size of specific pipe.
usbh_enable_nak_interrupt	Enable NAK mask for the pipe.
usbh_check_nak_timeout	Check NAK time out.
usbh_increase_busy_cnt	Increase pipe busy count.
usbh_prepare_retransfer	Host prepare for pipe retransfer.
usbh_enter_suspend	Enter/Exit suspend state.
usbh_port_test_ctrl	Send port test request, only for CTS test.

Class Callback

USB host class driver is defined by type usbh_class_driver_t as a group of callbacks:

typedef struct {
        u8 class_code;
        u8(*attach)(struct _usb_host_t *host);
        u8(*detach)(struct _usb_host_t *host);
        u8(*setup)(struct _usb_host_t *host);
        u8(*process)(struct _usb_host_t *host);
        u8(*sof)(struct _usb_host_t *host);
        u8(*nak)(struct _usb_host_t *host, u8 pipe_num);
} usbh_class_driver_t;

Where:

API	Description
class_code	Class code specified by USB IF.
attach	Called when SET_CONFIGURATION request is successfully responsed.
detach	Called when device is disconnected.
setup	Called after class attached to process class-specific control requests.
process	Cyclically called after class setup to process class-specific transfers.
sof	Called at SOF interrupt for class-specific timing process.
nak	Called at NAK interrupt of specific pipe.

API for Host Applications

API	Description
usbh_init	Initialize USB host core driver with configuration parameters defined by type usbh_config_t. Refer to USB Host Core Driver Configuration.
usbh_deinit	De-initialize USB host core driver.
usbh_get_status	Get device connection status: 0 - Disconnected, 1 - Connected.
usbh_reenumerate	Redo enumeration.

USB Host Core Driver Configuration

USB host core driver provides type usbh_config_t to define the core driver configuration parameters:

typedef struct {
        u32 ext_intr_enable;
        u16 rx_fifo_depth;
        u16 nptx_fifo_depth;
        u16 ptx_fifo_depth;
        u8 main_task_priority;
        u8 isr_task_priority;
        u8 alt_max_cnt;
        u8 transfer_retry_max_cnt;
        u8 speed;
        u8 dma_enable;
        u8 sof_tick_enable;
        u8 hub_enable;
} usbd_config_t;

Where:

Parameter	Description
ext_intr_enable	Enable optional extended USB interrupts. Set it to 0 to disable all optional interrupts and set it to following values to enable specific interrupt(s) as needed by applications: USBH_SOF_INTR: SOF interrupt (GINTSTS.Sof), used for host class driver to handle timing issues in SOF callback
rx_fifo_depth	Share receive FIFO depth, only for SoCs with dedicated USB FIFO. Min value 16 and max value restricted by SoC hardware, refer to Hardware Features.
nptx_fifo_depth	Share non-periodic transmit FIFO depth, only for SoCs with dedicated USB FIFO. Min value 16 and max value restricted by SoC hardware, refer to Hardware Features.
ptx_fifo_depth	Share periodic transmit FIFO depth, only for SoCs with dedicated USB FIFO. Min value 16 and max value restricted by SoC hardware, refer to Hardware Features.
main_task_priority	The priority of main task in USB host core driver, the main task processes the USB host messages.
isr_task_priority	The priority of ISR task in USB host core driver, the ISR task processes the USB host interrupts.
alt_max_cnt	The max number of alternate settings allowed in interface descriptor.
transfer_retry_max_cnt	USB transfer retry max count.
speed	USB host speed mode, valid values: USB_SPEED_HIGH: high-speed mode, applicable to SoCs supporting high-speed USB USB_SPEED_HIGH_IN_FULL: full-speed mode, applicable to SoCs supporting high-speed USB and low bandwidth applications such as UAC and HID USB_SPEED_FULL: full-speed mode, applicable to SoCs supporting full-speed-only USB
dma_enable	Enable DMA mode.
sof_tick_enable	Flag to set the timing strategy of USB host core driver. The timing strategy is used to trigger periodic transfers based on the bInterval value of device endpoint descriptor and to detect transfer timeouts: 0: Uses the system clock (e.g., SysTick, DebugTimer, depending on the SoC) for timing. 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. 1: Uses SOF interrupts for timing and requires the USBH_SOF_INTR optional interrupt. Since it needs to periodically respond to SOF interrupts, CPU usage is higher, but timing accuracy matches SOF counting precision.
hub_enable	Support 1-level HUB, 0-Disable, 1-Enable.

Note

The configured total FIFO depth rx_fifo_depth + nptx_fifo_depth + ptx_fifo_depth shall not exceed the max total FIFO depth supported by the SoC hardware, refer to Hardware Features.

Host Class Driver

CDC ACM Class Driver

Source Location

{SDK}/component/usb/host/cdc_acm

API for Applications

API header file: {SDK}/component/usb/host/cdc_acm/usbh_cdc_acm.h

API	Description
usbh_cdc_acm_init	Initializes class driver with application callback handler, refer to Application Callback.
usbh_cdc_acm_deinit	Deinitializes class driver
usbh_cdc_acm_set_line_coding	Sends SET_LINE_CODING control request
usbh_cdc_acm_get_line_coding	Sends GET_LINE_CODING control request
usbh_cdc_acm_set_control_line_state	Sends SET_CONTROL_LINE_STATE control request
usbh_cdc_acm_transmit	Initiates bulk OUT transfer
usbh_cdc_acm_receive	Initiates bulk IN transfer
usbh_cdc_acm_notify_receive	Initiates interrupt IN transfer to get device status notifications
usbh_cdc_acm_get_bulk_ep_mps	Retrieves max packet size of the device bulk IN endpoint

Application Callback

The class driver defines an application callback structure usbh_cdc_acm_cb_t:

typedef struct {
   int(* init)(void);
   int(* deinit)(void);
   int(* attach)(void);
   int(* detach)(void);
   int(* setup)(void);
   int(* notify)(u8 *buf, u32 len);
   int(* receive)(u8 *buf, u32 len);
   int(* transmit)(usbh_urb_state_t state);
   int(* line_coding_changed)(usbh_cdc_acm_line_coding_t *line_coding);
} usbh_cdc_acm_cb_t;

Where:

API	Description
init	Called when class driver initialized, used to allocate application-specific resources
deinit	Called when class driver de-initialized, used to release application-specific resources
attach	Called when device attached, used to report device connection status
detach	Called when device detached, used to report device disconnection status
setup	Called when device setup done, used to indicate that device is ready for bulk transfer
notify	Called when interrupt IN transfer completed, used to report interrupt notifications
receive	Called when bulk IN transfer completed, used for application to handle the received bulk IN data
transmit	Called when bulk OUT transfer completed, used to report bulk OUT transfer completion status
line_coding_changed	Called when device line coding parameters change

CDC ECM Class Driver

Location

{SDK}/component/usb/host/cdc_ecm

API for Applications

API header file: {SDK}/component/usb/host/cdc_ecm/usbh_cdc_ecm_hal.h

API	Description
usbh_cdc_ecm_do_init	Initializes class driver with application callback handler, refer to Application Callback.
usbh_cdc_ecm_do_deinit	Deinitializes class driver
usbh_cdc_ecm_usb_is_ready	Check if CDC ECM device is ready
usbh_cdc_ecm_process_mac_str	Retrieves the MAC address information of attached CDC ECM device
usbh_cdc_ecm_send_data	Initiates bulk OUT data transfer
usbh_cdc_ecm_get_connect_status	Queries device connection status
usbh_cdc_ecm_get_receive_mps	Retrieves max packet size of the device bulk IN endpoint
usbh_cdc_ecm_get_device_vid	Get CDC ECM device VID
usbh_cdc_ecm_get_device_pid	Get CDC ECM device PID
usbh_cdc_ecm_hex_to_char	Convert variable type from hex to char
usbh_cdc_ecm_prepare_done	Check if ecm transfer can begin

Application Callback

The class driver defines an application callback structure usb_report_data:

typedef void (*usb_report_data)(u8 *buf, u32 len);

Where:

API	Description
usb_report_data	Processes received bulk IN network packets

MSC Class Driver

Location

{SDK}/component/usb/host/msc

API for Applications

API header file: {SDK}/component/usb/host/msc/usbh_msc.h

API	Description
usbh_msc_init	Initializes class driver with application callback handler, refer to Application Callback.
usbh_msc_deinit	Deinitializes class driver

Application Callback

The class driver defines an application callback structure usbh_msc_cb_t:

typedef struct {
   int(* attach)(void);
   int(* detach)(void);
   int(* setup)(void);
} usbh_msc_cb_t;

Where:

API	Description
attach	Called when device attached, used to report device connection status
detach	Called when device detached, used to report device disconnection status
setup	Called when device setup done, used to indicate that device is ready for bulk transfer

FATFS Disk Driver API

The class driver defines a FATFS disk driver USB_disk_Driver typed with ll_diskio_drv:

API	Description
disk_initialize	Initializes USB disk
disk_deinitialize	Deinitializes USB disk
disk_status	Returns disk status (RES_OK/RES_ERROR)
disk_read	Reads data from USB disk (sector-aligned)
disk_write	Writes data to USB disk (requires _USE_WRITE set in FATFS)
disk_ioctl	Implements FATFS IO control commands: CTRL_SYNC: No-op (USB implements write-through) GET_SECTOR_COUNT: Returns total sectors GET_SECTOR_SIZE: Returns sector size GET_BLOCK_SIZE: Returns erase block size

UVC Class Driver

Location

{SDK}/component/usb/host/uvc

API for Applications

API header file: {SDK}/component/usb/host/uvc/usbh_uvc_intf.h

API	Description
usbh_uvc_init	Initializes class driver with application callbacks, refer to Application Callback.
usbh_uvc_deinit	Deinitializes class driver
usbh_uvc_stream_on	Activates video streaming
usbh_uvc_stream_off	Terminates video streaming
usbh_uvc_stream_state	Returns streaming status (STREAMING_OFF/STREAMING_ON)
usbh_uvc_set_param	Configures video parameters (resolution, frame rate, format)
usbh_uvc_get_frame	Captures a video frame from frame buffer
usbh_uvc_put_frame	Releases captured frame buffer for reuse

Application Callback

The class driver defines an application callback structure usbh_uvc_cb_t:

typedef struct {
   int(* init)(void);
   int(* deinit)(void);
   int(* attach)(void);
   int(* detach)(void);
} usbh_uvc_cb_t;

Where:

API	Description
init	Called when class driver initialized, used to allocate application-specific resources
deinit	Called when class driver de-initialized, used to release application-specific resources
attach	Called when device attached, used to report device connection status
detach	Called when device detached, used to report device disconnection status

Vendor Class Driver

Source Location

{SDK}/component/usb/host/vendor

API for Applications

API header file: {SDK}/component/usb/host/vendor/usbh_vendor.h

API	Description
usbh_vendor_init	Initializes class driver with application callback handler, refer to Application Callback.
usbh_vendor_deinit	Deinitializes class driver
usbh_vendor_bulk_transmit	Initiates bulk OUT transfer
usbh_vendor_bulk_receive	Initiates bulk IN transfer
usbh_vendor_intr_transmit	Initiates interrupt OUT transfer
usbh_vendor_intr_receive	Initiates interrupt IN transfer
usbh_vendor_isoc_transmit	Initiates isochronous OUT transfer
usbh_vendor_isoc_receive	Initiates isochronous IN transfer
usbh_vendor_get_bulk_ep_mps	Retrieves max packet size of the device bulk IN endpoint
usbh_vendor_get_intr_ep_mps	Retrieves max packet size of the device interrupt IN endpoint

Application Callback

The class driver defines an application callback structure usbh_vendor_cb_t:

typedef struct {
   int(* attach)(void);
   int(* detach)(void);
   int(* setup)(void);
   int(* receive)(u8 ep_type, u8 *buf, u32 len);
   int(* transmit)(u8 ep_type);
} usbh_vendor_cb_t;

Where:

API	Description
attach	Called when device attached, used to report device connection status
detach	Called when device detached, used to report device disconnection status
setup	Called when device setup done, used to indicate that device is ready for data transfer
receive	Called when IN transfer completed, used for application to handle the received IN data
transmit	Called when OUT transfer completed, used to report OUT transfer completion status

Device Driver

Device Core Driver API Overview

USB device core driver API definition header file: {SDK}/component/usb/device/core/usbd.h

API for Device Class Drivers

API	Description
usbd_register_class	Register a device class driver, called in class initialization function. The class driver is defined by type usbd_class_driver_t, refer to Class Callback.
usbd_unregister_class	Un-register a class, called in class de-initialization function.
usbd_ep_init	Initialize an endpoint, typically called in following scenarios: In the set_config callback function of the device class driver. In the setup callback function of the device class driver, when receiving specific requests (such as SET_INTERFACE) that require endpoint (re-)initialization.
usbd_ep_deinit	Deinitialize an endpoint, typically called in following scenarios: In the clear_config callback function of the device class driver. In the setup callback function of the device class driver, when receiving specific requests (such as SET_INTERFACE) that require endpoint deinitialization.
usbd_ep_transmit	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 device class driver. ZLP will be automatically transmitted as needed by device core driver.
usbd_ep_receive	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 device class driver.
usbd_ep_set_stall	Sets the specified endpoint to STALL state.
usbd_ep_clear_stall	Clears the STALL state of the specified endpoint.
usbd_ep_is_stall	Checks whether the specified endpoint is in STALL state.
usbd_get_str_desc	Converts ASCII strings to UNICODE16-encoded USB string descriptors. Note: The destination buffer must accommodate twice the source length plus 2 bytes (for the length and type fields of string descriptor).

Class Callback

USB device class driver is defined by type usbd_class_driver_t as a group of callbacks:

typedef struct _usbd_class_driver_t {
   u16(*get_descriptor)(usb_dev_t *dev, usb_setup_req_t *req, u8 *buf);
   u8(*set_config)(usb_dev_t *dev, u8 config);
   u8(*clear_config)(usb_dev_t *dev, u8 config);
   u8(*setup)(usb_dev_t *dev, usb_setup_req_t *req);
   u8(*sof)(usb_dev_t *dev);
   u8(*suspend)(usb_dev_t *dev);
   u8(*resume)(usb_dev_t *dev);
   u8(*ep0_data_in)(usb_dev_t *dev, u8 status);
   u8(*ep0_data_out)(usb_dev_t *dev);
   u8(*ep_data_in)(usb_dev_t *dev, u8 ep_addr, u8 status);
   u8(*ep_data_out)(usb_dev_t *dev, u8 ep_addr, u16 len);
   void (*status_changed)(usb_dev_t *dev, u8 old_status, u8 status);
} usbd_class_driver_t;

Where:

API	Required	Description
get_descriptor	Yes	Called during enumeration when host requests USB descriptors. The class driver must return the descriptor data buffer and length againt the wValue value of host setup request: USB_DESC_TYPE_DEVICE: Device Descriptor, mandatory USB_DESC_TYPE_CONFIGURATION: Configuration Descriptor, mandatory USB_DESC_TYPE_DEVICE_QUALIFIER: Device Qualifier Descriptor, required for dual-speed (FS/HS) devices USB_DESC_TYPE_OTHER_SPEED_CONFIGURATION：Other Speed Configuration Descriptor, required for dual-speed devices USB_DESC_TYPE_STRING: String descriptors (language ID, manufacturer, product, serial), optional Refer to Device Descriptor Customization for USB descriptors.
set_config	Yes	Called upon SET_CONFIGURATION request in ADDRESSED state. The device class driver must: Initialize endpoints via usbd_ep_init Prepare first OUT transfer via usbd_ep_receive
clear_config	Yes	Called when: Core driver receives SET_CONFIGURATION control request in CONFIGURED state and needs to switch configuration Core driver receives SET_CONFIGURATION control request in non-ADDRESSED/CONFIGURED state Core driver processes enumeration complete interrupt (GINTSTS.EnumDone) Core driver processes Session end interrupt (GOTGINT.SesEndDet) USB core driver API usbd_deinit is called Typically, the device class driver shall call usbd_ep_deinit to deinitialize the endpoints.
setup	Yes	Called at control transfer setup phase to handle class-specific control requests: Standard interface requests (SET_INTERFACE/GET_INTERFACE/GET_STATUS) Class-specific requests per relevant class specifications Vendor-defined requests for custom devices
ep_data_in	No	Called when bulk/interrupt/isochronous IN transfer done for IN transfer status indication. The device class driver may mark endpoint ready for next transfer or retry failed transfers.
ep_data_out	No	Called when bulk/interrupt/isochronous OUT transfer done for received data handling. Typically, the device class driver shall: Process received data via application callback Prepare next OUT transfer via usbd_ep_receive
ep0_data_in	No	Called when control IN transfer done for IN transfer status indication.
ep0_data_out	No	Called when control OUT transfer done for received data handling. Note: the device driver does not need to re-enable the control OUT transfer since it is automatically done in core driver.
sof	No	Called upon SOF interrupt (GINTSTS.Sof) for timing-sensitive operations (e.g., UAC clock synchronization).
suspend	No	Called upon suspend interrupt (GINTSTS.USBSusp) for power management.
resume	No	Called upon resume interrupt (GINTSTS.WkUpInt) for resource recovery.
status_changed	Yes	Called upon connection state changed for hot-plug support (e.g., do reinitialization on host disconnection), refer to Device Connection Status Detection.

Note

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

API for Device Applications

API	Description
usbd_init	Initialize USB device core driver with configuration defined by type usbd_config_t, refer to USB Device Core Driver Configuration
usbd_deinit	Deinitialize USB device core driver
usbd_get_status	Get USB attach status with return value defined by usbd_attach_status_t: USBD_ATTACH_STATUS_INIT = 0U, // Initialized USBD_ATTACH_STATUS_ATTACHED = 1U, // Attached to USB host USBD_ATTACH_STATUS_DETACHED = 2U // Detached from USB host or suspend
usbd_get_bus_status	Get USB bus status. Return HAL_OK on success, with the status parameter containing USB bus status information represented as a bitwise combination of usbd_bus_status_t enumeration values: USBD_BUS_STATUS_DN = BIT0, // D- line logic level USBD_BUS_STATUS_DP = BIT1, // D+ line logic level USBD_BUS_STATUS_SUSPEND = BIT2, // Suspend status
usbd_wake_host	Sends a remote wakeup signal to the USB host to resume communication

USB Device Core Driver Configuration

USB device core driver provides type usbd_config_t to define the core driver configuration parameters:

typedef struct {
   u32 nptx_max_epmis_cnt;
   u32 ext_intr_enable;
   u16 rx_fifo_depth;
   u16 ptx_fifo_depth[USB_MAX_ENDPOINTS - 1];
   u8 speed;
   u8 isr_priority;
   u8 isr_in_critical : 1;
   u8 dma_enable : 1;
   u8 intr_use_ptx_fifo : 1;
} usbd_config_t;

Where:

Parameter	Description
nptx_max_epmis_cnt	Threshold count of EPMis interrupts for non-periodic IN transfers, only for SoCs with shared USB FIFO
ext_intr_enable	Optional USB interrupt enable flags: USBD_SOF_INTR: SOF interrupt typically for host-device clock synchronization USBD_EOPF_INTR: End-of-frame interrupt for isochronous frame parity setting (slave mode only) USBD_EPMIS_INTR: EPMis interrupt for restarting IN transfers, applicable to scenarios with multiple non-periodic IN endpoints, only for SoCs with shared USB FIFO
rx_fifo_depth	Receive FIFO depth in DWORD (must not exceed hardware limits), only for SoC with dedicated FIFO, refer to Hardware Features.
ptx_fifo_depth	Transmit FIFO depth in DWORD (must not exceed hardware limits), ptx_fifo_depth[n] corresponds to transmit FIFO n+1 (transmit FIFO index 0 uses hardware defaults). Only for SoC with dedicated FIFO, refer to Hardware Features.
speed	USB device speed mode: USB_SPEED_HIGH: High-speed mode (for HS-capable SoCs) USB_SPEED_HIGH_IN_FULL: Full-speed mode (for HS-capable SoCs with low bandwidth applcations like UAC) USB_SPEED_FULL: Full-speed mode (for FS-only SoCs)
isr_priority	Priority level of USB interrupt service routine
isr_in_critical	Execute USB ISR in critical region (0: disabled, 1: enabled)
dma_enable	DMA mode control (0: disabled, 1: enabled)
intr_use_ptx_fifo	Use dedicated periodic transmit FIFO for interrupt IN transfers (0: disabled, 1: enabled), only for SoCs with shared USB FIFO

Note

• 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 + Σ(ptx_fifo_depth[n]) <= Hardware total FIFO depth

  Refer to Hardware Features.

Device Class Driver

CDC ACM Class Driver

Location

{SDK}/component/usb/device/cdc_acm

API for Applications

API header file: {SDK}/component/usb/device/cdc_acm/usbd_cdc_acm.h

API	Description
usbd_cdc_acm_init	Initializes class driver with application callback handler, refer to Application Callback
usbd_cdc_acm_deinit	Deinitializes class driver
usbd_cdc_acm_transmit	Transmits data via bulk IN endpoint
usbd_cdc_acm_notify_serial_state	Transmits status via interrupt IN endpoint

Application Callback

The class driver defines an application callback structure usbd_cdc_acm_cb_t:

typedef struct {
   u8(* init)(void);
   u8(* deinit)(void);
   u8(* setup)(usb_setup_req_t *req, u8 *buf);
   u8(* received)(u8 *buf, u32 len);
   void(* transmitted)(u8 status);
   void (*status_changed)(u8 old_status, u8 status);
} usbd_cdc_acm_cb_t;

Where:

API	Description
init	Called during class driver initialization for application resource setup
deinit	Called during class driver deinitialization for resource cleanup
setup	Called during control transfer SETUP/DATA phases to handle application-specific control requests
received	Called when bulk OUT transfer done, for application to handle the received data
transmitted	Called when bulk IN transfer done, for asynchronous bulk IN transfer status notification
status_changed	Called upon USB attach status changes for application to support hot-plug events

HID Class Driver

Location

{SDK}/component/usb/device/hid

API for Applications

API header file: {SDK}/component/usb/device/hid/usbd_hid.h

API	Description
usbd_hid_init	Initializes class driver with application callback handler, refer to Application Callback
usbd_hid_deinit	Deinitializes class driver
usbd_hid_send_data	Transmit HID data with interrupt IN endpoint

Application Callback

The class driver defines an application callback structure usbd_hid_usr_cb_t:

typedef struct {
        void(* init)(void);
        void(* deinit)(void);
        void(* setup)(void);
        void(* transmitted)(u8 status);
        void(* received)(u8 *buf, u32 len);
        void (*status_changed)(u8 old_status, u8 status);
} usbd_hid_usr_cb_t;

Where:

API	Description
init	Called during class driver initialization for application resource setup
deinit	Called during class driver deinitialization for resource cleanup
setup	Called during control transfer SETUP/DATA phases to handle application-specific control requests
received	Called when interrupt OUT transfer done, only for keyboard application to handle the received host command
transmitted	Called when interrupt IN transfer done, for asynchronous interrupt IN transfer status notification
status_changed	Called upon USB attach status changes for application to support hot-plug events

MSC Class Driver

Location

{SDK}/component/usb/device/msc

API for Applications

API header file: {SDK}/component/usb/device/msc/usbd_msc.h

API	Description
usbd_msc_init	Initializes class driver with application callback handler, refer to Application Callback.
usbd_msc_deinit	Deinitializes class driver
usbd_msc_disk_init	Initializes storage media
usbd_msc_disk_deinit	Deinitializes storage media

Application Callback

The class driver defines an application callback structure usbd_msc_cb_t:

typedef struct {
   void (*status_changed)(u8 old_status, u8 status);
} usbd_msc_cb_t;

Where:

API	Description
status_changed	Called upon USB attach status changes for application to support USB hot-plug events

UAC Class Driver

Location

{SDK}/component/usb/device/uac

API for Applications

UAC 1.0 API header file: {SDK}/component/usb/device/uac/usbd_uac1.h

UAC 2.0 API header file: {SDK}/component/usb/device/uac/usbd_uac2.h

API	Description
usbd_uac_init	Initializes class driver with application callback handler, refer to Application Callback
usbd_uac_deinit	Deinitializes class driver
usbd_uac_config	Configures audio parameters
usbd_uac_start_play	Starts receiving audio data to ring buffer
usbd_uac_stop_play	Stops audio data reception
usbd_uac_read	Reads audio data from ring buffer for playing
usbd_uac_get_read_frame_cnt	Gets queued audio frames count

Application Callback

The class driver defines an application callback structure usbd_uac_cb_t:

typedef struct {
        usbd_audio_cfg_t in;
        usbd_audio_cfg_t out;
        void *audio_ctx;
        int(* init)(void);
        int(* deinit)(void);
        int(* setup)(usb_setup_req_t *req, u8 *buf);
        int(* set_config)(void);
        void(* status_changed)(u8 old_status, u8 status);
        void(* mute_changed)(u8 mute);
        void(* volume_changed)(u8 volume);
        void(* format_changed)(u32 freq, u8 ch_cnt);
        void(* sof)(void);
} usbd_uac_cb_t;

Where:

API	Description
init	Called during class driver initialization for application resource setup
deinit	Called during class driver deinitialization for resource cleanup
setup	Called during control transfer SETUP/DATA phases to handle application-specific control requests
set_config	Notifies application layer when UAC driver becomes operational
status_changed	Called upon USB attach status changes for application to support hot-plug events
mute_changed	Handles mute setting updates from USB host
volume_changed	Adjusts playback volume according to host-side volume changes
format_changed	Updates audio parameters (sample rate/channels) when modified by host
sof	Called upon SOF interrupt for clock synchronization

INIC Class Driver

Location

{SDK}/component/usb/device/inic_dplus

API for Applications

API header file: {SDK}/component/usb/device/inic_dplus/usbd_inic.h

API	Description
usbd_inic_init	Initializes class driver with application callback handler, refer to Application Callback
usbd_inic_deinit	Deinitializes class driver
usbd_inic_transmit_ctrl_data	Transmits control IN data
usbd_inic_transmit_data	Transmits non-control IN data
usbd_inic_receive_data	Prepares to receive non-control OUT data

Application Callback

The class driver defines an application callback structure usbd_inic_cb_t:

typedef struct {
        int(* init)(void);
        int(* deinit)(void);
        int(* setup)(usb_setup_req_t *req, u8 *buf);
        int(* set_config)(void);
        int(* clear_config)(void);
        void(* transmitted)(usbd_inic_ep_t *in_ep, u8 status);
        int(* received)(usbd_inic_ep_t *out_ep, u16 len);
        void (*status_changed)(u8 old_status, u8 status);
        void(*suspend)(void);
        void(*resume)(void);
} usbd_uac_cb_t;

Where:

API	Description
init	Called during class driver initialization for application resource setup
deinit	Called during class driver deinitialization for resource cleanup
setup	Called during control transfer SETUP/DATA phases to handle application-specific control requests
set_config	Notifies application layer when INIC driver becomes operational
clear_config	Notifies application layer when INIC driver becomes non-operational
transmitted	Called when non-control IN transfer done, for asynchronous non-control IN transfer status notification
received	Called when non-control OUT transfer done, for application to handle the received host command/data
status_changed	Called upon USB attach status changes for application to support hot-plug events
suspend	Called at suspend interrupt (GINTSTS.USBSusp) , used for application-specific suspend handling
resume	Called at resume interrupt (GINTSTS.WkUpInt) , used for application-specific resume handling

Composite Class Driver

Location

{SDK}/component/usb/device/composite

API for Applications

CDC ACM + HIDCDC ACM + UACHID + UAC

Composite Class Driver API

API header file: {SDK}/component/usb/device/composite/usbd_composite_cdc_acm_hid.h

API	Description
usbd_composite_init	Initializes class driver with application callback handlers: CDC ACM application callback, refer to CDC ACM Application Callback HID application callback, refer to HID Application Callback Composite application callback, refer to Composite Application Callback
usbd_composite_deinit	Deinitializes class driver

CDC ACM Class Driver API

API header file: {SDK}/component/usb/device/composite/usbd_composite_cdc_acm.h

API	Description
usbd_composite_cdc_acm_transmit	Transmits CDC ACM data via bulk IN endpoint
usbd_composite_cdc_acm_notify_serial_state	Transmits CDC ACM status via interrupt IN endpoint

HID Class Driver API

API header file: {SDK}/component/usb/device/composite/usbd_composite_hid.h

API	Description
usbd_composite_hid_send_data	Transmits HID data via interrupt IN endpoint

Composite Application Callback

The class driver defines an application callback structure usbd_composite_cb_t:

typedef struct {
        void (*status_changed)(u8 old_status, u8 status);
        int (* set_config)(void);
} usbd_composite_cb_t;

Where:

API	Description
set_config	Notifies application layer that the class driver becomes operational
status_changed	Called upon USB attach status changes for application to support hot-plug events

CDC ACM Application Callback

The class driver defines a CDC ACM application callback structure usbd_composite_cdc_acm_usr_cb_t:

typedef struct {
        u8(* init)(void);
        u8(* deinit)(void);
        u8(* setup)(usb_setup_req_t *req, u8 *buf);
        u8(* received)(u8 *buf, u32 len);
} usbd_composite_cdc_acm_usr_cb_t;

Where:

API	Description
init	Called during class driver initialization for application resource setup
deinit	Called during class driver deinitialization for resource cleanup
setup	Called during control transfer SETUP/DATA phases to handle application-specific control requests
received	Called when bulk OUT transfer done, for application to handle the received bulk OUT data

HID Application Callback

The class driver defines a HID application callback structure usbd_composite_hid_usr_cb_t:

typedef struct {
        int(* init)(void);
        void(* deinit)(void);
        int(* setup)(usb_setup_req_t *req, u8 *buf);
        void(* transmitted)(u8 status);
} usbd_composite_hid_usr_cb_t;

Where:

API	Description
init	Called during class driver initialization for application resource setup
deinit	Called during class driver deinitialization for resource cleanup
setup	Called during control transfer SETUP/DATA phases to handle application-specific control requests
transmitted	Called when interrupt IN transfer done, for asynchronous interrupt IN transfer status notification

Vendor Class Driver

Location

{SDK}/component/usb/device/vendor

API for Applications

API header file: {SDK}/component/usb/device/vendor/usbd_vendor.h

API	Description
usbd_vendor_init	Initializes class driver with application callback handler, refer to Application Callback
usbd_vendor_deinit	Deinitializes class driver
usbd_vendor_transmit_ctrl_data	Transmits data via control IN endpoint
usbd_vendor_transmit_bulk_data	Transmits data via bulk IN endpoint
usbd_vendor_receive_bulk_data	Receives data via bulk OUT endpoint
usbd_vendor_transmit_intr_data	Transmits data via interrupt IN endpoint
usbd_vendor_receive_intr_data	Receives data via interrupt OUT endpoint
usbd_vendor_transmit_isoc_data	Transmits data via isochronous IN endpoint
usbd_vendor_receive_isoc_data	Receives data via isochronous OUT endpoint

Application Callback

The class driver defines an application callback structure usbd_vendor_cb_t:

typedef struct {
   int(* init)(void);
   int(* deinit)(void);
   int(* setup)(usb_setup_req_t *req, u8 *buf);
   int(* set_config)(void);
   int(* bulk_received)(u8 *buf, u32 len);
   int(* intr_received)(u8 *buf, u32 len);
   int(* isoc_received)(u8 *buf, u32 len);
   void(* bulk_transmitted)(u8 status);
   void(* intr_transmitted)(u8 status);
   void(* isoc_transmitted)(u8 status);
   void (*status_changed)(u8 old_status, u8 status);
} usbd_vendor_cb_t;

Where:

API	Description
init	Called during class driver initialization for application resource setup
deinit	Called during class driver deinitialization for resource cleanup
setup	Called during control transfer SETUP/DATA phases to handle application-specific control requests
set_config	Used to notify application layer that the class driver becomes operational
bulk_received	Called when bulk OUT transfer done, for application to handle the received data
intr_received	Called when interrupt OUT transfer done, for application to handle the received data
isoc_received	Called when isochronous OUT transfer done, for application to handle the received data
bulk_transmitted	Called when bulk IN transfer done, for asynchronous bulk IN transfer status notification
intr_transmitted	Called when interrupt IN transfer done, for asynchronous interrupt IN transfer status notification
isoc_transmitted	Called when isochronous IN transfer done, for asynchronous isochronous IN transfer status notification
status_changed	Called upon USB attach status changes for application to support hot-plug events