fbuild debug: no-probe GDB debugging via injected/native monitor stubs (+ fbuild crashdump)

[zackees]

Proposal from the FastLED/soundwave debug-architecture work (see soundwave's "Programming and debug architecture" README section, and issues FastLED/soundwave#36 + FastLED/soundwave#38): make no-probe GDB debugging a build-tool feature, not a library feature.

Why fbuild owns this (analysis summary)

A monitor-mode GDB stub has two halves. The on-device half is a small per-architecture component; the host half is pure orchestration -- build flags, injection, flashing, port discovery, gdb attach, symbols. The orchestration half is a build-tool verb by nature (dev builds carry the stub, release builds strip it -- a decision only the build system can make). And the per-target reality seals it: several targets already HAVE native stubs (ESP32's ROM/IDF gdbstub), some can host an injected one (RISC-V/CH32V via EBREAK + trap handler), and some can't have one at all (AVR: no trap architecture). A tool can express that capability matrix honestly; a library (e.g. FastLED itself) cannot -- it would be a single-target feature wearing a cross-platform badge, plus trap-vector/interrupt ownership conflicts with cycle-critical LED drivers. FastLED core stays untouched; at most a future docs/example integration.

Proposed verbs

• fbuild debug: build with the stub enabled (injected or native per target) -> flash -> discover the CDC/serial port -> launch gdb -ex "target remote ..." with the right ELF/symbols. One command from source to breakpoint.
• fbuild crashdump: offload a persisted crash dump (registers + stack saved to flash at fault time) over CDC and open GDB against it for post-mortem analysis.

Per-target capability matrix (initial)

Target	Mechanism	Status
CH32V (RISC-V, e.g. soundwave's CH32V203)	injected stub (EBREAK + trap handler, CDC transport) -- reference implementation tracked in FastLED/soundwave#38	first target
ESP32 family	orchestrate the existing native IDF/ROM gdbstub -- no code injection needed	high value, low effort
ARM targets (Teensy, STM, nRF, RP2040)	DebugMon/BKPT-based monitor stubs exist per-family; evaluate individually	later
AVR	no trap architecture -- honestly unsupported	never (documented)

Requirements

• Stub injection is dev-build-only and fully absent from release builds (flag-gated at the fbuild level)
• Port discovery: find the target's CDC interface automatically (VID/PID or probe)
• Capability matrix surfaced in tooling output ("debug not supported on " is a first-class message, not a cryptic failure)
• Symbol/ELF plumbing: gdb launches with the exact build's symbols
• Crash-dump format defined jointly with the on-device side (FastLED/soundwave#38) so fbuild crashdump decodes it
• Docs: the ownership split (stub = firmware component, orchestration = fbuild, FastLED core uninvolved)

Known limits (accepted, documented)

Self-hosted debug dies with the core it rides on: a wedged core, early boot, or bugs in the USB/CDC stack itself need external hardware (for CH32V: RVSWD via WCH-Link -- soundwave's SBU dongle, FastLED/soundwave#36). fbuild debug targets the ~80-90% of debugging hours that don't.

🤖 Generated with Claude Code