docs: update demo

Signed-off-by: sakumisu <[email protected]>

5 files changed, 149 insertions, 7 deletions

diff --git a/docs/zh/api/api_host.rst b/docs/zh/api/api_host.rst
index 46d1e428..ad93d2fb 100644
--- a/docs/zh/api/api_host.rst
+++ b/docs/zh/api/api_host.rst
@@ -214,7 +214,7 @@ usbh_serial_write
 usbh_serial_read
 """"""""""""""""""""""""""""""""""""
 
-``usbh_serial_read`` 从串口读数据。 **如果没有设置波特率，不允许使用该 API，设置波特率后，内部会开启 rx 接收并将数据写入 ringbuf **。
+``usbh_serial_read`` 从串口读数据。  **如果没有设置波特率，不允许使用该 API，设置波特率后，内部会开启 rx 接收并将数据写入 ringbuf**。
 
 .. code-block:: C
 
diff --git a/docs/zh/demo/usb_otg.rst b/docs/zh/demo/usb_otg.rst
index 5cb371c6..bdc92886 100644
--- a/docs/zh/demo/usb_otg.rst
+++ b/docs/zh/demo/usb_otg.rst
@@ -1,7 +1,7 @@
 USB OTG
 =================
 
-如果需要使用 OTG 功能，首先使用的芯片需要支持 ID 检测功能，然后使能 ``CONFIG_USB_OTG_ENABLE`` 宏，将之前的例程中 ``usbh_initialize`` 或者 ``usbh_initialize``
+如果需要使用 OTG 功能，首先使用的芯片需要支持 ID 检测功能，然后使能 ``CONFIG_USB_OTG_ENABLE`` 宏，将之前的例程中 ``usbd_initialize`` 或者 ``usbh_initialize``
 替换成 ``usbotg_initialize`` 即可。
 
 ID 检测电路根据不同的 USB 接口类型有所不同，常见的有 micro-USB 和 USB-C 两种接口类型。
diff --git a/docs/zh/demo/usbh_audio.rst b/docs/zh/demo/usbh_audio.rst
index 18933801..4cde7e6b 100644
--- a/docs/zh/demo/usbh_audio.rst
+++ b/docs/zh/demo/usbh_audio.rst
@@ -1,4 +1,89 @@
 Audio Host
 =================
 
-.. note:: Host UAC 为商用收费，请联系官方购买授权。
\ No newline at end of file
+.. note:: Host UAC 框架和 ISO 驱动为商用收费，请联系官方购买授权。
+
+
+MIC 使用流程
+--------------
+
+- 注册 frame 内存池, AUDIO_MIC_EP_MAX_MPS 可以改成实际能支持的最大 iso ep_in_mps 以减少 RAM 消耗。 **一个 frame 收到的数据大小范围为 0 ~ x * AUDIO_MIC_ISO_PACKETS**。x 为实际 iso ep_in_mps。
+
+.. code-block:: C
+
+    #define AUDIP_MIC_POOL_SIZE (10)
+    static USB_MEM_ALIGNX uint8_t frame_mic_buffer[AUDIO_MIC_EP_MAX_MPS * AUDIO_MIC_ISO_PACKETS * AUDIP_MIC_POOL_SIZE];
+    static struct usbh_audioframe frame_mic_pool[AUDIP_MIC_POOL_SIZE];
+
+    for (uint8_t i = 0; i < AUDIP_MIC_POOL_SIZE; i++) {
+        frame_mic_pool[i].frame_buf = frame_mic_buffer + i * AUDIO_MIC_EP_MAX_MPS * AUDIO_MIC_ISO_PACKETS;
+        frame_mic_pool[i].frame_bufsize = AUDIO_MIC_EP_MAX_MPS * AUDIO_MIC_ISO_PACKETS;
+    }
+
+    usbh_audio_mic_stream_create(frame_mic_pool, AUDIP_MIC_POOL_SIZE);
+
+- 开启 MIC 数据接收线程并处理，处理完成后需要将 frame 重新入队。
+
+.. code-block:: C
+
+    static void usbh_audio_mic_frame_thread(void *argument)
+    {
+        int ret;
+        struct usbh_audioframe *frame;
+
+        while (1) {
+            ret = usbh_audio_mic_stream_dequeue(&frame, 0xfffffff);
+            if (ret < 0) {
+                continue;
+            }
+
+            USB_LOG_RAW("frame buf:%p,frame len:%d\r\n", frame->frame_buf, frame->frame_size);
+
+            usbh_audio_mic_stream_enqueue(frame);
+        }
+    }
+
+- 调用 `usbh_audio_mic_stream_start` 启动 MIC 流，调用 `usbh_audio_mic_stream_stop` 停止 MIC 流。
+
+SPEAKER 使用流程
+------------------
+
+- 注册 frame 内存池, AUDIO_SPEAKER_EP_MAX_MPS 可以改成实际能支持的最大 iso ep_out_mps 以减少 RAM 消耗。一个 frame 必须按照 ep_out_mps * AUDIO_SPEAKER_ISO_PACKETS 的大小来填充数据。
+
+.. code-block:: C
+
+    #define AUDIO_SPEAKER_POOL_SIZE (10)
+    static USB_MEM_ALIGNX uint8_t frame_speaker_buffer[AUDIO_SPEAKER_EP_MAX_MPS * AUDIO_SPEAKER_ISO_PACKETS * AUDIO_SPEAKER_POOL_SIZE];
+    static struct usbh_audioframe frame_speaker_pool[AUDIO_SPEAKER_POOL_SIZE];
+
+    for (uint8_t i = 0; i < AUDIO_SPEAKER_POOL_SIZE; i++) {
+        frame_speaker_pool[i].frame_buf = frame_speaker_buffer + i * AUDIO_SPEAKER_EP_MAX_MPS * AUDIO_SPEAKER_ISO_PACKETS;
+        frame_speaker_pool[i].frame_bufsize = AUDIO_SPEAKER_EP_MAX_MPS * AUDIO_SPEAKER_ISO_PACKETS;
+    }
+
+    usbh_audio_speaker_stream_create(frame_speaker_pool, AUDIO_SPEAKER_POOL_SIZE);
+
+- 调用 `usbh_audio_speaker_stream_start` 启动 SPEAKER 流，调用 `usbh_audio_speaker_stream_stop` 停止 SPEAKER 流。
+- 调用 `usbh_uac_speaker_frame_alloc` 申请一个 frame，填充数据后调用 `usbh_uac_speaker_frame_send` 将数据入队。
+- 当前 speaker frame 的处理是在 `usbh_audio_speaker_stream_start` 启动以后的周期性中断中循环接收和发送，用户也可以改成使用线程来进行接收和发送。
+
+宏的说明
+-------------
+
+.. code-block:: C
+
+    #define AUDIO_MIC_ISO_PACKETS  (1)
+    #define AUDIO_MIC_EP_MAX_MPS   1024
+
+- AUDIO_MIC_ISO_PACKETS：每次传输的 ISO 个数，单位是 bInterval 计算出来的帧或者微针时间。例如 全速 bInterval 为1或者高速 bInterval 为4时表示 1ms传输一个包。
+- AUDIO_MIC_EP_MAX_MPS：音频输入端点最大包大小，单位为字节。
+
+.. code-block:: C
+
+    #define AUDIO_SPEAKER_ISO_PACKETS  (1)
+    #define AUDIO_SPEAKER_EP_MAX_MPS   1024
+
+- AUDIO_SPEAKER_ISO_PACKETS：每次传输的 ISO 个数，单位是 bInterval 计算出来的帧或者微针时间。例如 全速 bInterval 为1或者高速 bInterval 为4时表示 1ms传输一个包。
+- AUDIO_SPEAKER_EP_MAX_MPS：音频输出端点最大包大小，单位为字节。
+
+.. note:: 增大 AUDIO_MIC_ISO_PACKETS or AUDIO_SPEAKER_ISO_PACKETS 可以降低传输中断频率，但是会增加 RAM 的开销，需要目标 IP 支持 scatter-gather DMA 才有效果，对于 buffer dma 或者 fifo 模式的 IP 不会降低中断频率。
\ No newline at end of file
diff --git a/docs/zh/demo/usbh_video.rst b/docs/zh/demo/usbh_video.rst
index 7de4b457..d257aec4 100644
--- a/docs/zh/demo/usbh_video.rst
+++ b/docs/zh/demo/usbh_video.rst
@@ -1,4 +1,61 @@
 Video Host
 =================
 
-.. note:: Host UVC 为商用收费，请联系官方购买授权。
\ No newline at end of file
+.. note:: Host UVC 框架和 ISO 驱动为商用收费，请联系官方购买授权。
+
+使用流程
+------------
+
+- 注册 frame 内存池，通常设计为双buffer。
+
+.. code-block:: C
+
+    static uint8_t frame_buffer1[IMAGE_WIDTH * IMAGE_HEIGHT * 2];
+    static uint8_t frame_buffer2[IMAGE_WIDTH * IMAGE_HEIGHT * 2];
+    static struct usbh_videoframe frame_pool[2];
+
+    frame_pool[0].frame_buf = frame_buffer1;
+    frame_pool[0].frame_bufsize = IMAGE_WIDTH * IMAGE_HEIGHT * 2;
+    frame_pool[1].frame_buf = frame_buffer2;
+    frame_pool[1].frame_bufsize = IMAGE_WIDTH * IMAGE_HEIGHT * 2;
+
+    usbh_video_stream_create(frame_pool, 2);
+
+- 创建 frame 接收线程并处理。frame->frame_format 指示当前帧的格式，frame->frame_buf 指向帧数据，frame->frame_size 指示帧数据大小。处理完成后需要调用 usbh_video_stream_enqueue 将 frame 重新入队。
+
+.. code-block:: C
+
+    static void usbh_video_frame_thread(void *argument)
+    {
+        int ret;
+        struct usbh_videoframe *frame;
+
+        while (1) {
+            ret = usbh_video_stream_dequeue(&frame, 0xfffffff);
+            if (ret < 0) {
+                continue;
+            }
+
+            USB_LOG_RAW("frame buf:%p,frame len:%d\r\n", frame->frame_buf, frame->frame_size);
+
+            usbh_video_stream_enqueue(frame);
+        }
+    }
+
+    usb_osal_thread_create("uvc_frame", 3072, 5, usbh_video_frame_thread, NULL);
+
+- `usbh_video_fps_init` 函数辅助打印帧率
+- 调用 `usbh_video_stream_start` 启动视频流，调用 `usbh_video_stream_stop` 停止视频流。
+
+宏的说明
+-------------
+
+.. code-block:: C
+
+    #define VIDEO_ISO_PACKETS  (8 * 2)
+    #define VIDEO_EP_MAX_MPS   3072
+
+- VIDEO_ISO_PACKETS：每次传输的 ISO 个数。 **要求是 8 的倍数，对应高速设备（1ms 8个包），全速设备（8ms 8个包）**。 这里我们限定摄像头 bInterval 是 1，并且目前没有不是 1 的摄像头。
+- VIDEO_EP_MAX_MPS：视频流端点的最大包大小，单位为字节。 **如果 USB IP 能够支持到 3072字节，则支持市面上所有的摄像头，如果不支持，则只能支持部分摄像头或者需要定制摄像头**。对 BULK 摄像头没有要求。
+
+.. note:: 增大 VIDEO_ISO_PACKETS 可以降低传输中断频率，但是会增加 RAM 的开销，需要目标 IP 支持 scatter-gather DMA 才有效果，对于 buffer dma 或者 fifo 模式的 IP 不会降低中断频率。
\ No newline at end of file
diff --git a/docs/zh/quick_start/opensource.rst b/docs/zh/quick_start/opensource.rst
index 75697861..24ffc0bb 100644
--- a/docs/zh/quick_start/opensource.rst
+++ b/docs/zh/quick_start/opensource.rst
@@ -56,9 +56,6 @@
     * - phobia
       - rombrew
       - https://github.com/rombrew/phobia
-    * - FMT-Firmware
-      - Firmament-Autopilot
-      - https://github.com/Firmament-Autopilot/FMT-Firmware
     * - sdk-bsp-stm32h7r-realthread-artpi2
       - RT-Thread
       - https://github.com/RT-Thread-Studio/sdk-bsp-stm32h7r-realthread-artpi2
@@ -71,3 +68,6 @@
     * - f1c200s_library
       - lhdjply
       - https://gitee.com/lhdjply/f1c200s_library
+    * - MuseCube
+      - dydcyy-gh
+      - https://github.com/dydcyy-gh/MuseCube