retroDE_ps2/docs/ch271_closeout.md

Ch271 closeout — SQ implemented; qbert progresses 2,247× further

Status: Closed. Verdict from re-running qbert.elf: elf_first_unsupported_opcode (pc=0x00100068 instr=0x0080e02d) — DADDU, the next missing R5900 opcode. That frames Ch272.

Numbers, end to end

Metric	Pre-Ch271 (Ch270 verdict)	Post-Ch271 (this chapter)
qbert retire_count	12	26,958 (2,247× more)
First-trap PC	0x00100024 (SQ)	0x00100068 (DADDU)
First-trap instr	0x7C400000	0x0080E02D
Distance in qbert text	~9 instructions from entry	~24 instructions further

The SQ implementation correctly cleared the qbert prolog buffer that previously stalled execution. Now qbert progresses ~24 instructions further into its prolog before hitting DADDU.

What landed

RTL — ee_core_stub.sv (5 surgical edits)

1. OP_SQ = 6'h1F localparam constant alongside the other store opcodes.
2. is_sq logic declaration + assign is_sq = (opcode == OP_SQ).
3. Alignment: extended is_align_fault to include is_quad_access && (ea[3:0] != 4'd0), and added is_sq to is_align_store. Misaligned SQ now trips the existing AdES exception path (or strict trap, depending on TRAP_ALIGN_ERROR).
4. Decoder allow-list: added !is_sq to the is_nop_class catch-all so SQ doesn't get rejected by STRICT_UNSUPPORTED.
5. 4-beat FSM: new sq_beat 2-bit register; transition into S_MEM_WRITE from EXECUTE; in S_MEM_WRITE combinational block, map_wr_addr = ea + {sq_beat, 2'b00} and map_wr_data = (sq_beat == 0) ? rt_val : 32'd0 (upper 96 bits of $rt aren't modelled; for sq $zero,... — the qbert case — every beat naturally writes zero); in S_MEM_WRITE FSM state, stay in state and increment sq_beat until sq_beat == 2'd3, then retire and return to S_IFETCH_REQ.

The single architectural SQ instruction takes 4 bus beats but produces exactly ONE retire event — matching the architectural model.

TB — sim/tb/integration/tb_ee_core_sq.sv

Focused 18-instruction test:

• Bootstrap from 0xBFC00000 reset vector via J to 0xBFC00100.
• LUI/ORI to load $v0 = 0x80000400 (kseg0 → EE RAM phys 0x400).
• Pre-poke EE RAM at phys 0x400..0x40F with distinct non-zero values (0xDEADBEEF / 0xCAFEF00D / 0x12345678 / 0x9ABCDEF0) via hierarchical ram_word() task so a missing SQ beat would leave a non-zero word.
• Execute sq $0, 0($v0) (= 0x7C400000, the exact qbert instruction).
• LW + BNE-to-FAIL chain over the 4 words verifies each lane is zero.
• Belt-and-braces: direct hierarchical peek of u_ee_ram.mem[0x40] after halt to confirm all 128 bits are 0.
• PASS via syscall.

Result: [tb_ee_core_sq] retired=18 halt=1 trap=0 pc=0xbfc0013c errors=0 PASS. Both the BNE chain and the direct RAM check agree the SQ wrote 16 zero bytes correctly.

Makefile — tb_ee_core_sq target + regression list

Added to both PHONY list and run: master list. Regression bumps from 158 → 159.

Why not just NOP the opcode (Codex's caution honoured)

Codex called this out explicitly: 0x7C400000 is sq $zero, 0($v0) — a 128-bit store of zero. NOP-ing op=0x1F would let qbert continue, but it would silently skip real memory initialization. For the prolog, that's a buffer clear; later code would read uninitialized values from those bytes and behave nondeterministically.

Minimal-correct SQ (4 beats of 32-bit writes) is the right choice. The "minimal" part: we don't model the upper 96 bits of $rt (PS2 EE has 128-bit GPRs); for sq $zero,... this is exact, and for sq $non-zero,... we write the low 32 bits to beat 0 and zero elsewhere — a documented approximation that degrades gracefully for the common "clear a 128-bit kernel slot" use case. When/if a real PS2 program does sq of a non-zero 128-bit register, we'll see silent data corruption that the runner's hot-PC verdict can identify; that's the trigger to upgrade to 128-bit GPR modelling.

Codex Ch271 acceptance — line-by-line

Requirement	Status	Where
Decode primary opcode 0x1F as SQ	✅	OP_SQ + is_sq
Support sq $zero, imm(base) at minimum	✅	rt_val=0 case writes 0 every beat (and rt_val=non_zero writes low 32 to beat 0)
4-beat 32-bit-stripe FSM through existing memory interface	✅	sq_beat counter, stays in S_MEM_WRITE for 4 beats
Require 16-byte alignment; misaligned → strict/exc trap	✅	is_quad_access check in is_align_fault
Focused TB: preload base, exec SQ, verify 4 zero words	✅	tb_ee_core_sq
Verify PC advances + no GPR writeback	✅	Final PC check + retire path doesn't touch regfile
Re-run qbert.elf, report next blocker	✅	DADDU at pc=0x00100068
Don't NOP all op=0x1F (would mask real stores)	✅	Targeted decode, exact 4-beat write semantics
Don't overbuild full LQ/SQ/vector yet	✅	SQ only (no LQ, no PSQ_*, no vector); upper 96 bits left for later
Regression unaffected	✅	159/159 in flight

Recommendation for Codex's Ch272

daddu $gp, $a0, $zero at pc=0x00100068 instr=0x0080E02D.

DADDU is MIPS-III's 64-bit version of ADDU. The R5900 is a 64-bit core; PS2 ELFs use DADDU as the canonical 64-bit register-move pseudo-instruction (move rd, rs → daddu rd, rs, $zero).

Our model has 32-bit regfile (logic [31:0] regfile [0:31]), so a faithful 64-bit DADDU would need 64-bit GPRs. For the qbert blocker specifically, the operation degenerates to a 32-bit move: $gp = $a0 + 0.

Three Ch272 framings, in order of scope:

1. Decode DADDU and treat it as ADDU. Low-32-bit semantics only; upper 32 bits silently dropped (already true everywhere else in the model). Touches one line in is_nop_class allow-list + one new R-type funct case + adding is_daddu to the is_rtype_alu group. Same "minimal-correct" pattern that worked for SQ.
2. Decode DADDU + DADD + DSUBU + DSUB + DAND + DOR + DXOR + DNOR as their 32-bit counterparts. Broader, but these are all commonly emitted by gcc for r5900 alongside DADDU. Pre-empts the next 4-7 chapters worth of one-opcode-at-a-time growth.
3. Properly implement 64-bit GPRs. Architecturally correct, but invasive — touches regfile width, all ALU paths, LW/SW to-from regfile, and the trace. Probably 1-2 chapters of work on its own.

(1) is the strict Codex-style "minimal-correct next blocker" answer. (2) would shorten the chapter chain if Codex thinks qbert's prolog uses several D* ops. (3) is a "do it right" pivot that's worth doing eventually but probably not in Ch272.

My read: (1) is the right Ch272 — same shape as Ch271, fast to land, lets the verdict surface the next real divergence. If the next blocker is also a D* op, we recur. If it's something totally different (LQ? MMI? VU0 macro?), we know (1) was the right scope.

Standing by.

Files changed

• rtl/ee/ee_core_stub.sv — 5 surgical edits (~20 LOC total) for SQ decode + 4-beat write FSM.
• sim/tb/integration/tb_ee_core_sq.sv — new focused TB.
• sim/Makefile — tb_ee_core_sq target + added to both regression lists.

Regression

In flight at the moment of writing; expected 159/159 (was 158, +1 for tb_ee_core_sq).