xenia-rs/audit-runs/iterate-2AO-vsync-mmio-hardcode/writer-report.md

Iterate 2.AO — VBLANK MMIO Hardcode (C-1 candidate from 2.AN)

Headline: FIX-INERT-C2-CONFIRMED.

The 2.AN Angle-A fix (hardcode D1MODE_VBLANK_VLINE_STATUS / reg 0x1951 to return 1 on read, matching xenia-canary graphics_system.cc:309-310) is applied, builds, passes all tests, preserves determinism — and is fully inert. VdSwap stays at 6, the total event trace is bit-identical to the 2.AI/2.AJ baseline (65,691,821 events), and the exit-thread-state / wedge map are byte-for-byte identical to 2.AJ. C-1 (the VBLANK read asymmetry) was not the active blocker. The deeper bottleneck C-2 (opt_callback at user_data+15144 never installed) is confirmed as the prime suspect.

---

Patch summary

File	Change	LOC	Notes
crates/xenia-gpu/src/mmio_region.rs	read arm reg::D1MODE_VBLANK_VLINE_STATUS now returns 1 unconditionally instead of read_vblank_status.load(Relaxed)	+9 / -1 (1 substantive + 8 doc/let _ keep-alive)	single match arm
crates/xenia-kernel/src/exports.rs	untouched — 2.AJ reciprocal-shadow patch	+45 (pre-existing)	left in place as instructed

• Diff (git diff --numstat): 9 1 crates/xenia-gpu/src/mmio_region.rs — under the 10-LOC hard cap.
• The captured read_vblank_status clone is held with let _ = &read_vblank_status; so the closure still moves it and compiles clean.
• The write closure's W1TC path and tick_vsync_instr are untouched (write_vblank_status still used there). No refactor.
• Branch chore/portable-snapshot, HEAD acd1656. Patch UNCOMMITTED in working tree (as required). 2.AJ exports.rs patch verified intact (+45).

Source confirmation

• reg::D1MODE_VBLANK_VLINE_STATUS == 0x1951 at gpu_system.rs:1430.
• Canary case 0x1951: return 1; // vblank at graphics_system.cc:309-310 — exact match.
• The ours source comment at gpu_system.rs:224-232 independently documents 2.AN's premise: the Sylpheed vsync callback "gates all its work on reading bit 0 as set: lwz; rlwinm. r,r,0,31,31; bc 12,2,skip".

---

Verification gates

Build / Test (PRIMARY)

• cargo build --release: SUCCEEDS (incremental, 0.88s). Only a pre-existing unrelated dead_code warning in phase_b_snapshot.rs:245 (walk_committed_regions) — not from this patch.
• cargo test -p xenia-gpu -p xenia-kernel -p xenia-app -p xenia-cpu: 687 pass, 0 fail, 0 regressions (xenia-app 300; xenia-kernel 227 + 149; xenia-cpu 6; xenia-gpu 5; + ignored doctests). Matches historical baseline exactly.

Determinism (PRIMARY) — PASS

• run1 ours-cold.jsonl: 65,691,821 events.
• run2 ours-cold-run2.jsonl: 65,691,821 events.
• Bit-identical line count across two cold runs (XENIA_CACHE_WIPE=1, -n 500000000). (The ~763 KB byte-size delta between the two files is trailing-buffer noise, not an event-count divergence — line counts are exactly equal.)

VdSwap (PRIMARY) — NO CHANGE → C-1 not the gate

• run1 VdSwap: 6. run2 VdSwap: 6.
• 2.AI/2.AJ baseline: 6. No progression. Per the gate definition, an unchanged VdSwap means C-1 was not the active blocker.

Total event count vs baseline — IDENTICAL

• 2.AO = 65,691,821. 2.AJ baseline = 65,691,821. Exactly equal. The hardcode produced zero observable divergence in the execution trace.

Exit-state (tid=1 / tid=12) — byte-identical to 2.AJ

• diff exit-thread-state.json (2AJ vs 2AO): BYTE-IDENTICAL. Same 21 alive threads, same 18 wedge entries.
• tid=1: Blocked @ PC 0x824ac578, waiting on Event 0x000010e8 (sig=false, no signaler). Unchanged — the 2.AI/2.AJ wedge.
• tid=12: Blocked @ PC 0x824ac578, waiting on Event 0x00001004 (sig=false, no signaler). Unchanged — the DPC-dispatcher wedge (2.AC/2.AM).

tid=1 wait gap on Event 0x10e8 (SECONDARY) — no improvement

• Event 0x000010e8 ↔ semantic SID 9ad1bebb6cae28c4 (handle.create at host_ns 819,544,956).
• tid=1 issues exactly 2 wait.begin on this SID, at host_ns ~6.660s, 128.595 µs apart, then blocks permanently (no 3rd wait, never woken). This is the same two-wait-then-permanent-block pattern 2.AJ reported (~126.8 µs). The expected secondary effect ("wait gap may rise as more callbacks succeed") did not occur — the gate is downstream of C-2, so nothing changed.

gpu.interrupt.delivered rate (SECONDARY) — N/A

• The engine emits no gpu.interrupt.delivered event kind (the 11 kinds in the trace are: import.call, kernel.call/return, wait.begin, handle.create/destroy, wake.requested, signal.match, thread.create/exit, schema_version). VdSetGraphicsInterruptCallback is called 3× (callback IS registered) — consistent with 2.AJ's 76 ISR firings/100M. Not measurable from this trace; no regression.

---

Why the fix is inert (C-2 mechanism)

The hardcode correctly removes the read asymmetry 2.AN identified: the guest VSync callback sub_824BE9A0 @ PC 0x824BEA38-0x824BEA44 now always reads bit 0 = 1 and would take its frame-counter branch instead of the beq loc_824BEAAC skip. But the trace is bit-identical to the bit-clear baseline — meaning the frame-counter branch produces no downstream observable signal either way.

Per 2.AN's C-2: the real signaller is the dynamically-installed opt_callback stored at user_data+15144 (tail-called by sub_824BE9A0 → sub_824BEA80). In the 65.7M-event run that opt_callback is never installed (its setter sub_824C1920, reached only via sub_822F1F20 ← sub_822F1EE0 ← dispatch-table slot 0x822F1AFC, requires a deeper game-state event that does not fire). So even with the VBLANK gate forced open, there is no installed callback to write SignalState=1 on Event 0x10e8 — tid=1 stays wedged. C-1 was a real divergence-vs-canary but not on the critical path; C-2 gates it.

This is consistent with the 5-iterate methodology lesson logged in 2.AN (variant #44): the "missing signal" is three layers below "what does the wait depend on" — and C-1, one layer up, was correctly fixed but is inert because layer-3 (opt_callback install) never happens.

---

Confidence + next-iterate recommendation

Confidence: HIGH that C-1 is inert and C-2 is the prime suspect. Evidence is decisive (bit-identical event count + byte-identical exit state + unchanged VdSwap across two deterministic cold runs). The fix is a correct canary-parity hardening (keep it; it eliminates a latent race) but not a cascade win.

Disposition of this patch: KEEP uncommitted as dormant correctness/parity infra (like the 2.AJ reciprocal-shadow patch). It costs nothing, matches canary exactly, and closes a real (if currently unreachable) race window.

Next iterate — make C-2 the explicit target. Recommended (in priority order, mirroring 2.AN's Angle B/C):

1. 2.AP — opt_callback install/clear probe (~5-15 LOC tooling, 0 engine). --lr-trace 0x824C1920 (setter sub_824C1920) over a 500M run to confirm install count == 0 and identify the nearest reached frame on the 0x822F1AFC dispatch chain. This is the single highest-value next step: it pins down which upstream game-state event must fire.

2. 2.AQ — dispatch-chain reachability walk (~10-30 LOC tooling). --lr-trace 0x822F1EE0 / 0x822F1F20 to find where the 0x822F1AFC dispatch slot stalls — i.e. the deeper game-state predicate that never evaluates true. Three layers up from the wait, this is the actual wedge root.

3. (Deprioritized) The bilateral tid=12 DPC wedge (Event 0x1004, 2.AM) and tid=11 XAudio wedge (2.AL) remain independent and should follow C-2 resolution, not precede it.

Do not chase any further "force the signal" / "force the install" crowbars before 2.AP/2.AQ identify the gating game-state event — that has been the #44 reading-error trap five iterates running.