From 7df1a2d785dbfeb4745fcda1ba3eee860ebc7878 Mon Sep 17 00:00:00 2001 From: Dejvino Date: Sun, 15 Nov 2026 12:19:21 +0100 Subject: [PATCH] Fix short beeps silent on HW: i2s_zero_dma_buffer erased the unplayed DMA ring MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- emulator/src/shim/driver/i2s.h | 75 +++++++++++++++++++++++++- emulator/tests/harness.h | 17 ++++++ emulator/tests/unit_tests.h | 98 ++++++++++++++++++++++++++++++++++ src/netdeck/STATUS.md | 41 ++++++++++++++ src/netdeck/sound_engine.cpp | 85 +++++++++++++++++++++-------- src/netdeck/sound_engine.h | 11 +++- 6 files changed, 303 insertions(+), 24 deletions(-) diff --git a/emulator/src/shim/driver/i2s.h b/emulator/src/shim/driver/i2s.h index 95eb89e..4e30d6a 100644 --- a/emulator/src/shim/driver/i2s.h +++ b/emulator/src/shim/driver/i2s.h @@ -5,6 +5,8 @@ #pragma once #include #include +#include +#include #include #include "../Arduino.h" // emu::claimPin — GPIO-matrix pin-ownership model @@ -48,8 +50,60 @@ inline SDL_AudioStream *&emuAudioStream() return s; } +// --- TX DMA ring model (parity with the legacy ESP32 driver) ---------------- +// The real legacy driver copies i2s_write() data into a ring of DMA buffers +// (dma_buf_count x dma_buf_len samples) and consumes it at the sample rate; +// a buffer is handed back to i2s_write() only after the DMA finished playing +// it, and i2s_zero_dma_buffer() memsets the WHOLE ring — erasing everything +// not yet played. The live SDL path below stays direct-fed (interactive audio +// keeps working with zero latency machinery), but this shadow model records +// what the DAC would actually have emitted, so headless tests can reproduce +// hardware-only sound bugs deterministically — e.g. the sound engine zeroing +// the ring right after rendering a short beep, wiping it before playback +// (every game beep ≤ 64 ms was silent on HW while the emulator sounded fine). +namespace emu { +struct DmaRing { + size_t cap = 0; // ring capacity in samples + std::vector buf; // ring contents + size_t ppos = 0, wpos = 0; // play / write cursors + size_t used = 0; // samples written but not yet played + std::deque played; // bounded log: what the DAC emitted + + void reset(size_t capacity) + { + cap = capacity; + buf.assign(cap, 0); + ppos = wpos = used = 0; + played.clear(); + } + bool full() const { return used == cap; } + void playOne() // DMA consumed the sample at ppos + { + played.push_back(buf[ppos]); + if (played.size() > 8192) played.pop_front(); + ppos = (ppos + 1) % cap; + --used; + } + void writeOne(int16_t v) + { + buf[wpos] = v; + wpos = (wpos + 1) % cap; + ++used; + } +}; + +inline DmaRing &emuDmaRing() +{ + static DmaRing r; + return r; +} +} // namespace emu + inline int i2s_driver_install(i2s_port_t, const i2s_config_t *cfg, int, void *) { + // Model the TX DMA ring with the configured geometry. + emu::emuDmaRing().reset((size_t)cfg->dma_buf_count * (size_t)cfg->dma_buf_len); + // SDL3 audio: open a stream on the default playback device with our // spec (conversion to the device format is automatic) and feed it from // i2s_write() via SDL_PutAudioStreamData(). @@ -87,9 +141,28 @@ inline int i2s_set_pin(i2s_port_t, const i2s_pin_config_t *pins) inline int i2s_write(i2s_port_t, const void *src, size_t size, size_t *written, unsigned) { + // Shadow the legacy TX DMA ring: data lands at the write cursor and only + // pushes already-played samples out of the ring. When the ring is full + // the real driver blocks here until the DMA frees a buffer; the model + // advances playback instead (deterministic, no real-time waiting). + const int16_t *s = (const int16_t *)src; + size_t n = size / sizeof(int16_t); + emu::DmaRing &r = emu::emuDmaRing(); + if (r.cap > 0) { + for (size_t i = 0; i < n; i++) { + if (r.full()) r.playOne(); + r.writeOne(s[i]); + } + } if (emuAudioStream()) SDL_PutAudioStreamData(emuAudioStream(), src, (int)size); if (written) *written = size; return ESP_OK; } -inline void i2s_zero_dma_buffer(i2s_port_t) {} +inline void i2s_zero_dma_buffer(i2s_port_t) +{ + // Faithful to the legacy driver: memset the ring contents. Every sample + // written but not yet played is erased and will never be heard. + auto &r = emu::emuDmaRing(); + std::fill(r.buf.begin(), r.buf.end(), 0); +} diff --git a/emulator/tests/harness.h b/emulator/tests/harness.h index af4764b..23c25c2 100644 --- a/emulator/tests/harness.h +++ b/emulator/tests/harness.h @@ -11,6 +11,7 @@ */ #pragma once #include "Arduino.h" +#include "driver/i2s.h" // emu::emuDmaRing — TX DMA ring model #include "TFT_eSPI.h" // rgb565to888 for pixel assertions #include "emu_gfx.h" #include @@ -77,6 +78,22 @@ inline void resetInput() // queue a key on the fake 0x55 keyboard device (consumed by pollKeyboard()) inline void typeKey(char c) { emu::keyboard.push_back((uint8_t)c); } +// --- audio helpers (the TX DMA ring model in the i2s shim) --- +// resetAudio(): empty + zero the ring, clear the "what the DAC emitted" log. +// Keeps the capacity configured by i2s_driver_install(); when no install has +// happened yet it defaults to the sound engine's geometry (8 x 64 = 512). +inline void resetAudio() +{ + auto &r = emu::emuDmaRing(); + r.reset(r.cap ? r.cap : 512); +} +// samples the DAC actually emitted (may be far fewer than i2s_write() got — +// that gap is exactly the class of hardware bug the ring model exposes) +inline const std::deque &playedAudio() +{ + return emu::emuDmaRing().played; +} + // --- framebuffer helpers (E2E pixel assertions) --- inline uint32_t pixel(int x, int y) { diff --git a/emulator/tests/unit_tests.h b/emulator/tests/unit_tests.h index d84b3b8..f2c53cc 100644 --- a/emulator/tests/unit_tests.h +++ b/emulator/tests/unit_tests.h @@ -388,3 +388,101 @@ TEST(unit/shim_edge_survives_same_dispatch_pulse) detachInterrupt(BOARD_BOOT_PIN); emu::releasePin(BOARD_BOOT_PIN); } + +// --- emulator shim: I2S TX DMA ring model ----------------------------------- +// The legacy ESP32 driver buffers i2s_write() data in a TX DMA ring +// (dma_buf_count x dma_buf_len samples = 512 = 64 ms @ 8 kHz here) and hands +// a buffer back to i2s_write() only after the DMA finished playing it, while +// i2s_zero_dma_buffer() memsets the WHOLE ring instantly — erasing everything +// not yet played. The shim models exactly that (plus a bounded log of what +// the DAC actually emitted) so hardware-only sound bugs reproduce headlessly. + +TEST(unit/shim_zero_dma_erases_unplayed) +{ + // Pin the model to the legacy driver's semantics, both directions: + // written data plays out, but i2s_zero_dma_buffer() wipes anything that + // has not been played yet (it is never heard). This fidelity is the + // premise the sound-engine regression below relies on. + int16_t tone[16]; + for (int i = 0; i < 16; i++) tone[i] = (i & 1) ? -12345 : 12345; + int16_t zeros[64] = {0}; + size_t bw; + + // phase A: no zeroing — the samples reach the DAC in order + test::resetAudio(); + i2s_write(0, tone, sizeof(tone), &bw, 0); + for (int i = 0; i < 10; i++) // drain the ring with silence + i2s_write(0, zeros, sizeof(zeros), &bw, 0); + const auto &played = test::playedAudio(); + EXPECT(played.size() >= 16); + for (int i = 0; i < 16; i++) EXPECT_EQ(played[i], tone[i]); + + // phase B: zero_dma before playback — the samples vanish unheard + test::resetAudio(); + i2s_write(0, tone, sizeof(tone), &bw, 0); + i2s_zero_dma_buffer(0); + for (int i = 0; i < 10; i++) + i2s_write(0, zeros, sizeof(zeros), &bw, 0); + for (int16_t v : test::playedAudio()) EXPECT_EQ(v, 0); +} + +TEST(unit/sound_short_tone_reaches_dac) +{ + // Regression for the sound task calling i2s_zero_dma_buffer() as soon as + // the queue drained: a 10 ms beep (80 samples) fits into the ring's free + // space without ever blocking i2s_write(), so the render finished in + // microseconds and the zeroing erased the tone before the DMA played a + // single sample — silent on hardware. (Every game beep ≤ 80 ms was in + // that dead zone; longer tones survived because i2s_write blocks on a + // full ring and paces rendering to real-time playback.) The fix flushes + // the ring with paced silence writes instead, which reuse each DMA buffer + // only after the DMA finished playing it. + sound.begin(false); // queue only — no task thread + test::resetAudio(); + + SndEvent e = {SND_TONE, 400, 0, 10, 12000}; // the link-active beep + sound.play(e); + sound.pumpOne(); // render + (queue drained) ring purge + + const auto &played = test::playedAudio(); + // the DAC must have heard the tone: ~41 full-amplitude samples at + // amp 12000 * vol 5/8 = 7500, plus the ramp shoulders + size_t loud = 0; + for (int16_t v : played) + if (v > 7000 || v < -7000) loud++; + EXPECT(loud >= 40); + // and the purge must leave silence behind — no tail replaying forever + bool tailClean = true; + for (size_t i = 80; i < played.size(); i++) + if (played[i] != 0) { tailClean = false; break; } + EXPECT(tailClean); + + emu::releasePin(BOARD_I2S_BCK); // begin() claimed the I2S pins + emu::releasePin(BOARD_I2S_WS); + emu::releasePin(BOARD_I2S_DOUT); +} + +TEST(unit/sound_long_tone_plays_out_fully) +{ + // And the purge must never truncate a long tone either: the 500 ms + // link-build beep (4000 samples) outlives the 512-sample DMA ring, so + // i2s_write() blocks mid-render and playback stays real-time paced — + // every steady-state sample must still reach the DAC. + sound.begin(false); + test::resetAudio(); + + SndEvent e = {SND_TONE, 500, 0, 500, 13000}; // playLinkBuild() + sound.play(e); + sound.pumpOne(); + + const auto &played = test::playedAudio(); + EXPECT(played.size() >= 4000); // whole tone, then silence + size_t loud = 0; + for (int16_t v : played) + if (v > 8000 || v < -8000) loud++; + EXPECT(loud >= 3800); // 3872 steady samples + + emu::releasePin(BOARD_I2S_BCK); + emu::releasePin(BOARD_I2S_WS); + emu::releasePin(BOARD_I2S_DOUT); +} diff --git a/src/netdeck/STATUS.md b/src/netdeck/STATUS.md index f45935b..14fe959 100644 --- a/src/netdeck/STATUS.md +++ b/src/netdeck/STATUS.md @@ -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`. diff --git a/src/netdeck/sound_engine.cpp b/src/netdeck/sound_engine.cpp index 6783ea9..417de09 100644 --- a/src/netdeck/sound_engine.cpp +++ b/src/netdeck/sound_engine.cpp @@ -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; diff --git a/src/netdeck/sound_engine.h b/src/netdeck/sound_engine.h index f3f540c..fb431e6 100644 --- a/src/netdeck/sound_engine.h +++ b/src/netdeck/sound_engine.h @@ -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);