Deploying to gh-pages from @ cherry-embedded/CherryUSB@a8ef0c4cac 🚀

.buildinfo

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: 1ff4012dec7a873e68569e5f5af97599
+tags: 645f666f9bcd5a90fca523b33c5a78b7

_sources/api/api_config.rst.txt

@@ -0,0 +1,158 @@
+USB CONFIG 说明
+=========================
+
+通用 CONFIG
+---------------------
+
+CONFIG_USB_PRINTF
+^^^^^^^^^^^^^^^^^^^^
+
+USB log 功能，默认重定向到 printf，需要注意，USB log 会在中断中使用，因此重定向的 api 不允许阻塞。举例，如果使用的是 rt-thread，请更换成 rt-kprintf
+
+CONFIG_USB_DBG_LEVEL
+^^^^^^^^^^^^^^^^^^^^^^
+
+控制 log 的打印级别
+
+CONFIG_USB_PRINTF_COLOR_ENABLE
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+控制 log 颜色打印，默认开启
+
+CONFIG_USB_ALIGN_SIZE
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+USB buffer 的对齐大小，默认是 4。IP 在 dma 模式下可能对输入的 buffer有对齐要求，一般是4，如果是其他对齐方式，请修改此值。
+
+USB_NOCACHE_RAM_SECTION
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+如果芯片没有 cache 功能，此宏无效。如果有，则 USB 的输入输出 buffer 必须放在 nocache ram 中，保证数据一致性。
+
+设备协议栈 CONFIG
+---------------------
+
+CONFIG_USBDEV_REQUEST_BUFFER_LEN
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+控制传输接收和发送的 buffer 最大长度，默认是 512。
+
+CONFIG_USBDEV_SETUP_LOG_PRINT
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+使能或者关闭 setup 包的 dump 信息，默认关闭。
+
+CONFIG_USBDEV_DESC_CHECK
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+暂时没有实现
+
+CONFIG_USBDEV_TEST_MODE
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+使能或者关闭 usb test mode
+
+CONFIG_USBDEV_MSC_MAX_BUFSIZE
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+msc 缓存的最大长度，缓存越大，USB 的速度越高，因为介质一般多个 block 读写速度比单个 block 高很多，比如 sd 卡。
+默认 512 ，如果是 flash 需要改成 4K, 缓存的大小需要是介质的一个 block size 的整数倍。
+
+CONFIG_USBDEV_MSC_MANUFACTURER_STRING
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+CONFIG_USBDEV_MSC_PRODUCT_STRING
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+CONFIG_USBDEV_MSC_VERSION_STRING
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+CONFIG_USBDEV_MSC_POLLING
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+将 usbd_msc_sector_read 和 usbd_msc_sector_write 操作放在 while1 中运行，裸机下使用。
+
+CONFIG_USBDEV_MSC_THREAD
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+使能或者关闭 msc 线程，默认关闭。usbd_msc_sector_read 和 usbd_msc_sector_write 默认是在中断中执行，所以如果开启了 os 建议开启此宏，那么，
+usbd_msc_sector_read 和 usbd_msc_sector_write 就会在线程中执行。
+
+CONFIG_USBDEV_MSC_PRIO
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+MSC 读写线程的优先级，默认是 4，数值越小，优先级越高
+
+CONFIG_USBDEV_MSC_STACKSIZE
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+MSC 读写线程的堆栈大小，默认 2K 字节
+
+CONFIG_USBDEV_RNDIS_RESP_BUFFER_SIZE
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+rndis 控制传输最大接收和发送的长度，根据 RNDIS options list 决定最小长度，默认要大于等于 156
+
+CONFIG_USBDEV_RNDIS_ETH_MAX_FRAME_SIZE
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+rndis 以太网帧的最大长度，默认 1580
+
+CONFIG_USBDEV_RNDIS_VENDOR_ID
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+CONFIG_USBDEV_RNDIS_VENDOR_DESC
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+CONFIG_USBDEV_RNDIS_USING_LWIP
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+rndis 与 lwip 接口的对接
+
+主机协议栈 CONFIG
+---------------------
+
+以下参数决定了支持的最大外部hub数量，接口数，每个接口的端点数和 altsetting 数量，更改此值会影响 ram 的大小，建议根据实际情况更改。
+
+.. code-block:: C
+
+    #define CONFIG_USBHOST_MAX_RHPORTS          1
+    #define CONFIG_USBHOST_MAX_EXTHUBS          1
+    #define CONFIG_USBHOST_MAX_EHPORTS          4
+    #define CONFIG_USBHOST_MAX_INTERFACES       6
+    #define CONFIG_USBHOST_MAX_INTF_ALTSETTINGS 1
+    #define CONFIG_USBHOST_MAX_ENDPOINTS        4
+
+以下参数决定了支持的 class 数目，更改此值会影响 ram 的大小，建议根据实际情况更改。
+
+.. code-block:: C
+
+    #define CONFIG_USBHOST_MAX_CDC_ACM_CLASS 4
+    #define CONFIG_USBHOST_MAX_HID_CLASS     4
+    #define CONFIG_USBHOST_MAX_MSC_CLASS     2
+    #define CONFIG_USBHOST_MAX_AUDIO_CLASS   1
+    #define CONFIG_USBHOST_MAX_VIDEO_CLASS   1
+
+CONFIG_USBHOST_PSC_PRIO
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+主机插拔线程的优先级，默认是 0，数值越小，优先级越高
+
+CONFIG_USBHOST_PSC_STACKSIZE
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+主机插拔线程的堆栈大小，默认 2K 字节
+
+CONFIG_USBHOST_REQUEST_BUFFER_LEN
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+控制传输能够接收或者发送的最大长度
+
+CONFIG_USBHOST_CONTROL_TRANSFER_TIMEOUT
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+控制传输发送或者接收的超时时间，默认 1s
+
+CONFIG_USBHOST_MSC_TIMEOUT
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+MSC 读写传输的超时时间，默认 5s

_sources/api/api_device.rst.txt

@@ -0,0 +1,479 @@
+设备协议栈
+=========================
+
+设备协议栈主要负责枚举和驱动加载，枚举这边就不说了，驱动加载，也就是接口驱动加载，主要是依靠 `usbd_add_interface` 函数，用于记录传入的接口驱动并保存到接口数组表，当主机进行类请求时就可以查找接口表进行访问了。
+在调用 `usbd_desc_register` 以后需要进行接口注册和端点注册，口诀如下：
+
+- 有多少个接口就调用多少次 `usbd_add_interface`，参数填相关 `xxx_init_intf`, 如果没有支持的，手动创建一个 intf 填入
+- 有多少个端点就调用多少次 `usbd_add_endpoint`，当中断完成时，会调用到注册的端点回调中。
+
+CORE
+-----------------
+
+.. note:: 请注意，v1.1 版本开始增加 busid 形参，其余保持不变，所以 API 说明不做更新
+
+端点结构体
+""""""""""""""""""""""""""""""""""""
+
+端点结构体主要用于注册不同端点地址的中断完成回调函数。
+
+.. code-block:: C
+
+    struct usbd_endpoint {
+        uint8_t ep_addr;
+        usbd_endpoint_callback ep_cb;
+    };
+
+- **list** 端点的链表节点
+- **ep_addr** 端点地址（带方向）
+- **ep_cb** 端点完成中断回调函数。
+
+.. note:: 总结一句话：in 回调函数等价于 dma 发送完成中断回调函数；out 回调函数等价于 dma 接收完成中断回调函数
+
+接口结构体
+""""""""""""""""""""""""""""""""""""
+
+接口结构体主要用于注册不同类设备除了标准设备请求外的其他请求，包括类设备请求、厂商设备请求和自定义设备请求。以及协议栈中的相关通知回调函数。
+
+.. code-block:: C
+
+    struct usbd_interface {
+        usbd_request_handler class_interface_handler;
+        usbd_request_handler class_endpoint_handler;
+        usbd_request_handler vendor_handler;
+        usbd_notify_handler notify_handler;
+        const uint8_t *hid_report_descriptor;
+        uint32_t hid_report_descriptor_len;
+        uint8_t intf_num;
+    };
+
+- **class_interface_handler** class setup 请求回调函数,接收者为接口
+- **class_endpoint_handler** class setup 请求回调函数,接收者为端点
+- **vendor_handler** vendor setup 请求回调函数
+- **notify_handler** 中断标志、协议栈相关状态回调函数
+- **hid_report_descriptor** hid 报告描述符
+- **hid_report_descriptor_len** hid 报告描述符长度
+- **intf_num** 当前接口偏移
+- **ep_list** 端点的链表节点
+
+usbd_desc_register
+""""""""""""""""""""""""""""""""""""
+
+``usbd_desc_register`` 用来注册 USB 描述符，描述符种类包括：设备描述符、配置描述符（包含配置描述符、接口描述符、class 类描述符、端点描述符）、字符串描述符、设备限定描述符。
+
+.. code-block:: C
+
+    void usbd_desc_register(const uint8_t *desc);
+
+- **desc**  描述符的句柄
+
+.. note:: 当前 API 仅支持一种速度，如果需要更高级的速度切换功能，请开启 CONFIG_USBDEV_ADVANCE_DESC，并且包含了下面所有描述符注册功能
+
+
+usbd_msosv1_desc_register
+""""""""""""""""""""""""""""""""""""
+
+``usbd_msosv1_desc_register`` 用来注册一个 WINUSB 1.0 描述符。
+
+.. code-block:: C
+
+    void usbd_msosv1_desc_register(struct usb_msosv1_descriptor *desc);
+
+- **desc**  描述符句柄
+
+usbd_msosv2_desc_register
+""""""""""""""""""""""""""""""""""""
+
+``usbd_msosv2_desc_register`` 用来注册一个 WINUSB 2.0 描述符。
+
+.. code-block:: C
+
+    void usbd_msosv2_desc_register(struct usb_msosv2_descriptor *desc);
+
+- **desc**  描述符句柄
+
+usbd_bos_desc_register
+""""""""""""""""""""""""""""""""""""
+
+``usbd_bos_desc_register`` 用来注册一个 BOS 描述符， USB 2.1 版本以上必须注册。
+
+.. code-block:: C
+
+    void usbd_bos_desc_register(struct usb_bos_descriptor *desc);
+
+- **desc**  描述符句柄
+
+usbd_add_interface
+""""""""""""""""""""""""""""""""""""
+
+``usbd_add_interface`` 添加一个接口驱动。 **添加顺序必须按照描述符顺序**。
+
+.. code-block:: C
+
+    void usbd_add_interface(struct usbd_interface *intf);
+
+- **intf**  接口驱动句柄，通常从不同 class 的 `xxx_init_intf` 函数获取
+
+usbd_add_endpoint
+""""""""""""""""""""""""""""""""""""
+
+``usbd_add_endpoint`` 添加一个端点中断完成回调函数。
+
+.. code-block:: C
+
+    void usbd_add_endpoint(struct usbd_endpoint *ep);;
+
+- **ep**    端点句柄
+
+usbd_initialize
+""""""""""""""""""""""""""""""""""""
+
+``usbd_initialize`` 用来初始化 usb device 寄存器配置、usb 时钟、中断等，需要注意，此函数必须在所有列出的 API 最后。 **如果使用 os，必须放在线程中执行**。
+
+.. code-block:: C
+
+    int usbd_initialize(void);
+
+usbd_event_handler
+""""""""""""""""""""""""""""""""""""
+
+``usbd_event_handler`` 是协议栈中中断或者协议栈一些状态的回调函数。大部分 IP 仅支持 USBD_EVENT_RESET 和 USBD_EVENT_CONFIGURED
+
+.. code-block:: C
+
+    void usbd_event_handler(uint8_t event);
+
+CDC ACM
+-----------------
+
+usbd_cdc_acm_init_intf
+""""""""""""""""""""""""""""""""""""
+
+``usbd_cdc_acm_init_intf`` 用来初始化 USB CDC ACM 类接口，并实现该接口相关的函数。
+
+- ``cdc_acm_class_interface_request_handler`` 用来处理 USB CDC ACM 类 Setup 请求。
+- ``cdc_notify_handler`` 用来处理 USB CDC 其他中断回调函数。
+
+.. code-block:: C
+
+    struct usbd_interface *usbd_cdc_acm_init_intf(struct usbd_interface *intf);
+
+- **return**  接口句柄
+
+usbd_cdc_acm_set_line_coding
+""""""""""""""""""""""""""""""""""""
+
+``usbd_cdc_acm_set_line_coding`` 用来对串口进行配置，如果仅使用 USB 而不用 串口，该接口不用用户实现，使用默认。
+
+.. code-block:: C
+
+    void usbd_cdc_acm_set_line_coding(uint8_t intf, struct cdc_line_coding *line_coding);
+
+- **intf** 控制接口号
+- **line_coding** 串口配置
+
+usbd_cdc_acm_get_line_coding
+""""""""""""""""""""""""""""""""""""
+
+``usbd_cdc_acm_get_line_coding`` 用来获取串口进行配置，如果仅使用 USB 而不用 串口，该接口不用用户实现，使用默认。
+
+.. code-block:: C
+
+    void usbd_cdc_acm_get_line_coding(uint8_t intf, struct cdc_line_coding *line_coding);
+
+- **intf** 控制接口号
+- **line_coding** 串口配置
+
+usbd_cdc_acm_set_dtr
+""""""""""""""""""""""""""""""""""""
+
+``usbd_cdc_acm_set_dtr`` 用来控制串口 DTR 。如果仅使用 USB 而不用 串口，该接口不用用户实现，使用默认。
+
+.. code-block:: C
+
+    void usbd_cdc_acm_set_dtr(uint8_t intf, bool dtr);
+
+- **intf** 控制接口号
+- **dtr** dtr 为1表示拉低电平，为0表示拉高电平
+
+usbd_cdc_acm_set_rts
+""""""""""""""""""""""""""""""""""""
+
+``usbd_cdc_acm_set_rts`` 用来控制串口 RTS 。如果仅使用 USB 而不用 串口，该接口不用用户实现，使用默认。
+
+.. code-block:: C
+
+    void usbd_cdc_acm_set_rts(uint8_t intf, bool rts);
+
+- **intf** 控制接口号
+- **rts** rts 为1表示拉低电平，为0表示拉高电平
+
+CDC_ACM_DESCRIPTOR_INIT
+""""""""""""""""""""""""""""""""""""
+
+``CDC_ACM_DESCRIPTOR_INIT`` 配置了默认的 cdc acm 需要的描述符以及参数，方便用户使用。总长度为 `CDC_ACM_DESCRIPTOR_LEN` 。
+
+.. code-block:: C
+
+    CDC_ACM_DESCRIPTOR_INIT(bFirstInterface, int_ep, out_ep, in_ep, str_idx);
+
+- **bFirstInterface** 表示该 cdc acm 第一个接口所在所有接口的偏移
+- **int_ep** 表示中断端点地址（带方向）
+- **out_ep** 表示 bulk out 端点地址（带方向）
+- **in_ep** 表示 bulk in 端点地址（带方向）
+- **str_idx** 控制接口对应的字符串 id
+
+HID
+-----------------
+
+usbd_hid_init_intf
+""""""""""""""""""""""""""""""""""""
+
+``usbd_hid_init_intf`` 用来初始化 USB HID 类接口，并实现该接口相关的函数：
+
+- ``hid_class_interface_request_handler`` 用来处理 USB HID 类的 Setup 请求。
+- ``hid_notify_handler`` 用来处理 USB HID 其他中断回调函数。
+
+.. code-block:: C
+
+    struct usbd_interface *usbd_hid_init_intf(struct usbd_interface *intf, const uint8_t *desc, uint32_t desc_len);
+
+- **desc** 报告描述符
+- **desc_len** 报告描述符长度
+
+MSC
+-----------------
+
+usbd_msc_init_intf
+""""""""""""""""""""""""""""""""""""
+``usbd_msc_init_intf`` 用来初始化 MSC 类接口，并实现该接口相关函数，并且注册端点回调函数。（因为 msc bot 协议是固定的，所以不需要用于实现，因此端点回调函数自然不需要用户实现）。
+
+- ``msc_storage_class_interface_request_handler`` 用于处理 USB MSC Setup 中断请求。
+- ``msc_storage_notify_handler`` 用于实现 USB MSC 其他中断回调函数。
+
+- ``mass_storage_bulk_out`` 用于处理 USB MSC 端点 out 中断。
+- ``mass_storage_bulk_in`` 用于处理 USB MSC 端点 in 中断。
+
+.. code-block:: C
+
+    struct usbd_interface *usbd_msc_init_intf(struct usbd_interface *intf, const uint8_t out_ep, const uint8_t in_ep);
+
+- **out_ep**     out 端点地址
+- **in_ep**      in 端点地址
+
+usbd_msc_get_cap
+""""""""""""""""""""""""""""""""""""
+
+``usbd_msc_get_cap`` 用来获取存储器的 lun、扇区个数和每个扇区大小。用户必须实现该函数。
+
+.. code-block:: C
+
+    void usbd_msc_get_cap(uint8_t lun, uint32_t *block_num, uint16_t *block_size);
+
+- **lun** 存储逻辑单元，暂时无用，默认支持一个
+- **block_num**  存储扇区个数
+- **block_size**  存储扇区大小
+
+usbd_msc_sector_read
+""""""""""""""""""""""""""""""""""""
+
+``usbd_msc_sector_read`` 用来对存储器某个扇区开始的地址进行数据读取。用户必须实现该函数。
+
+.. code-block:: C
+
+    int usbd_msc_sector_read(uint32_t sector, uint8_t *buffer, uint32_t length);
+
+- **sector** 扇区偏移
+- **buffer** 存储读取的数据的指针
+- **length** 读取长度
+
+
+usbd_msc_sector_write
+""""""""""""""""""""""""""""""""""""
+
+``usbd_msc_sector_write``  用来对存储器某个扇区开始写入数据。用户必须实现该函数。
+
+.. code-block:: C
+
+    int usbd_msc_sector_write(uint32_t sector, uint8_t *buffer, uint32_t length);
+
+- **sector** 扇区偏移
+- **buffer** 写入数据指针
+- **length** 写入长度
+
+UAC
+-----------------
+
+usbd_audio_init_intf
+""""""""""""""""""""""""""""""""""""
+``usbd_audio_init_intf``  用来初始化 USB Audio 类接口，并实现该接口相关的函数：
+
+- ``audio_class_interface_request_handler`` 用于处理 USB Audio Setup 接口接收者中断请求。
+- ``audio_class_endpoint_request_handler`` 用于处理 USB Audio Setup 端点接收者中断请求。
+- ``audio_notify_handler`` 用于实现 USB Audio 其他中断回调函数。
+
+.. code-block:: C
+
+    struct usbd_interface *usbd_audio_init_intf(struct usbd_interface *intf);
+
+- **class** 类的句柄
+- **intf**  接口句柄
+
+usbd_audio_open
+""""""""""""""""""""""""""""""""""""
+
+``usbd_audio_open``  用来开启音频数据传输。
+
+.. code-block:: C
+
+    void usbd_audio_open(uint8_t intf);
+
+- **intf** 开启的接口号
+
+usbd_audio_close
+""""""""""""""""""""""""""""""""""""
+
+``usbd_audio_close``  用来关闭音频数据传输。
+
+.. code-block:: C
+
+    void usbd_audio_close(uint8_t intf);
+
+- **intf** 关闭的接口号
+
+usbd_audio_add_entity
+""""""""""""""""""""""""""""""""""""
+
+``usbd_audio_add_entity``  用来添加 unit 相关控制，例如 feature unit、clock source。
+
+.. code-block:: C
+
+    void usbd_audio_add_entity(uint8_t entity_id, uint16_t bDescriptorSubtype);
+
+- **entity_id** 要添加的 unit id
+- **bDescriptorSubtype** entity_id 的描述符子类型
+
+usbd_audio_set_mute
+""""""""""""""""""""""""""""""""""""
+
+``usbd_audio_set_mute``  用来设置静音。
+
+.. code-block:: C
+
+    void usbd_audio_set_mute(uint8_t ch, uint8_t enable);
+
+- **ch** 要设置静音的通道
+- **enable** 为1 表示静音，0相反
+
+usbd_audio_set_volume
+""""""""""""""""""""""""""""""""""""
+
+``usbd_audio_set_volume``  用来设置音量。
+
+.. code-block:: C
+
+    void usbd_audio_set_volume(uint8_t ch, float dB);
+
+- **ch** 要设置音量的通道
+- **dB** 要设置音量的分贝，其中 UAC1.0范围从 -127 ~ +127dB，UAC2.0 从 0 ~ 256dB
+
+usbd_audio_set_sampling_freq
+""""""""""""""""""""""""""""""""""""
+
+``usbd_audio_set_sampling_freq``  用来设置设备上音频模块的采样率
+
+.. code-block:: C
+
+    void usbd_audio_set_sampling_freq(uint8_t ep_ch, uint32_t sampling_freq);
+
+- **ch** 要设置采样率的端点或者通道，UAC1.0为端点，UAC2.0 为通道
+- **dB** 要设置的采样率
+
+usbd_audio_get_sampling_freq_table
+""""""""""""""""""""""""""""""""""""
+
+``usbd_audio_get_sampling_freq_table``  用来获取支持的采样率列表，如果函数没有实现，则使用默认采样率列表。
+
+.. code-block:: C
+
+    void usbd_audio_get_sampling_freq_table(uint8_t **sampling_freq_table);
+
+- **sampling_freq_table** 采样率列表地址，格式参考默认采样率列表
+
+usbd_audio_set_pitch
+""""""""""""""""""""""""""""""""""""
+
+``usbd_audio_set_pitch``  用来设置音频音调，仅 UAC1.0 有这功能。
+
+.. code-block:: C
+
+    void usbd_audio_set_pitch(uint8_t ep, bool enable);
+
+- **ep** 要设置音调的端点
+- **enable** 开启或关闭音调
+
+UVC
+-----------------
+
+usbd_video_init_intf
+""""""""""""""""""""""""""""""""""""
+``usbd_video_init_intf``  用来初始化 USB Video 类接口，并实现该接口相关的函数：
+
+- ``video_class_interface_request_handler`` 用于处理 USB Video Setup 中断请求。
+- ``video_notify_handler`` 用于实现 USB Video 其他中断回调函数。
+
+.. code-block:: C
+
+    struct usbd_interface *usbd_video_init_intf(struct usbd_interface *intf,
+                                             uint32_t dwFrameInterval,
+                                             uint32_t dwMaxVideoFrameSize,
+                                             uint32_t dwMaxPayloadTransferSize);
+
+- **class** 类的句柄
+- **intf**  接口句柄
+
+usbd_video_open
+""""""""""""""""""""""""""""""""""""
+
+``usbd_video_open``  用来开启视频数据传输。
+
+.. code-block:: C
+
+    void usbd_video_open(uint8_t intf);
+
+- **intf** 开启的接口号
+
+usbd_video_close
+""""""""""""""""""""""""""""""""""""
+
+``usbd_video_close``  用来关闭视频数据传输。
+
+.. code-block:: C
+
+    void usbd_video_open(uint8_t intf);
+
+- **intf** 关闭的接口号
+
+usbd_video_payload_fill
+""""""""""""""""""""""""""""""""""""
+
+``usbd_video_payload_fill``  用来填充 mjpeg 到新的 buffer中，其中会对 mjpeg 数据按帧进行切分，切分大小由 ``dwMaxPayloadTransferSize`` 控制，并添加头部信息，当前头部字节数为 2。头部信息见 ``struct video_mjpeg_payload_header``
+
+.. code-block:: C
+
+    uint32_t usbd_video_payload_fill(uint8_t *input, uint32_t input_len, uint8_t *output, uint32_t *out_len);
+
+- **input** mjpeg 格式的数据包，从 FFD8~FFD9结束
+- **input_len** mjpeg数据包大小
+- **output** 输出缓冲区
+- **out_len** 输出实际要发送的长度大小
+- **return** 返回 usb 按照 ``dwMaxPayloadTransferSize`` 大小要发多少帧
+
+DFU
+-----------------
+
+PRINTER
+-----------------
+
+MTP
+-----------------

_sources/api/api_host.rst.txt

@@ -0,0 +1,167 @@
+主机协议栈
+=========================
+
+关于主机协议栈中结构体的命名、分类、成员组成，参考下面这两张图：
+
+.. figure:: img/api_host1.png
+.. figure:: img/api_host2.png
+
+CORE
+-----------------
+
+CLASS 驱动信息结构体
+""""""""""""""""""""""""""""""""""""
+
+.. code-block:: C
+
+    struct usbh_class_info {
+        uint8_t match_flags; /* Used for product specific matches; range is inclusive */
+        uint8_t class;       /* Base device class code */
+        uint8_t subclass;    /* Sub-class, depends on base class. Eg. */
+        uint8_t protocol;    /* Protocol, depends on base class. Eg. */
+        uint16_t vid;        /* Vendor ID (for vendor/product specific devices) */
+        uint16_t pid;        /* Product ID (for vendor/product specific devices) */
+        const struct usbh_class_driver *class_driver;
+    };
+
+端点结构体
+""""""""""""""""""""""""""""""""""""
+
+.. code-block:: C
+
+    struct usbh_endpoint {
+        struct usb_endpoint_descriptor ep_desc;
+    };
+
+接口备用结构体
+""""""""""""""""""""""""""""""""""""
+
+.. code-block:: C
+
+    struct usbh_interface_altsetting {
+        struct usb_interface_descriptor intf_desc;
+        struct usbh_endpoint ep[CONFIG_USBHOST_MAX_ENDPOINTS];
+    };
+
+接口结构体
+""""""""""""""""""""""""""""""""""""
+
+.. code-block:: C
+
+    struct usbh_interface {
+        char devname[CONFIG_USBHOST_DEV_NAMELEN];
+        struct usbh_class_driver *class_driver;
+        void *priv;
+        struct usbh_interface_altsetting altsetting[CONFIG_USBHOST_MAX_INTF_ALTSETTINGS];
+        uint8_t altsetting_num;
+    };
+
+配置结构体
+""""""""""""""""""""""""""""""""""""
+
+.. code-block:: C
+
+    struct usbh_configuration {
+        struct usb_configuration_descriptor config_desc;
+        struct usbh_interface intf[CONFIG_USBHOST_MAX_INTERFACES];
+    };
+
+hubport 结构体
+""""""""""""""""""""""""""""""""""""
+
+.. code-block:: C
+
+    struct usbh_hubport {
+        bool connected;   /* True: device connected; false: disconnected */
+        uint8_t port;     /* Hub port index */
+        uint8_t dev_addr; /* device address */
+        uint8_t speed;    /* device speed */
+        uint8_t depth;    /* distance from root hub */
+        uint8_t route;    /* route string */
+        uint8_t slot_id;  /* slot id */
+        struct usb_device_descriptor device_desc;
+        struct usbh_configuration config;
+        const char *iManufacturer;
+        const char *iProduct;
+        const char *iSerialNumber;
+        uint8_t *raw_config_desc;
+        struct usb_setup_packet *setup;
+        struct usbh_hub *parent;
+        struct usbh_hub *self; /* if this hubport is a hub */
+        struct usbh_bus *bus;
+        struct usb_endpoint_descriptor ep0;
+        struct usbh_urb ep0_urb;
+        usb_osal_mutex_t mutex;
+    };
+
+hub 结构体
+""""""""""""""""""""""""""""""""""""
+
+.. code-block:: C
+
+    struct usbh_hub {
+        bool connected;
+        bool is_roothub;
+        uint8_t index;
+        uint8_t hub_addr;
+        uint8_t speed;
+        uint8_t nports;
+        uint8_t powerdelay;
+        uint8_t tt_think;
+        bool ismtt;
+        struct usb_hub_descriptor hub_desc; /* USB 2.0 only */
+        struct usb_hub_ss_descriptor hub_ss_desc; /* USB 3.0 only */
+        struct usbh_hubport child[CONFIG_USBHOST_MAX_EHPORTS];
+        struct usbh_hubport *parent;
+        struct usbh_bus *bus;
+        struct usb_endpoint_descriptor *intin;
+        struct usbh_urb intin_urb;
+        uint8_t *int_buffer;
+        struct usb_osal_timer *int_timer;
+    };
+
+usbh_initialize
+""""""""""""""""""""""""""""""""""""
+
+``usbh_initialize`` 用来初始化 usb 主机协议栈，包括：初始化 usb 主机控制器，创建 roothub 设备，创建 hub 检测线程。
+
+.. code-block:: C
+
+    int usbh_initialize(uint8_t busid, uint32_t reg_base);
+
+- **busid**  bus id，从 0开始，不能超过 `CONFIG_USBHOST_MAX_BUS`
+- **reg_base**  hcd 寄存器基地址
+- **return**  0 表示正常其他表示错误
+
+usbh_find_class_instance
+""""""""""""""""""""""""""""""""""""
+
+``usbh_find_class_instance`` 根据注册的 class 名称查找对应的 class 结构体句柄。
+
+.. code-block:: C
+
+    void *usbh_find_class_instance(const char *devname);
+
+- **devname**  class 名称
+- **return**  class 结构体句柄
+
+lsusb
+""""""""""""""""""""""""""""""""""""
+
+``lsusb`` 用来查看和操作 hub 上的设备信息。需要借助 shell 插件使用。
+
+.. code-block:: C
+
+    int lsusb(int argc, char **argv);
+
+CDC ACM
+-----------------
+
+HID
+-----------------
+
+MSC
+-----------------
+
+RNDIS
+-----------------

_sources/api/api_port.rst.txt

@@ -0,0 +1,261 @@
+主从驱动
+=========================
+
+.. note:: 请注意，v1.1 版本开始增加 busid 形参，其余保持不变，所以 API 说明不做更新
+
+device controller(dcd)
+-------------------------
+
+usb_dc_init
+""""""""""""""""""""""""""""""""""""
+
+``usb_dc_init`` 用于初始化 usb device controller 寄存器，设置 usb 引脚、时钟、中断等等。 **此函数不对用户开放**。
+
+.. code-block:: C
+
+    int usb_dc_init(void);
+
+- **return** 返回 0 表示正确，其他表示错误
+
+usb_dc_deinit
+""""""""""""""""""""""""""""""""""""
+
+``usb_dc_deinit`` 用于反初始化 usb device controller 寄存器。 **此函数不对用户开放**。
+
+.. code-block:: C
+
+    int usb_dc_deinit(void);
+
+- **return** 返回 0 表示正确，其他表示错误
+
+usbd_set_address
+""""""""""""""""""""""""""""""""""""
+
+``usbd_set_address`` 设置设备地址。 **此函数不对用户开放**。
+
+.. code-block:: C
+
+    int usbd_set_address(const uint8_t addr);
+
+- **addr** 设备地址
+- **return** 返回 0 表示正确，其他表示错误
+
+usbd_ep_open
+""""""""""""""""""""""""""""""""""""
+
+``usbd_ep_open`` 设置端点的属性，开启对应端点的中断。 **此函数不对用户开放**。
+
+.. code-block:: C
+
+    int usbd_ep_open(const struct usb_endpoint_descriptor *ep);
+
+- **ep** 端点描述符
+- **return** 返回 0 表示正确，其他表示错误
+
+usbd_ep_close
+""""""""""""""""""""""""""""""""""""
+
+``usbd_ep_close`` 关闭端点。 **此函数不对用户开放**。
+
+.. code-block:: C
+
+    int usbd_ep_close(const uint8_t ep);
+
+- **ep** 端点地址
+- **return** 返回 0 表示正确，其他表示错误
+
+usbd_ep_set_stall
+""""""""""""""""""""""""""""""""""""
+
+``usbd_ep_set_stall`` 将端点设置成 stall 状态并发送 stall 握手包。 **此函数对用户开放**。
+
+.. code-block:: C
+
+    int usbd_ep_set_stall(const uint8_t ep);
+
+- **ep** 端点地址
+- **return** 返回 0 表示正确，其他表示错误
+
+usbd_ep_clear_stall
+""""""""""""""""""""""""""""""""""""
+
+``usbd_ep_clear_stall`` 清除端点的 stall 状态。 **此函数不对用户开放**。
+
+.. code-block:: C
+
+    int usbd_ep_clear_stall(const uint8_t ep);
+
+- **ep** 端点地址
+- **return** 返回 0 表示正确，其他表示错误
+
+usbd_ep_is_stalled
+""""""""""""""""""""""""""""""""""""
+
+``usbd_ep_is_stalled`` 读取当前端点的 stall 状态。 **此函数不对用户开放**。
+
+.. code-block:: C
+
+    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 端点传输完成中断回调函数。该函数为异步发送。 **此函数对用户开放**。
+
+.. code-block:: C
+
+    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 端点传输完成中断回调函数。该函数为异步接收。 **此函数对用户开放**。
+
+.. code-block:: C
+
+    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
+
+host controller(hcd)
+------------------------
+
+usb_hc_init
+""""""""""""""""""""""""""""""""""""
+
+``usb_hc_init`` 用于初始化 usb host controller 寄存器，设置 usb 引脚、时钟、中断等等。 **此函数不对用户开放**。
+
+.. code-block:: C
+
+    int usb_hc_init(void);
+
+- **return** 返回 0 表示正确，其他表示错误
+
+usb_hc_deinit
+""""""""""""""""""""""""""""""""""""
+
+``usb_hc_deinit`` 用于反初始化 usb host controller 寄存器。 **此函数不对用户开放**。
+
+.. code-block:: C
+
+    int usb_hc_deinit(void);
+
+- **return** 返回 0 表示正确，其他表示错误
+
+usbh_roothub_control
+""""""""""""""""""""""""""""""""""""
+
+``usbh_roothub_control`` 用来对 roothub 发起请求， **此函数不对用户开放**。
+
+.. code-block:: C
+
+    int usbh_roothub_control(struct usb_setup_packet *setup, uint8_t *buf);
+
+- **setup** 请求
+- **buf** 接收缓冲区
+- **return** 返回 0 表示正确，其他表示错误
+
+usbh_submit_urb
+""""""""""""""""""""""""""""""""""""
+
+``usbh_submit_urb`` 对某个地址上的端点进行数据请求。 **此函数对用户开放**。
+
+.. code-block:: C
+
+    int usbh_submit_urb(struct usbh_urb *urb);
+
+- **urb** usb 请求块
+- **return** 返回 0 表示正确，其他表示错误
+
+其中， `urb` 结构体信息如下：
+
+.. code-block:: C
+
+  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` 可以返回以下值：
+
+.. code-block:: C
+
+  #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` 结构体信息如下：
+
+.. code-block:: C
+
+  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** 错误码

_sources/class/class_audio.rst.txt

@@ -0,0 +1,4 @@
+UAC
+=========================
+
+参考官方 audio 相关 pdf

_sources/class/class_cdc.rst.txt

@@ -0,0 +1,4 @@
+CDC
+=========================
+
+参考官方 cdc 相关 pdf

_sources/class/class_hid.rst.txt

@@ -0,0 +1,4 @@
+HID
+=========================
+
+参考官方 hid 相关 pdf

_sources/class/class_msc.rst.txt

@@ -0,0 +1,4 @@
+MSC
+=========================
+
+参考官方 msc 相关 pdf

_sources/class/class_video.rst.txt

@@ -0,0 +1,4 @@
+UVC
+=========================
+
+参考官方 video 相关 pdf

_sources/class/winusb.rst.txt

@@ -0,0 +1,2 @@
+WINUSB
+=========================

_sources/demo/usbd_audiov1.rst.txt

@@ -0,0 +1,2 @@
+usbd_audiov1
+===============

_sources/demo/usbd_audiov2.rst.txt

@@ -0,0 +1,2 @@
+usbd_audiov2
+===============

_sources/demo/usbd_cdc_acm.rst.txt

@@ -0,0 +1,2 @@
+usbd_cdc_acm
+===============

_sources/demo/usbd_ecm.rst.txt

@@ -0,0 +1,2 @@
+usbd_cdc_ecm
+===============

_sources/demo/usbd_hid.rst.txt

@@ -0,0 +1,2 @@
+usbd_hid
+===============