retroDE_ps2/docs/ch288_closeout.md

Ch288 closeout — DMAC passive per-channel surface; MMIO clear, syscall 0x78 surfaces

Status: Closed. Verdict from re-running qbert.elf: elf_first_unhandled_syscall (pc=0x00112AA4 $v1=0x78 (=120)). qbert advanced 27,912 → 27,920 retires (+8) — past the per-channel clear loop and on to another kernel syscall.

The standout signal: saw_unmapped_mmio = 0 for the first time since Ch286. The Ch287 + Ch288 combination now covers every EE DMAC MMIO surface qbert touches during its init sweep — the verdict shape flipped back to "unhandled syscall," which means qbert is back in normal control flow and the MMIO era closes (for now).

What landed

Per Codex's "lightweight per-channel register surface, no transfer FSM" framing, Ch288 delivers:

New module — rtl/dmac/ee_dmac_passive_chan_stub.sv

A single channel-multiplexed register stub covering five DMAC channels (the unmodeled ones):

Channel	Base	Endpoint	Internal idx
ch0	0x10008000	VIF0	0
ch1	0x10009000	VIF1	1
(ch2)	(0x1000A000)	(GIF)	(skip — dedicated dmac_reg_stub on ee_dmac_ch2_* ports)
ch3	0x1000B000	IPU_FROM	2
ch4	0x1000C000	IPU_TO	3 ← qbert blocker
ch5	0x1000D000	SIF0	4

Per channel: CHCR / MADR / QWC / TADR (4 latched 32-bit registers at offsets 0x00/0x10/0x20/0x30). Writes latch. Reads return last latched value. Reset = 0. No transfer FSM. No start-bit side effects. No D_STAT interaction.

The module decodes the channel index from chan_addr[15:12]:

• 0x8 → idx 0 (ch0)
• 0x9 → idx 1 (ch1)
• 0xB → idx 2 (ch3)
• 0xC → idx 3 (ch4)
• 0xD → idx 4 (ch5)
• 0xA (= ch2) → silently dropped (chan_valid=0): the real GIF stub lives elsewhere; this module must not shadow it.

Unknown register offsets within a valid channel: write dropped, read returns 0.

Memory-map integration — rtl/memory/ee_memory_map_stub.sv

Five mechanical edits (the now-standard new-region recipe):

1. REGION_EE_DMAC_PASSIVE = 64'd14 localparam.
2. ee_rd_is_dmac_passive / ee_wr_is_dmac_passive predicates:

   (phys[28:16] == 13'h1000) &&
   ((phys[15:12] == 8) || (== 9) || (== B) || (== C) || (== D))
   

   The != 0xA exclusion keeps ch2 GIF on its dedicated port.
3. Internal instantiation of ee_dmac_passive_chan_stub.
4. New ee_rd_was_dmac_passive latch + response-mux arm.
5. New trace branches (read AND write) emitting REGION_EE_DMAC_PASSIVE. The Ch287 footgun avoided — trace branches added at the same time as the predicate, not as a follow-up.

TB — tb_ee_dmac_passive_chan_stub.sv

18 named assertions covering:

1. ch4 reset reads zero for all four registers.
2. ch4 round-trip writes/readbacks of CHCR/MADR/QWC/TADR with distinct values.
3. Channel independence: write to ch5; verify ch4 values unchanged; verify ch5 readback.
4. ch2 filter: write to chan_nibble=0xA returns 0 on read (this stub does NOT shadow ch2 — that's dmac_reg_stub's territory).
5. ch0 / ch1 / ch3 reset verifies multi-channel initialization.
6. Unknown register offset on a valid channel: read returns 0, write doesn't damage the channel; the next valid read still works.

Result: errors=0 PASS (18/18 sub-checks).

Makefile + regression

• tb_ee_dmac_passive_chan_stub target.
• rtl/dmac/ee_dmac_passive_chan_stub.sv added to RTL_SRCS.
• TB added to both PHONY list and run: master list.
• Regression: 174 → 175.

qbert progression

Chapter	Blocker	retire_count	unmapped_mmio?
Post-Ch286 (EI)	0x1000E010 D_STAT (unmapped MMIO)	27,907	YES
Post-Ch287 (DMAC ctrl stub)	0x1000C000 ch4 base (unmapped MMIO)	27,912	YES
Post-Ch288 (DMAC passive)	syscall $v1=0x78 at PC 0x00112AA4	27,920	NO

The MMIO era (Ch287..Ch288) ran for just two chapters and added ~+13 retires worth of init-sweep coverage. With the per-channel clear loop satisfied, qbert advanced to a SECOND kernel syscall beyond the Ch285 $v1=0x40 — namely $v1=0x78 (120). Argument snapshot at halt:

• $a0 = 0x00000000 (zero / null)
• $a1 = 0x00130000 (heap-ish or code-ish)
• $a2 = 0x20000000 (high bit set; kseg0+0 = "uncached pointer" base in PS2 convention)
• $a3 = 0x001328c0 (code/data pointer-looking)

Per the Ch285 framing principle ("don't over-trust the SDK name; model the observed behavior"), the right Ch289 move is probably another narrow case: $v0 = 0; PC += 4 and see what happens. If qbert misbranches, return the $a2 arg pattern instead. PS2 syscall 120 in the standard table is commonly cited as one of the GS-control or threading-related calls; Codex can pick the right stub-return semantics.

Ch289 framing

Two narrow options for Codex:

• (a) Add $v1 == 0x78 to the existing HLE dispatcher with $v0 = 0, PC += 4. Trivial; one switch case.
• (b) Identify the exact PS2 kernel service for syscall 120 and pick a context-aware return value (e.g. echo $a2 if it's a "register and return previous" pattern).

I lean (a) for the first pass — matches the Ch285 precedent. If qbert misbranches downstream, revisit and try $a2 or $a1 as the return.

Files changed

• rtl/dmac/ee_dmac_passive_chan_stub.sv — new module (~160 LOC).
• rtl/memory/ee_memory_map_stub.sv — predicate, internal instance, mux arm, trace branches.
• sim/tb/dmac/tb_ee_dmac_passive_chan_stub.sv — new focused TB.
• sim/Makefile — RTL_SRCS entry, new tb target, both regression lists.

Pattern review (18 chapters)

Ch	Blocker	Edits	Pattern
271..286	opcodes	various	opcode-era
287	DMAC ctrl MMIO	~30	NEW MMIO stub + map routing
288	DMAC passive per-channel	~30	REUSE Ch287 internal-stub pattern

The internal-stub pattern from Ch287 paid off in Ch288: the same predicate-instance-mux-trace mechanical sequence dropped a second MMIO region into place without disturbing the 88 TBs that use ee_memory_map_stub. The chapter cost stayed flat at ~30 edits across one new RTL file + one map extension + one TB.

The trace-branch addition was done correctly at the same time as the predicate (the Ch287 footgun avoided).

Regression

175/175 PASS (was 174/174 in Ch287; +1 for the new tb_ee_dmac_passive_chan_stub).