3.9 KiB

WCH CH32V build template

This repository is a template for a project built for the WCH CH32V RISC-V microcontroller series, without using the MounRiver tools. A GCC toolchain is built in a Docker container to make the build simple on all decent platforms; I use it on macOS and have tested it on Linux.

Supported parts

  • CH32V10x family
  • CH32v30x family

You will need

Everything else is downloaded into the Docker container.

How to do stuff

  • Building in Docker:
    • make (make all) — full build. Will create the docker image (expect 10-30min) if needed.
    • make rb — clean and rebuild of just the build, not the docker image
    • make wipe — full clean and rebuild including the docker image
  • Building locally, if you have your own toolchain already:
    • make lall ("local all")
    • make lrb ("local rebuild")
    • make clean lall (equivalent to make wipe)
  • To flash:
    • make flash

make flash expects to find a WCH-compatible patched openocd on the system PATH. If yours lives elsewhere, define OPENOCD_DIR on the environment.

Using gdb

The Docker container has gdb too. To debug, first launch openocd:

make openocd

Next, launch gdb:

make gdb

This make target will launch gdb inside Docker, routing openocd port 3333 from the container to the host, and automatically load the firmware file and connect to openocd.

As above, if you're not using Docker, make lgdb will launch gdb locally, also automatically loading the firmware and connecting.


  • make shell will open a shell in Docker.

What's in here?

The directory tree contains:

  • Dockerfile — specification for the Docker image, which will be called riscv-ubuntu.
  • Makefile — makefile, orchestrating Docker, Meson, and OpenOCD.
  • — meson build file; this does the actual build.
  • meson_cross_riscv.txt — meson cross-compile definition file
  • wch-riscv.cfg — OpenOCD configuration for the CH32V103
  • subprojects/ch32v10x — CH32V10x vendor libraries, Apache 2.0 licensed
  • subprojects/ch32v30x — CH32V30x vendor libraries, Apache 2.0 licensed
  • mbuild/ — output build directory
  • src/ — project source code
    • main.c — contains main()

Making it yours

  • Put code under src/ (you can start in main.c if you like)
  • Edit to list the files that need to be built, and select which peripheral libraries you want
    • Consider changing the project name from firmware for more descriptive filenames
    • Make sure to only include either the CH32V10x block or the CH32V30x block
  • Have a look in the subproject readme for either ch32v10x or ch32v30x, they have some cool options.
  • Replace this readme with your own

Changes I made to the WCH support code

  • Pull user config values out of system_ch32v10x.c and ch32v10x.h and define them via meson options.

Other useful resources

Nobody seems to link directly to these except WCH themselves, so I'm putting them here:

Copying and changing

Intellectual property is bullshit and fake, steal this and don't credit me. You might want to credit WCH for their parts, which have a pesky Apache 2.0 license header on them.