update rst

5 files changed, 180 insertions, 36 deletions

diff --git a/docs/source/api/api_common.rst b/docs/source/api/api_common.rst
index 6f743643..3c4653d9 100644
--- a/docs/source/api/api_common.rst
+++ b/docs/source/api/api_common.rst
@@ -1,2 +1,48 @@
 其他
 =========================
+
+usb_malloc
+""""""""""""""""""""""""""""""""""""
+
+``usb_malloc``  用来申请内存。
+
+.. code-block:: C
+
+    void *usb_malloc(size_t size);
+
+- **size** 要申请的内存大小
+- **return** 申请的内存地址
+
+usb_free
+""""""""""""""""""""""""""""""""""""
+
+``usb_free``  用来释放申请的内存。
+
+.. code-block:: C
+
+    void usb_free(void *ptr);
+
+- **ptr** 要释放的内存地址
+
+usb_iomalloc
+""""""""""""""""""""""""""""""""""""
+
+``usb_iomalloc``  用来申请内存，并按照 `CONFIG_DCACHE_LINE_SIZE` 对齐，一般使用到 dcache 和 dma 需要对齐操作的时候使用。
+
+.. code-block:: C
+
+    void *usb_iomalloc(size_t size);
+
+- **size** 要申请的内存大小
+- **return** 申请的内存地址
+
+usb_iofree
+""""""""""""""""""""""""""""""""""""
+
+``usb_iofree``  用来释放申请的内存。
+
+.. code-block:: C
+
+    void usb_iofree(void *ptr);
+
+- **ptr** 要释放的内存地址
diff --git a/docs/source/api/api_device.rst b/docs/source/api/api_device.rst
index 4e3fbad2..60d1d888 100644
--- a/docs/source/api/api_device.rst
+++ b/docs/source/api/api_device.rst
@@ -289,6 +289,21 @@ usbd_cdc_acm_set_rts
 
 - **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
 -----------------
 
@@ -421,6 +436,40 @@ usbd_audio_add_interface
 - **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
 """"""""""""""""""""""""""""""""""""
 
@@ -428,9 +477,10 @@ usbd_audio_set_mute
 
 .. code-block:: C
 
-    void usbd_audio_set_mute(uint8_t mute);
+    void usbd_audio_set_mute(uint8_t ch, uint8_t enable);
 
-- **mute** 为1 表示静音，0相反
+- **ch** 要设置静音的通道
+- **enable** 为1 表示静音，0相反
 
 usbd_audio_set_volume
 """"""""""""""""""""""""""""""""""""
@@ -439,31 +489,45 @@ usbd_audio_set_volume
 
 .. code-block:: C
 
-    void usbd_audio_set_volume(uint8_t vol);
+    void usbd_audio_set_volume(uint8_t ch, float dB);
 
-- **vol** 音量，从 0-100
+- **ch** 要设置音量的通道
+- **dB** 要设置音量的分贝，其中 UAC1.0范围从 -127 ~ +127dB，UAC2.0 从 0 ~ 256dB
 
-usbd_audio_open
+usbd_audio_set_sampling_freq
 """"""""""""""""""""""""""""""""""""
 
-``usbd_audio_open``  用来开启音频数据传输。
+``usbd_audio_set_sampling_freq``  用来设置设备上音频模块的采样率
 
 .. code-block:: C
 
-    void usbd_audio_open(uint8_t intf);
+    void usbd_audio_set_sampling_freq(uint8_t ep_ch, uint32_t sampling_freq);
 
-- **intf** 开启的接口号
+- **ch** 要设置采样率的端点或者通道，UAC1.0为端点，UAC2.0 为通道
+- **dB** 要设置的采样率
 
-usbd_audio_close
+usbd_audio_get_sampling_freq_table
 """"""""""""""""""""""""""""""""""""
 
-``usbd_audio_close``  用来关闭音频数据传输。
+``usbd_audio_get_sampling_freq_table``  用来获取支持的采样率列表，如果函数没有实现，则使用默认采样率列表。
 
 .. code-block:: C
 
-    void usbd_audio_close(uint8_t intf);
+    void usbd_audio_get_sampling_freq_table(uint8_t **sampling_freq_table);
 
-- **intf** 关闭的接口号
+- **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
 -----------------
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 968d8ad1..469fefea 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -22,8 +22,8 @@ extensions = [
 ]
 
 intersphinx_mapping = {
-    'python': ('https://docs.python.org/3/', None),
-    'sphinx': ('https://www.sphinx-doc.org/en/master/', None),
+#    'python': ('https://docs.python.org/3/', None),
+#    'sphinx': ('https://www.sphinx-doc.org/en/master/', None),
 }
 intersphinx_disabled_domains = ['std']
 
diff --git a/docs/source/demo/usb2uart.rst b/docs/source/demo/usb2uart.rst
index f02bd0c4..b57b79b1 100644
--- a/docs/source/demo/usb2uart.rst
+++ b/docs/source/demo/usb2uart.rst
@@ -7,7 +7,7 @@ USB转串口即实现计算机USB接口到通用串口之间的转换。为没�
 - 有 UART 外设
 - 有 USB DEVICE 外设
 
-接下来，我们就可以愉快的进行代码的编写了。USB 转串口我们采用的是 CDC ACM 类。
+接下来，我们就可以愉快的进行代码的编写了。USB 转串口我们采用的是 CDC ACM 类。第一步我们先让 USB 能正常收发。
 
 - 首先是实现 `usbd_cdc_acm_set_line_coding` 函数，这个函数的作用就是当我们点击电脑上的串口软件设置串口相关信息时（如下图所示），主机会通过 USB 发送设置串口的命令给设备，对设备上的串口进行配置，所以这边我们需要根据形参来配置串口。
 
@@ -98,7 +98,7 @@ USB转串口即实现计算机USB接口到通用串口之间的转换。为没�
 
 .. caution:: 注意数组最后的结束符，不要遗漏
 
-- cdc acm 一共需要两个接口，一个控制接口，一个数据接口，由于我们只有一个 cdc acm，所以只需要注册一个 class + 两个接口。其中控制接口需要一个中断端点，数据接口需要两个中断端点，由于接口驱动我们已经支持，所以调用 cdc acm 相关的添加接口的 API 即可。那么代码就如下：
+- cdc acm 一共需要两个接口，一个控制接口，一个数据接口，由于我们只有一个 cdc acm，所以只需要注册一个 class + 两个接口。其中控制接口需要一个中断端点，数据接口需要两个 bulk 端点，由于接口驱动我们已经支持，所以调用 cdc acm 相关的添加接口的 API 即可。代码如下：
 
 .. code-block:: C
 
@@ -109,6 +109,31 @@ USB转串口即实现计算机USB接口到通用串口之间的转换。为没�
     /*!< interface two */
     usbd_interface_t cdc_data_intf;
 
+    /*!< endpoint call back */
+    usbd_endpoint_t cdc_out_ep = {
+        .ep_addr = CDC_OUT_EP,
+        .ep_cb = usbd_cdc_acm_out
+    };
+
+    usbd_endpoint_t cdc_in_ep = {
+        .ep_addr = CDC_IN_EP,
+        .ep_cb = usbd_cdc_acm_in
+    };
+
+    usbd_desc_register(cdc_descriptor);
+    /*!< add interface */
+    usbd_cdc_add_acm_interface(&cdc_class, &cdc_cmd_intf);
+    usbd_cdc_add_acm_interface(&cdc_class, &cdc_data_intf);
+    /*!< interface add endpoint */
+    usbd_interface_add_endpoint(&cdc_data_intf, &cdc_out_ep);
+    usbd_interface_add_endpoint(&cdc_data_intf, &cdc_in_ep);
+
+    usbd_initialize();
+
+- 最后调用 `usbd_initialize` 初始化 usb。
+
+.. code-block:: C
+
     /* function ------------------------------------------------------------------*/
     void usbd_cdc_acm_out(uint8_t ep)
     {
@@ -129,32 +154,35 @@ USB转串口即实现计算机USB接口到通用串口之间的转换。为没�
         printf("in\r\n");
     }
 
-    /*!< endpoint call back */
-    usbd_endpoint_t cdc_out_ep = {
-        .ep_addr = CDC_OUT_EP,
-        .ep_cb = usbd_cdc_acm_out
-    };
+    volatile uint8_t dtr_enable = 0;
 
-    usbd_endpoint_t cdc_in_ep = {
-        .ep_addr = CDC_IN_EP,
-        .ep_cb = usbd_cdc_acm_in
-    };
+    void usbd_cdc_acm_set_dtr(bool dtr)
+    {
+        if (dtr) {
+            dtr_enable = 1;
+        } else {
+            dtr_enable = 0;
+        }
+    }
 
-    usbd_desc_register(cdc_descriptor);
-    /*!< add interface */
-    usbd_cdc_add_acm_interface(&cdc_class, &cdc_cmd_intf);
-    usbd_cdc_add_acm_interface(&cdc_class, &cdc_data_intf);
-    /*!< interface add endpoint */
-    usbd_interface_add_endpoint(&cdc_data_intf, &cdc_out_ep);
-    usbd_interface_add_endpoint(&cdc_data_intf, &cdc_in_ep);
+    void cdc_acm_data_send_with_dtr_test(void)
+    {
+        if (dtr_enable) {
+            uint8_t data_buffer[10] = { 0x31, 0x32, 0x33, 0x34, 0x35, 0x31, 0x32, 0x33, 0x34, 0x35 };
+            usbd_ep_write(CDC_IN_EP, data_buffer, 10, NULL);
+        }
+    }
+
+-  out 中断中我们将接收的数据进行打印，in 中断则是当 `usbd_ep_write` 发送完成后，进行打印
+- 实现 `usbd_cdc_acm_set_dtr` 进行流控
 
 .. caution:: 注意端点接收中断中，接收 buf 的大小根据全速和高速来定，并且尽量不要在中断中开辟这么大的 buf
 
-- 最后调用 `usbd_initialize` 初始化 usb。
-- 此时，插上电脑可以枚举出一个 USB 设备，名称为 **USB 串行设备（COMx）**，然后我们可以打开枚举的串口，发一些数据，然后看调试口是否有数据，有的话，证明 USB 方面是通的。
+
+- 此时，插上电脑可以枚举出一个 USB 设备，名称为 **USB 串行设备（COMx）**，然后我们可以打开枚举的串口，发一些数据，然后看调试口是否有数据，有的话，证明 USB 方面是通的，那上面测试的一些代码就可以删删了。
 
 
-上面完成后，接下来就是跟 UART 配合使用了，那怎么完成最终的 USB 转串口呢？首先我们需要梳理一下，整个的数据传输。
+上面完成后，第二步，则是跟 UART 配合使用了，那怎么完成最终的 USB 转串口呢？首先我们需要梳理一下，整个的数据传输。
 
 - 首先是 USB 发数据给设备，设备接收到数据以后，通过 UART TX 发送出去
 - 其次是 UART RX 接收的数据，通过 USB 发送给主机
@@ -165,4 +193,6 @@ USB转串口即实现计算机USB接口到通用串口之间的转换。为没�
 - 初始化 Ringbuffer A 和 Ringbuffer B
 - USB out 中断中读取数据并存入 Ringbuffer A 中
 - while（1） 中从 Ringbuffer A 中读取数据，并使用 UART 发送函数发出去
-- UART RX 中断中接收数据，并存入 Ringbuffer B 中，while（1）中从 Ringbuffer B 中读取数据，并使用 USB 发送函数发出去
\ No newline at end of file
+- UART RX 中断中接收数据，并存入 Ringbuffer B 中，while（1）中从 Ringbuffer B 中读取数据，并使用 USB 发送函数发出去
+
+代码参考 ：https://github.com/bouffalolab/bl_mcu_sdk/tree/master/examples/usb/usb2uart
\ No newline at end of file
diff --git a/docs/source/index.rst b/docs/source/index.rst
index d55745a1..66670705 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -8,6 +8,10 @@ CherryUSB 使用指南
 
 CherryUSB 是一个小而美的、可移植性高的、用于嵌入式系统的 USB 主从协议栈。
 
+- 从机协议栈视频教程：https://www.bilibili.com/video/BV1Ef4y1t73d
+- 主机协议栈视频教程：TODO
+- github ：https://github.com/sakumisu/CherryUSB
+
 .. toctree::
    :maxdepth: 1
    :caption: 快速上手