docs(xrusb): add STM32/CH32 platform guides; enable Mermaid

Author: Jiu-xiao

docs/basic_coding/core/core-rw.md

@@ -185,10 +185,10 @@ public:
 };
 ```
 
-- **Stream(WritePort*, WriteOperation)**：构造时尝试锁定，锁定失败则回退为普通写入模式。
-- **~Stream()**：析构自动提交所有数据、释放锁。
-- **operator<<**：链式添加要写入的数据。
-- **Commit()**：立即将当前追加的数据全部写入队列并（如需要）释放锁，可用于分段 flush。
+- **`Stream(WritePort*, WriteOperation)`**：构造时尝试锁定，锁定失败则回退为普通写入模式。
+- **`~Stream()`**：析构自动提交所有数据、释放锁。
+- **`operator<<`**：链式添加要写入的数据。
+- **`Commit()`**：立即将当前追加的数据全部写入队列并（如需要）释放锁，可用于分段 flush。
 
 ---
 

docs/concept.md

@@ -8,7 +8,7 @@ sidebar_position: 2
 
 ## `无锁数据结构与 ISR 驱动的数据流`
 
-在 LibXR 中，所有 I/O 均建立在无锁队列与环形缓冲之上，运行期不依赖互斥锁或关中断的临界区，保证传输路径的确定性与时延可控。设备事件完全由硬件中断驱动，中断仅承担双缓冲切换与状态机切换等任务，不涉入额外逻辑，从而使数据流动严格受硬件节奏控制，不依赖操作系统调度。由此，LibXR 的 I/O 成为一条由中断推动的无锁流水线，具备轻量、实时的特性。
+所有 I/O 均应建立在无锁队列与环形缓冲之上，运行期不依赖互斥锁或关中断的临界区，保证传输路径的确定性与时延可控。设备事件完全由硬件中断驱动，中断仅承担双缓冲切换与状态机切换等任务，不涉入额外逻辑，从而使数据流动严格受硬件节奏控制，不依赖操作系统调度。由此，LibXR 的 I/O 成为一条由中断推动的无锁流水线，具备轻量、实时的特性。
 
 ## `嵌入式系统中，运行时的内存分配是设计缺陷`
 

docs/env_setup/ch32.md

@@ -8,7 +8,7 @@ sidebar_position: 2
 
 CH32的RISC-V工具链极其混乱，推荐使用的有如下两种：
 
-* [官方MRS自带的riscv-wch-elf](http://www.mounriver.com/download)： 支持WCH的rv32imafcxw拓展指令集，但是对C++标准实现有残缺，无法使用Eigen等C++库
+* ~~[官方MRS自带的riscv-wch-elf](http://www.mounriver.com/download)： 支持WCH的rv32imafcxw拓展指令集，但是对C++标准实现有残缺，无法使用Eigen等C++库~~
 * [上游riscv32-unknown-elf](https://github.com/riscv-collab/riscv-gnu-toolchain)：不支持WCH的拓展指令集，但是对C++标准实现完整，需要自行编译。Windows下需要使用MSYS2进行编译，过程较为繁琐。
 
 快速编译可以使用本项目提供的Docker镜像。

docs/env_setup/stm32.md

@@ -69,7 +69,7 @@ export CLANG_GCC_CMSIS_COMPILER=/opt/st-arm-clang
 
 编译时还要指定`-DCMAKE_TOOLCHAIN_FILE="cmake/gcc-arm-none-eabi.cmake"`或者`-DCMAKE_TOOLCHAIN_FILE="cmake/starm-clang.cmake"`来选择工具链。
 
-### 旧版CubeMX工程(<15.0)迁移到新版本编译问题
+### `旧版CubeMX工程(<15.0)迁移到新版本编译问题`
 
 如果提示链接不到库`ob`，则在工程根目录的`CMakeLists.txt`中添加:
 

docs/intro.md

@@ -8,4 +8,14 @@ sidebar_position: 1
 
 本文档会分块介绍LibXR, CodeGenerator和XRobot的环境配置、基础使用和进阶用法。有任何问题欢迎在对应仓库提交issue或者加入QQ群交流。
 
+## 引导
+
+* [LibXR](../docs/basic_coding): 跨平台的C++兼容层，包含外设驱动、数据结构、通信中间件、操作系统封装与数学工具等
+
+* [XRUSB](../docs/xrusb): LibXR内置的USB协议栈
+
+* [CodeGenerator](../docs/code_gen): 自动生成外设的C++初始化代码、CMake等内容
+
+* [XRobot](../docs/proj_man): 软件包、软件源和依赖管理，模块参数管理与实例化，函数入口生成
+
 ![XRobot Logo](/img/XRobot.png)

docs/xrusb/README.md

@@ -6,4 +6,4 @@ sidebar_position: 8
 
 # XRUSB
 
-TODO:
+XRUSB由不同平台的USB设备与端点驱动，结合统一的上层class抽象组成。

docs/xrusb/plat_ep_dev/README.md

@@ -0,0 +1,47 @@
+---
+id: xrusb-plat-dev
+title: 平台相关实现
+sidebar_position: 1
+---
+
+# 平台相关实现
+
+本节介绍XRUSB在不同平台的实现原理与构造方式。对于使用不同的class，只需要在构造的最后传入指针即可。
+
+例如：
+
+```cpp
+/* USB Classes */
+LibXR::USB::CDCUart cdc_uart;
+LibXR::USB::HIDKeyboard hid_keyboard;
+
+static constexpr auto LANG_PACK =
+    LibXR::USB::DescriptorStrings::MakeLanguagePack(
+        /* Language Code */
+        LibXR::USB::DescriptorStrings::Language::EN_US, 
+        /* Manufacturer */
+        "XRobot",
+        /* Product */
+        "XRUSB USB CDC Demo", 
+        /* Serial Number */
+        "123456789");
+
+
+XXXUSBDevice usb(
+    /* USB Hardware and Endpoints config */
+    ..., 
+    /* EP0 Packet Size */
+    USB::DeviceDescriptor::PacketSize0::SIZE_8,
+    /* Vendor ID */
+    0x483,
+    /* Product ID */
+    0x5740,
+    /* BcdDevice */
+    0xF407,
+    /* Language Pack */
+    LANG_PACK,
+    /* Classes */
+    {{&cdc_uart, &hid_keyboard}});
+```
+
+

docs/xrusb/plat_ep_dev/ch32_usb.md

@@ -0,0 +1,67 @@
+---
+id: xrusb-plat-dev-ch32
+title: CH32 USB 实现
+sidebar_position: 2
+---
+
+# CH32 USB 实现
+
+CH32一共有三种USB设备，如下所示。
+
+| 名称                  | 角色      | 端点是否为双向       | 双缓冲        | DMA支持 |
+| --------------------- | --------- | -------------------- | ------------- | ------- |
+| USB_DEVICE (尚未支持) | 从机      | 硬件双缓冲不支持双向 | 软件/硬件实现 | 不支持  |
+| USBHS                 | 主机/从机 | 硬件双缓冲不支持双向 | 硬件双缓冲    | 支持    |
+| USBFS                 | 主机/从机 | 双向                 | 硬件双缓冲    | 支持    |
+
+## USBFS
+
+CH32 USBFS只支持这样声明端点，建议非EP0端点的缓冲区大小为128字节：
+
+1. `{{ep0_buffer}, ...}`: 直接传入缓冲区即可，除了EP0都会被分割为IN/OUT缓冲区，端点号自动递增
+
+```cpp
+LibXR::CH32USBDeviceFS usb_dev(
+    /* EP */
+    {
+        {ep0_buffer},
+        {ep1_buffer},
+        {ep2_buffer},
+    },
+    /* packet size */
+    LibXR::USB::DeviceDescriptor::PacketSize0::SIZE_64,
+    /* vid pid bcd */
+    0x1209, 0x0001, 0x0100,
+    /* language */
+    {&LANG_PACK_EN_US},
+    /* config */
+    {{&cdc1}});
+```
+
+## USBHS
+
+CH32 USBHS支持三种端点声明方式，非EP0端点的缓冲区大小推荐为1024字节，端点号自动递增：
+
+1. `{ep0_buffer_hs}`: 直接传入EP0端点的缓冲区
+1. `{ep1_buffer_tx_hs, true}`：传入缓冲区并开启双缓冲
+   - ep1_buffer_tx_hs: EP1 端点的缓冲区
+   - true: 是否配置为IN端点 
+1. `{ep2_buffer_rx_hs, ep2_buffer_tx_hs}`：传入双向端点的缓冲区，不开启双缓冲
+
+```cpp
+LibXR::CH32USBDeviceHS usb_dev_hs(
+    /* EP */
+    {
+        {ep0_buf_hs},                    // EP0
+        {ep1_in_buf_hs, true},           // EP1 IN（单向，双缓冲）
+        {ep2_out_buf_hs, false},         // EP2 OUT（单向，双缓冲）
+        {ep3_out_buf_hs, ep3_in_buf_hs}  // EP3 双向（不启双缓冲）
+    },
+    /* vid pid bcd */
+    0x1209, 0x0001, 0x0100,
+    /* language */
+    {&LANG_PACK_EN_US},
+    /* config */
+    {{&cdc2}});
+```
+

docs/xrusb/plat_ep_dev/stm32_usb.md

@@ -0,0 +1,88 @@
+---
+id: xrusb-plat-dev-stm32
+title: STM32 USB 实现
+sidebar_position: 1
+---
+
+# STM32 USB 实现
+
+STM32一共有四种USB设备，如下所示。可以参考代码生成工具自动生成的CDC代码，了解USB设备的端点配置。
+
+| 名称          | 角色      | 端点是否为双向       | 双缓冲        | DMA支持 |
+| ------------- | --------- | -------------------- | ------------- | ------- |
+| USB_DEVICE_FS | 从机      | 硬件双缓冲不支持双向 | 软件/硬件实现 | 不支持  |
+| USB_DRV_FS    | 主机/从机 | 硬件双缓冲不支持双向 | 软件/硬件实现 | 不支持  |
+| USB_OTG_FS    | 主机/从机 | 双向                 | 支持          | 不支持  |
+| USB_OTG_HS    | 主机/从机 | 双向                 | 支持          | 支持    |
+
+## USB_DEVICE_FS/USB_DRV_FS
+
+支持两种端点的声明方式，缓冲区端点号自动递增：
+
+1. `{usb_fs_ep0_in_buf, usb_fs_ep0_out_buf, 8, 8}`：声明一个双向端点，无法使用硬件双缓冲
+    - usb_fs_ep0_in_buf: EP0 IN软件缓冲区数组
+    - usb_fs_ep0_out_buf: EP0 OUT软件缓冲区大小
+    - 8: EP0 IN硬件RAM大小
+    - 8: EP0 OUT硬件RAM大小
+2. `{usb_fs_ep2_in_buf, 16, true}`：声明一个单向端点，使用硬件双缓冲
+    - usb_fs_ep2_in_buf: EP2 IN软件缓冲区数组
+    - 16: EP2 IN硬件RAM大小
+
+为了确保传输速度，对于bulk端点，硬件RAM大小应当不小于64，软件缓冲区可以远大于64，大小与传输速度成正比。
+
+```cpp
+STM32USBDeviceDevFs usb_fs(
+    /* USB Handler */
+    &hpcd_USB_FS,
+    /* Endpoints */
+    {
+        {usb_fs_ep0_in_buf, usb_fs_ep0_out_buf, 8, 8},
+        {usb_fs_ep1_in_buf, usb_fs_ep1_out_buf, 128, 128},
+        {usb_fs_ep2_in_buf, 16, true}
+    },
+    USB::DeviceDescriptor::PacketSize0::SIZE_8,
+    0x483, 0x5740, 0xF407,
+    {&USB_FS_LANG_PACK},
+    {{&usb_fs_cdc}}
+);
+```
+
+## USB_OTG_FS/USB_OTG_HS
+
+STM32USBDeviceOtgHS和STM32USBDeviceOtgFS同样支持两种端点声明方式，IN/OUT端点缓冲区端点号各自自动递增：
+
+1. `{{usb_otg_fs_ep0_in_buf, 8},...}`：in端点必须声明缓冲区与Fifo大小
+2. `{usb_otg_fs_ep0_out_buf, ...}`：out端点只需要声明缓冲区
+
+所有out端点共用一个rx fifo，应该分配较大的空间。为了保证速度，IN端点Fifo的大小不应小于包大小，软件缓冲区大小与传输速度成正比。
+
+```cpp
+// STM32USBDeviceOtgHS usb_hs(
+STM32USBDeviceOtgFS usb_fs(
+    /* USB Handler */
+    &hpcd_USB_OTG_FS,
+    /* RX Fifo Size */
+    256,
+    /* Out Endpoints */
+    {usb_otg_fs_ep0_out_buf, usb_otg_fs_ep1_out_buf},
+    /* In Endpoints */
+    {{usb_otg_fs_ep0_in_buf, 8}, {usb_otg_fs_ep1_in_buf, 128}, {usb_otg_fs_ep2_in_buf, 16}},
+    USB::DeviceDescriptor::PacketSize0::SIZE_8,
+    0x483, 0x5740, 0xF407,
+    {&USB_OTG_FS_LANG_PACK},
+    {{&usb_otg_fs_cdc}}
+  );
+  usb_fs.Init();
+  usb_fs.Start();
+```
+
+## 运行
+
+添加以下语句即可。
+
+```cpp
+usb_fs.Init();
+usb_fs.Start();
+```
+
+

docusaurus.config.js

@@ -1,3 +1,5 @@
+const { themes: prismThemes } = require('prism-react-renderer');
+
 module.exports = {
   title: 'XRobot Docs',
   tagline: 'Want to be the best embedded framework',
@@ -20,6 +22,10 @@ module.exports = {
     },
   ],
 
+  markdown: {
+    mermaid: true,
+  },
+
   i18n: {
     defaultLocale: 'zh',
     locales: ['en', 'zh'],
@@ -42,6 +48,8 @@ module.exports = {
     ],
   ],
 
+  themes: ['@docusaurus/theme-mermaid'],
+
   presets: [
     [
       'classic',
@@ -153,9 +161,13 @@ module.exports = {
       copyright: `Copyright © ${new Date().getFullYear()} XRobot`,
     },
 
+    mermaid: {
+      theme: { light: 'neutral', dark: 'forest' },
+    },
+
     prism: {
-      theme: require('prism-react-renderer/themes/github'),
-      darkTheme: require('prism-react-renderer/themes/dracula'),
+      theme: prismThemes.github,
+      darkTheme: prismThemes.dracula,
       additionalLanguages: ['cmake', 'bash'],
     },
   },