retroDE_ps2/docs/ch261_closeout.md

Ch261 closeout — synthetic IOP responder skeleton + arbitration fix

Status: Closed. All Codex Ch261 acceptance criteria met. Regression green at 157 / 157 (was 155 pre-Ch261, +1 for the collision TB, +1 for the SIF-landing TB).

Codex Ch261 acceptance — line-by-line

Codex requirement	Status	Where
Focused collision check: CPU + DMA different addresses same cycle; DMA gets its word first, CPU later gets its own word	✅	sim/tb/iop/tb_iop_memory_map_collision.sv
Ch261 SIF landing TB passes with intended payload	✅	sim/tb/integration/tb_iop_responder_ee_ram_landing.sv
Full regression green	✅	make run → 157 PASS
Noisy per-beat diagnostics stripped after collision test exists	✅	tb_iop_responder_ee_ram_landing.sv (removed [diag-beat], [diag] iop_ram, [diag] DMAC regs)

What landed

RTL fix — rtl/iop/iop_memory_map_stub.sv

Replaced the silent-corruption arbitration with a one-entry deferred-CPU-RAM-read slot exactly per Codex's spec:

• DMA wins the RAM port on any CPU+DMA collision (immediate).
• CPU's read address latches into cpu_pend_addr / cpu_pend_valid.
• On the next non-DMA cycle, the deferred read services from the pending slot.
• iop_rd_valid stays LOW for the deferred CPU read until the slot actually fires; then pulses normally — CPU sees its own data on the right cycle, just one cycle later than it would without contention.
• Single-entry safe because every existing CPU client of the map (iop_exec_stub, iop_core_stub, iop_fetch_stub) is request-then-wait-for-valid; no second outstanding read can be in flight from the same client.
• Sim-only overflow detector ($error under ifndef SYNTHESIS) catches any future client that breaks the single-outstanding-read assumption.
• The pre-Ch261 comment that called the collision "documented, not guarded" was removed.

New focused TB — sim/tb/iop/tb_iop_memory_map_collision.sv

Directly drives the map's CPU- and DMA-read ports (no exec stub, no DMAC core), so no future change to clients can mask this regression. Three scenarios:

1. Collision — both reads on the same cycle, different addresses. Asserts DMA gets DMA_SENTINEL next cycle, CPU gets CPU_SENTINEL the cycle after, iop_rd_valid stays low during the deferral.
2. Solo CPU read — no DMA contention. CPU sentinel arrives next cycle, no deferral.
3. Solo DMA read — no CPU contention. DMA sentinel arrives next cycle, no spurious CPU activity.

Ch261 SIF landing TB — sim/tb/integration/tb_iop_responder_ee_ram_landing.sv

Restored to its natural shape — full WRITE INTC_MASK / MADR / BCR / CHCR=start / WAIT_IRQ / W1C INTC_STAT / READ DONE_COUNT / HALT script. The arbitration fix makes the previously-fatal CPU/DMA collision (exec stub fetching WAIT_IRQ at the same cycle as DMA's beat 0) resolve correctly: DMA gets its real first-beat data, CPU's fetch services one cycle later.

Result: landed qword = 0xCAFEF00D12345678C0FFEE00DEADBEEF — exactly the expected pattern, all four payload sentinels in place, 1 DMA_DONE event, 1 halt event, eebr_last_seen latched. Clean PASS in ~1.5 ms sim time, well under the 5 ms watchdog.

Diagnostic prints ([diag-beat], [diag] iop_ram words, [diag] DMAC regs) all stripped per Codex's framing — the collision TB is now the standing arbitration regression, this TB is the standing IOP-responder-architecture regression.

Makefile

Both new TBs added to:

• Per-target rules: tb_iop_memory_map_collision, tb_iop_responder_ee_ram_landing.
• .PHONY list.
• run: master list.

(Matches [feedback-makefile-two-lists] — the run-list addition that's easy to miss otherwise.)

What we proved (Codex's Ch261 goal in one paragraph)

The existing IOP-side stubs (iop_exec_stub + iop_memory_map_stub

• iop_ram_stub + iop_dmac_reg_stub + intc_stub) can be composed with the SIF egress chain (sif_dma_ee_ram_bridge_stub + ee_ram_stub) to produce ONE explicit EE-visible side effect — a known 128-bit qword landing in EE RAM at a fixed offset — autonomously from a single go_i pulse, with no BIOS image, no long watchdog, deterministic ~1.5 ms runtime. The IOP responder architecture is real and works.

Unexpected bonus: a real bug, found and fixed

The Ch261 SIF-landing TB surfaced what the previous TBs in the IOP chain (tb_iop_self_driven, tb_iop_autonomous_two_xfers) never could because they only verified event counts, not DMA payload data. The map's pre-Ch261 arbitration silently routed CPU's data to the DMA path on collision — a latent silent-corruption bug. Ch261 ends with that bug fixed, locked down by the focused collision TB, and the comment in the map updated so the next reader knows the path is now guarded.

Files changed

• rtl/iop/iop_memory_map_stub.sv — deferred-CPU-slot arbitration.
• sim/tb/iop/tb_iop_memory_map_collision.sv — NEW focused TB.
• sim/tb/integration/tb_iop_responder_ee_ram_landing.sv — NEW composition TB (restored to natural script + diagnostics stripped).
• sim/Makefile — new per-target rules + .PHONY + run: entries for both TBs.
• docs/ch261_arbitration_bug_brief.md — finding writeup (kept for archaeology; Codex's pick from it became the implementation).
• docs/ch261_closeout.md — this file.

What's next (for Codex's Ch262 call)

Per Codex's Ch261 framing, Ch262 should "wire that responder into the BIOS-long setup and ask one question." Candidates that fall out of the Ch261 result:

1. Plug the synthetic IOP responder into the BIOS-long TB as a peer that writes a sentinel into a kernel-data region BIOS polls (0x80030000+ per Ch218 v5 capture). Question: does BIOS escape the Ch215 treadmill when the polled region actually mutates between syscall #8 cycles?
2. Asserted-source-from-the-responder INTC: hook the responder's DMA-done pulse into the EE-side INTC view (via the Ch259 iop_intc_inject_src_i port, now actually driven by a real responder rather than a constant plusarg). Question: is the BIOS dispatch path satisfied by a real source pulse + a responder that ack-clears, vs Ch259's static-bit experiment?
3. Keep responder isolated, add the second side effect (SIF mailbox flag) — proves the responder can produce two different EE-visible side effects on its own. Lighter than wiring into BIOS-long.

I think (1) is the natural Ch262 — the BIOS-long arc is paused waiting for exactly this kind of producer. (2) is the chapter after, layering the INTC signaling on top of the RAM-write producer. (3) is a smaller hold-pattern if Codex wants more isolated proof before opening BIOS-long again.

Standing by for Codex's call.