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
+74 -1
View File
@@ -5,6 +5,8 @@
#pragma once
#include <cstdint>
#include <cstddef>
#include <vector>
#include <algorithm>
#include <SDL3/SDL.h>
#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<int16_t> buf; // ring contents
size_t ppos = 0, wpos = 0; // play / write cursors
size_t used = 0; // samples written but not yet played
std::deque<int16_t> 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);
}
+17
View File
@@ -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 <cstdio>
@@ -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<int16_t> &playedAudio()
{
return emu::emuDmaRing().played;
}
// --- framebuffer helpers (E2E pixel assertions) ---
inline uint32_t pixel(int x, int y)
{
+98
View File
@@ -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);
}
+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);