update doc

6 files changed, 463 insertions, 11 deletions

diff --git a/docs/source/api/api_config.rst b/docs/source/api/api_config.rst
new file mode 100644
index 00000000..d7754fd0
--- /dev/null
+++ b/docs/source/api/api_config.rst
@@ -0,0 +1,116 @@
+USB CONFIG 宏
+=========================
+
+
+设备相关 CONFIG  宏
+---------------------
+
+.. code-block:: C
+
+    /* USB DEVICE Configuration */
+    /* core */
+    #ifndef CONFIG_USBDEV_REQUEST_BUFFER_LEN
+    #define CONFIG_USBDEV_REQUEST_BUFFER_LEN 256
+    #endif
+
+    #ifndef CONFIG_USBDEV_DESC_CHECK
+    #define CONFIG_USBDEV_DESC_CHECK 0
+    #endif
+
+    #ifndef CONFIG_USBDEV_TEST_MODE
+    #define CONFIG_USBDEV_TEST_MODE 0
+    #endif
+
+    /* msc class */
+    #ifndef CONFIG_USBDEV_MSC_MANUFACTURER_STRING
+    #define CONFIG_USBDEV_MSC_MANUFACTURER_STRING ""
+    #endif
+
+    #ifndef CONFIG_USBDEV_MSC_PRODUCT_STRING
+    #define CONFIG_USBDEV_MSC_PRODUCT_STRING ""
+    #endif
+
+    #ifndef CONFIG_USBDEV_MSC_VERSION_STRING
+    #define CONFIG_USBDEV_MSC_VERSION_STRING "0.01"
+    #endif
+
+    /* audio class */
+    #ifndef CONFIG_USBDEV_AUDIO_VERSION
+    #define CONFIG_USBDEV_AUDIO_VERSION 0x0100
+    #endif
+
+    #ifndef CONFIG_USBDEV_AUDIO_MAX_CHANNEL
+    #define CONFIG_USBDEV_AUDIO_MAX_CHANNEL 2
+    #endif
+
+
+主机相关 CONFIG  宏
+---------------------
+
+.. code-block:: C
+
+    /* USB HOST Configuration */
+    #ifndef CONFIG_USBHOST_RHPORTS
+    #define CONFIG_USBHOST_RHPORTS 1
+    #endif
+
+    #ifndef CONFIG_USBHOST_EHPORTS
+    #define CONFIG_USBHOST_EHPORTS 4
+    #endif
+
+    #ifndef CONFIG_USBHOST_PIPE_NUM
+    #define CONFIG_USBHOST_PIPE_NUM 10
+    #endif
+
+    #ifndef CONFIG_USBHOST_INTF_NUM
+    #define CONFIG_USBHOST_INTF_NUM 6
+    #endif
+
+    #ifndef CONFIG_USBHOST_EP_NUM
+    #define CONFIG_USBHOST_EP_NUM 4
+    #endif
+
+    #ifndef CONFIG_USBHOST_CONTROL_TRANSFER_TIMEOUT
+    #define CONFIG_USBHOST_CONTROL_TRANSFER_TIMEOUT 5000
+    #endif
+
+    #ifndef CONFIG_USBHOST_MSC_TIMEOUT
+    #define CONFIG_USBHOST_MSC_TIMEOUT 5000
+    #endif
+
+    #ifndef CONFIG_USBHOST_HPWORKQ_PRIO
+    #define CONFIG_USBHOST_HPWORKQ_PRIO 5
+    #endif
+    #ifndef CONFIG_USBHOST_HPWORKQ_STACKSIZE
+    #define CONFIG_USBHOST_HPWORKQ_STACKSIZE 2048
+    #endif
+
+    #ifndef CONFIG_USBHOST_LPWORKQ_PRIO
+    #define CONFIG_USBHOST_LPWORKQ_PRIO 1
+    #endif
+    #ifndef CONFIG_USBHOST_LPWORKQ_STACKSIZE
+    #define CONFIG_USBHOST_LPWORKQ_STACKSIZE 2048
+    #endif
+
+    #ifndef CONFIG_USBHOST_PSC_PRIO
+    #define CONFIG_USBHOST_PSC_PRIO 4
+    #endif
+    #ifndef CONFIG_USBHOST_PSC_STACKSIZE
+    #define CONFIG_USBHOST_PSC_STACKSIZE 4096
+    #endif
+
+    #ifndef CONFIG_USBHOST_DEV_NAMELEN
+    #define CONFIG_USBHOST_DEV_NAMELEN 16
+    #endif
+
+    #define CONFIG_USBHOST_ASYNCH
+    //#define CONFIG_USBHOST_GET_STRING_DESC
+
+    /* EHCI Configuration */
+    #define CONFIG_USB_EHCI_HCCR_BASE (0x20072000)
+    #define CONFIG_USB_EHCI_HCOR_BASE (0x20072000 + 0x10)
+    #define CONFIG_USB_EHCI_QH_NUM    (10)
+    #define CONFIG_USB_EHCI_QTD_NUM   (10)
+    // #define CONFIG_USB_EHCI_INFO_ENABLE
+    #define CONFIG_USB_ECHI_HCOR_RESERVED_DISABLE
+    // #define CONFIG_USB_EHCI_CONFIGFLAG
\ No newline at end of file
diff --git a/docs/source/api/api_device.rst b/docs/source/api/api_device.rst
index ea243edc..42830f6c 100644
--- a/docs/source/api/api_device.rst
+++ b/docs/source/api/api_device.rst
@@ -260,8 +260,9 @@ usbd_cdc_acm_set_line_coding
 
 .. code-block:: C
 
-    void usbd_cdc_acm_set_line_coding(uint32_t baudrate, uint8_t databits, uint8_t parity, uint8_t stopbits);
+    void usbd_cdc_acm_set_line_coding(uint8_t intf, uint32_t baudrate, uint8_t databits, uint8_t parity, uint8_t stopbits);
 
+- **intf** 控制接口号
 - **baudrate** 波特率
 - **databits**  数据位
 - **parity**  校验位
@@ -274,8 +275,9 @@ usbd_cdc_acm_set_dtr
 
 .. code-block:: C
 
-    void usbd_cdc_acm_set_dtr(bool dtr);
+    void usbd_cdc_acm_set_dtr(uint8_t intf, bool dtr);
 
+- **intf** 控制接口号
 - **dtr** dtr 为1表示拉低电平，为0表示拉高电平
 
 usbd_cdc_acm_set_rts
@@ -285,8 +287,9 @@ usbd_cdc_acm_set_rts
 
 .. code-block:: C
 
-    void usbd_cdc_acm_set_rts(bool rts);
+    void usbd_cdc_acm_set_rts(uint8_t intf, bool rts);
 
+- **intf** 控制接口号
 - **rts** rts 为1表示拉低电平，为0表示拉高电平
 
 CDC_ACM_DESCRIPTOR_INIT
@@ -597,5 +600,8 @@ usbd_video_mjpeg_payload_fill
 DFU
 -----------------
 
-PORTING
+PRINTER
+-----------------
+
+MTP
 -----------------
\ No newline at end of file
diff --git a/docs/source/api/api_host.rst b/docs/source/api/api_host.rst
index fdee2c18..92c42d00 100644
--- a/docs/source/api/api_host.rst
+++ b/docs/source/api/api_host.rst
@@ -1,6 +1,11 @@
 主机协议栈
 =========================
 
+关于主机协议栈中结构体的命名、分类、成员组成，参考下面这两张图：
+
+.. figure:: img/api_host1.png
+.. figure:: img/api_host2.png
+
 CORE
 -----------------
 
@@ -94,7 +99,7 @@ hub 结构体
 usbh_event_notify_handler
 """"""""""""""""""""""""""""""""""""
 
-``usbh_event_notify_handler`` 是 USB 中断中的核心，用于处理不同的中断标志。包括复位、端点0 IN/OUT/SETUP、其他端点 IN/OUT 、SUSPEND、RESUME、SOF 中断等等。用于需要在 porting 接口中的 USB中断中调用该接口。
+``usbh_event_notify_handler`` 是 USB 中断中的核心，主要用于处理 **设备连接** 和 **设备断开** 中断，从而唤醒线程去执行枚举。
 
 .. code-block:: C
 
@@ -115,7 +120,7 @@ usbh_event_notify_handler
 usbh_initialize
 """"""""""""""""""""""""""""""""""""
 
-``usbh_initialize`` 用来初始化 usb 主机协议栈，包括：创建插拔检测用的信号量和枚举线程、高低工作队列、初始化 roothub端点0 配置，初始化 usb 主机控制器。
+``usbh_initialize`` 用来初始化 usb 主机协议栈，包括：创建插拔检测用的信号量和枚举线程、高低工作队列、初始化 roothub 端点0 配置，初始化 usb 主机控制器。
 
 .. code-block:: C
 
@@ -151,11 +156,8 @@ HID
 MSC
 -----------------
 
-UAC
------------------
-
-UVC
+RNDIS
 -----------------
 
-PORTING
+PRINTER
 -----------------
\ No newline at end of file
diff --git a/docs/source/api/api_port.rst b/docs/source/api/api_port.rst
new file mode 100644
index 00000000..294b0eb2
--- /dev/null
+++ b/docs/source/api/api_port.rst
@@ -0,0 +1,328 @@
+Porting
+=========================
+
+device controller(dcd)
+-------------------------
+
+usb_dc_init
+""""""""""""""""""""""""""""""""""""
+
+``usb_dc_init`` 用于初始化 usb device controller 寄存器，设置 usb 引脚、时钟、中断等等。 **此函数不对用户开放**。
+
+.. code-block:: C
+
+    int usb_dc_init(void);
+
+- **return**
+
+usb_dc_deinit
+""""""""""""""""""""""""""""""""""""
+
+``usb_dc_deinit`` 用于反初始化 usb device controller 寄存器。 **此函数不对用户开放**。
+
+.. code-block:: C
+
+    int usb_dc_deinit(void);
+
+- **return**
+
+usb_dc_attach
+""""""""""""""""""""""""""""""""""""
+
+``usb_dc_attach`` 使能上拉或者下拉电阻，从而能够让设备被主机枚举。 **此函数对用户开放**。
+
+.. code-block:: C
+
+    int usb_dc_attach(void);
+
+- **return**
+
+usb_dc_detach
+""""""""""""""""""""""""""""""""""""
+
+``usb_dc_detach``断开设备与主机的连接。 **此函数对用户开放**。
+
+.. code-block:: C
+
+    int usb_dc_detach(void);
+
+- **return**
+
+usbd_set_address
+""""""""""""""""""""""""""""""""""""
+
+``usbd_set_address`` 设置设备地址。 **此函数不对用户开放**。
+
+.. code-block:: C
+
+    int usbd_set_address(const uint8_t addr);
+
+- **return**
+
+usbd_ep_open
+""""""""""""""""""""""""""""""""""""
+
+``usbd_ep_open`` 设置端点的属性，开启对应端点的中断。 **此函数不对用户开放**。
+
+.. code-block:: C
+
+    int usbd_ep_open(const struct usbd_endpoint_cfg *ep_cfg);
+
+- **return**
+
+usbd_ep_close
+""""""""""""""""""""""""""""""""""""
+
+``usbd_ep_close`` 关闭端点。 **此函数不对用户开放**。
+
+.. code-block:: C
+
+    int usbd_ep_close(const uint8_t ep);
+
+- **event**
+
+usbd_ep_set_stall
+""""""""""""""""""""""""""""""""""""
+
+``usbd_ep_set_stall`` 将端点设置成 stall 状态并发送 stall 握手包。 **此函数对用户开放**。
+
+.. code-block:: C
+
+    int usbd_ep_set_stall(const uint8_t ep);
+
+- **ep** 端点地址
+
+usbd_ep_clear_stall
+""""""""""""""""""""""""""""""""""""
+
+``usbd_ep_clear_stall`` 清除端点的 stall 状态。 **此函数不对用户开放**。
+
+.. code-block:: C
+
+    int usbd_ep_clear_stall(const uint8_t ep);
+
+- **ep** 端点地址
+
+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_write
+""""""""""""""""""""""""""""""""""""
+
+``usbd_ep_write`` 向某个端点发送数据， **如果该函数在中断中使用则是异步传输，否则是阻塞传输**。 **此函数对用户开放**。
+
+.. code-block:: C
+
+    int usbd_ep_write(const uint8_t ep, const uint8_t *data, uint32_t data_len, uint32_t *ret_bytes);
+
+- **ep** in 端点地址
+- **data** 要发送的数据缓冲区
+- **data_len** 发送长度，需要小于等于端点最大包长
+- **ret_bytes** 实际发送的长度，异步传输该参数无效。 **如果长度为 0，表示发送 0 长数据包（zero length packet）**
+- **return** 返回 0 表示正确，其他表示错误
+
+usbd_ep_read
+""""""""""""""""""""""""""""""""""""
+
+``usbd_ep_read`` 从某个端点接收数据， **该函数仅能在 usb out 中断中使用**。 **此函数对用户开放**。
+
+.. code-block:: C
+
+    int usbd_ep_read(const uint8_t ep, uint8_t *data, uint32_t max_data_len, uint32_t *read_bytes);
+
+- **ep** out 端点地址
+- **data** 要接收的数据缓冲区
+- **data_len** 接收长度，需要小于等于端点最大包长，推荐直接设置成最大包长。 **如果长度为 0 表示启动下次接收**
+- **ret_bytes** 实际接收的长度
+- **return** 返回 0 表示正确，其他表示错误
+
+host controller(hcd)
+------------------------
+
+usb_hc_init
+""""""""""""""""""""""""""""""""""""
+
+``usb_hc_init`` 用于初始化 usb host controller 寄存器，设置 usb 引脚、时钟、中断等等。 **此函数不对用户开放**。
+
+.. code-block:: C
+
+    int usb_hc_init(void);
+
+- **return** 返回 0 表示正确，其他表示错误
+
+usbh_get_port_connect_status
+""""""""""""""""""""""""""""""""""""
+
+``usbh_get_port_connect_status`` 获取当前 hubport 连接状态。 **此函数不对用户开放**。
+
+.. code-block:: C
+
+    int usbh_get_port_connect_status(const uint8_t port);
+
+- **port** 端口号
+- **return** 返回 1 表示连接，0 表示未连接
+
+usbh_reset_port
+""""""""""""""""""""""""""""""""""""
+
+``usbh_reset_port`` 复位指定的 hubport **此函数不对用户开放**。
+
+.. code-block:: C
+
+    int usbh_reset_port(const uint8_t port);
+
+- **port** 端口号
+- **return** 返回 0 表示正确，其他表示错误
+
+usbh_get_port_speed
+""""""""""""""""""""""""""""""""""""
+
+``usbh_get_port_speed`` 获取当前 hubport 上连接的设备速度。 **此函数不对用户开放**。
+
+.. code-block:: C
+
+    int usbh_get_port_speed(const uint8_t port);
+
+- **port** 端口号
+- **return** 返回 1 表示低速，2 表示全速，3 表示高速
+
+usbh_ep0_reconfigure
+""""""""""""""""""""""""""""""""""""
+
+``usbh_ep0_reconfigure`` 重新设置端点 0 的属性。 **此函数不对用户开放**。
+
+.. code-block:: C
+
+    int usbh_ep0_reconfigure(usbh_epinfo_t ep, uint8_t dev_addr, uint8_t ep_mps, uint8_t speed);
+
+- **ep** 端点信息
+- **dev_addr** 端点所在设备地址
+- **ep_mps** 端点最大包长
+- **speed** 端点所在设备的速度
+- **return** 返回 0 表示正确，其他表示错误
+
+usbh_ep_alloc
+""""""""""""""""""""""""""""""""""""
+
+``usbh_ep_alloc`` 为端点分配相关属性，初始化相关寄存器，并保存相关信息到 **ep** 句柄中。 **此函数不对用户开放**。
+
+.. code-block:: C
+
+    int usbh_ep_alloc(usbh_epinfo_t *ep, const struct usbh_endpoint_cfg *ep_cfg);
+
+- **ep** 端点信息
+- **ep_cfg** 端点初始化需要的一些信息
+- **return** 返回 0 表示正确，其他表示错误
+
+usbh_ep_free
+""""""""""""""""""""""""""""""""""""
+
+``usbh_ep_free`` 释放端点的一些属性。 **此函数不对用户开放**。
+
+.. code-block:: C
+
+    int usbh_ep_free(usbh_epinfo_t ep);
+
+- **ep** 端点信息
+- **return** 返回 0 表示正确，其他表示错误
+
+usbh_control_transfer
+""""""""""""""""""""""""""""""""""""
+
+``usbh_control_transfer`` 对端点 0 进行控制传输，并且 **此函数为阻塞式传输，默认超时时间 5s**。 **此函数对用户开放**。
+
+.. code-block:: C
+
+    int usbh_control_transfer(usbh_epinfo_t ep, struct usb_setup_packet *setup, uint8_t *buffer);
+
+- **ep** 端点信息
+- **setup** setup 包
+- **buffer** 要发送或者读取的数据缓冲区，为 NULL 表示没有数据要发送或者接收
+- **return** 返回 0 表示正确，其他表示错误
+
+usbh_ep_bulk_transfer
+""""""""""""""""""""""""""""""""""""
+
+``usbh_ep_bulk_transfer`` 对指定端点进行批量传输， **此函数为阻塞式传输**。 **此函数对用户开放**。
+
+.. code-block:: C
+
+    int usbh_ep_bulk_transfer(usbh_epinfo_t ep, uint8_t *buffer, uint32_t buflen, uint32_t timeout);
+
+- **ep** 端点信息
+- **buffer** 要发送或者读取的数据缓冲区
+- **buflen** 要发送或者接收的长度，最大不得高于 16K
+- **timeout** 超时时间，单位 ms
+- **return** 大于等于0 表示实际发送或者接收的长度，小于 0 表示错误
+
+其中小于 0 的错误码如下：
+
+.. list-table::
+    :widths: 30 30
+    :header-rows: 1
+
+    * - ERROR CODE
+      - desc
+    * - ENODEV
+      - 设备未连接
+    * - EBUSY
+      - 当前数据发送或者接收还未完成
+    * - EAGAIN
+      - 主机一直收到 NAK 包
+    * - ETIMEDOUT
+      - 数据发送或者接收超时
+    * - EPERM
+      - 主机收到 STALL 包
+    * - EIO
+      - 数据传输错误
+    * - EPIPE
+      - 数据溢出
+    * - ENXIO
+      - 设备断开，传输中止
+
+usbh_ep_intr_transfer
+""""""""""""""""""""""""""""""""""""
+
+``usbh_ep_intr_transfer`` 同上。
+
+usbh_ep_bulk_async_transfer
+""""""""""""""""""""""""""""""""""""
+
+``usbh_ep_bulk_async_transfer`` 对指定端点进行批量传输，传输完成将触发指定回调函数， **此函数为异步传输**。 **此函数对用户开放**。
+
+.. code-block:: C
+
+    int usbh_ep_bulk_async_transfer(usbh_epinfo_t ep, uint8_t *buffer, uint32_t buflen, usbh_asynch_callback_t callback, void *arg);
+
+- **ep** 端点信息
+- **buffer** 要发送或者读取的数据缓冲区
+- **buflen** 要发送或者接收的长度，最大不得高于 16K
+- **callback** 传输完成回调函数， **该函数最终处于中断上下文**
+- **arg** 用户自定义参数
+- **return** 为 0 表示配置正常，小于0 表示错误
+
+usbh_ep_intr_async_transfer
+""""""""""""""""""""""""""""""""""""
+
+``usbh_ep_intr_async_transfer`` 同上。
+
+usb_ep_cancel
+""""""""""""""""""""""""""""""""""""
+
+``usb_ep_cancel`` 中止当前端点传输， **此函数不对用户开放**。
+
+.. code-block:: C
+
+    int usb_ep_cancel(usbh_epinfo_t ep);
+
+- **ep** 端点信息
+- **return** 为 0 表示正确，小于0 表示错误
diff --git a/docs/source/api/img/api_host1.png b/docs/source/api/img/api_host1.png
new file mode 100644
index 00000000..82932f50
--- /dev/null
+++ b/docs/source/api/img/api_host1.png
diff --git a/docs/source/api/img/api_host2.png b/docs/source/api/img/api_host2.png
new file mode 100644
index 00000000..7f6d60b8
--- /dev/null
+++ b/docs/source/api/img/api_host2.png