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

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

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

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