CH32 环境配置

当前默认使用 WCH 提供的 GCC15 工具链，编译器前缀为 riscv32-wch-elf-。

模板工程按此配置。docker-image-ch32-riscv 镜像提供同一工具链（WCH GCC15 v240）。

CMake 配置

CH32 工程至少要额外指定一个选项：LIBXR_CH32_CONFIG_FILE，用于告诉 LibXR 当前使用哪份 CH32 外设配置头文件，例如 ch32v30x_conf.h。

set(LIBXR_SYSTEM FreeRTOS)
set(LIBXR_DRIVER ch)

set(LIBXR_CH32_CONFIG_FILE "ch32v30x_conf.h")

add_subdirectory(libxr)

模板工程自动确定工具链前缀。自行搭建工程或机器上装有多套 RISC-V 工具链时，用 COMPILER_PREFIX 显式指定。

驱动库问题

WCH 官方外设库本身有一些长期存在的问题，当前示例工程已经处理过的包括：

• extern "C" 重复定义，导致 C++ 下包含头文件报错
• USB 外设的部分源文件和头文件虽然存在，但默认并没有被正确引用
• FreeRTOS 的 mstatus 位设置有问题，会影响线程切换和优先级
• 某些不存在的外设组定义仍然出现在官方库里

不从示例工程开始、自行整理外设库时，需要重新处理这些问题。

Systick

当前 CH32Timebase 直接从 CH32 的 64 位 SysTick 硬件计数器换算微秒和毫秒，不再依赖 SysTick_Handler 中的软件累加函数。

在构造 CH32Timebase 之前，BSP 需要把 SysTick 配成：

• HCLK 作为计数时钟；
• 64 位自由运行的向上计数器；
• 计数器已经使能；
• 不使用自动重装和向下计数；
• SystemCoreClock >= 1 MHz。

使用期间不要停止或清零这个计数器，也不要在没有重新建立时间基的情况下修改 HCLK。RTOS 的比较值和 tick 中断仍可由 BSP 管理，但不能通过周期性清零同一个计数器来实现 tick。

Flash 问题

要注意的几点：

• 擦写期间驱动把 Flash 访问时钟切换为 SYSCLK/2，并要求 SystemCoreClock 不超过 120 MHz
• 擦除完成但尚未写入时，虽然表面上全是 0xff，实际读回可能会看到魔数 0xE339u
• 很多型号带有赠送 Flash，这部分速度会比主 Flash 低很多
• 用到额外 Flash 时，OpenOCD 里通常要补 wch_riscv unfreeze，否则烧录不稳定

参考 openocd 命令：

"openOCDLaunchCommands": [
    "init",
    "wch_riscv unfreeze"
],

示例工程

• CH32V307+FreeRTOS+XRUSB
• CH32V203+FreeRTOS+XRUSB