Migrating STM32 to CH32V307: RISC-V Low-Level Differences for FreeRTOS / RT-Thread

A frequent question on the 21ic RISC-V board (and in our own community) is what changes when an STM32F103/F4 Cortex-M project is ported to a CH32V307 (RISC-V RV32IMAC)? FreeRTOS or RT-Thread typically works out of the box — but several low-level traps exist that bite first-time migrators. This thread compiles the practical differences you need to know, drawing on WCH EVT examples, RT-Thread's BSP support, and community debugging.

1. Toolchain Choice Switches the ABI

ARM Cortex-M uses the AAPCS ABI (r0-r12 caller-saved, sp/r13/lr/r14/pc/r15, xPSR). RISC-V uses ILP32 with its own conventions: x0 (zero), x1 (ra), x2 (sp), x8-x9 (s0/fp, s1), x10-x11 (a0-a1, return regs), x12-x17 (a2-a7, args), x18-x27 (s2-s11). If you previously relied on which registers are clobbered by an interrupt, you need to recheck.

Practical consequence: any inline assembly in your STM32 code (often CMSIS-DSP functions or zero-delay busy loops) will not assemble and must be rewritten.

2. Interrupt Stack Handling Is Different

The biggest day-one surprise for ARM migrators is the interrupt stack. ARM Cortex-M uses a dedicated MSP stack for handlers and PSP for threads; the FPU pushes lazily. RISC-V, by contrast, has no hardware-maintained exception frame. The trap handler saves the full register context (including mepc, mstatus, mcause, mtval) onto the current stack or a dedicated IRQ stack.

For FreeRTOS this means:

• The WCH port supplied in WCH-EVT uses portSAVE_CONTEXT / portRESTORE_CONTEXT macros that push the full 32+ register context on the current task's stack
• If you upgrade the FreeRTOS version, double-check the RISC-V port macro names — they have changed between FreeRTOS-Kernel 10.x and 11.x
• Stack overflow detection must account for the larger saved context (~144 bytes minimum on RV32, more if extended with FPU registers)

For RT-Thread the BSP for CH32V307 (in rt-thread/bsp/wch) handles this transparently, but if you write a custom interrupt, you must call rt_interrupt_enter() / rt_interrupt_leave() to enable accurate scheduling statistics.

3. Clock Tree Configuration

CH32V307's clock tree differs in two ways from STM32F4:

• HSE is 8 MHz typical but the PLL multiplier matrix is different; PLL multipliers of 5/7/9 etc. work fine, but the USB 48 MHz derivation requires PLL_Q = 9 on STM32, while CH32V307 uses a dedicated USB clock divider
• The internal HSI trim registers live at different addresses; if you copy-paste an LSE/HSE fallback from an STM32 HAL, you will hang the boot

WCH provides a clock-config wizard inside MounRiver Studio (MRS) that generates correct SystemClock setups. Use it instead of guessing.

4. FSMC and GPIO Quirks

If your STM32F4 used FSMC to talk to an external SRAM/NOR/PSRAM, CH32V307's FSMC is largely compatible at the API surface but expects a slightly different timing-pattern layout. The good news: WCH-EVT provides a working FSMC example for 16-bit SRAM and 16-bit NAND.

GPIO is mostly drop-in, but three subtle differences:

• CH32V307 has 5 V-tolerant GPIO pins (PA0/PA1/PB0/PB1/PB2) — useful but easy to forget on F4 ports where most pins are 5 V
• EXTI lines are mapped differently for some pins; check the alternate-function table, not just the pin number
• AF remapping bits sit at a different offset in the CFGR registers

5. Toolchain & Library Compatibility

MounRiver Studio (MRS) is WCH's official IDE. It bundles GCC for RISC-V (including picolibc and newlib-nano options), OpenOCD profiles for WCH-Link, and a graphical clock config / pin mux viewer. For STM32CubeMX-style projects, MRS imports the MX-ioc pin file format for CH32V-series parts.

Third-party library compatibility hurdles:

• CMSIS packs: there are no official CMSIS-Pack archives for CH32V. You must replace CMSIS device headers with WCH-EVT equivalents. Most ARM-only HAL wrappers need rewriting.
• DSP libraries: CMSIS-DSP is for ARM NEON/CM4 SIMD. CH32V407 has RVV (vector) extension and CH32V307 does not; do not assume SIMD intrinsics work.
• Real-time OS: FreeRTOS has an official RISC-V port that works; RT-Thread has BSPs for CH32V003/V203/V307/V407; Zephyr has had WCH in-tree support since 2025 (Tech62 on the WCH BBS has been actively answering Zephyr questions).
• OpenOCD debugging: WCH-LinkE / WCH-Link are the canonical debug probes. If you prefer J-Link or CMSIS-DAP, check RISC-V compatibility before buying.

6. Practical Migration Checklist

When porting an STM32 project, walk through this checklist:

1. Update toolchain from arm-none-eabi-gcc to riscv-none-elf-gcc (MRS bundles this)
2. Replace startup file with WCH-EVT equivalent (startup_ch32v30x.s)
3. Replace CMSIS device headers with ch32v30x.h
4. Rewrite any inline asm
5. Validate clock config via MRS wizard
6. Migrate FreeRTOS port to the upstream RISC-V port (the WCH-EVT port is a known-good starting point)
7. For RT-Thread, swap in bsp/wch/ch32v307 and update Kconfig options
8. Validate GPIO AF mappings against the alternate-function table
9. Recheck any DMA stream-to-channel mapping — CH32V307 uses different DMA controllers than STM32F4
10. Validate USB 2.0 FS code; CH32V307 has a built-in USB FS PHY but the register layout is not 1:1 with STM32

7. When to Stay on STM32 vs Migrate

Migration is worth it when:

• You need the USB high-speed peripheral (CH32V317 at 480 Mbps; CH32H417 at 5 Gbps; or CH32V208 at BLE 5.3)
• You need extra Ethernet (CH32V307 has built-in gigabit Ethernet)
• BOM cost matters — WCH parts are typically 30-60% cheaper than comparable STM32 at high quantity
• You are planning a vector-extension upgrade path (CH32V407 with RVV is pin-compatible with the V307 in many layouts)

Stay on STM32 when:

• Existing CMSIS-DSP SIMD code is central to performance
• The toolchain investment in your team is significant and not repaid by the BOM savings
• Your code relies on ARM-specific peripherals (TrustZone, MPU region layouts)

Sources & Further Reading

• 21ic forum thread: STM32 to CH32V307 RTOS migration Q&A
• WCH-EVT repository (FreeRTOS + RT-Thread + bare-metal examples): https://www.wch.cn/products/CH32V307.html
• FreeRTOS RISC-V port documentation
• RT-Thread BSP for CH32V307

For more WCH RISC-V discussion, see our WCH MCU category. For K1/K3 and broader RISC-V SoC topics, browse the K1 / K3 / OpenWrt categories.

---

Source: 21ic RISC-V forum thread "STM32 migration to CH32V307 RTOS porting differences" — https://bbs.21ic.com/icview-3528952-1-1.html

感谢您在 Open RISC-V 论坛提问！

CH32V003 入门指南

CH32V003 是基于 RISC-V RV32EC 指令集的超低成本 MCU，批量价约 $0.1，主频 48MHz，非常适合替代传统 8 位 MCU（如 STM8S003）。

开发环境搭建

推荐使用 MounRiver Studio（基于 Eclipse）：

1. 下载并安装 MounRiver Studio： http://www.mounriver.com
2. 创建 RISC-V 工程，选择 CH32V003 芯片
3. 使用 WCH-LinkE 调试器连接 SWIO 单线调试接口

最小系统电路

VDD ── 3.3V VSS ── GND PD1/SWIO ── WCH-LinkE SWIO NRST ── 10K 上拉到 VDD（可选）

GPIO 示例代码

#include "ch32v00x.h"

int main(void) { RCC_APB2PeriphClockCmd(RCC_APB2Periph_GPIOD, ENABLE); GPIO_InitTypeDef cfg = {GPIO_Pin_4, GPIO_Speed_50MHz, GPIO_Mode_Out_PP}; GPIO_Init(GPIOD, &cfg); while (1) { GPIO_WriteBit(GPIOD, GPIO_Pin_4, Bit_RESET); Delay_Ms(500); GPIO_WriteBit(GPIOD, GPIO_Pin_4, Bit_SET); Delay_Ms(500); } }

注意事项

• FLASH 擦写寿命约 10 万次，避免频繁写内部 Flash
• 内部 RC 振荡器精度约 ±2%（全温范围），高精度场景建议外接晶振
• 上电默认 PA1/PA2 为 SWIO 接口，注意引脚复用冲突

更多资料请访问 open-riscv.com 芯片资料专区。

如有更多问题，欢迎在论坛继续讨论或联系 contact@open-riscv.com

Update: MounRiver Studio + CLion Integration for WCH MCU Development

A recent discussion on the WCH community forum explored using CLion alongside MounRiver Studio for WCH RISC-V MCU development. The setup involves using MounRiver Studio for project initialization, CLion for code editing/compiling/debugging, and WCH-LinkE as the debug probe.

WCH's Official Response

WCH staff responded with the following guidance:

1. MRS2 is recommended -- MounRiver Studio 2 provides the full toolchain (compile, download, debug) with no extra configuration needed.
2. Toolchain can be used independently -- The WCH toolchain consists of:

- WCHToolChain for compilation - OpenOCD for download and debugging

1. No official documentation for non-MRS2 environments -- Developers wanting to use CLion, VS Code, or other IDEs need to configure the toolchain themselves.
2. CMakeLists generation -- MRS2 can generate CMakeLists for a project, which can then be used in CLion or other CMake-compatible IDEs.

Practical Migration Path (STM32 to WCH RISC-V)

For developers migrating from STM32 + Keil/STM32CubeIDE to WCH RISC-V:

Step 1: Create project in MRS2 (select chip, peripherals, clock config) Step 2: Export CMakeLists from MRS2 (File -> Export -> CMakeLists) Step 3: Open CMakeLists in CLion Step 4: Configure toolchain: WCHToolChain for compiler, OpenOCD for debugger Step 5: Connect WCH-LinkE debug probe (SWD 2-wire interface) Step 6: Build and debug from CLion

Key Differences from STM32 Development

The RISC-V toolchain (riscv-none-elf-gcc) is GCC-based and well-supported. For developers familiar with GCC-based ARM development (like STM32 + GCC), the transition is straightforward -- the main difference is the RISC-V-specific flags (-march=rv32imac, -mabi=ilp32) and the interrupt controller differences (CLIC vs NVIC). Source: WCH Forum -- MounRiver Studio + CLion + WCH-LinkE

A practical note to add to this migration guide, because it is the first thing that bites people coming from STM32 and it is not in the reference manual's migration sections.

On CH32V (and every RV32 part from WCH), the trap vector table must be populated at link time with entries that are actual C functions marked as interrupt handlers. STM32's startup files give you pre-named weak aliases like DMA1_Channel4_IRQHandler; on RISC-V there is no such naming convention unless your startup assembly declares it. If you copy an STM32 vector table into a CH32V project, the table entries will point at addresses that the C compiler never emitted, and the first interrupt lands wherever the linker happened to place data.

Three concrete items to verify:

1. mcause and mtvec must be read and restored with the correct width and volatile semantics. A common bug is declaring mtvec as a plain uint32_t pointer and letting the compiler cache it across the handler; it must be volatile, and writing mtvec requires the low bits to be cleared because the mode field occupies them.
2. mepc holds the return address of the interrupted instruction. For a synchronous exception such as an illegal instruction, you must advance mepc before mret or you will re-execute the faulting instruction forever. For an asynchronous interrupt from a peripheral, you enter and exit without modifying mepc.
3. Writing mepc and mstatus from C requires registers that the compiler must not reorder around mret. In WCH's examples the save and restore is done in a naked assembly wrapper, not in C; keep it that way.

If you are moving FreeRTOS or RT-Thread across, the scheduler's context switch is a separate path from the trap entry and both need checking: the software interrupt used for yield must not share the same save frame as the hardware interrupt path unless you deliberately designed it to.

Once that layer is correct the rest of the migration is routine, and the FreeRTOS port notes we published cover the nesting and critical-section specifics that differ from the Cortex-M baseline. For product inquiries, contact contact@open-riscv.com or visit /forum/inquiry