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`.
+63 -22
View File
@@ -17,9 +17,22 @@
#define SND_I2S_PORT I2S_NUM_0
#define SND_CHUNK 128 // samples per i2s_write call
#define SND_FADE_MS 8 // fade in/out to avoid clicks
#define SND_DMA_BUFS 8 // TX DMA ring: buffer count (cfg.dma_buf_count)
#define SND_DMA_LEN 64 // ... and samples per buffer (cfg.dma_buf_len)
// Ring capacity in samples: 512 = 64 ms of audio at 8 kHz. Playback lags
// i2s_write() by up to this much — see purgeRing().
#define SND_RING_SAMPLES (SND_DMA_BUFS * SND_DMA_LEN)
bool SoundEngine::begin()
bool SoundEngine::begin(bool spawnTask)
{
// Queue first: the headless tests call begin(false) in environments
// without an audio device, where i2s_driver_install() legitimately fails
// (the shim just runs silent) — the render path itself must still work.
q_ = xQueueCreate(12, sizeof(SndEvent));
if (q_ == nullptr) {
return false;
}
i2s_config_t cfg = {};
cfg.mode = (i2s_mode_t)(I2S_MODE_MASTER | I2S_MODE_TX);
cfg.sample_rate = SND_SAMPLE_RATE;
@@ -27,8 +40,8 @@ bool SoundEngine::begin()
cfg.channel_format = I2S_CHANNEL_FMT_ONLY_LEFT;
cfg.communication_format = I2S_COMM_FORMAT_STAND_I2S;
cfg.intr_alloc_flags = ESP_INTR_FLAG_LEVEL1;
cfg.dma_buf_count = 8;
cfg.dma_buf_len = 64;
cfg.dma_buf_count = SND_DMA_BUFS;
cfg.dma_buf_len = SND_DMA_LEN;
if (i2s_driver_install(SND_I2S_PORT, &cfg, 0, NULL) != ESP_OK) {
return false;
@@ -46,9 +59,8 @@ bool SoundEngine::begin()
pins.mck_io_num = I2S_PIN_NO_CHANGE;
i2s_set_pin(SND_I2S_PORT, &pins);
q_ = xQueueCreate(12, sizeof(SndEvent));
if (q_ == nullptr) {
return false;
if (!spawnTask) {
return true; // tests drive pumpOne() by hand
}
// Render on core 0; the game loop runs on core 1.
@@ -70,21 +82,50 @@ void SoundEngine::trampoline(void *arg)
void SoundEngine::task()
{
for (;;) {
SndEvent e;
xQueueReceive(q_, &e, portMAX_DELAY);
switch (e.type) {
case SND_TONE: renderTone(e.freq, e.dur, e.amp); break;
case SND_SWEEP: renderSweep(e.freq, e.freq2, e.dur, e.amp); break;
case SND_NOISE: renderNoise(e.dur, e.amp); break;
}
// After the LAST queued event the I2S TX DMA ring would keep
// replaying its remaining ~64 ms of buffer forever — heard as the
// sound's tail (rocket sweep, melody tone) repeating endlessly.
// Zero the ring once the queue is empty (not between queued events,
// which would punch silence-gaps into back-to-back melodies).
if (uxQueueMessagesWaiting(q_) == 0) {
i2s_zero_dma_buffer(SND_I2S_PORT);
}
pumpOne();
}
}
// One render-loop iteration: take the next queued event, render it, and —
// once nothing else is queued — flush the TX DMA ring with silence. Public
// test seam: the headless tests call this directly (deterministic, no task
// thread); task() simply loops it on the device.
void SoundEngine::pumpOne()
{
if (q_ == nullptr) return;
SndEvent e;
xQueueReceive(q_, &e, portMAX_DELAY);
switch (e.type) {
case SND_TONE: renderTone(e.freq, e.dur, e.amp); break;
case SND_SWEEP: renderSweep(e.freq, e.freq2, e.dur, e.amp); break;
case SND_NOISE: renderNoise(e.dur, e.amp); break;
}
// Flush only after the LAST queued event — between queued events a flush
// would punch silence gaps into back-to-back melodies.
if (uxQueueMessagesWaiting(q_) == 0) {
purgeRing();
}
}
// Overwrite the whole TX DMA ring with silence so the DMA wrap-around cannot
// replay the sound's tail. This MUST be paced i2s_write() calls, NOT
// i2s_zero_dma_buffer(): the legacy driver's zero_dma memsets the entire ring
// instantly, erasing everything not yet played. Any sound that fits inside
// the ring (512 samples = 64 ms @ 8 kHz — every short beep in the game) was
// written into free ring space without ever blocking, so the zeroing wiped it
// before the DMA reached a single sample: silent on hardware, while longer
// tones survived because i2s_write blocks on a full ring and paces rendering
// to real-time playback. Writing zeros through i2s_write instead reuses each
// DMA buffer only after the DMA has finished playing it — the sound plays out
// fully, and the ring then loops silence (no tail replay either).
void SoundEngine::purgeRing()
{
static int16_t silence[SND_CHUNK]; // zero-initialized
for (uint32_t n = 0; n < SND_RING_SAMPLES + SND_CHUNK; n += SND_CHUNK) {
size_t bw;
i2s_write(SND_I2S_PORT, silence, sizeof(silence), &bw, portMAX_DELAY);
}
}
@@ -126,7 +167,7 @@ static inline uint32_t scaledAmp(uint16_t amp, uint8_t vol)
// Fade envelope over the first/last SND_FADE_MS of the whole event
static inline uint32_t envelope(uint32_t pos, uint32_t total, uint32_t fade, uint32_t amp)
{
if (fade * 2 > total) fade = total / 2;
if (fade * 4 > total) fade = total / 4;
uint32_t s = amp;
if (pos < fade) s = s * pos / fade;
uint32_t tail = total - pos;
+10 -1
View File
@@ -32,9 +32,17 @@ class SoundEngine {
public:
static const uint8_t VOL_MAX = 8;
bool begin();
// spawnTask=false: headless tests create the queue but drive pumpOne()
// by hand (no task thread, fully deterministic).
bool begin(bool spawnTask = true);
void play(const SndEvent &e);
// One iteration of the render loop: take the next queued event, render
// it, and once nothing else is queued flush the TX DMA ring with silence.
// Public so the headless tests can step the sound pipeline
// deterministically; task() simply loops this forever.
void pumpOne();
// Master volume, applied to every rendered sound
void volumeUp();
void volumeDown();
@@ -45,6 +53,7 @@ public:
private:
static void trampoline(void *arg);
void task();
void purgeRing();
void renderTone(uint16_t freq, uint16_t durMs, uint16_t amp);
void renderSweep(uint16_t freq0, uint16_t freq1, uint16_t durMs, uint16_t amp);
void renderNoise(uint16_t durMs, uint16_t amp);