Fix short beeps silent on HW: i2s_zero_dma_buffer erased the unplayed DMA ring

The legacy I2S driver buffers i2s_write() data in a TX DMA ring
(8x64 samples = 64 ms @ 8 kHz) and hands a buffer back to i2s_write()
only after the DMA finished playing it. After the last queued event
the sound task called i2s_zero_dma_buffer(), which memsets the whole
ring instantly — erasing everything not yet played. Any sound <= 64 ms
was written into free ring space without ever blocking, so the zeroing
wiped it before the DMA reached a single sample: completely silent on
hardware. Longer tones force i2s_write() to block on a full ring,
pacing rendering to real-time playback — hence only long beeps were
audible, and the fade-envelope cap never moved the threshold. Every
game beep <= 80 ms (link-active 10, laser 30, sever 40, bleep/ICE 50,
feedback 80) sat in the dead zone. The emulator never showed it: its
i2s_write shim fed SDL directly and had no ring at all.

Fix: replace the instant zeroing with a paced silence purge — once the
queue drains, write one ring + one chunk of zero samples through
i2s_write(), reusing each DMA buffer only after the DMA played it. The
sound plays out fully and the ring then loops silence (still kills the
tail-replay bug the zeroing existed for). Keep the envelope cap at
total/4 so short tones keep a steady-state portion.

Emulator shim gains a TX DMA ring model (write/play cursors + bounded
DAC-emitted log) so the bug class reproduces headlessly: unit/
sound_short_tone_reaches_dac fails on the zero_dma code, passes on the
purge (A/B verified); shim_zero_dma_erases_unplayed pins model fidelity;
sound_long_tone_plays_out_fully guards against truncation. SoundEngine
gains a pumpOne() test seam and begin(spawnTask) for deterministic
driving. Full suite: 26 unit + 7 integration + 4 E2E, 0 failures.
This commit is contained in:
Dejvino
2026-11-15 12:19:21 +01:00
parent 8008b78db0
commit 7df1a2d785
6 changed files with 303 additions and 24 deletions
+41
View File
@@ -202,3 +202,44 @@ contact-bounce collapse (the proven `CrtTerminal` pattern). The
emulator gained a GPIO-matrix pin-ownership model + edge-accurate ISR
latch so this class of bug reproduces there (`e2e/trackball_click`
fails on the old code, passes on the fix) — see [HW.md](HW.md).
### Sound fix: short beeps silent on hardware (fixed this commit)
Two stacked defects, and both only bite real hardware — the emulator's
`i2s_write` shim fed SDL directly and had no DMA ring, so neither ever
reproduced there:
1. **TX DMA ring zeroing erased short sounds entirely (the real killer).**
The legacy I2S driver copies `i2s_write()` data into a TX DMA ring
(8 × 64 samples = 512 samples = **64 ms** @ 8 kHz) and consumes it at the
sample rate; a buffer is handed back to `i2s_write()` only after the DMA
finished playing it. After the last queued event the sound task called
`i2s_zero_dma_buffer()`, which memsets the whole ring instantly — erasing
everything not yet played. Any sound ≤ 64 ms was written into free ring
space without ever blocking, so the render finished in microseconds and
the zeroing wiped it before the DMA reached a single sample:
**completely silent**. Sounds longer than the ring force `i2s_write()` to
block, pacing rendering to real-time playback, so their beginning had
already played — which is why only long beeps were audible and the
threshold never moved with the fade envelope. Every game beep ≤ 80 ms
(link-active 10 ms, laser 30 ms, sever 40 ms, bleep/ICE 50 ms, feedback
80 ms) sat in that dead zone. Fix: replace the instant zeroing with a
**paced silence purge** — once the queue drains, write one ring + one
chunk of zero samples through `i2s_write()`, which reuses each DMA buffer
only after the DMA finished playing it. The sound plays out fully, then
the ring loops silence (the zeroing existed to stop the tail replaying
forever; the purge still does that job, without the erase race).
2. **Fade envelope ate short tones.** `envelope()` capped the fade at
`total / 2`, so a 10 ms tone (80 samples) spent its whole duration in
fade-in + fade-out — zero steady-state samples even if the samples had
reached the DAC. Fix: cap at `total / 4` (10 ms tone now keeps ~41
steady-state samples; ≥ 50 ms tones unchanged).
The emulator shim gained a TX DMA ring model (write/play cursors + a bounded
"what the DAC emitted" log) so this class of bug reproduces headlessly:
`unit/sound_short_tone_reaches_dac` fails on the zero_dma code and passes on
the purge (A/B verified), `unit/sound_long_tone_plays_out_fully` guards the
purge against truncating long tones, and `unit/shim_zero_dma_erases_unplayed`
pins the model's fidelity to the legacy driver semantics. Reflash required:
`pio run -t upload`.