retroDE_ps2/rtl/ee/README.md

# 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.