USB
概述
USB（Universal Serial Bus）是连接电脑与设备的一种序列总线标准，也是一种输入输出（I/O）连接端口的技术规范，广泛应用于个人电脑和移动设备等信息通信产品， 并扩展至摄影器材、数字电视（机顶盒）、游戏机等其它相关领域。 目前USB支持7种数据信号速率，USB1.0（Low Speed）的最大传输速率为 1.5Mbps，USB1.1（Full Speed）为 12Mbps，USB2.0（High Speed）为 480Mbps， USB3.0（USB3.2 Gen 1×1）为 5Gbps，USB3.1 Gen2（USB3.2 Gen 2x1）为 10Gbps，USB3.2（USB3.2 Gen 2x2）为 20Gbps，最新支持的 USB4.0 速度可达到 40Gbps， 比常规的并行接口、串行接口快得多。 USB 根据设备功能及类型，可以分为 USB 主机端、USB 设备端。USB 主机端包括两大部分，分别为与系统总线进行数据交互的 USB 控制器和 USB 总线的根集线器。USB 设备端可以是 集线器，为USB提供扩展的连接点。也可以是为系统提供具体功能的接口，如 U 盘，USB 摄像头，键盘鼠标等。
WQSDK 使用 TinyUSB 开源库实现 USB 协议栈，当前 WQ7036A，WQ7036AX 支持 USB，仅支持做设备功能，不支持做主机功能。支持 USB2.0（High Speed）规范，并向下兼容 USB1.1（Full Speed）。
功能特性
支持常用设备类型，如通信控制设备（cdc），大容量存储设备（msc），人机界面设备（hid），音效设备（uac）
支持复合设备
支持最多 5 个 IN/OUT 端点（包含控制端点 0）
配置选项
CONFIG_USB_LIB_ENABLE 使能 USB 组件
CONFIG_TUD_CDC_COUNT 配置支持的 cdc 接口数量
CONFIG_TUD_MSC_ENABLE 使能 msc 接口
CONFIG_TUD_HID_COUNT 配置支持的 hid 接口数量
CONFIG_TUD_AUDIO_COUNT 配置支持的 uac 接口数量
用法流程--以 cdc 为例
选择配置项：CONFIG_USB_LIB_ENABLE 配置为 y，CONFIG_TUD_CDC_COUNT 配置为 1
初始化 usb lib:
tusb_cfg_t config = {0}; // 用户可自定义描述符，不定义则用默认值(仅支持 cdc, msc)
wq_usb_lib_init(&config);
操作 cdc 设备：
wq_usb_lib_cdc_connected(); // 判断 cdc 设备是否连接
wq_usb_lib_cdc_read(); // 读 cdc 设备
wq_usb_lib_cdc_write(); // 写 cdc 设备
注销 usb lib:
wq_usb_lib_deinit();
参考示例
examples/usb_demo/cdc, examples/usb_demo/msc, examples/usb_demo/uac_speaker
API 介绍
Typedefs
-
typedef void (*wq_usb_lib_trans_done_callback)(void *buffer, uint32_t length, void *param)
usb trans done callback, invoke when data send or receive on usb.
Enums
-
enum WQ_USB_LIB_DIR
Values:
-
enumerator WQ_USB_LIB_DIR_RX
usb out
-
enumerator WQ_USB_LIB_DIR_TX
usb in
-
enumerator WQ_USB_LIB_DIR_RX
-
enum WQ_USB_LIB_CDC_PORT
Values:
-
enumerator WQ_USB_LIB_CDC_PORT_0
usb cdc port 0
-
enumerator WQ_USB_LIB_CDC_PORT_1
usb cdc port 1
-
enumerator WQ_USB_LIB_CDC_PORT_0
Functions
-
void wq_usb_lib_init(const tusb_cfg_t *config)
initialize usb lib, after call this api, usb stack will init, and will enum device according to the descriptors
备注
this api is non-reentrant and non-threadsafe, becareful call this init api and deinit api with mutex in multithread program, also, before call init, you should make sure cpu clock great than 48MHZ!!!
- 参数:
config -- usb init configuration param, include device/config/string descriptors
-
void wq_usb_lib_deinit(void)
deinitialize usb lib, after call this api, usb device will destory and all resources will release
备注
this api is non-reentrant and non-threadsafe, becareful call this deinit api and init api with mutex in multithread program, after call deinit, you can restore cpu clock to whatever you want.
-
WQ_RET wq_usb_lib_cdc_read(uint8_t port, uint8_t *buffer, uint32_t length, wq_usb_lib_trans_done_callback callback)
read data through cdc port, first of all, caller should judge the return value, only WQ_RET_OK means everything is ok, then callback will invoke in task context, and return the actual read length, after that caller can process the read buffer
- 参数:
port -- cdc com port
buffer -- read data buffer address
length -- read data length
callback -- callback function when read done
- 返回:
uint8_t result::WQ_RET
-
WQ_RET wq_usb_lib_cdc_write(uint8_t port, const uint8_t *buffer, uint32_t length, wq_usb_lib_trans_done_callback callback, bool zero_copy)
write data through cdc port, first of all, caller should judge the return value, only WQ_RET_OK means everything is ok, then callback will invoke in task context, caller can process the write buffer
- 参数:
port -- cdc com port
buffer -- write data buffer address
length -- write data length
callback -- callback function when write done
zero_copy -- true if caller itself manage buffer malloc/free, false if caller want usb lib to manage buffer malloc/free
- 返回:
uint8_t result::WQ_RET
-
bool wq_usb_lib_cdc_connected(uint8_t port)
detect whether cdc port connected
- 参数:
port -- cdc com port
- 返回:
bool true if connected, false if disconnected
-
WQ_RET wq_usb_lib_hid_write(WQ_USB_LIB_HID_TYPE type, uint8_t report_id, const char *string, uint32_t length, wq_usb_lib_trans_done_callback cb)
write hid type report data
- 参数:
type -- hid type
report_id -- hid module report
string -- write data buffer address
length -- data length
cb -- transfer done callback function
- 返回:
WQ_RET
-
WQ_RET wq_usb_lib_msc_install_driver(msc_diskio_driver_t *io_driver)
install usb msc diskio driver, for example, inner flash or sd card
- 参数:
io_driver -- the diskio driver info usb msc will use in class stack
- 返回:
WQ_RET_OK for success, else for fail
-
void wq_usb_lib_msc_uninstall_driver(void)
uninstall usb msc diskio driver current in use.
-
struct tusb_cfg_t
Public Members
-
const tusb_desc_device_t *device_descriptor
Pointer to a device descriptor. If set to NULL, usb device will use a default device descriptor whose values are set in Kconfig
-
const char **string_descriptor
Pointer to array of string descriptors. If set to NULL, usb device will use a default string descriptors whose values are set in Kconfig
-
int string_descriptor_count
Number of descriptors in above array
-
const uint8_t *hs_configuration_descriptor
Pointer to a highspeed configuration descriptor. If set to NULL, usb device will use a default configuration descriptor whose values are set in Kconfig
-
const uint8_t *fs_configuration_descriptor
Pointer to a fullspeed configuration descriptor. If set to NULL, usb device will use a default configuration descriptor whose values are set in Kconfig
-
const tusb_desc_device_t *device_descriptor
-
struct msc_diskio_driver_t
Public Members
-
WQ_USB_LIB_MSC_DISKIO_TYPE io_type
msc disk io type
-
WQ_SFC_PORT port
inner flash sfc port
-
union msc_diskio_driver_t::[anonymous] io_u
-
WQ_USB_LIB_MSC_DISKIO_TYPE io_type