CH32V003 hardware bring-up: validate the existing CH32V pipeline on real silicon

[zackees]

Summary

A physical CH32V003 is now on the bench. fbuild's CH32V support was built out across #1102/#1130 and is green in CI, but every bit of it has only ever been validated by a compile job — no firmware from this repo has been proven to run on real silicon. This issue is the step-by-step bring-up: take the existing paper support to a verified blink, then close the remaining gaps that only show up with hardware attached.

The FastLED-side platform port is tracked separately in FastLED/FastLED — see the companion issue linked below. This issue stops at "fbuild can build, flash, and talk to a CH32V003."

What already exists (do not rebuild)

Layer	Location	State
Platform::Ch32v	crates/fbuild-core/src/lib.rs:128, :169	done
RISC-V toolchain	crates/fbuild-toolchain/src/toolchain/riscv.rs — xPack riscv-none-elf-gcc 14.2.0-3, per-host SHA-256 table	done
Arduino core	crates/fbuild-library/src/library/ch32v_core.rs — OpenWCH arduino_core_ch32 1.0.4+d767162.ch32l103	done
MCU config	crates/fbuild-build-mcu/src/ch32v/configs/ch32v003.json	done
Orchestrator / compiler / linker	crates/fbuild-build-mcu/src/ch32v/	done
Board JSONs	crates/fbuild-config/assets/boards/json/genericCH32V003*.json (+13 more CH32)	done
Deployers	crates/fbuild-deploy/src/wlink.rs (pinned wlink v0.1.2), wchisp.rs	done, never run against hardware
Deploy dispatch	crates/fbuild-daemon/src/handlers/operations/deploy.rs:809-825	done
Test project	tests/platform/ch32v003/	done
CI	.github/workflows/build-ch32v003.yml from ci/board_families.json:31	green

Verified board record (genericCH32V003F4P6.json): march: rv32ec_zicsr, mabi: ilp32e, f_cpu: 48000000L, rom 16384, ram 2048, upload.protocol: wch-link.

Known gaps

1. No hardware validation of any of the above. Primary purpose of this issue.
2. WCH-LinkE has no USB identity. 1A86:8010 (RV mode) / 1A86:8012 (DAP mode) are absent from the FastLED/boards registry. Per CLAUDE.md these must not be added to this repo — the fix is a PR to FastLED/boards, ingested at runtime via fbuild_core::usb::profiles::profiles_for. Today crates/fbuild-serial/src/boards.rs:613 (test-only table) would wildcard 0x1A86 to Esp32ExternalUart, which is wrong for a probe.
3. No probe-rs support. probe_rs.rs:358 map_board_to_probe_rs_chip() handles only lpc845. Upstream probe-rs does not support CH32 either (probe-rs#28), so this is likely permanent — wlink is the path.
4. Framework locked to arduino. orchestrator.rs:260 validate_ch32v_framework() rejects noneos-sdk and ch32v003fun even though the board JSON advertises them (ch32v: framework field is ignored — noneos-sdk envs silently build the OpenWCH Arduino core (4 of 9 CI envs affected) #1108).
5. No debug. crates/fbuild-cli/src/cli/debug.rs:131 → Platform::Ch32v => DebugSupport::Injected.
6. No emulator. No QEMU rv32; infer_default_emulator_kind returns None for ch32v.
7. minichlink referenced in board JSON upload.protocols but not implemented.

Hardware

• Target: CH32V003F4P6 — RV32EC @ 48 MHz, 16 KB flash / 2 KB SRAM, no hardware multiply, single-wire debug (SWIO), no USB peripheral.
• Programmer: WCH-LinkE (1A86:8010 RV mode). wchisp is not usable — wchisp.rs:152 supports_mcu() correctly excludes V003/V006, which have no factory USB-ISP bootloader (fix(boards): drop 'isp' protocol from CH32V003/CH32V006 board JSONs - parts have no reachable ISP bootloader #1125).
• At time of filing, no VID_1A86 device is enumerated on the bench machine. There is one Unknown USB Device (Device Descriptor Request Failed) at VID_0000&PID_0002 — rule this out (cable/port/hub) as step 0.

Step-by-step

Phase 0 — Establish the probe

• Confirm the WCH-LinkE enumerates as 1A86:8010. If it comes up as 1A86:8012 (DAP mode), hold the button while plugging in to toggle to RV mode.
• Windows: bind WinUSB to the probe interface via Zadig if wlink can't claim it. Record the exact procedure — this is the single most common first-time failure and belongs in the docs.
• wlink status sees the chip and reports the correct flash size. Record the WCH-Link firmware version (wlink v0.1.2 is tested against 2.15).
• Wire SWIO / GND / 3V3 to the target and confirm the chip ID reads back.

Exit criteria: wlink status prints a CH32V003 chip ID.

Phase 1 — Build

• soldr cargo run -p fbuild-cli -- build tests/platform/ch32v003 -e ch32v003
• Confirm the toolchain downloads and validates (riscv-none-elf-gcc 14.2.0-3), and that the rv32ec/ilp32e libgcc multilib is actually present — a missing multilib links rv32i objects and fails on register-count violations.
• Record the produced .bin size against the 16 KB budget.
• Verify SYSCLK_FREQ_* is injected (fix(ch32v): no SYSCLK_FREQ_* define injected - all CH32V firmware runs at reset-default HSI (2-18x under-clocked) #1119 regression guard) — the part must run at 48 MHz, not reset-default HSI.

Exit criteria: a .bin under 16384 bytes.

Phase 2 — First flash (the actual bring-up)

• soldr cargo run -p fbuild-cli -- deploy tests/platform/ch32v003 -e ch32v003 (defaults to the wlink deployer).
• Confirm ensure_wlink_installed() downloads and checksum-verifies the pinned v0.1.2 asset into ~/.fbuild/{prod|dev}/tools/wlink/.
• Observe the blink on a scope or LED. This is the first time fbuild firmware has ever executed on this architecture — a successful flash is not sufficient evidence.
• Verify the 48 MHz clock empirically (toggle a pin in a known-cycle loop and measure), rather than trusting the define.

Exit criteria: measured blink at the expected rate. This is the bring-up milestone.

Phase 3 — Close the hardware-visible gaps

• FastLED/boards PR adding 1A86:8010 and 1A86:8012 with purpose: probe / role: debug-probe. Then re-verify fbuild serial probe list classifies the WCH-LinkE as a probe and not as an ESP32 UART bridge. Do not patch fbuild-serial tables.
• Decide and document the SDI-print / serial story. V003 has no USB, so console output is either SDI-print over the debug link (wlink supports it) or a USART pin to a separate bridge. Whichever is chosen, fbuild serial needs to know about it.
• Add a DTR/RTS matrix row for the WCH-LinkE CDC interface in docs/usb-cdc-control-line-matrix.md.
• Fix boards.rs:613's (0x1A86, _) wildcard so a probe isn't misclassified.

Phase 4 — Harden

• Add a #[ignore = "requires CH32V003 + WCH-LinkE probe"] hardware integration test covering build → flash → verify.
• Update docs/BOARD_STATUS.md: CH32V003 moves from compile-verified to hardware-verified, with the bench setup documented.
• Write up the Zadig/WinUSB procedure and probe-mode toggle in the CH32V README.
• Consider bumping the xPack toolchain to 14.3.0-1 or 15.2.0-1 (both 2025-10-23) — only if Phase 1/2 surface a codegen problem. Not part of bring-up.

Out of scope (file separately if wanted)

• framework = ch32v003fun support (ch32v: framework field is ignored — noneos-sdk envs silently build the OpenWCH Arduino core (4 of 9 CI envs affected) #1108)
• minichlink deployer
• GDB / fbuild debug for CH32V
• QEMU rv32 emulation

References

• wlink — https://github.com/ch32-rs/wlink (v0.1.2)
• ch32fun / minichlink — https://github.com/cnlohr/ch32fun
• OpenWCH Arduino core — https://github.com/openwch/arduino_core_ch32
• Community PlatformIO platform — https://github.com/Community-PIO-CH32V/platform-ch32v
• xPack riscv-none-elf-gcc — https://github.com/xpack-dev-tools/riscv-none-elf-gcc-xpack/releases
• Prior CH32V work: meta: CH32V deployment-pipeline audit — 7 defects from board JSON to deploy #1102, ch32v: deploy is unimplemented while board JSONs advertise wch-link/minichlink/isp/wlink and docs say Supported #1105, fix(toolchain): riscv g++ -isystem set misses the default multilib dir - rv32imac CH32V C++ builds fail on Windows #1118, fix(ch32v): no SYSCLK_FREQ_* define injected - all CH32V firmware runs at reset-default HSI (2-18x under-clocked) #1119, fix(ch32v): restore -DCH32V30x_D8 on genericCH32V303VCT6 - V303 HAL compiles with V307 (D8C) register/IRQ layout #1120, fix(ch32v): CH32V203RB links the D6 startup/vector table while HAL compiles as D8 #1121, fix(boards): drop 'isp' protocol from CH32V003/CH32V006 board JSONs - parts have no reachable ISP bootloader #1125, fix(serial): family_from_usb_profile requires platform 'espressif32' but registry publishes 'esp32' #1126, chore(ch32v): LOW batch - toolchain checksums, silent series fallback, dead JSON fields, variant pin-map docs, DTR/RTS matrix rows, deploy-message nits #1129, meta: CH32V bench-readiness sweep - deployment-strategy audit + 13 findings (post-#1102) #1130

[zackees]

Companion FastLED-side platform port issue: FastLED/FastLED#3755

[zackees]

Tracked by meta issue #1209 (CH32V003 bring-up: this + FastLED/FastLED#3755).

[zackees]

Phase 1 ✅ — verified on real toolchain (#1210, merged as 4544faa5)

First time the CH32V pipeline has run outside CI's compile-only job.

fbuild build tests/platform/ch32v003 -e ch32v003:

Check	Result
xPack riscv-none-elf-gcc 14.2.0-3 download + checksum + validate	✅
ISA / ABI	✅ -march=rv32ec_zicsr -mabi=ilp32e
ELF header	✅ ELF32, RISC-V, Flags 0x9, RVC, RVE, soft-float ABI
rv32ec/ilp32e libgcc multilib	✅ present (link succeeds)
SYSCLK_FREQ_* injected (#1119 guard)	✅ -DSYSCLK_FREQ_48MHZ_HSI=48000000
Flash	✅ 8896 / 16384 B (54.3%)
RAM	1180 / 2048 B (57.6%)

RVE in the ELF flags is the important one — it confirms the E base (16 registers), so the multilib really is RV32EC and not a silent rv32i fallback. That was the Phase 1 risk called out in the issue body.

Worth carrying to FastLED/FastLED#3755: a bare blink already consumes 57.6% of the 2 KB SRAM, leaving ~868 bytes. Tighter than the issue assumed.

Plan corrections

1. Phase 3's FastLED/boards PR is not needed — drop it. The WCH-LinkE is already published with correct semantics:

1a86:8010  purpose=probe       role=debug_probe     family=wch-link      platform=ch32v  prio=1000
1a86:8012  purpose=probe       role=debug_probe     family=wch-link-dap  platform=ch32v  prio=1000
1a86:55e0  purpose=bootloader  role=bootloader_dfu  family=wchisp        platform=ch32v  prio=1000

2. The boards.rs:613 concern was overstated in the issue body. Because the registry sets role=debug_probe alongside purpose=probe, the production path already classified the WCH-LinkE correctly — the wildcard never applied to it. I reordered the probe check ahead of the usb_uart_bridge check anyway as hardening (the two fields are orthogonal in the schema, so the bad combination is representable), but to be accurate: 0 of 3524 live profiles carry purpose=probe + role=usb_uart_bridge, so no live defect was fixed. The cfg(test) wildcard was genuinely wrong and is now narrowed.

New defect found and fixed (was blocking Phase 1)

Phase 1 initially hung silently for ~10 minutes.

The post-spawn readiness poll was bounded by iteration count — for _ in 0..100 with a 100 ms sleep, documented as "up to 10 seconds". That holds only when health() returns instantly, i.e. when the port is refused. When the endpoint times out, each health() burns its own ~2 s request timeout → ~3.5 min per attempt, ~10 min across all three, with zero output.

Reachable in ordinary development: cargo run -p fbuild-cli doesn't build fbuild-daemon, so daemon_executable_hint() finds no sibling and falls back to PATH. Here that resolved to a PyPI-installed v2.5.2 daemon against a local v2.5.4 CLI; since daemon_endpoint_key() hashes CARGO_PKG_VERSION (#1009), they derived different ports (49411 vs 52289) and could never meet. #1009's isolation working as designed, but the failure mode was a silent hang.

Now wall-clock bounded, with the resolved daemon path and that explanation in the error. Workaround for anyone hitting it: soldr cargo build -p fbuild-daemon.

Phases 0 and 2 — still open, blocked on hardware

No WCH device enumerates on this host. The only candidate is an Unknown USB Device (Device Descriptor Request Failed) under null VID 0000:0002 — a cable/port/hub fault, not a driver problem. Charge-only USB cables are the usual culprit.

Phase 2's measured-blink milestone therefore remains unmet. Once a probe enumerates as 1a86:8010:

soldr cargo test -p fbuild-deploy wlink::tests::try_wlink_status_detects_ch32v003 -- --ignored --nocapture

CH32V003_FIRMWARE=tests/platform/ch32v003/.fbuild/build/release/firmware.bin \
  soldr cargo test -p fbuild-deploy wlink::tests::try_flash_real_ch32v003 -- --ignored --nocapture

A firmware binary is already built and sitting at that path from the Phase 1 run.

There is also a no-hardware test that catches a rotted wlink release URL or stale checksum:

soldr cargo test -p fbuild-deploy wlink::tests::try_install_wlink_from_pinned_release -- --ignored --nocapture

Remaining Phase 3/4 items

• Probe bring-up docs (RV/DAP toggle, Zadig WinUSB, SWIO wiring) — in crates/fbuild-build-mcu/src/ch32v/README.md
• DTR/RTS matrix row for WCH-LinkE
• Hardware-gated integration tests
• docs/BOARD_STATUS.md → hardware-verified — deliberately not done, since Phase 2 hasn't happened. Claiming it now would be false.
• SDI-print vs USART console decision — needs the probe to evaluate.

[zackees]

Addendum: wlink acquisition + exit-code semantics validated (no hardware needed)

Ran the new no-hardware test — the deployer's tool-acquisition path had never been exercised before:

installing wlink-v0.1.2-win-x64.zip (v0.1.2)
wlink --version: wlink 0.1.2
test wlink::tests::try_install_wlink_from_pinned_release ... ok

Pinned URL live, SHA-256 matches, extraction works, binary runs. ✅

Also verified the failure semantics the deployer depends on, since WlinkDeployer::deploy decides success purely from the exit code:

Command (no probe attached)	Exit	stderr
wlink status	1	Error: WCH-Link not found, please check your connection
wlink flash <file>	1	Error: WCH-Link not found, please check your connection

wlink exits non-zero on probe-absent, so result.success() is trustworthy — there is no path where a missing probe would be reported as a successful flash. Worth confirming explicitly rather than assuming, since a false success here would be the worst possible failure mode for a bring-up.

The error text is also clear enough to surface verbatim, so no extra wrapping is needed in the deployer.

[zackees]

Status: all software-reachable work complete; Phases 0 & 2 blocked on physical hardware

Merged: #1210 (4544faa5), #1211 (e7c594ac).

Phase	State
0 — probe enumerates	⛔ blocked — no WCH device on this host
1 — build → <16 KB .bin	✅ flash 8896/16384 (54.3%), RAM 1180/2048 (57.6%), ELF RVC, RVE, soft-float
2 — flash → measured blink	⛔ blocked on Phase 0
3 — close gaps	✅ all software items; FastLED/boards PR found unnecessary
4 — harden	✅ except BOARD_STATUS.md, deliberately left at compile-verified

Why Phases 0/2 can't be closed from software

Get-PnpDevice reports 0 devices under VID 1A86. The only candidate is:

USB\VID_0000&PID_0002\6&3AF0F9CE&0&14
Unknown USB Device (Device Descriptor Request Failed)
ProblemCode 43 (CM_PROB_FAILED_POST_START), Port_#0014.Hub_#0001, parent USB\ROOT_HUB30

A null VID with code 43 means the device never returned a valid descriptor — electrical/cable-level, not driver state. I attempted forced re-enumeration via Disable-PnpDevice/Enable-PnpDevice and pnputil /restart-device; both failed (Access is denied — session is not elevated), and I did not escalate privileges unattended. Even elevated, re-enumeration rarely recovers a code-43 null-VID device. There is also no evidence this device is the WCH-LinkE at all.

The physical action that unblocks it

1. Replace the USB cable — charge-only cables are the most common cause of exactly this signature. Plug directly into a root port, no hub.
2. Confirm it enumerates as 1A86:8010. If it comes up 1A86:8012 (DAP), run wlink mode-switch --rv, or hold the button while plugging in if wlink can't reach it yet.
3. Windows: bind WinUSB to the probe interface with Zadig.
4. Wire SWIO/GND/3V3 (or wlink set-power enable3v3).

Then Phase 0 and Phase 2 are two commands — the firmware is already built and waiting:

soldr cargo test -p fbuild-deploy wlink::tests::try_wlink_status_detects_ch32v003 -- --ignored --nocapture

CH32V003_FIRMWARE=tests/platform/ch32v003/.fbuild/build/release/firmware.bin   soldr cargo test -p fbuild-deploy wlink::tests::try_flash_real_ch32v003 -- --ignored --nocapture

And then observe the blink. A passing flash is not the milestone; the test says so in its own output.

Deliberately not done

docs/BOARD_STATUS.md still says compile-verified. Promoting it to hardware-verified before anyone has seen the part run would be a false claim, and BOARD_STATUS is exactly where that claim would be trusted. It should flip in the same commit that records the observed blink.

Leaving this issue open — the bring-up milestone is genuinely unmet.

[zackees]

Phase 2 harness strengthened — #1212 (bc233927)

wlink flash exiting 0 only means the tool accepted the write. Two new hardware-gated tests close the gap between that and "the firmware is on the chip and running":

• try_verify_flash_readback_ch32v003 — dumps flash from 0x08000000 and byte-compares against the image, reporting the first differing offset. Catches partial writes, wrong base address, write-protected flash. The flash exit code distinguishes none of these.
• try_ch32v003_core_is_executing — resumes and samples registers twice 250 ms apart, asserting state advanced. Distinguishes flashed but halted / fault-looping from running — readback alone cannot.

Bench sequence now documented in the CH32V README, ordered so each step rules out a failure the previous can't see:

status → build → flash → readback → core-executing → observe blink (manual)

These are proxies, not the milestone. They prove the image is on-chip and the CPU is retiring instructions; they say nothing about GPIO toggling at the right rate. I made both tests state that in their output rather than let a green suite imply a bring-up that hasn't happened.

---

Where this issue stands

Three PRs merged: #1210, #1211, #1212. Every software-reachable item in this issue is now done. What remains is not a software task:

Phase 2 exit criteria: "measured blink at the expected rate."

That is a physical observation. It requires a working probe, jumper wires to the target, and a scope or LED. I have exhausted the automation side — including building the strongest available software proxies above — and I cannot perform the observation itself.

The hardware blocker, restated precisely

Get-PnpDevice reports 0 devices under VID 1A86. The sole candidate is USB\VID_0000&PID_0002, problem code 43 (CM_PROB_FAILED_POST_START) on Port_#0014.Hub_#0001. A null VID with code 43 means the device never returned a valid descriptor — electrical, not driver state.

Remediation attempted and failed: Disable-PnpDevice/Enable-PnpDevice and pnputil /restart-device both returned Access is denied (session not elevated). I did not escalate privileges unattended. Even elevated, re-enumeration rarely recovers a code-43 null-VID device — and there is no evidence this device is the WCH-LinkE at all.

One physical action unblocks everything

Swap the USB cable — charge-only cables produce exactly this signature — directly into a root port, no hub. Then the five commands in the README's bench sequence run end to end; firmware.bin is already built and waiting from the Phase 1 run.

Leaving this open. The bring-up milestone is unmet, and closing it would misrepresent the state of the port.