主从驱动

Note

请注意，v1.1 版本开始增加 busid 形参，其余保持不变，所以 API 说明不做更新

device controller(dcd)

usb_dc_init

usb_dc_init 用于初始化 usb device controller 寄存器，设置 usb 引脚、时钟、中断等等。 此函数不对用户开放。

int usb_dc_init(void);

return 返回 0 表示正确，其他表示错误

usb_dc_deinit

usb_dc_deinit 用于反初始化 usb device controller 寄存器。 此函数不对用户开放。

int usb_dc_deinit(void);

return 返回 0 表示正确，其他表示错误

usbd_set_address

usbd_set_address 设置设备地址。 此函数不对用户开放。

int usbd_set_address(const uint8_t addr);

addr 设备地址
return 返回 0 表示正确，其他表示错误

usbd_ep_open

usbd_ep_open 设置端点的属性，开启对应端点的中断。 此函数不对用户开放。

int usbd_ep_open(const struct usb_endpoint_descriptor *ep);

ep 端点描述符
return 返回 0 表示正确，其他表示错误

usbd_ep_close

usbd_ep_close 关闭端点。 此函数不对用户开放。

int usbd_ep_close(const uint8_t ep);

ep 端点地址
return 返回 0 表示正确，其他表示错误

usbd_ep_set_stall

usbd_ep_set_stall 将端点设置成 stall 状态并发送 stall 握手包。 此函数对用户开放。

int usbd_ep_set_stall(const uint8_t ep);

ep 端点地址
return 返回 0 表示正确，其他表示错误

usbd_ep_clear_stall

usbd_ep_clear_stall 清除端点的 stall 状态。 此函数不对用户开放。

int usbd_ep_clear_stall(const uint8_t ep);

ep 端点地址
return 返回 0 表示正确，其他表示错误

usbd_ep_is_stalled

usbd_ep_is_stalled 读取当前端点的 stall 状态。 此函数不对用户开放。

int usbd_ep_is_stalled(const uint8_t ep, uint8_t *stalled);

ep 端点地址
return 返回 1 表示 stalled，0 表示没有 stall

usbd_ep_start_write

usbd_ep_start_write 启动端点发送，发送完成以后，会调用注册的 in 端点传输完成中断回调函数。该函数为异步发送。 此函数对用户开放。

int usbd_ep_start_write(const uint8_t ep, const uint8_t *data, uint32_t data_len);

ep in 端点地址
data 发送数据缓冲区
data_len 发送长度，原则上无限长，推荐 16K 字节以内
return 返回 0 表示正确，其他表示错误

usbd_ep_start_read

usbd_ep_start_read 启动端点接收，接收完成以后，会调用注册的 out 端点传输完成中断回调函数。该函数为异步接收。 此函数对用户开放。

int usbd_ep_start_read(const uint8_t ep, uint8_t *data, uint32_t data_len);

ep out 端点地址
data 接收数据缓冲区
data_len 接收长度，原则上无限长，推荐 16K 字节以内，并且推荐是最大包长的整数倍
return 返回 0 表示正确，其他表示错误

Note

启动接收以后，以下两种情况，会进入传输完成中断：1、最后一包为短包（小于 EP MPS）；2、接收总长度等于 data_len

Note

对于 bulk 传输，data_len 通常设计为 EP MPS，以下三种情况可以修改为多个 EP MPS: 固定长度；自定义协议并携带长度（MSC）; 主机手动发送 ZLP 或者短包（RNDIS）

host controller(hcd)

usb_hc_init

usb_hc_init 用于初始化 usb host controller 寄存器，设置 usb 引脚、时钟、中断等等。 此函数不对用户开放。

int usb_hc_init(void);

return 返回 0 表示正确，其他表示错误

usb_hc_deinit

usb_hc_deinit 用于反初始化 usb host controller 寄存器。 此函数不对用户开放。

int usb_hc_deinit(void);

return 返回 0 表示正确，其他表示错误

usbh_roothub_control

usbh_roothub_control 用来对 roothub 发起请求， 此函数不对用户开放。

int usbh_roothub_control(struct usb_setup_packet *setup, uint8_t *buf);

setup 请求
buf 接收缓冲区
return 返回 0 表示正确，其他表示错误

usbh_submit_urb

usbh_submit_urb 对某个地址上的端点进行数据请求。 此函数对用户开放。

int usbh_submit_urb(struct usbh_urb *urb);

urb usb 请求块
return 返回 0 表示正确，其他表示错误

其中， urb 结构体信息如下：

struct usbh_urb {
    void *hcpriv;
    struct usbh_hubport *hport;
    struct usb_endpoint_descriptor *ep;
    uint8_t data_toggle;
    struct usb_setup_packet *setup;
    uint8_t *transfer_buffer;
    uint32_t transfer_buffer_length;
    int transfer_flags;
    uint32_t actual_length;
    uint32_t timeout;
    int errorcode;
    uint32_t num_of_iso_packets;
    uint32_t start_frame;
    usbh_complete_callback_t complete;
    void *arg;
#if defined(__ICCARM__) || defined(__ICCRISCV__) || defined(__ICCRX__)
    struct usbh_iso_frame_packet *iso_packet;
#else
    struct usbh_iso_frame_packet iso_packet[0];
#endif
};

hcpriv 主机控制器驱动私有成员
hport 当前 urb 使用的 hport
ep 当前 urb 使用的 ep
data_toggle 当前 data toggle
setup setup 请求缓冲区，端点0使用
transfer_buffer 传输的数据缓冲区
transfer_buffer_length 传输长度
transfer_flags 传输时携带的 flag
actual_length 实际传输长度
timeout 传输超时时间，为 0 该函数则为非阻塞，可在中断中使用
errorcode 错误码
num_of_iso_packets iso 帧或者微帧个数
complete 传输完成回调函数
arg 传输完成时携带的参数
iso_packet iso 数据包

Note

timeout 如何没有特别对时间的要求，必须设置成 0xffffffff，原则上不允许超时，如果超时了，一般不能再继续工作

errorcode 可以返回以下值：

#define USB_ERR_NOMEM    1
#define USB_ERR_INVAL    2
#define USB_ERR_NODEV    3
#define USB_ERR_NOTCONN  4
#define USB_ERR_NOTSUPP  5
#define USB_ERR_BUSY     6
#define USB_ERR_RANGE    7
#define USB_ERR_STALL    8
#define USB_ERR_BABBLE   9
#define USB_ERR_NAK      10
#define USB_ERR_DT       11
#define USB_ERR_IO       12
#define USB_ERR_SHUTDOWN 13
#define USB_ERR_TIMEOUT  14

其中 iso_packet 结构体信息如下：

struct usbh_iso_frame_packet {
    uint8_t *transfer_buffer;
    uint32_t transfer_buffer_length;
    uint32_t actual_length;
    int errorcode;
};

transfer_buffer 传输的数据缓冲区
transfer_buffer_length 传输长度
actual_length 实际传输长度
errorcode 错误码