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.

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

Host Class Driver

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

设备类驱动

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);
} 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

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