2023-01-08 05:31:19 +00:00
|
|
|
|
# WCH CH32V build template
|
2022-11-26 01:20:14 +00:00
|
|
|
|
|
2023-01-08 05:31:19 +00:00
|
|
|
|
This repository is a template for a project built for the WCH CH32V RISC-V
|
|
|
|
|
microcontroller series, _without_ using the
|
|
|
|
|
[MounRiver tools](http://mounriver.com/). 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
|
2022-11-26 01:20:14 +00:00
|
|
|
|
|
|
|
|
|
## You will need
|
|
|
|
|
|
|
|
|
|
- Docker
|
|
|
|
|
- Patched openocd supporting wlink/WCH-link; either from the
|
|
|
|
|
[MounRiver tools](http://mounriver.com) or
|
|
|
|
|
[from source](https://github.com/newbrain/riscv-openocd-wch).
|
|
|
|
|
- make (probably GNU make?)
|
|
|
|
|
|
|
|
|
|
Everything else is downloaded into the Docker container.
|
|
|
|
|
|
2022-11-26 05:19:58 +00:00
|
|
|
|
## How to do stuff
|
2022-11-26 01:20:14 +00:00
|
|
|
|
|
2022-11-26 05:19:58 +00:00
|
|
|
|
- Building in Docker:
|
|
|
|
|
- `make` (`make all`) — full build. Will create the docker image
|
|
|
|
|
(expect 10-30min) if needed.
|
2023-01-03 17:34:03 +00:00
|
|
|
|
- `make rb` — clean and rebuild of just the build, not the docker image
|
|
|
|
|
- `make wipe` — full clean and rebuild including the docker image
|
2022-11-26 01:20:14 +00:00
|
|
|
|
- Building locally, if you have your own toolchain already:
|
|
|
|
|
- `make lall` ("local all")
|
2023-01-03 17:34:03 +00:00
|
|
|
|
- `make lrb` ("local rebuild")
|
2022-11-26 01:20:14 +00:00
|
|
|
|
- `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.
|
|
|
|
|
|
2022-11-26 05:19:58 +00:00
|
|
|
|
### Using gdb
|
2022-11-26 05:18:20 +00:00
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
2022-11-26 05:19:58 +00:00
|
|
|
|
### Miscellaneous
|
|
|
|
|
|
|
|
|
|
- `make shell` will open a shell in Docker.
|
|
|
|
|
|
2022-11-26 01:20:14 +00:00
|
|
|
|
## 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` — 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
|
2023-01-08 05:33:07 +00:00
|
|
|
|
- `subprojects/ch32v10x` — CH32V10x vendor libraries, Apache 2.0 licensed
|
|
|
|
|
- `subprojects/ch32v30x` — CH32V30x vendor libraries, Apache 2.0 licensed
|
2022-11-26 01:20:14 +00:00
|
|
|
|
- `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 `meson.build` 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
|
2023-01-08 05:31:19 +00:00
|
|
|
|
- Make sure to only include either the CH32V10x block or the CH32V30x block
|
2023-01-12 01:05:43 +00:00
|
|
|
|
- Have a look in the subproject readme for either `ch32v10x` or `ch32v30x`,
|
|
|
|
|
they have some cool options.
|
2022-11-26 01:20:14 +00:00
|
|
|
|
- Replace this readme with your own
|
|
|
|
|
|
|
|
|
|
## Changes I made to the WCH support code
|
|
|
|
|
|
2023-01-08 05:31:19 +00:00
|
|
|
|
- Pull user config values out of `system_ch32v10x.c` and `ch32v10x.h` and
|
|
|
|
|
define them via meson options.
|
2022-11-26 01:20:14 +00:00
|
|
|
|
|
|
|
|
|
## Other useful resources
|
|
|
|
|
|
|
|
|
|
Nobody seems to link directly to these except WCH themselves, so I'm putting them
|
|
|
|
|
here:
|
|
|
|
|
|
|
|
|
|
- [CH32V10x datasheet](http://www.wch-ic.com/downloads/CH32V103DS0_PDF.html)
|
|
|
|
|
- [CH32x10x reference manual](http://www.wch-ic.com/downloads/CH32xRM_PDF.html) — beware that this also covers the Cortex-M version
|
2023-01-08 05:31:19 +00:00
|
|
|
|
- [CH32V303/305 datasheet](http://www.wch-ic.com/downloads/CH32V20x_30xDS0_PDF.html)
|
|
|
|
|
- [CH32V307 datasheet](http://www.wch-ic.com/downloads/CH32V307DS0_PDF.html)
|
|
|
|
|
- [CH32x30x reference manual](http://www.wch-ic.com/downloads/CH32FV2x_V3xRM_PDF.html) — beware that this also covers the Cortex-M version
|
2022-11-26 01:20:14 +00:00
|
|
|
|
|
|
|
|
|
## 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.
|