# rtl/ee Emotion Engine-side RTL. Matches `docs/contracts/ee.md`. ## Current contents - `ee_fetch_stub.sv` — minimal sequential fetcher from the early waves. On reset, PC = BIOS reset vector (0xBFC00000). Each cycle while `enable` is high, issues a read at PC and advances PC += 4. No decode, no branches, no exceptions. Emits `EV_RESET` once at reset exit and `EV_IFETCH` for each returned response. Retained for the Milestone-B golden-reference comparison. - `ee_core_stub.sv` — **first real EE instruction-decoding core.** Structural mirror of `iop_core_stub`: same multi-cycle FSM, same R3000 subset (LUI/ORI/ADDIU/LW/SW/BEQ/BNE/J/JR/NOP/SYSCALL/MFC0/MTC0/ RFE), same branch-delay-slot discipline, same minimal COP0 + exception entry, same `STRICT_UNSUPPORTED` trap gate. Separate file from the IOP core because the EE is fundamentally an R5900 and will eventually need 64-bit registers, COP1/COP2, VU-side plumbing the IOP will never grow. Emits traces under `SUBSYS_EE` (vs. `SUBSYS_IOP` for the IOP core). ## Current status The EE side has a first real execution primitive (`ee_core_stub`) and runs hand-assembled bootstraps from the shared BIOS ROM window. The IOP side is ahead — it has DMAC ch9 data path, real interrupt exception entry, BIOS reset, and strict-mode BIOS smoke bring-up. The EE side's next natural growth (in roughly this order) is: 1. ~~CPU-side LW/SW to EE RAM.~~ **Done** (`tb_ee_core_memops`). EE memory map now routes CPU 32-bit reads and writes into the 128-bit `ee_ram_stub` with lane-select on reads and byte-enable masking on writes. CPU wins over DMAC on same-cycle RAM-read collisions and over the SIF egress bridge on RAM-write collisions. 2. ~~EE DMAC register access from the core.~~ **Done** (`tb_ee_core_dmac`, `tb_ee_core_dmac_poll`). Chapter 3 added the write-side: EE map decodes a CPU write at `phys[28:12] == 17'h1_000A` (0x1000_A000-0x1000_AFFF, ch2 GIF) and routes it through a new `ee_dmac_ch2_wr_*` port into `dmac_reg_stub`. The EE core programs MADR/QWC/CHCR via SW; the DMAC fetches from EE RAM through the map's `dmac_rd_*` port and completes with real DMA_START/BEAT/DONE events. Chapter 4 added the read-side: `dmac_reg_stub` grew a `reg_rd_*` surface (CHCR/MADR/QWC/TADR + DONE_COUNT monotonic counter at 0x40), and the EE map forwards CPU reads in the same DMAC window via a new `ee_dmac_ch2_rd_*` port. The core polls CHCR.start until the DMAC clears it, then reads DONE_COUNT and writes the witness to RAM — no more fixed NOP padding. 3. ~~EE INTC + exception entry.~~ **Done** (`tb_ee_core_dmac_intc`). EE map now decodes the EE INTC register window at `phys[28:12] == 17'h1_000F` (0x1000_F000/0x1000_F010 for STAT/MASK) and carries both directions through new `ee_intc_{wr,rd}_*` ports. An `intc_stub` instance on the EE side latches `dmac_reg_stub.irq_completion_o` and drives `ee_core_stub.cpu_irq` (which feeds `cause_ip[2]`). Bootstrap enables interrupts (Status = IEc | IM[2]), programs INTC_MASK, kicks the DMAC, and waits on DONE_COUNT; a RAM-resident ISR at `EXC_VECTOR=0x80` acks INTC_STAT via W1C, MFC0 EPC, JR + RFE. Core takes exactly one exception + one RFE, strictly after DMA_DONE. 4. ~~EE-side strict BIOS smoke.~~ **Done** (`tb_ee_core_bios_smoke`). EE mirror of the IOP smoke harness: `ee_core_stub` instantiated with `STRICT_UNSUPPORTED=1'b1`; synthetic CI bootstrap ends in an `AND` (SPECIAL func 0x24) that the core doesn't decode, so `trap_o`/`trap_pc_o`/`trap_instr_o` fire and halt the core loudly. Swap in a real BIOS via `make tb_ee_core_bios_smoke BIOS=/path/to/bios.hex` (plusarg-driven `$readmemh` into `u_bios.mem`, same convention as the IOP target). Output line includes an inline mnemonic decoder so the iteration loop (drop in BIOS, read output, add the missing opcode) works without a separate disassembler. 5. **Widen the core opcode set, driven by real-BIOS smoke.** The iteration loop is live: drop a BIOS dump in via `make tb_ee_core_bios_smoke BIOS=...`, read `trap_instr` + `mnemonic` from the output, implement the op, re-run. Progress so far (each step landed a dedicated coverage TB and kept full_checks green): - **SLTI / SLTIU** (I-type compare, opcodes 0x0A / 0x0B). First real-BIOS trip at 0xBFC0_0008. TB: `tb_ee_core_slti`. - **ADDI** (opcode 0x08). Implemented as ADDIU (no overflow trap — real BIOS doesn't emit ADDI where overflow could actually happen). TB: `tb_ee_core_addi`. - **ANDI** (opcode 0x0C, zero-extended). TB: `tb_ee_core_andi`. - **AND / OR / XOR / NOR** (SPECIAL R-type logic family, func 0x24-0x27; destination = rd). Batched because they share the R-type ALU plumbing. TB: `tb_ee_core_rtype_logic`. - **SB** (opcode 0x28, byte store with lane broadcast + one-hot byte-enable on the map write bus). TB: `tb_ee_core_sb`. Unlocked a 1500-instruction stretch (retired=180 → 1704). - **LB** (opcode 0x20, sign-extended byte load via `map_rd_data` lane extraction + 24-bit sign-extend in `S_MEM_WAIT`). TB: `tb_ee_core_lb`. - **JAL** (opcode 0x03, jump-and-link; writes `$31 = pc+8`). TB: `tb_ee_core_jal`. - **ADDU / SUBU** (SPECIAL R-type arith, func 0x21 / 0x23). Batched, share R-type ALU. TB: `tb_ee_core_rtype_addu`. Codex pre-approved the grouping. - **SLT / SLTU** (SPECIAL R-type compare, func 0x2A / 0x2B). Batched with the R-type ALU; register-form pair of SLTI/SLTIU. TB: `tb_ee_core_slt`. Unlocked a 5700- instruction stretch (retired=1717 → 7385). - **LH / LHU** (opcodes 0x21 / 0x25, halfword load with sign- and zero-extension respectively). Batched — same lane- extraction plumbing, differ only in fill semantics. Halfword addressing uses `ea[1]` (ea[0] must be zero for aligned access). TBs: `tb_ee_core_lh`, `tb_ee_core_lhu` (each covers both halfword lanes + the fill discipline for negative high-lane values). Unlocked retired=7385 → 8207. - **SLL / SRL / SRA** (SPECIAL R-type shifts, func 0x00 / 0x02 / 0x03). Batched per Codex pre-approval. Destination = rd, operand = rt, shift amount = `shamt` (bits [10:6]). SRA uses `$signed(rt_val) >>> shamt` for arithmetic right shift (sign fill); SRL uses `rt_val >> shamt` (zero fill). SLL $0,$0,0 is the canonical NOP encoding and flows through this path harmlessly — the rd_idx=0 writeback guard blocks any phantom write. TB: `tb_ee_core_shift` (critical probes: SRL vs SRA on the same negative input to catch sign-vs-zero fill bugs). Unlocked a **12,000-instruction stretch** (retired=8207 → 20327). - **SH** (opcode 0x29, halfword store). Store-side mate to LH/LHU; same lane-broadcast + byte-enable idiom as SB but at halfword granularity via `ea[1]`. 2-of-4 byte-enable (`4'b0011` for low lane, `4'b1100` for high lane) preserves the non-addressed halfword. TB: `tb_ee_core_sh` — two chained probes with register values that have distinctive upper halves (0xCAFE_FACE, 0x1234_5678). If the byte-enable is wrong or the full register leaks into the map_wr_data bus, the preservation check catches it (RAM word ends up 0x5678_FACE after both stores; wrong behavior would corrupt the non-addressed halfword). Unlocked a **56,000- instruction stretch** (retired=20327 → 76406) once the RAM-size infra issue was also fixed in the same chapter — see next bullet. - **Real-BIOS RAM size (chapter 7.9 infra fix).** Before this chapter, `tb_ee_core_bios_smoke` used only 4 KiB of EE RAM — fine for the synthetic CI program (which never writes beyond the first qword), but destructive once the real BIOS copies a large chunk of itself into RAM and jumps there. Addresses beyond 4 KiB silently aliased into the same window, producing 156k "retires" that were actually the core executing a scrambled mix of overwritten bytes, with no trap ever firing because whatever happened to land at the aliased offset decoded to something supported. Bumped `EE_RAM_BYTES` in the bench to 4 MiB (real PS2 has 32 MiB; 4 MiB covers BIOS init comfortably without ballooning sim memory). After the fix, real-BIOS smoke runs honestly and trapped on JALR at 0xBFC5_29E8. - **JALR** (SPECIAL func 0x09, register-indirect call). Target is `rs_val` (same path as JR); link address pc+8 is written to `rd_idx`. Unlike JAL's hardcoded `$31`, JALR's link destination is explicit in the instruction, and `rd==0` is a valid encoding that suppresses the link write. TB: `tb_ee_core_jalr` — two probes: canonical `jalr $31, $rs` (what the BIOS used) plus `jalr $20, $rs` with the return via `jr $20` to prove the rd field is honored and not accidentally hardcoded to $31. Unlocked retired=76406 → 84112 and the BIOS fully jumped into RAM-resident code (next trap_pc is `0x0000_060C`, a RAM address, not BIOS). - **ADD / SUB** (SPECIAL R-type, func 0x20 / 0x22). Batched per Codex's guidance — same pragmatic policy as ADDI vs ADDIU: this core does not model the Arithmetic Overflow exception, so ADD behaves as ADDU and SUB behaves as SUBU. Merged into the existing `rs_val + rt_val` / `rs_val - rt_val` arms of `rtype_alu_wb`. TB: `tb_ee_core_add_sub` — four probes including INT_MAX+1 wrap, which documents the deferred-exception policy (the wrap is the *expected* outcome, so the TB will fail loudly if overflow trapping ever lands without the TB being updated). - **COP0 Count (reg 9)** — first machine-state chapter after the iter-14 transition. Free-running 32-bit counter that increments every clock and resets to 0. Exposed read-only through MFC0 $9. MTC0 $9 silently dropped (no reset-to-value yet; revisit if BIOS depends on it). TB: `tb_ee_core_cop0_count` — two probes covering consecutive- MFC0 advance and a canonical `while (now < target)` poll that must exit. - **Enhanced bios_smoke PC sampler** with `peek_instr(addr)` helper (hierarchical read through `u_bios.mem` / `u_ee_ram.mem`) and a parallel `retired_history` array. Timeout now reports the instruction and retired count at each sample, not just pc. Timeout window bumped 5 ms → 20 ms for BIOS runway. - **Sampler pointer snapshots + 80 ms timeout.** After the instruction-aware sampler showed the loop was a linked-list walk (not a hardware wait), Codex directed "extend timeout first, then add pointer snapshots only if still stuck". Timeout bumped 20 ms → 80 ms: retired grew linearly to 2.46 M, still 100% in the same loop (≈350k iterations — way beyond any plausible BIOS list length). Added `u_core.regfile[5]` and `[6]` hierarchical snapshots at each sample. Finding: - `$5` (sentinel) = `0x00000974` — plausible low-RAM pointer - `$6` (current) = `0xDEADBEEF` — **the EE map's unmapped- read poison value**. The cycle is self-perpetuating: `lw $2, 0($6)` with `$6 = 0xDEADBEEF` reads address 0xDEADBEEF, which is unmapped, returning 0xDEADBEEF; the `bne $2, $0` stays taken forever. The real root cause is an **earlier** BIOS read from an unmapped address that poisoned a data structure — the traversal followed the poisoned pointer and locked in. - *(next-move call is with Codex: add an unmapped-read tracer to find the first bad address, implement whatever peripheral the BIOS was reading, change the poison value to 0 so the loop exits and exposes further BIOS progress, or something else.)* - **Bench-drift note (chapter 7.5):** the synthetic BIOS smoke sentinel was originally AND; once AND was added to the R-type ALU, the synthetic test silently stopped tripping and started timing out. Codex caught it; sentinel is now BREAK (SPECIAL func 0x0D). See project memory for the full post-mortem. Lesson: avoid using real opcodes as "unsupported sentinels" in test benches. ## Scope boundary This directory owns EE CPU execution and its immediate coprocessors (COP0 minimum; eventually COP1 FPU and COP2 VU macro mode). It does **not** own: - memory map / address decode — that's `rtl/memory/ee_memory_map_stub.sv`. - interrupt controller — that's `rtl/intc/` (generic; the same `intc_stub` module already serves the IOP side). - DMAC, VIF/VU, GIF/GS — separate directories.