meta: CH32V bench-readiness sweep - deployment-strategy audit + 13 findings (post-#1102)

[zackees]

Follow-up sweep to #1102 (closed today by PRs #1110–#1116), run against main @ 69b51cf ahead of the CH32V hardware bench test in two days (2026-07-23). Two questions: (1) what bugs remain in the CH32V pipeline, and (2) is the deployment strategy right, or do we need a different one / several? Cross-checked against the pinned OpenWCH core (arduino_core_ch32 @ d767162), WCH datasheets (wch-ic.com; mirrors cited below — FastLED/datasheets has no WCH docs yet, see FastLED/datasheets#6), the WCH-Link User Manual V2.3, and the wlink/wchisp/minichlink/probe-rs/Community-PIO sources.

TL;DR in plain terms

• Main is broken right now: fix(ch32v): validate framework selection #1114 shipped a one-line syntax error, so fbuild does not compile and CI on main is red (fix(ch32v): main fails to compile - adjacent string literals in validate_ch32v_framework format! (#1114 regression) #1117). Fix that first — nothing else can ship until it lands.
• The scariest bench bug is invisible in a blink test: no clock-init macro is ever passed to the core, so every CH32V boots at its slow reset clock (a V203 runs at 8 MHz while F_CPU claims 144 MHz). Blink and serial look fine because the core's own timekeeping is consistently slow — but FastLED's cycle-counted WS2812 waveforms come out 18× too slow, i.e. dead LEDs (fix(ch32v): no SYSCLK_FREQ_* define injected - all CH32V firmware runs at reset-default HSI (2-18x under-clocked) #1119).
• Windows can't even build the bigger chips since the fix(ch32v): honor board ISA and ABI settings #1113 ISA fix exposed a missing C++ include path for the toolchain's default multilib — and CI never sees it because the CH32V workflows are Ubuntu-only (fix(toolchain): riscv g++ -isystem set misses the default multilib dir - rv32imac CH32V C++ builds fail on Windows #1118).
• Deployment strategy verdict: the current strategy (build-only + "flash manually with wlink") is honest but not a strategy. One tool is not enough for a probe-free story, but one tool IS enough for full coverage: adopt TWO strategies — wlink + WCH-LinkE probe as the primary deployer (covers all 9 series, Rust, permissively licensed, pinned release assets, matches our probe-rs pattern), and wchisp USB-ISP as the probe-free fallback for the 7 series that have a factory USB bootloader (feat(deploy): CH32V wlink deployer - primary flashing strategy (WCH-LinkE, all 9 series) #1123, feat(deploy): wchisp USB-ISP fallback deployer for USB-bootloader CH32V parts #1124). CH32V003/V006 physically cannot be flashed without a probe (no USB, bootloader unreachable on a blank chip), so a probe-free-only plan is impossible. Do not adopt PlatformIO's default OpenOCD fork — WCH distributes it without a license file, source by email only; unshippable (details below).

Sub-issues (work top-down; one PR per issue)

Blocks the bench (fix before 2026-07-23):

• fix(ch32v): main fails to compile - adjacent string literals in validate_ch32v_framework format! (#1114 regression) #1117 — CRITICAL — main fails to compile (adjacent string literals from fix(ch32v): validate framework selection #1114). Everything is behind this.
• fix(toolchain): riscv g++ -isystem set misses the default multilib dir - rv32imac CH32V C++ builds fail on Windows #1118 — CRITICAL — riscv g++ -isystem misses the default multilib → all rv32imac C++ builds fail on Windows (the bench box).
• fix(ch32v): no SYSCLK_FREQ_* define injected - all CH32V firmware runs at reset-default HSI (2-18x under-clocked) #1119 — CRITICAL — inject SYSCLK_FREQ_* from board f_cpu+clock_source; today all firmware runs 2–18× under-clocked and FastLED timing is broken.
• fix(monitor): fbuild monitor never streams serial lines; bare invocation returns immediately; default port is /dev/ttyUSB0 on Windows #1122 — CRITICAL (bench loop) — fbuild monitor never streams serial lines; use fbuild serial probe read on the bench until fixed.
• fix(ch32v): restore -DCH32V30x_D8 on genericCH32V303VCT6 - V303 HAL compiles with V307 (D8C) register/IRQ layout #1120 — HIGH — V303 HAL compiles as V307/D8C against a D8 vector table (restore -DCH32V30x_D8); IRQs ≥ 58 misroute.
• fix(ch32v): CH32V203RB links the D6 startup/vector table while HAL compiles as D8 #1121 — HIGH — V203RB links the D6 startup/vector table with a D8 HAL (bug-compatible with PlatformIO; fix is a deliberate divergence). Only matters if RB hardware benches with TIM5/extended IRQs.

Deployment strategy (decision above; implementation):

• Add WCH identities: WCH-Link(E) probe (1a86:8010/8012), CH32 ISP bootloader (4348:55e0, 1a86:55e0), CH32V board entries boards#56 — registry: WCH-Link (1a86:8010/8012) + ISP bootloader (4348:55e0, 1a86:55e0) + CH32V board entries. Prerequisite for feat(deploy): CH32V wlink deployer - primary flashing strategy (WCH-LinkE, all 9 series) #1123/feat(deploy): wchisp USB-ISP fallback deployer for USB-bootloader CH32V parts #1124 device matching (repo rule: no VID/PIDs in fbuild).
• feat(deploy): CH32V wlink deployer - primary flashing strategy (WCH-LinkE, all 9 series) #1123 — HIGH — wlink deployer (primary; all 9 series via WCH-LinkE; pinned v0.1.2 assets; supersedes the ch32v: deploy is unimplemented while board JSONs advertise wch-link/minichlink/isp/wlink and docs say Supported #1105 Phase-2 outline).
• feat(deploy): wchisp USB-ISP fallback deployer for USB-bootloader CH32V parts #1124 — MEDIUM — wchisp USB-ISP fallback deployer (7 USB-bootloader series; pinned v0.3.0; GPL-2.0 invoked as external binary).
• fix(boards): drop 'isp' protocol from CH32V003/CH32V006 board JSONs - parts have no reachable ISP bootloader #1125 — MEDIUM — drop the bogus "isp" protocol from the six CH32V003/V006 board JSONs.
• fix(serial): family_from_usb_profile requires platform 'espressif32' but registry publishes 'esp32' #1126 — MEDIUM — serial classifier expects platform == "espressif32", registry publishes "esp32" — fix before the new WCH registry rows are dead on arrival.

Hygiene / follow-ups:

• chore(ch32v): patch_backup_header is a silent no-op against the pinned core; obsolete test + redundant X035 define #1127 — MEDIUM — patch_backup_header silent no-op + obsolete test + redundant X035 define.
• perf(ch32v): V303/V307 build soft-float despite QingKe V4F FPU - evaluate rv32imafc/ilp32f #1128 — MEDIUM — V303/V307 soft-float despite FPU (perf; depends on fix(toolchain): riscv g++ -isystem set misses the default multilib dir - rv32imac CH32V C++ builds fail on Windows #1118's multilib fix).
• chore(ch32v): LOW batch - toolchain checksums, silent series fallback, dead JSON fields, variant pin-map docs, DTR/RTS matrix rows, deploy-message nits #1129 — LOW batch — toolchain sha256s, silent series fallback, dead JSON fields, variant pin-map docs, DTR/RTS matrix rows, deploy-message nits.
• Add wch/ vendor tree: datasheets + reference manuals for CH32V003/V006/V103/V203/V208/V30x/X035/L103 + WCH-Link datasheets#6 — add wch/ vendor tree (datasheets + reference manuals + WCH-Link manual) so future audits cite pinned documents instead of mirrors.

Deployment strategy — the audit in full

Why not one strategy? The chips split into two hardware classes:

Class	Chips	Flash paths that exist	Probe-free possible?
SDI-only	CH32V003, CH32V006	1/2-wire SDI (WCH-LinkE only — old WCH-Link can't do it); UART bootloader exists but is software-entry-only (no BOOT pin) → unreachable on a blank chip	No
USB-bootloader	V103, V203, V208, V303, V307, X035, L103	SWD/SDI probe; factory USB+UART ISP via BOOT0 (X035: PC16/PC17 power-on trick, no BOOT pin)	Yes (wchisp)

Tool ranking for fbuild (full matrix + sources in #1123/#1124):

1. wlink v0.1.2 (primary): all 9 series, one code path, Rust, MIT/Apache-2.0, per-OS release assets → fits our pinned-flasher model exactly. Gaps: no linux-aarch64/macos-x64 assets; "not production ready" disclaimer → smoke-test per family before bench day.
2. wchisp v0.3.0 (fallback): probe-free for the USB class; needs user BOOT0 entry + WinUSB driver on Windows; stable release does NOT support V00x.
3. probe-rs (fast-follow): native WCH-Link driver + released CH32V0/V2/V3 flash algorithms in v0.31.0; V103/X035/L103/V006 targets master-only. Cheap for us later since we already pin probe-rs — not for bench day.
4. minichlink: keep as the manual fallback it already is in our error message; no release binaries of its own.
5. WCH OpenOCD fork (PlatformIO's default wch-link protocol): no license file, source by email — do not pin or redistribute. Our board JSONs keep the wch-link protocol name for PIO parity, but fbuild should never ship that binary.

Board-JSON parity check: our protocols: ["wch-link","minichlink","isp","wlink"] matches Community-PIO exactly — correct except the isp entry on V003/V006 (#1125, PIO's list is equally wrong there).

Bench-day recipe that works on current main (once #1117 lands)

1. soldr cargo run -p fbuild-cli -- build tests/platform/<env> -e <env> (on Windows, non-V003 targets also need fix(toolchain): riscv g++ -isystem set misses the default multilib dir - rv32imac CH32V C++ builds fail on Windows #1118).
2. Flash: wlink flash <project>/.fbuild/build/<env>/firmware.bin with a WCH-LinkE (firmware ≥ 2.15, RV mode — if it enumerates as 1a86:8012 run wlink mode-switch). Old CH549 WCH-Link cannot flash V003/V006/X035/L103.
3. Monitor: fbuild serial probe list → fbuild serial probe read --port COMx --baud 115200 --seconds N (NOT bare fbuild monitor — fix(monitor): fbuild monitor never streams serial lines; bare invocation returns immediately; default port is /dev/ttyUSB0 on Windows #1122), or Python fbuild.api.SerialMonitor.
4. Pre-install Windows drivers before the bench: WCH-LinkE RV mode WinUSB (via WCH-LinkUtility/MounRiver); Zadig WinUSB for 55e0 if trying ISP.
5. Expect under-clocked firmware until fix(ch32v): no SYSCLK_FREQ_* define injected - all CH32V firmware runs at reset-default HSI (2-18x under-clocked) #1119 lands — LED protocol tests will fail even on a good flash; X035 blink runs visibly ~6× slow.

Verified reference facts

• Bootloader matrix, probe-capability table (which Link flashes which chip), and USB identities are recorded in feat(deploy): CH32V wlink deployer - primary flashing strategy (WCH-LinkE, all 9 series) #1123/feat(deploy): wchisp USB-ISP fallback deployer for USB-bootloader CH32V parts #1124/Add WCH identities: WCH-Link(E) probe (1a86:8010/8012), CH32 ISP bootloader (4348:55e0, 1a86:55e0), CH32V board entries boards#56 with per-claim sources: WCH-LinkUserManual V2.3 Table 5 (Olimex mirror), CH32V003/V20x/X035 datasheets (wch-ic.com / akizukidenshi mirrors), wchisp device YAMLs, probe-rs wlink driver, basilhussain/ch32v003-bootloader-docs, Community-PIO-CH32V builder scripts.
• Chip memory/ISA table (flash/RAM/_eusrstack/march) is unchanged from meta: CH32V deployment-pipeline audit — 7 defects from board JSON to deploy #1102 and re-verified this sweep; board JSON rom/ram/march/mabi/f_cpu all check out against datasheets (V103 correctly 72 MHz, not 144).
• Confirmed non-issues this sweep (so nobody re-audits them): defsym wiring for all series incl. 32K/10K V203C6 and 128K/64K RB/208; normalize_march output accepted by xPack GCC 14.2.0-3; series→system-dir mapping for all 9 families incl. v006→CH32VM00X and v208→CH32V20x; V208 D8W startup; variant dirs exist at the pinned commit; hwids-free board JSONs (registry rule compliant); CI path filters post-fix(ci): update CH32V path filters after crate split #1110; all 9 test envs framework = arduino.

Sweep run 2026-07-21 with four independent audit passes (build pipeline, board data, deploy/serial, deployment-strategy research); every CRITICAL/HIGH was re-verified by hand before filing.