QEMU Emulator for WCH CH32V RISC-V MCUs

A community-driven QEMU fork now provides system-level emulation for WCH QingKe RISC-V microcontrollers. Instead of flashing every test build to real hardware, developers can compile a CH32V firmware ELF, drop it into QEMU, and immediately see serial output, interact with an RT-Thread shell, ping a virtual Ethernet interface, or step through code with GDB. This is especially useful for early logic verification, protocol-stack debugging, and CI/CD pipelines where keeping a board farm connected is impractical.

What the Project Covers

The emulator is built around standard QEMU TCG plus WCH-specific extensions. It accepts the actual firmware ELF produced by MounRiver Studio or riscv32-wch-elf-gcc, boots it through the same reset vector used on silicon, and models enough peripherals that many EVT examples run unmodified.

Verified use cases include:

• Bare-metal printf through USART1
• RT-Thread msh interactive shell
• LwIP network communication over a host TAP interface
• CherryUSB host-stack enumeration of real USB devices
• EVT interrupt examples with 8-level nesting, VTF fast interrupts, and PMP
• Independent watchdog timeout reset

Supported Machines

QEMU machine Chip series Core Ethernet ch32v317 CH32V317 V4F (RV32IMAFC+XW) CH182 100 M ch32v307 CH32V307 V4F Built-in 10 M ch32v305 CH32V305 V4F CH182 100 M ch32v303 CH32V303 V4F CH182 100 M ch32v203 CH32V203 V4B (RV32IMAC+XW) — ch32v203rb CH32V203RBT6 V4B ETH10M ch32v103 CH32V103 V3A (RV32IMAC) — ch32v003 CH32V003 V2C placeholder — ch32v407 CH32V407/V467 V3V (RV32IMACB+XW) CH182 100 M ch32h417 CH32H417 V5F —

CH571/573, CH581/582/583, CH584/585, CH591/592, CH643/645, and CH32X033/X035 can also be tested by selecting the closest core machine. Bluetooth and wireless radios are not emulated, so those stacks still need real hardware.

Quick Start

Build QEMU with the bundled script and then run a firmware image:

./build-wch-qemu.sh -j$(nproc) qemu-system-riscv32 -M ch32v317 -serial stdio -kernel your-app.elf

Serial output is routed directly to the terminal, so a simple printf loop becomes visible immediately.

Already Modeled Peripherals

• PFIC / SysTick / VTF: full MMIO, 8-level nesting, VTF fast interrupt, automatic IACTR clear on mret
• Ethernet MAC+DMA: three PHY models (CH182, built-in 10 M, RTL8211F), TX/RX checksum offload, TAP backend
• USBHS host and USBFS host: real device enumeration through QEMU's USB stack
• USART1: full duplex over -serial stdio
• RCC: HSI/HSE/PLL ready flags, SWS follow, clock enables
• IWDG: key sequence, feed, timeout reset
• RTC / CRC / RNG: modeled
• PMP: four regions with WCH-specific behavior
• GPIO / DMA / TIM / SPI / I2C: register stubs that read back last value and do not block initialization

QingKe ISA Extensions in QEMU

The fork implements WCH's non-standard QingKe extensions inside QEMU TCG:

• XW compressed memory access: c.lbu, c.lhu, c.sb, c.sh and SP-relative variants, matching the -march=...xw toolchain
• HPE hardware stack push: automatic save of 16 caller GPRs on entry, automatic restore on mret
• xwchmcpy hardware memcpy instructions for V3B/V3C/V3F/V3V
• M+U privilege modes for V3/V4/V5; M-only for V2
• VTF fast interrupt with four vector-free channels
• WCH custom CSRs: gintenr (0x800), intsyscr (0x804), wch_misc (0xbc0)

Network Emulation Example

Create a TAP interface on the host and start QEMU with a NIC:

sudo ip tuntap add tap0 mode tap user $(whoami) sudo ip link set tap0 up sudo ip addr add 192.168.1.1/24 dev tap0 qemu-system-riscv32 -M ch32v317 -serial stdio \ -nic "tap,ifname=tap0,script=no,downscript=no" \ -kernel OrayOS-Tiny-qemu.elf

After the guest finishes booting, the host can ping the guest address configured in the firmware, and TCP/HTTP services running inside QEMU are reachable from the host.

GDB Debugging

QEMU exposes a built-in GDB stub. Start QEMU with the CPU halted:

qemu-system-riscv32 -M ch32v317 -serial stdio \ -kernel your-app.elf -s -S

Then connect from a second terminal:

riscv32-wch-elf-gdb your-app.elf (gdb) target remote :1234 (gdb) break main (gdb) continue (gdb) info registers (gdb) x/10i $pc

This is often faster than JTAG for inspecting register state and stepping through startup code.

Where This Fits in a Workflow

• No board on the desk yet: verify register initialization and task scheduling in QEMU while waiting for hardware.
• CI/CD: compile every commit, boot it in QEMU, and check that the RT-Thread shell or network stack comes up without manual flashing.
• Protocol debugging: run LwIP, MQTT, or HTTP against a host broker through TAP before moving to real PHY hardware.
• Teaching RISC-V: single-step through QingKe code and inspect CSRs without a physical debugger.

If you are evaluating WCH CH32V003, CH32V208, CH32V307, CH32V317, CH32V407, or CH32H417 for a new design, this emulator can shorten the first weeks of bring-up dramatically.

Project Links

• GitHub: https://github.com/lintel/qemu-ch32v
• License: CC0 1.0 Universal

Source: [首发] CH32V系列RISC-V MCU的Qemu模拟器 (WCH Community) https://www.wch.cn/bbs/thread-157174-1.html