硬件抽象层驱动

概述

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

硬件抽象层 API

硬件抽象层驱动提供了类型为 usb_hal_driver_t 的回调函数集:

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	描述
init	SoC相关的硬件（电源、时钟、使能）初始化
deinit	SoC相关的硬件（电源、时钟、使能）去初始化
enable_interrupt	使能USB中断
disable_interrupt	失能USB中断
register_irq_handler	注册USB中断处理函数
unregister_irq_handler	注销USB中断处理函数
get_cal_data	获取SoC相关的USB PHY校准数据
cg	USB CG 功耗测试

另外，硬件抽象层驱动还提供了如下 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

主机驱动

主机驱动软件架构

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

面向 Class 层的 API

API	描述
usbh_register_class	注册主机类驱动，主机类驱动类型为usbh_class_driver_t, 具体参考 Class层回调函数
usbh_unregister_class	注销主机类驱动
usbh_alloc_pipe	初始化通道
usbh_free_pipe	注销通道
usbh_open_pipe	打开通道
usbh_close_pipe	关闭通道
usbh_reactivate_pipe	重新激活指定通道中的传输请求
usbh_get_configuration	获取指定subclass对应的配置索引
usbh_set_configuration	设定配置索引
usbh_get_interface	获取指定class、subclass和protocol的interface索引
usbh_set_interface	设定当前的interface索引
usbh_get_interface_descriptor	获取指定interface索引和alternate setting对应的解析后的interface描述符
usbh_get_active_raw_configuration_descriptor	获取当前有效的配置描述符
usbh_get_raw_configuration_descriptor	获取对应index的未解析的配置描述符
usbh_get_device_descriptor	获取解析后的设备描述符
usbh_get_interval	获取bInterval对应的物理值
usbh_set_toggle	设置指定通道的PID翻转
usbh_get_toggle	获取指定通道的当前PID翻转设置
usbh_get_ep_type	获取指定通道对应的设备端点类型
usbh_get_urb_state	获取指定通道当前URB状态
usbh_notify_class_state_change	向核心驱动层发送事件，指示类驱动层状态有变更
usbh_notify_urb_state_change	向核心驱动层发送事件，指示URB状态有变更
usbh_ctrl_set_interface	向设备发送SET_INTERFACE标准请求
usbh_ctrl_set_feature	向设备发送SET_FEATURE标准请求
usbh_ctrl_clear_feature	向设备发送CLEAR_FEATURE标准请求
usbh_ctrl_request	向设备发送自定义控制请求
usbh_bulk_receive_data	发起批量传输，从设备接收数据
usbh_bulk_send_data	发起批量传输，向设备发送数据
usbh_intr_receive_data	发起中断传输，从设备接收数据
usbh_intr_send_data	发起中断传输，向设备发送数据
usbh_isoc_receive_data	发起等时传输，从设备接收数据
usbh_isoc_send_data	发起等时传输，向设备发送数据
usbh_get_current_frame	获取当前的帧号
usbh_get_last_transfer_size	获取指定通道上一次传输的数据长度
usbh_enable_nak_interrupt	使能对应pipe 的 NAK 中断掩码
usbh_check_nak_timeout	检查对应pipe NAK 是否超时
usbh_increase_busy_cnt	增加pipe 的忙计数
usbh_prepare_retransfer	准备重新发起传输
usbh_enter_suspend	进入或退出suspend状态
usbh_port_test_ctrl	发送端口测试指令，用于CTS测试

Class 层回调函数

主机核心驱动层提供了类型 usbh_class_driver_t 用于定义主机类驱动:

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;

具体定义如下:

API	描述
class_code	USB IF定义的类代码
attach	在SET_CONFIGURATION请求成功执行后被调用
detach	在设备连接断开时被调用
setup	在attach回调执行成功后被调用，用于处理类驱动相关的控制请求
process	在setup回调执行成功后被消息驱动循环调用，用于处理类驱动相关的消息
sof	在SOF中断发生时被调用，一般用于class层处理与时序相关的事务
nak	在指定通道发生NAK中断时被调用

面向应用层的 API

API	描述
usbh_init	初始化USB主机核心驱动，配置信息通过类型为 usbh_config_t 的参数指定，具体参考 USB主机核心驱动配置参数
usbh_deinit	注销USB主机核心驱动
usbh_get_status	获取设备连接状态，0 - 断开，1 - 连接
usbh_reenumerate	重新枚举

USB 主机核心驱动配置参数

主机核心驱动层提供了类型 usbh_config_t 用于定义 USB 主机协议栈配置参数:

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;

具体定义如下:

参数	描述
ext_intr_enable	使能可选的USB中断，设定值为0时不开任何可选中断，可根据应用设计需要，设定为以下宏定义值（支持按位组合）： USBH_SOF_INTR：SOF中断（GINTSTS.Sof），当Class层需要使能sof回调函数时开启，用于处理与时序相关的事务
rx_fifo_depth	USB主机共享接收缓存深度，最小值16，最大值不能超过硬件允许的最大值，仅适用于配置了专用缓存的SoC，具体参考 硬件配置
nptx_fifo_depth	USB主机共享非周期性发送缓存深度，最小值16，最大值不能超过硬件允许的最大值，仅适用于配置了专用缓存的SoC， 具体参考 硬件配置
ptx_fifo_depth	USB主机共享周期性发送缓存深度，最小值16，最大值不能超过硬件允许的最大值，仅适用于配置了专用缓存的SoC，具 体参考 硬件配置
main_task_priority	USB主机核心驱动主消息处理任务的优先级
isr_task_priority	USB主机核心驱动中断处理任务的优先级
alt_max_cnt	Interface描述符中支持的最大的alternate setting数量
transfer_retry_max_cnt	USB 传输的重传最大次数
speed	USB主机速度，有效值： USB_SPEED_HIGH：高速模式，适用于支持高速USB的Ameba SoC USB_SPEED_HIGH_IN_FULL：全速模式，适用于支持高速USB的Ameba SoC，用于连接全速UAC等对带宽要求不高的设备 USB_SPEED_FULL：全速模式，适用于仅支持全速USB的Ameba SoC
dma_enable	使能DMA模式
sof_tick_enable	设置USB主机核心驱动的计时方式，该计时用于根据设备端点描述符bInterval来触发周期性传输，以及传输超时检测： 0：利用系统时钟（如SysTick、DebugTimer，因SoC而异）计时，不需要响应额外的中断，CPU占用率较低，但与SOF 计数可能会有偏差。 适用于要求低CPU占用率、或者对传输周期要求不苛刻的应用场景。 1：利用SOF中断计时，需要配合USBH_SOF_INTR可选中断使用，因为需要周期性响应SOF中断，CPU占用率较高，计时 精度与SOF计数精度匹配
hub_enable	支持一级 HUB

备注

配置的缓存总深度 rx_fifo_depth + nptx_fifo_depth + ptx_fifo_depth 不得超过硬件支持的最大总缓存深度，具体参考 硬件配置 。

主机类驱动

CDC ACM 类驱动

类驱动路径

{SDK}/component/usb/host/cdc_acm

类驱动 API

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

API	描述
usbh_cdc_acm_init	初始化类驱动，初始化时会传入应用层回调指针，具体参考 应用层回调API。
usbh_cdc_acm_deinit	注销类驱动
usbh_cdc_acm_set_line_coding	发送CTRL请求，设置USB设备的line coding
usbh_cdc_acm_get_line_coding	发送CTRL请求，获取USB设备的line coding
usbh_cdc_acm_set_control_line_state	发送CTRL请求，设置USB设备的control line state
usbh_cdc_acm_transmit	发送批量OUT数据到USB设备
usbh_cdc_acm_receive	从USB设备读取批量IN数据
usbh_cdc_acm_notify_receive	从USB设备读取中断IN数据
usbh_cdc_acm_get_bulk_ep_mps	获取USB设备批量IN端点的MPS值

应用层回调 API

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

具体定义如下:

API	描述
init	在类驱动初始化时被调用，用于初始化应用相关的资源
deinit	在类驱动注销时被调用，用于注销应用相关的资源
attach	在类驱动执行attach回调时被调用，用于应用层处理设备连接事件
detach	在类驱动执行detach回调时被调用，用于应用层处理设备断开事件
setup	在类驱动执行setup回调时被调用，用于指示应用层类驱动已准备好进行批量传输
notify	在类驱动收到中断IN数据时被调用，用于应用层处理设备上报的状态信息
receive	在类驱动收到批量IN数据时被调用，用于应用层处理设备上报的数据
transmit	在类驱动批量OUT数据传输完成时被调用，用于应用层获取批量OUT传输状态
line_coding_changed	在类驱动收到设备上报的line coding数据，并与历史数据进行比对，发现有变更时被调用，用于应用层对line coding的改变作对应处理

CDC ECM 类驱动

类驱动路径

{SDK}/component/usb/host/cdc_ecm

类驱动 API

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

API	描述
usbh_cdc_ecm_do_init	初始化类驱动，初始化时会传入应用层回调指针，具体参考 应用层回调API。
usbh_cdc_ecm_do_deinit	注销类驱动
usbh_cdc_ecm_usb_is_ready	检查CDC ECM设备是否枚举成功
usbh_cdc_ecm_process_mac_str	获取CDC ECM设备的MAC信息
usbh_cdc_ecm_send_data	发送批量OUT数据
usbh_cdc_ecm_get_connect_status	获取CDC ECM设备的连接状态
usbh_cdc_ecm_get_receive_mps	获取CDC ECM设备批量IN端点的MPS值
usbh_cdc_ecm_get_device_vid	获取CDC ECM设备VID值
usbh_cdc_ecm_get_device_pid	获取CDC ECM设备PID值
usbh_cdc_ecm_hex_to_char	变量类型从hex转换为char
usbh_cdc_ecm_prepare_done	检查CDC ECM TRX 是否可以开始传输

应用层回调 API

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

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

具体定义如下:

API	描述
usb_report_data	处理接收到的批量IN网络数据

MSC 类驱动

类驱动路径

{SDK}/component/usb/host/msc

类驱动 API

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

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

应用层回调 API

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

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

具体定义如下:

API	描述
attach	在类驱动执行attach回调时被调用，用于应用层处理MSC设备连接事件
detach	在类驱动执行detach回调时被调用，用于应用层处理MSC设备断开事件
setup	当类驱动完成对MSC设备的初始化时被调用，用于指示应用层类驱动已准备好与MSC设备进行数据传输

FATFS 磁盘驱动 API

类驱动提供了类型为 ll_diskio_drv 的 FATFS 磁盘驱动 USB_disk_Driver，实现了以下 API:

API	描述
disk_initialize	初始化USB磁盘
disk_deinitialize	注销USB磁盘
disk_status	获取USB磁盘状态：RES_OK - 就绪，RES_ERROR - 未就绪
disk_read	从USB磁盘中读取数据
disk_write	将数据写入USB磁盘，仅当FATFS使能_USE_WRITE时有效
disk_ioctl	支持以下FATFS IO控制指令： CTRL_SYNC：强制将缓冲区的数据写入物理存储介质，对于USB磁盘，可认为是写穿透的，不需要SYNC GET_SECTOR_COUNT：获取sector数量 GET_SECTOR_SIZE：获取sector大小 GET_BLOCK_SIZE：获取block大小

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回调时被调用，用于应用层处理设备断开事件

Vendor 类驱动

类驱动路径

{SDK}/component/usb/host/vendor

类驱动 API

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

API	描述
usbh_vendor_init	初始化类驱动，初始化时会传入应用层回调指针，具体参考 应用层回调API。
usbh_vendor_deinit	注销类驱动
usbh_vendor_bulk_transmit	发送批量OUT数据到USB设备
usbh_vendor_bulk_receive	从USB设备读取批量IN数据
usbh_vendor_intr_transmit	发送中断OUT数据到USB设备
usbh_vendor_intr_receive	从USB设备读取中断IN数据
usbh_vendor_isoc_transmit	发送等时OUT数据到USB设备
usbh_vendor_isoc_receive	从USB设备读取等时IN数据
usbh_vendor_get_bulk_ep_mps	获取USB设备批量IN端点的MPS值
usbh_vendor_get_intr_ep_mps	获取USB设备中断IN端点的MPS值

应用层回调 API

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

具体定义如下:

API	描述
attach	在类驱动执行attach回调时被调用，用于应用层处理设备连接事件
detach	在类驱动执行detach回调时被调用，用于应用层处理设备断开事件
setup	在类驱动执行setup回调时被调用，用于指示应用层类驱动已准备好进行数据传输
receive	在类驱动收到IN数据时被调用，用于应用层处理设备上报的数据
transmit	在类驱动OUT数据传输完成时被调用，用于应用层获取OUT传输状态

设备驱动

设备驱动软件架构

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

面向类驱动层的 API

API	描述
usbd_register_class	注册设备类驱动，在设备类驱动初始化函数中调用, 类驱动定义参考 类驱动层回调函数。
usbd_unregister_class	注销设备类驱动，在设备类驱动注销函数中调用。
usbd_ep_init	初始化端点，一般会在以下场景中被调用： 设备类驱动set_config回调函数中 设备类驱动setup回调函数中，收到SET_INTERFACE之类的需要重新初始化端点的特定请求时
usbd_ep_deinit	注销端点，一般会在以下场景中被调用： 设备类驱动clear_config回调函数中 设备类驱动setup回调函数中，收到SET_INTERFACE之类的需要注销端点的特定请求时
usbd_ep_transmit	通过指定端点向USB主机发送数据，即发起IN传输。 传输的执行是异步的，函数返回并不表示传输已完成，可在设备类驱动ep_data_in/ep0_data_in回调函数中获取 传输执行状态。 设备核心驱动会根据需要自动补发ZLP，类驱动层和应用层不需要处理。
usbd_ep_receive	准备从指定端点从USB主机接受数据，即发起OUT传输。 传输的执行是异步的，函数返回并不表示传输已完成，可在设备类驱动ep_data_out/ep0_data_out回调函数中获 取传输完成的数据。
usbd_ep_set_stall	将指定端点状态设置为STALL，根据USB协议或者应用设计需求调用。
usbd_ep_clear_stall	清除指定端点的STALL状态，根据USB协议或者应用设计需求调用。
usbd_ep_is_stall	检查指定端点是否处于STALL状态。
usbd_get_str_desc	用于将ASCII编码的字符串转换为UNICODE 16编码的USB字符串描述符。 注意目标字符串缓存的大小为源字符串大小的两倍再加两个字节，多出的两个字节为USB字符串描述符长度和 描述符类型标识。

类驱动层回调函数

设备核心驱动层提供了类型 usbd_class_driver_t 用于定义设备类驱动:

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;

具体定义如下:

API	是否必须	描述
get_descriptor	是	在设备核心驱动枚举阶段收到USB主机获取USB描述符请求时被调用，所有类型的描述符统一通过该回调函数获 取。 设备类驱动需要在该回调函数中，根据Setup请求wValue字段定义的描述符类型，返回对应的描述符数组指针 和数组长度信息： USB_DESC_TYPE_DEVICE：设备描述符，必须支持 USB_DESC_TYPE_CONFIGURATION：配置描述符，必须支持 USB_DESC_TYPE_DEVICE_QUALIFIER：设备限定描述符，对于需要同时支持全速与高速的设备，必须支持 USB_DESC_TYPE_OTHER_SPEED_CONFIGURATION：其它速率配置描述符，对于需要同时支持全速与高速的设备， 必须支持 USB_DESC_TYPE_STRING：字符串描述符，具体又包含语言ID、厂商、产品、串号等字符串描述符，可选 关于USB描述符的介绍，参考 设备描述符定制。
set_config	是	当设备核心驱动在ADDRESSED状态下收到SET_CONFIGURATION控制请求时被调用。 类驱动一般需要在该回调函数中初始化端点资源并为OUT传输做好准备： 调用usbd_ep_init初始化当前配置对应的所有端点 调用usbd_ep_receive准备好进行第一笔OUT传输
clear_config	是	在以下场景中会被调用： 设备核心驱动在CONFIGURED状态下收到SET_CONFIGURATION控制请求切到新的配置或切到未配置状态时 设备核心驱动在非ADDRESSED/CONFIGURED状态下收到SET_CONFIGURATION控制请求时 设备核心驱动处理枚举完成（GINTSTS.EnumDone）中断时 设备核心驱动处理会话完成（GOTGINT.SesEndDet）中断时 在usbd_deinit被调用时 类驱动一般需要在该回调函数中调用usbd_ep_deinit注销端点资源。
setup	是	在控制IN/OUT传输的Setup阶段完成时被调用，用于类驱动层处理与类驱动相关的控制请求： 标准接口请求：USB_REQ_SET_INTERFACE、USB_REQ_GET_INTERFACE、USB_REQ_GET_STATUS 类相关请求：具体参考类规范中的相关定义 自定义请求：对于用户自定义的非标准类设备，用户可以根据需要自定义控制请求
ep_data_in	否	在批量/中断/等时IN传输的Data阶段完成时被调用，用于指示IN传输的完成状态。 类驱动可在该回调函数中调用应用层回调函数，允许发起新的IN传输或在IN传输失败时进行重传。
ep_data_out	否	在批量/中断/等时OUT传输的Data阶段完成时被调用，用于处理接收到的OUT数据，类驱动可在该回调函数中做 如下处理： 调用应用层回调函数，由应用层处理接收到的数据 调用usbd_ep_receive准备好进行下一笔OUT传输
ep0_data_in	否	在控制IN传输的Data阶段完成时被调用，用于指示控制IN传输的完成状态，允许发起新的控制IN传输或在控制 IN传输失败时进行重传
ep0_data_out	否	在控制OUT传输的Data阶段完成时被调用，用于处理接收到的控制OUT数据。 注意EP0的OUT传输使能在设备核心驱动层自动完成，类驱动层不需要处理。
sof	否	在SOF中断发生时被调用，一般用于处理与时序相关的事务，比如UAC应用可以通过该回调函数做与USB主机的时 钟同步
suspend	否	在suspend中断发生时被调用, 用于类驱动层在suspend发生时做资源挂起处理
resume	否	在resume中断发生时被调用, 用于类驱动层在resume发生时做资源恢复处理
status_changed	是	在USB连接状态改变时被调用，类驱动层可通过该回调函数支持USB热插拔。 例如可以调用应用层回调函数，让应用层在检测到与USB主机连接/通信断开时注销并重新初始化USB设备。 具体参考 设备连接状态检测

备注

上述所有设备类驱动回调函数均在中断上下文中被调用，不得在回调函数中执行耗时或阻塞操作。

面向应用层的 API

API	描述
usbd_init	初始化USB设备核心驱动，配置信息通过类型为 usbd_config_t 的参数指定，具体参考 USB设备核心驱动配置参数
usbd_deinit	注销USB设备
usbd_get_status	获取USB连接状态，返回值为 usbd_attach_status_t 定义的枚举值： USBD_ATTACH_STATUS_INIT = 0U, // 初始化 USBD_ATTACH_STATUS_ATTACHED = 1U, // 连接到USB主机 USBD_ATTACH_STATUS_DETACHED = 2U // 与USB主机断开连接或停止通信
usbd_get_bus_status	获取USB总线状态，当返回值为HAL_OK时，参数status返回有效的USB总线状态信息， 取值范围为 usbd_bus_state_t 定义的枚举值的按位组合值： USBD_BUS_STATUS_DN = BIT0, // D-线上的逻辑电平 USBD_BUS_STATUS_DP = BIT1, // D+线上的逻辑电平 USBD_BUS_STATUS_SUSPEND = BIT2, // Suspend状态指示
usbd_wake_host	向USB主机发送remote wakeup信号，唤醒USB主机

USB 设备核心驱动配置参数

设备核心驱动层提供了类型 usbd_config_t 用于定义 USB 设备核心驱动配置参数:

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;

具体定义如下:

参数	描述
nptx_max_epmis_cnt	非周期性IN传输产生EPMis中断的EPMis次数阈值，仅适用于配置了共享缓存的Ameba SoC
ext_intr_enable	使能可选的USB中断 USBD_SOF_INTR：SOF中断，一般用于需要通过SOF与USB主机端进行时钟同步的应用场景 USBD_EOPF_INTR：用于等时传输时设定下一帧的奇偶性，仅用于slave模式 USBD_EPMIS_INTR：用于在使能了多个非周期IN端点的应用场景下，发生EPMis中断后重启IN传输， 仅适用于配置了共享缓存的Ameba SoC
rx_fifo_depth	接收缓存深度，单位是DWORD，设定值不能超过硬件允许的最大值，仅适用于配置了专用缓存的Ameba SoC，具体参考 硬件配置
ptx_fifo_depth	发送缓存深度，单位是DWORD，ptx_fifo_depth[n]对应索引为n+1的发送缓存。 设定值不能超过硬件允许的最大值，索引为0的发送缓存深度不允许配置，使用硬件默认值。 仅适用于配置了专用缓存的Ameba SoC，具体参考 硬件配置 。
speed	USB设备速度，有效值： USB_SPEED_HIGH：高速模式，适用于支持高速USB的Ameba SoC USB_SPEED_HIGH_IN_FULL：全速模式，适用于支持高速USB的Ameba SoC，一般用于UAC等对带宽要求不高的应用场景 USB_SPEED_FULL：全速模式，适用于仅支持全速USB的Ameba SoC
isr_priority	USB设备核心驱动中的中断处理事件优先级
isr_in_critical	是否使能将USB设备核心驱动中的中断处理事件在保护区中运行，0-失能, 1-使能
dma_enable	是否使能DMA模式，0-失能, 1-使能
intr_use_ptx_fifo	是否需要使用专用的周期性传输缓存来处理中断IN传输，0-失能, 1-使能，仅适用于配置了共享缓存的Ameba SoC

备注

• 支持共享缓存的 Ameba SoC 不需要配置缓存深度；

• 支持专用缓存的 Ameba SoC 在配置缓存深度时，注意 rx_fifo_depth 和所有 ptx_fifo_depth 的设定值之和不能超过 SoC 支持的最大缓存深度。

具体参考 硬件配置 。

设备类驱动

CDC-ACM 类驱动

类驱动路径

{SDK}/component/usb/device/cdc_acm

类驱动 API

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

API	描述
usbd_cdc_acm_init	初始化类驱动，初始化时会传入应用层回调指针，具体参考 应用层回调API。
usbd_cdc_acm_deinit	注销类驱动
usbd_cdc_acm_transmit	发送批量IN数据到USB主机，数据长度不能超过批量IN最大传输长度
usbd_cdc_acm_notify_serial_state	通过中断IN发送状态数据到USB主机

应用层回调 API

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

具体定义如下:

API	描述
init	在类驱动初始化时被调用，用于初始化应用相关的资源
deinit	在类驱动注销时被调用，用于注销应用相关的资源
setup	在控制传输setup或data阶段被调用，用于处理应用相关的控制请求
received	在批量OUT传输完成时被调用，用于应用层处理接收到的数据
transmitted	在批量IN传输完成时被调用，用于应用层以异步的方式获取批量IN传输状态
status_changed	在USB连接状态改变时被调用，用于应用层处理USB热插拔事件

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热插拔事件

MSC 类驱动

类驱动路径

{SDK}/component/usb/device/msc

类驱动 API

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

API	描述
usbd_msc_init	初始化类驱动，初始化时会传入应用层回调指针，具体参考 应用层回调API。
usbd_msc_deinit	注销类驱动
usbd_msc_disk_init	初始化存储媒介
usbd_msc_disk_deinit	注销存储媒介

应用层回调 API

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

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

具体定义如下:

API	描述
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);
        void(*suspend)(void);
        void(*resume)(void);
} 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热插拔事件
suspend	在USB发生suspend中断后，类驱动suspend回调执行时被调用，用于应用层处理suspend事件
resume	在USB发生resume中断后，类驱动resume回调执行时被调用，用于应用层处理resume事件

Composite 类驱动

类驱动路径

{SDK}/component/usb/device/composite

类驱动 API

CDC ACM + HIDCDC ACM + UACHID + UAC

Composite 类驱动 API

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

API	描述
usbd_composite_init	初始化类驱动，初始化时会传入以下应用层回调指针： CDC ACM应用层回调，参考 CDC ACM应用层回调API HID应用层回调，参考 HID应用层回调API Composite应用层回调，参考 Composite应用层回调API
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传输状态

Vendor 类驱动

类驱动路径

{SDK}/component/usb/device/vendor

类驱动 API

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

API	描述
usbd_vendor_init	初始化类驱动，初始化时会传入应用层回调指针，具体参考 应用层回调API。
usbd_vendor_deinit	注销类驱动
usbd_vendor_transmit_ctrl_data	发送控制 IN 数据到 USB 主机
usbd_vendor_transmit_bulk_data	发送批量 IN 数据到 USB 主机
usbd_vendor_receive_bulk_data	从USB主机接收批量 OUT 数据
usbd_vendor_transmit_intr_data	发送中断 IN 数据到 USB 主机
usbd_vendor_receive_intr_data	从USB主机接收中断 OUT 数据
usbd_vendor_transmit_isoc_data	发送等时 IN 数据到 USB 主机
usbd_vendor_receive_isoc_data	从USB主机接收等时 OUT 数据

应用层回调 API

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

具体定义如下:

API	描述
init	在类驱动初始化时被调用，用于初始化应用相关的资源
deinit	在类驱动注销时被调用，用于注销应用相关的资源
setup	在控制传输setup或data阶段被调用，用于处理应用相关的控制请求
set_config	在类驱动set_config回调中被调用，用于通知应用层类驱动已就绪
bulk_received	在批量OUT传输完成时被调用，用于应用层处理接收到的数据
intr_received	在中断OUT传输完成时被调用，用于应用层处理接收到的数据
isoc_received	在等时OUT传输完成时被调用，用于应用层处理接收到的数据
bulk_transmitted	在批量IN传输完成时被调用，用于应用层以异步的方式获取批量IN传输状态
intr_transmitted	在中断IN传输完成时被调用，用于应用层以异步的方式获取批量IN传输状态
isoc_transmitted	在等时IN传输完成时被调用，用于应用层以异步的方式获取批量IN传输状态
status_changed	在USB连接状态改变时被调用，用于应用层处理USB热插拔事件