xenia-rs/audit-runs/phase-host-audio-eager/investigation.md

Phase Host-Audio-Eager — Investigation (2026-05-19)

Phase 0: Plan

Canary's XHostThread setup (verified from source)

• AudioSystem::AudioSystem (xenia-canary/src/xenia/apu/audio_system.cc:48-69): constructs 8 host semaphores (client_semaphores_[i]) at engine init time. Each is Semaphore::Create(initial=0, max=queued_frames_=8).
• AudioSystem::Setup (line 77-98): spawns XHostThread "Audio Worker" running WorkerThreadMain IMMEDIATELY. This is a HOST OS thread, not a guest thread. Runs continuously throughout engine lifetime.
• WorkerThreadMain (line 100-159): loops on WaitAny(client_semaphores_, ...) → on wake, calls processor_->Execute(thread_state, client_callback, args) which runs the guest callback IN-LINE on the host worker thread.
• RegisterClient (line 202-237): the moment a client registers, it client_semaphore->Release(queued_frames_=8) (line 210), seeding 8 semaphore permits. The already-running worker thread then drains these in a tight loop: callback runs, returns, semaphore decremented, repeat. 8 callback invocations happen BEFORE RegisterClient even returns (or shortly after).
• After SDL plays a frame, sdl_audio_driver.cc:199 releases ONE permit, re-arming the loop. Under --mute=true, SDL still drains and releases.

Ours's current ticker model (verified from source)

• main.rs:2125-2131 (round prologue): each round, if any client is registered, xaudio.tick_instr(stats.instruction_count) adds the delta of executed instructions to an accumulator; when accumulator crosses XAUDIO_INSTR_PERIOD=48_000, it enqueues one fire per registered client and decrements the accumulator.
• main.rs:2135-2137: try_inject_audio_callback then pulls one fire off the queue and injects it into the dedicated audio worker thread (parked on a synthetic handle), but only if is_in_callback() is false (mutex with graphics interrupts).
• Worker thread spawned at register time (exports.rs:4084-4160) with PC=callback_pc, parked Blocked(WaitAny[SYNTHETIC]). Injection flips state to ServicingIrq with pc=callback_pc, runs callback, returns to LR_HALT, restore path re-blocks worker on synthetic.

The ordering problem

Sylpheed boot sequence (verified per prior agent's traces):

1. tid=1 main calls XAudioRegisterRenderDriverClient → ours registers client at slot 0, spawns worker (tid=11), enqueues NOTHING.
2. tid=1 main continues executing thousands of instructions.
3. tid=1 main calls ExCreateThread for XAudio worker threads → tid=9 and tid=10 spawn. They start spinning on the uninitialized voice struct at [r31+356].
4. 48,000 instructions after register, the ticker finally fires, enqueueing one buffer-complete callback.
5. Audio worker tid=11 wakes, runs callback at 0x824D6640. The callback calls KeWaitForMultipleObjects([0x82928B04, 0x82928AE0]) and blocks. These dispatchers can only be signaled by tid=9/10.
6. tid=9/10 are stuck spinning → tid=11 stuck waiting → circular deadlock.

In canary: the worker is HOST-threaded and starts running BEFORE tid=1 even reaches the register call. Register seeds 8 permits → worker drains 8 callback invocations. By the time tid=14/15 spawn, the voice struct's [r31+356] field has been modified by 8 callback runs and is in a state where tid=14/15 take a different (non-spinning) control-flow path. Critically, IN CANARY THE CALLBACK DOES NOT BLOCK on those dispatchers — because the voice state is different.

Implementation steps

1. At XAudioRegisterRenderDriverClient after worker spawn succeeds, eagerly enqueue 8 fires (matching canary queued_frames_=8) into state.xaudio.pending. The ticker's existing per-round drain plus the existing try_inject_audio_callback will then deliver these 8 callbacks across subsequent rounds — but they will fire WITHIN the first few thousand instructions of register-return, well before tid=9/10 spawn.

2. Eagerly fire the audio injector once at the END of the register handler. The round prologue normally calls try_inject_audio_callback once per round; this gives us +1 immediate fire to maximize the chance of callback completion before tid=1 continues to spawn tid=9/10.

3. Update enqueue_all_active to NOT enqueue if queue is at cap (it already does this; we just rely on it).

4. Add 2-3 unit tests covering the eager-seed behavior in XAudioState.

5. Document the change in the existing register-handler block comment.

Risks

• Determinism shift: cold digest WILL change (8 extra fires re-order the round prologue's audio injection). Capture new digest, validate 3× reproducibility.
• Worker blocks on first callback (per prior agent's diagnosis): if tid=11's first callback blocks immediately on KeWaitForMultipleObjects, then queue depth 8 doesn't matter — fires 2-8 sit unused because is_in_callback() stays true. In that case progression metric won't move. This is an empirical question, not predictable from static analysis. The brief explicitly says "if the fix lands cleanly but progression doesn't move, that's the answer."
• Phase B image_canonical_sha256: unchanged (no changes to image-load path).
• Sister chains: tid=14→9 / tid=15→10 are the targets. Other chains (tid=11/16/4) may shift due to scheduling re-ordering.

Phase 1: Execution log (filled during implementation)

[See fix.diff for the actual code changes]

Phase 2: Validation (filled after cold runs)

[See re-validation.md and digests/]

Phase 3: Outcome (filled after measurement)

[See summary.md]