retroDE_ps2/rtl/iop/README.md

# rtl/iop

IOP subsystem. Matches `docs/contracts/iop.md`.

## Current contents

- `iop_ram_stub.sv` — 32-bit IOP RAM primitive. Default 16 KiB,
  parameterizable. Read + write ports with byte-enable granularity,
  one-cycle read latency, caller-provided `master_id` for trace
  attribution. Emits trace events under `SUBSYS_IOP`.
- `iop_memory_map_stub.sv` — IOP-side address decode. CPU-side port uses
  kseg0/kseg1 stripping (`phys = iop_addr[28:0]`). Second write-master
  port for DMA bridges (`bridge_wr_*`), physical addressing. Regions now
  decoded:
    - IOP RAM (phys 0x00000000-0x001FFFFF) → `iop_ram_stub`
    - SIF registers (phys 0x1D000000 block) → SIF register shell
      (`sif_mailbox_stub` IOP side) via `sif_rd_*` / `sif_wr_*` ports
    - IOP DMAC channel 9 (phys 0x1F801520-0x1F80152F) → IOP DMAC
      register shell via `iop_dmac_rd_*` / `iop_dmac_wr_*` ports
    - IOP INTC (phys 0x1F801070-0x1F80107F) → `intc_stub` (IOP-side
      instance) via `iop_intc_rd_*` / `iop_intc_wr_*` ports
    - Shared BIOS ROM (phys 0x1FC00000-0x1FFFFFFF, 4 MiB) →
      `bios_rom_stub` via `bios_rd_*` port. kseg1 aliasing makes
      `0xBFC0_0000` reset fetches land here transparently. BIOS is
      read-only; writes to this window trace as UNMAPPED.
    - everything else → UNMAPPED with deterministic 0xDEADBEEF
  Future regions (other DMAC channels, IOP timers, SPU2) reserved in
  comments. Arbitration between CPU and bridge writes on RAM path:
  CPU wins on same-cycle collision. SIF, DMAC, INTC, and BIOS are
  separate ports and don't contend with RAM.
- `iop_fetch_stub.sv` — minimal sequential 32-bit fetcher. Mirrors
  `ee_fetch_stub` in shape: PC-incrementing, no decode, no branches, no
  exceptions. Default `RESET_VECTOR` is in IOP RAM (0x00000000), NOT in
  BIOS space — explicitly non-BIOS boot. Emits `IOP RESET` once and
  `IOP IFETCH` per response. First execution-visible IOP traffic in the
  project; fetches route through `iop_memory_map_stub`.
- `iop_core_stub.sv` — **real instruction-decoding IOP core with
  minimal COP0, asynchronous interrupt exception entry, and the
  architectural MIPS reset vector.** Tiny MIPS R3000 subset,
  multi-cycle FSM, speaks the same map / DMAC / INTC protocol as every
  previous engine. Default `PC_RESET = 0xBFC0_0000` (kseg1 into the
  shared BIOS window; override with a parameter for RAM-only tests).
  Supported opcodes:
  LUI, ORI, ADDIU, LW, SW, BEQ, BNE, J, JR (SPECIAL func 0x08),
  NOP (any other SPECIAL func / unknown opcode), SYSCALL
  (SPECIAL func 0x0C, halts), **MFC0 / MTC0 / RFE** (COP0 opcode 0x10).
  32-entry register file with `$0` hardwired.
  **COP0 subset:** Status (IE/KU triple stack + IM), Cause (ExcCode +
  IP reflecting cpu_irq), EPC. Exception entry is sampled at clean
  instruction-retire boundaries: if a delay slot is outstanding, the
  exception defers until the delay slot resolves. On entry: push IE/KU
  stack, ExcCode=0, save EPC=next_pc, PC←EXC_VECTOR (parameter).
  **Branch delay slot** honoured from day one; taken-branch and
  delay-slot retires are both flagged in the trace.
  **Strict mode:** `STRICT_UNSUPPORTED` parameter (default 0). When
  set, unsupported opcodes halt the core and latch the offending
  pc/instr word into `trap_o` / `trap_pc_o` / `trap_instr_o` instead
  of silently retiring as NOPs. The canonical NOP (`instr == 32'h0`,
  SLL $0,$0,0) is always treated as a real NOP. Retire trace flag
  bit 7 marks strict-trap retires. Used by the BIOS smoke TB; other
  benches leave it off for backwards compatibility.
  Deferred: BD bit in Cause, nested interrupts, syscall/break
  exception dispatch, R-type ALU/shifts/HI-LO.
- `iop_exec_stub.sv` — **RAM-backed IOP execution primitive (bridge
  module).**
  Not a MIPS core, not an ISA decoder. A tiny FSM sequencer that fetches
  its micro-ops from IOP RAM through the real `iop_memory_map_stub`
  CPU-side port — the same way a future instruction-fetching CPU will.
  The control program is no longer RTL-resident; it lives as data in
  RAM that someone (a TB, eventually a BIOS loader) preloads before
  pulsing `go_i`.
  **Five opcodes**: `HALT`, `WRITE(addr, data)`, `READ(addr)`,
  `WAIT_IRQ`, `BNE(target_pc, expected)` — branch if the last READ's
  result does not equal `expected`, enabling real loops.
  Op layout in RAM: 16 bytes per op (`pc<<4` addressing). Word 0 is
  the opcode (low 4 bits), word 1 is addr or branch target, word 2 is
  data or expected value, word 3 is reserved. `SCRIPT_BASE` is a
  parameter (default 0x0000_0400).
  Takes `cpu_irq` from the IOP INTC; `WAIT_IRQ` genuinely blocks until
  a real interrupt asserts. One trace event per op completion with
  flag bits marking WAIT_IRQ exit (bit 1), HALT entry (bit 2), and
  BNE taken (bit 3). When a real MIPS decode primitive eventually
  arrives, it replaces this module while keeping the same map / DMA /
  INTC hookup verbatim.
- `iop_dmac_reg_stub.sv` — IOP DMAC for one SIF-facing channel
  (CHANNEL=9, PATH_ID=9, MASTER_ID=4). Register surface (low-byte
  offsets): MADR @ 0x00, BCR @ 0x04, CHCR @ 0x08, DONE_COUNT @ 0x0C
  (read-only monotonic counter); start bit is CHCR[0].
  Real data path: on start, DMAC latches MADR/BCR, then steps through
  IDLE → FETCH_WAIT → ACTIVE_SEND → DONE per beat, sourcing 32-bit words
  from IOP RAM through the map's `dma_rd_*` port (src_addr stepping by
  4 per beat). Endpoint is a word-granularity ready/valid/last stream
  with `ep_ready` back-pressure — no false completion under stall.
  Emits DMA_CFG on register writes, DMA_START on arm, DMA_BEAT per
  accepted beat (with src_addr + remaining count), DMA_DONE on the
  final beat. `done_count_o` is a monotonic visible counter.
  `irq_completion_o` is a one-cycle pulse on S_DONE — wired into the
  IOP INTC as source bit 0 so software can observe channel completion.
  Only reachable through the real IOP map at 0x1F80_1520.

## Explicit non-goals (current step)

- Full MIPS R3000 ISA coverage (the core is still a narrow subset;
  strict-mode halts on the first unsupported opcode so the BIOS tells
  us what to grow next)
- Full 2 MiB RAM sizing (stub defaults stay small for sim speed; the map
  window is 2 MiB and truncates at the connection to the smaller stub)
- IOP I/O beyond the currently decoded regions (DMAC ch9 / INTC / BIOS);
  SPU2, timers, and other peripherals are not wired yet
- IOP DMAC channels other than ch9 (SIF0 IOP→EE)
- Real Sony BIOS execution (the smoke TB's synthetic bootstrap is the
  current committed content; swapping in a user-supplied dump is a
  drop-in exercise that will reveal the next missing opcode)

## Scope boundary

This directory owns IOP CPU execution, IOP-local RAM/I/O decode, IOP
interrupt intake, IOP DMAC channels, and BIOS-side IOP boot sequencing
behavior (per `docs/contracts/iop.md`).

The IOP side now runs a MIPS R3000 subset from an architecturally
correct BIOS reset vector, with precise interrupt exception entry and
a RAM-resident ISR. The project has crossed five architectural seams:
  1. TB-orchestrated → fabric-orchestrated (scripted exec stub)
  2. RTL-resident → RAM-resident control (exec stub reads ops from RAM)
  3. Micro-op bridge → real ISA decode (iop_core_stub)
  4. Polled completion → asynchronous exception-driven control flow
     (COP0 + cpu_irq)
  5. TB-preloaded RAM as reset source → BIOS ROM at 0xBFC0_0000
     (shared BIOS wired through the IOP map; hand-assembled bootstraps
     prove the seam before any real Sony BIOS is attempted)

Each seam preserved every prior module — only where code comes from
evolved.

## Planned next increments

These are possibilities, not commitments — order will be decided per the
next architectural question:

- **BIOS-driven core growth:** point `tb_iop_core_bios_smoke` at a
  user-supplied BIOS dump (swap the TB's synthetic preload for
  `$readmemh` into `u_bios.mem`), observe the first unsupported
  opcode, add it to `iop_core_stub`, repeat. Expected near-term
  additions: ANDI, ADDU/SUBU, SLL/SRL/SRA, JAL, SLT(U). Do not add
  speculatively; let the BIOS trace drive the order.
- Core exception growth as the BIOS path demands it: BD bit in
  Cause, nested interrupts, syscall/break exception dispatch.
- Other IOP DMAC channels (CDVD / SPU2 / DEV9 / SIF1-2 / SIO2).
- IOP map expansion: remaining IOP I/O (0x1F800000), SPU2
  (0x1F900000).