SPI reliability: fix PE03 frame drops (RX-drain) + SPI_DIAG build; retire panel_master

[mbreiser]

Summary

Fixes the flickery-display / occasional PE03 seen during arena-master streaming bring-up, adds a silent on-demand SPI diagnostic build that found it, and retires the panel_master bench harness now that the real arena master is available. All at the arena's actual ~5 MHz operating point — no SPI rewrite; the PIO+DMA work remains future-proofing for >10 MHz.

The fix (headline): PE03 rejected frames — last-byte drop

custom_spi_read_blocking() broke out of the receive loop the instant gpio_get(cs_pin) read high. The final data byte's last SCK edge can precede the CS rising edge by less than the RP2350 RX-path latency (input synchronizer + SSP RX pipeline), so that byte wasn't spi_is_readable() yet when CS was sampled high → the read returned one byte short → check_length() failed → PE03.

Fix: after CS-high, drain any straggler bytes still arriving in the RX FIFO before returning, bounded by RX_DRAIN_SETTLE consecutive empty polls (reset on each read) so a finished/truncated transaction still exits promptly and can never hang. CS is high during the drain, so no next-transaction bytes can enter the FIFO.

Diagnostic key finding: parity never failed — only length, almost all got = expected − 1. So it was framing, not signal integrity.

What's in this PR (5 commits)

1. panel: make DEVEL serial heartbeat non-blocking — the per-1000-message heartbeat could stall core 0 between transactions; now it builds one line and writes only when the USB-CDC FIFO has room.
2. Retire panel_master harness; add high-speed SPI bench protocol — panel_master (≈250 kHz bitbang stand-in) removed; bench docs point at the real arena master; new panel/bench/handoff-spi-highspeed-bench.md.
3. panel: fix PE03 rejected frames — drain RX FIFO after CS-high — the fix above.
4. panel: add SPI_DIAG diagnostic build + ignore sub-minimum runts — new pico_v021_spidiag / pico_v031_spidiag envs (-DSPI_DIAG=1): behaves like production but silently tallies per-check fail counts, a per-command histogram, and a ring of the last 32 failures with got-vs-expected byte counts; d dumps in one burst, z zeros. Also: transactions below MESSAGE_MINIMUM_SIZE (1–2 byte CS glitch / aborted clock) no longer raise a glyph that would blank a streaming display (still counted by SPI_DIAG).
5. bench: fold canonical-spec facts into high-speed SPI protocol doc — controller clocks ~5 MHz today (g6_07); 30 MHz is aspirational/unmeasured; shared-CIPO + column-buffer topology; ≥0.5 ms CS-gap target.

Validation (v0.3.1 panel + arena master, via SPI_DIAG)

config	messages	rejects
GS2 / 200 Hz — before fix	24,130	10 (5× got=exp−1, 5× got=1)
GS2 / 200 Hz — after fix	24,101	0
GS16 — after fix	24,117	0
cumulative (GS2→GS16) — after fix	229,726	0

Production builds (pico_v021, pico_v031) and the *_spidiag builds all compile; the fix lives in panel_spi_custom.cpp, so production carries it too.

Notes / follow-ups

• The got=1 runts are a real ~1-byte CS glitch or master short-transaction (the drain actually recovered them). Source unconfirmed — a Saleae peek or a note to Frank would close it; low priority since they no longer affect the display.
• The PIO+DMA SPI-slave rewrite stays gated as future-proofing for the >10 MHz aspiration (see panel/bench/handoff-spi-highspeed-bench.md).

🤖 Generated with Claude Code