硬件抽象层驱动

概述

硬件抽象层驱动提供了 SoC 相关的 USB 电源管理、中断处理和 PHY 校准接口，并定义了上层 USB 核心驱动所需的系统常量。

../../_images/usb_hal_api_cn.svg

硬件抽象层驱动还提供了如下 USB 相关的宏定义：

宏定义

描述

USB_REG_BASE

USB寄存器基地址

USB_ADDON_REG_BASE

USB AddOn寄存器基地址

USB_MAX_ENDPOINTS

USB设备模式下支持的最大端点数量

USB_MAX_PIPES

USB主机模式下支持的最大通道数量

USB_VID

Realtek USB VID

USB_PID

Realtek USB PID

备注

  • 硬件抽象层默认编入 USB 主机/设备/DRD 核心库文件，不允许开发者修改

  • USB PHY 校准数据在 SoC 出厂前确定，原则上不需要开发者修改，如遇疑似校准导致的兼容性问题（如枚举失败、反复断线重连），请联系 Realtek FAE

主机驱动

主机驱动软件架构

../../_images/usb_host_api_cn.svg

主机核心驱动层 API 定义头文件: {SDK}/component/usb/host/core/usbh.h

UVC 类驱动

类驱动路径

{SDK}/component/usb/host/uvc

类驱动 API

类驱动 API 定义头文件：{SDK}/component/usb/host/uvc/usbh_uvc_intf.h

API

描述

usbh_uvc_init

初始化类驱动，初始化时会传入应用层回调指针，具体参考 应用层回调API。

usbh_uvc_deinit

注销类驱动

usbh_uvc_stream_on

开启视频流

usbh_uvc_stream_off

关闭视频流

usbh_uvc_stream_state

获取视频流状态：STREAMING_OFF - 关闭，STREAMING_ON - 开启

usbh_uvc_set_param

设置视频参数

usbh_uvc_get_frame

从帧缓存的视频流中截取一个数据帧

usbh_uvc_put_frame

将截取的数据帧释放回帧缓存

应用层回调 API

类驱动提供了类型为 usbh_uvc_cb_t 的应用层回调函数集:

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

具体定义如下:

API

描述

init

在类驱动初始化时被调用，用于初始化应用相关的资源

deinit

在类驱动注销时被调用，用于注销应用相关的资源

attach

在类驱动执行attach回调时被调用，用于应用层处理设备连接事件

detach

在类驱动执行detach回调时被调用，用于应用层处理设备断开事件

设备驱动

设备驱动软件架构

../../_images/usb_device_api_cn.svg

设备核心驱动层 API 定义头文件: {SDK}/component/usb/device/core/usbd.h

设备类驱动

HID 类驱动

类驱动路径

{SDK}/component/usb/device/hid

类驱动 API

类驱动 API 定义头文件：{SDK}/component/usb/device/hid/usbd_hid.h

API

描述

usbd_hid_init

初始化类驱动，初始化时会传入应用层回调指针，具体参考 应用层回调API

usbd_hid_deinit

注销类驱动

usbd_hid_send_data

发送HID数据

应用层回调 API

类驱动提供了类型为 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;

具体定义如下:

API

描述

init

在类驱动初始化时被调用，用于初始化应用相关的资源

deinit

在类驱动注销时被调用，用于注销应用相关的资源

setup

在控制传输setup或data阶段被调用，用于处理应用相关的控制请求

received

在中断OUT传输完成时被调用，用于应用层处理接收到的数据，仅对键盘应用有效

transmitted

在中断IN传输完成时被调用，用于应用层以异步的方式获取中断IN传输状态

status_changed

在USB连接状态改变时被调用，用于应用层处理USB热插拔事件

UAC 类驱动

类驱动路径

{SDK}/component/usb/device/uac

类驱动 API

UAC 1.0 类驱动 API 定义头文件: {SDK}/component/usb/device/uac/usbd_uac1.h

UAC 2.0 类驱动 API 定义头文件: {SDK}/component/usb/device/uac/usbd_uac2.h

API

描述

usbd_uac_init

初始化类驱动，初始化时会传入应用层回调指针，具体参考 应用层回调API

usbd_uac_deinit

注销类驱动

usbd_uac_config

配置音频参数

usbd_uac_start_play

开始接收需要播放的音频数据到ring buffer

usbd_uac_stop_play

停止接收音频数据

usbd_uac_read

从ring buffer中读取接收到的音频数据用于播放

usbd_uac_get_read_frame_cnt

获取待播放的帧数量

应用层回调 API

类驱动提供了类型为 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;

具体定义如下:

API

描述

init

在类驱动初始化时被调用，用于初始化应用相关的资源

deinit

在类驱动注销时被调用，用于注销应用相关的资源

setup

在控制传输setup或data阶段被调用，用于处理应用相关的控制请求

set_config

在类驱动set_config回调中被调用，用于通知应用层UAC类驱动已就绪

status_changed

在USB连接状态改变时被调用，用于应用层处理USB热插拔事件

mute_changed

USB主机静音设置发生变化时被调用，用于应用层处理静音设置

volume_changed

USB主机音量设置发生变化时被调用，用于应用层调节播放音量

format_changed

USB主机的音频参数设置发生变化时被调用，用于应用层调整音频参数

sof

收到SOF中断时被调用，用于应用层处理时钟同步

INIC 类驱动

类驱动路径

{SDK}/component/usb/device/inic_dplus

类驱动 API

类驱动 API 定义头文件：{SDK}/component/usb/device/inic_dplus/usbd_inic.h

API

描述

usbd_inic_init

初始化类驱动，初始化时会传入应用层回调指针，具体参考 应用层回调API

usbd_inic_deinit

注销类驱动

usbd_inic_transmit_ctrl_data

发送控制数据

usbd_inic_transmit_data

发送非控制数据

usbd_inic_receive_data

接收非控制数据

应用层回调 API

类驱动提供了类型为 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_inic_cb_t ;

具体定义如下:

API

描述

init

在类驱动初始化时被调用，用于初始化应用相关的资源

deinit

在类驱动注销时被调用，用于注销应用相关的资源

setup

在控制传输setup或data阶段被调用，用于处理应用相关的控制请求

set_config

在类驱动set_config回调中被调用，用于通知应用层INIC类驱动已就绪

clear_config

在类驱动clear_config回调中被调用，用于通知应用层INIC类驱动未就绪

transmitted

在非控制端点数据发送完成时被调用，用于应用层异步获取数据发送状态

received

在非控制端点数据接收完成时被调用，用于应用层处理接收到的数据

status_changed

在USB连接状态改变时被调用，用于应用层处理USB热插拔事件

Composite 类驱动

类驱动路径

{SDK}/component/usb/device/composite

类驱动 API

Composite 类驱动 API

API 定义头文件：{SDK}/component/usb/device/composite/usbd_composite_cdc_acm_hid.h

API

描述

usbd_composite_init

初始化类驱动，初始化时会传入以下应用层回调指针：

usbd_composite_deinit

注销类驱动

CDC ACM 类驱动 API

API 定义头文件：{SDK}/component/usb/device/composite/usbd_composite_cdc_acm.h

API

描述

usbd_composite_cdc_acm_transmit

发送批量IN数据到USB主机，数据长度不能超过批量IN最大传输长度

usbd_composite_cdc_acm_notify_serial_state

通过中断IN发送状态数据到USB主机

HID 类驱动 API

API 定义头文件：{SDK}/component/usb/device/composite/usbd_composite_hid.h

API

描述

usbd_composite_hid_send_data

通过中断IN端点发送HID数据到USB主机

Composite 应用层回调 API

类驱动提供了类型为 usbd_composite_cb_t 的 HID 应用层回调函数集:

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

具体定义如下:

API

描述

set_config

在类驱动set_config回调中被调用，用于通知应用层类驱动已就绪

status_changed

在USB连接状态改变时被调用，用于应用层处理USB热插拔事件

CDC ACM 应用层回调 API

类驱动提供了类型为 usbd_composite_cdc_acm_usr_cb_t 的 CDC ACM 应用层回调函数集:

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;

具体定义如下:

API

描述

init

在类驱动初始化时被调用，用于初始化应用相关的资源

deinit

在类驱动注销时被调用，用于注销应用相关的资源

setup

在控制传输setup或data阶段被调用，用于处理应用相关的控制请求

received

在批量OUT传输完成时被调用，用于应用层处理接收到的数据

HID 应用层回调 API

类驱动提供了类型为 usbd_composite_hid_usr_cb_t 的 HID 应用层回调函数集:

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;

具体定义如下:

API

描述

init

在类驱动初始化时被调用，用于初始化应用相关的资源

deinit

在类驱动注销时被调用，用于注销应用相关的资源

setup

在控制传输setup或data阶段被调用，用于处理应用相关的控制请求

transmitted

在中断IN传输完成时被调用，用于应用层以异步的方式获取中断IN传输状态