<!-- SPDX-License-Identifier: MIT -->
# CH32V003 ch32fun template (fully open source)

A minimal `make` project for the CH32V003 built on
[ch32fun](https://github.com/cnlohr/ch32fun) (MIT). It uses no WCH EVT SDK,
no WCH GCC, no `libprintf`, and no IQmath.

The example blinks an LED on `PD0`. Put your own application in `firmware.c`.

## Stack

| Component | Role | License |
|---|---|---|
| ch32fun | startup, headers, GPIO helpers, `printf`, linker script | MIT |
| `riscv64-elf-gcc` / binutils | compiler and binutils | GPL |
| `riscv64-elf-newlib` | **headers only** (`stdio.h`, `string.h`, ...) | BSD |
| `ch32fun/misc/libgcc.a` | compiler runtime | GCC runtime license |
| `minichlink` | flashing / SWIO monitor | MIT |
| `wchisp` (optional) | alternative flasher | GPL-2.0 |

### Why the missing `rv32ec` newlib multilib does not matter

Arch's `riscv64-elf-newlib` has no `rv32ec`/`ilp32e` library, but ch32fun
builds with `-nostdlib` and links its own `misc/libgcc.a`:

```text
-nostdlib ... -L.../misc -lgcc
```

Only newlib's **headers** are used. The CH32V003 startup, `printf`, and
runtime support come from ch32fun, so no WCH or newlib object code is linked.

## Requirements

Arch packages:

```bash
sudo pacman -S --needed base-devel riscv64-elf-gcc riscv64-elf-newlib libusb
```

`libusb` is only needed to build `minichlink` for flashing. `systemd-libs`
provides `libudev` and is normally already installed.

ch32fun checkout:

```bash
git clone https://github.com/cnlohr/ch32fun ~/code/ch32fun
```

The Makefile defaults to `~/code/ch32fun`. If yours is elsewhere:

```bash
make CH32FUN_ROOT=/path/to/ch32fun
```

It also defaults to the Arch newlib header directory
`/usr/riscv64-elf/include` and the compiler prefix `riscv64-elf`. Override
with `NEWLIB=...` or `PREFIX=...` if needed.

## Build

```bash
cd ch32fun-template
make
make size
```

Outputs:

```text
firmware.elf
firmware.bin
firmware.hex
firmware.lst
firmware.map
```

Only `firmware.bin` is written to the chip. `make` never flashes implicitly.

The template currently builds to about 620 bytes of flash:

```text
text    data    bss    dec    hex
620       0      0    620    26c    firmware.elf
```

## Flash and monitor

`make flash` builds `minichlink` on first use and writes `firmware.bin`:

```bash
make flash
```

`minichlink` needs permission to access the WCH-Link. Install its udev rules
once:

```bash
sudo make -C ~/code/ch32fun/minichlink install_udev_rules
```

Then reconnect the WCH-LinkE. Wiring for SWIO programming:

```text
WCH-LinkE       CH32V003
3V3      <-->   3V3
GND      <-->   GND
SWIO     <-->   PD1
```

View `printf` output over the SWIO debug channel:

```bash
make monitor
```

`make terminal` and `make unbrick` are also provided by ch32fun's build rules.

If you prefer `wchisp` from the AUR:

```bash
yay -S wchisp
wchisp flash firmware.bin
```

## Customize

- `firmware.c` — application code; `LED_PIN` is `PD0`.
- `funconfig.h` — clock and `printf` configuration.
- `TARGET` — output basename. It must match the application source name, so
  `TARGET := firmware` uses `firmware.c`.
- `TARGET_MCU` — defaults to `CH32V003`; change it to target another ch32fun
  MCU.

Useful overrides:

```bash
make TARGET_MCU=CH32V003
make CH32FUN_ROOT=/path/to/ch32fun
make PREFIX=riscv32-unknown-elf
make clean
```

For a Linux-hosted cross compiler instead of the bare-metal package:

```bash
make PREFIX=riscv64-linux-gnu EXTRA_CFLAGS=-no-pie
```

That path also works but is less clean; `riscv64-elf-gcc` is recommended.

## License

The template files (`Makefile`, `firmware.c`, `funconfig.h`, this README) are
MIT-licensed; see `LICENSE`. ch32fun is MIT-licensed. GCC, binutils, newlib,
and `minichlink` are open source under their respective licenses.