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:
@@ -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);
|
||||
}
|
||||
|
||||
@@ -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)
|
||||
{
|
||||
|
||||
@@ -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);
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user