ch32-rs flash-algorithms

probe-rs flash algorithms and target YAMLs for WCH's CH32 MCU families, built on top of ch32-metapac.

Coverage

One algo crate per (flash IP version, CPU arch) pair. f1 is a Cortex-M3 build of the same flash_v1 logic used by v1 on Qingke RISC-V — Cargo can't unify two ch32-metapac chip features, so the lib is duplicated.

Crate	Flash peripheral	Target triple	Chip families
algos/v0	flash_v0	riscv32ec-unknown-none-elf	CH32V003, CH641
algos/v00x	flash_v00x	riscv32ec_zmmul-unknown-none-elf	CH32V002/4/5/6/7, CH32M007
algos/v1	flash_v1	riscv32imac-unknown-none-elf	CH32V103
algos/v3	flash_v3	riscv32imac-unknown-none-elf	CH32V2xx, CH32V3xx
algos/x0	flash_x0	riscv32imac-unknown-none-elf	CH32X035/X033, CH643
algos/l1	flash_l1	riscv32imac-unknown-none-elf	CH32L103
algos/h4	flash_h4	riscv32imac-unknown-none-elf	CH32H415/H416/H417
algos/f1	flash_v1	thumbv7m-none-eabi	CH32F103 (Cortex-M3)
algos-ch5xx/ch5xx	FLASH_ROM	riscv32imac-unknown-none-elf	CH570/571/572/573, CH581/582/583/584/585, CH591/592 (PIC)
algos-ch5xx/ch569	FLASH_ROM	riscv32imac-unknown-none-elf	CH565/CH569

Each algos/* crate builds three binaries — usr, sys, ob — one per writable region. VND (vendor / ESIG) is read-only and not programmed.

algos-ch5xx/ch5xx is a standalone workspace crate that builds a single 1024-byte position-independent usr (CodeFlash) binary shared across CH570, CH571, CH572, CH573, CH581, CH582, CH583, CH584, CH585, CH591, and CH592, enforcing the per-chip CodeFlash ceiling dynamically via R8_CHIP_ID (0x40001041). Note that CH595 uses a newer hardware pre-program/page-latch Flash controller at 0x40001800..0x40001820 (CH59x_flash.c) rather than the SPI-like 0x40001800..0x40001806 interface, CH586/CH587 have up to 960 KiB CodeFlash, and CH577/CH578/CH579 are Cortex-M0 parts, so they are not covered by algos-ch5xx/ch5xx (and can be added as sibling crates under algos-ch5xx/).

algos-ch5xx/ch569 covers CH565/CH569 (448 KiB, 4 KiB sectors). Its flash window is in the SYS block (0x40001014/18/1a), not at 0x40001800, and the algorithm is linked into RAMX at 0x20020008.

Repo layout

ch32-metapac isn't pinned via crates.io or git rev — it's built from a ch32-data submodule and consumed through a path dep. The submodule sha is the single source of truth for both the chip JSON xtask reads and the PAC the algos link against.

flash-algorithms/
├── ch32-data/                  # submodule — pinned sha
│   └── build/                  # generated by `xtask --bootstrap-only` (gitignored)
│       ├── ch32-metapac/       # ← algo path dep target
│       └── data/chips/*.json   # ← xtask reads these
├── algos/{common,v0,v00x,v1,v3,l1,x0,h4,f1}/
├── algos-ch5xx/ch5xx/          # standalone PIC flash algorithms for CH5xx families
└── xtask/                      # standalone crate, NOT in the algos workspace

xtask lives outside the algos workspace because Cargo validates every workspace member's manifest on any workspace command — including the ch32-metapac path dep that doesn't exist until xtask has run its bootstrap.

Clone

git clone --recursive https://github.com/ch32-rs/flash-algorithms

If you forgot --recursive:

git submodule update --init

Bootstrap

Generates ch32-data/build/data/chips/*.json and ch32-data/build/ch32-metapac/. Required once after a fresh clone or after bumping the submodule sha; safe to re-run (no-op if outputs are already present):

cargo run --manifest-path xtask/Cargo.toml -- --bootstrap-only

Building algos

Each algo crate's .cargo/config.toml pins its target triple, so cargo only picks it up when run from inside the crate:

cd algos/v0
cargo build --release

Generating target YAMLs

Runs the bootstrap (if needed), builds every algo, walks ch32-data/build/data/chips/, and emits one probe-rs YAML per (chip × memory_option) into generated/ (gitignored):

cargo run --manifest-path xtask/Cargo.toml

Bumping ch32-data

cd ch32-data && git fetch && git checkout <new-sha> && cd ..
rm -rf ch32-data/build
cargo run --manifest-path xtask/Cargo.toml
git add ch32-data && git commit -m "bump ch32-data to <new-sha>"

Formatting

cargo fmt --all from the repo root reaches into the generated ch32-data/build/ch32-metapac/ path dep and complains about code we don't own. Mirror CI instead:

find algos algos-ch5xx xtask -name '*.rs' -not -path '*/target/*' -print0 \
  | xargs -0 rustfmt --edition 2024

License

Dual-licensed under MIT or Apache-2.0 at your option.