genesis: Sonic 3 special-stage audio (S/H compositing fast path, I2S task priority, internal-RAM headroom)

[finger563]

Follow-up to #128: Sonic 3's 3D special stages still ran 56–59 fps with stuttering audio. Measured with the [genesis perf] line (plus a new render-stage split) and fixed in three steps, each verified by ear on the BOX-3. The special stage now runs a locked 60.2–60.5 fps with audio that the tester could not distinguish from the real thing.

What was wrong, in order of discovery

1. A 7.5 ms per-pixel compositing loop. The special stages use the VDP's shadow/highlight mode. gwenesis's S/H path composited the sprite line over the plane line with a per-pixel switch for every one of the 320×224 pixels — and the actual S/H colour math in it is commented out, so it was priority compositing only. The sprite buffer is cleared per line and only sprite pixels write it, so most words are zero and can never win: it now walks the line a word at a time, copies the plane word through when the sprite word is zero, and resolves priority per byte only where a sprite pixel exists. Same winner rule, same operator-sprite exemption. merge 7.5 → 0.9 ms per drawn frame; stage 56–59 → 60.2 fps, 10% more frames drawn.
2. The I²S feed task was being starved. The BSP's audio task (default priority 19) shares core 1 with the Genesis sound task and the video task (both 20) and only ran in the gaps between frames. With core 1 saturated the DMA underran and the audio queue overflowed: the trial counters showed ~7% of the audio dropped per 12 s window while the emulator held 60 fps. It does microseconds of work per block, so it now runs at priority 21, above both; drops went to zero.
3. The I²S consumer pads partial blocks with silence (in espp's esp-box, not this repo): its block is sized for 48 kHz (3200 bytes = 30 ms at the Genesis's 26.6 kHz) and each time it wakes it takes whatever is queued up to a block and zero-fills the rest. The emulator pushes one 16.7 ms frame of audio at a time with frame-to-frame jitter, so any moment the queue held less than a block became up to 13 ms of injected silence. Fixed upstream in fix(bsp): audio tasks wait for a whole block instead of padding with silence (all 10 BSPs) espp#845 (receive with a trigger level of one block, timeout-protected; write exactly what was received; applied to all ten espp BSPs with audio), released as espp 1.3.8. This PR bumps espp/esp-box to >=1.3.8; the released component was verified on the box (Sonic 3 60.1–60.5 fps, 0 audio drops, special-stage sound unchanged from the trial build).

Also in this PR

• Genesis keeps ≥16 KB of internal RAM free. With every hot buffer preferring internal RAM, one launch left 36 bytes in the main internal heap, after which whatever needed a few hundred bytes in the first frame hung the box silently. Allocation order is now explicitly the priority order and each prefer-internal allocation spills to PSRAM once it would cross the reserve (on the BOX-3 only the sound queue moves, no measurable change).
• [genesis perf] reports the VDP render split per drawn frame (planes= sprites= merge=) from counters in gwenesis_vdp_gfx.c.
• The diagnostic task watchdog (only when CONFIG_ESP_TASK_WDT_EN is set in a local sdkconfig) is fed from the pause-menu loop too, and a launch that lands in that loop says so on the console.
• espp/esp-box >= 1.3.8 (see 3 above).

Review follow-up

• GENESIS_PERF is defined once in gwenesis_vdp.h and now also guards the VDP's render-stage counters, so GENESIS_PERF=0 compiles all of the profiling out (both objects build warning-free with the flag off).
• VRAM is allocated last in fact, not only in the comments: it moved to genesis_init_shared_vram(), called after the audio buffers, the index line buffer and the sound queue. Verified placement on the ESP-BOX: everything internal except sound_q and VRAM (PSRAM), VRAM last.
• genesis_index_buffer goes through the same headroom-aware allocator as every other internal buffer.

Still open

Silent hangs at boot/launch (no panic output even with the task and interrupt watchdogs armed, which points below software: a bus stall or supply issue). They cluster at power-hungry moments and started the day the box lost its battery; being investigated on hardware first.

🤖 Generated with Claude Code

https://claude.ai/code/session_01AWhoGwibqcKDhcG17mjVT1

[github-actions]

✅Static analysis result - no issues found! ✅

[Copilot]

🟡 Changes recommended

Allocation ordering and an unguarded buffer undermine the documented RAM policy, while VDP profiling cannot be disabled fully.

3 open findings

• GENESIS_PERF does not disable profiling instrumentation · New
• Genesis index buffer bypasses reserve-aware allocation · New
• VRAM allocation precedes higher-priority audio buffers · New

What changed in this PR

Optimizes Sonic 3 special-stage performance and audio reliability while reserving internal RAM for system operations.

Changes:

• Adds fast shadow/highlight compositing and render-stage profiling.
• Raises I²S task priority to prevent starvation.
• Introduces internal-RAM headroom and watchdog diagnostics.

File	Description
main/​cart.hpp	Feeds the watchdog in pause menus.
components/​genesis/​src/​genesis.cpp	Adds profiling and reserve-aware allocations.
components/​genesis/​src/​genesis_shared_memory.cpp	Implements RAM headroom and allocation ordering.
components/​genesis/​include/​genesis_shared_memory.hpp	Declares the 16 KiB reserve policy.
components/​genesis/​gwenesis/​src/​vdp/​gwenesis_vdp.h	Exposes render-stage counters.
components/​genesis/​gwenesis/​src/​vdp/​gwenesis_vdp_gfx.c	Adds optimized compositing and timing.
components/​box-emu/​src/​box-emu.cpp	Raises the I²S feed task priority.

🧠 Review effort: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[github-actions]

ESP-IDF Size Report for 'Esp Box Emu'

Metric	Base	PR	Delta
FLASH	4,054,072 bytes (64.44%)	4,054,828 bytes (64.45%)	🔺 +756 bytes (+0.01%)
DRAM	130,069 bytes (38.06%)	130,501 bytes (38.18%)	🔺 +432 bytes (+0.12%)
IRAM	0 bytes	0 bytes	0 bytes
RAM (DRAM+IRAM)	130,069 bytes	130,501 bytes	🔺 +432 bytes (+0.12%)

_{FLASH uses app .bin size or json2 flash sum. RAM sums DRAM+IRAM via idf_size. Percentages shown when totals are available.
DRAM/IRAM usage does not include memory used by the heap allocator at runtime.
This report was generated by esp-idf-size-delta.}