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
+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;