Initial commit: retroDE_ps2 — first-of-its-kind PS2 GS FPGA core (DE25-Nano / Agilex 5)

RTL (GS rasterizer, EE core stub, platform bridge, LPDDR4B path), sim regression
(272 TBs), docs, and tooling. Copyrighted PS2 content (BIOS, game code, GS dumps,
and all dump-derived textures/traces) is excluded via .gitignore and stays local.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

rtl/sif/README.md

@@ -0,0 +1,91 @@
+# rtl/sif
+
+EE↔IOP subsystem interface. Matches `docs/contracts/sif.md`.
+
+## Current contents
+
+- `sif_mailbox_stub.sv` — minimal four-register mailbox/flag shell
+  (MSCOM / SMCOM / MSFLG / SMFLG). Independent EE-side and IOP-side register
+  ports. Directional set/clear semantics deferred; this phase only proves
+  that both sides observe consistent storage and that side-of-origin is
+  trace-visible. Per-register write arbitration: EE wins on same-register
+  collision, independent writes to different registers coexist.
+- `sif_dma_stub.sv` — receive-side DMA endpoint. Accepts qwords from a
+  DMAC channel's `ep_*` port into a small internal buffer (default DEPTH=8).
+  Capacity-safe: `in_ready` drops when `rx_count >= DEPTH`, `full_o`
+  exposed for testbench observation. TB-controlled `stall_in` input for
+  explicit stall testing. Read port for payload verification. No consume
+  path yet — once full, stays full. NOT an IOP — purely a bounded receive
+  buffer with trace emission per accepted beat.
+- `sif_mailbox_peer_stub.sv` — tiny active peer used in integration tests
+  to play "the IOP side" of a specific mailbox protocol. Re-armable
+  command-echo state machine (poll MSFLG → read MSCOM → write SMCOM →
+  write SMFLG → wait for TB to clear MSFLG → repeat). Refuses to re-fire
+  while the doorbell bit stays high, so lifecycle is explicit. Exposes
+  `ack_count_o` for testbench synchronisation.
+  Explicitly NOT an IOP core: no code execution, no BIOS bring-up, no
+  implicit flag clearing (re-arm is the TB's responsibility). Kept under
+  `rtl/sif/` precisely so it does not get misread as IOP maturity progress.
+- `sif_dma_iop_ram_bridge_stub.sv` — width-adapting bridge from a 128-bit
+  SIF DMA endpoint to 32-bit IOP-side writes. Splits each incoming qword
+  into four 32-bit writes at consecutive physical addresses from
+  `DEST_BASE_ADDR`. Little-endian unpacking. Drives the IOP memory map's
+  bridge-write port (`bridge_wr_*`). In-ready drops while the bridge is
+  flushing a qword — natural backpressure to the DMAC.
+- `sif_dma_ack_peer_stub.sv` — protocol combiner for the first combined
+  control+data SIF milestone. Observes a mailbox doorbell (MSFLG pending
+  bit) AND `sif_dma_stub.last_seen` (payload completion); only emits the
+  ack sequence (SMCOM=cmd + SMFLG=ACK) once both are true. Composes two
+  existing SIF primitives; does not fatten the plain mailbox peer with
+  DMA awareness.
+  Explicitly NOT an IOP.
+- `sif_dma_ee_ram_bridge_stub.sv` — width-adapting bridge from a 32-bit
+  SIF DMA endpoint (IOP→EE egress) to 128-bit EE-side writes. Mirror of
+  `sif_dma_iop_ram_bridge_stub` in the other direction: accumulates four
+  consecutive 32-bit beats into a qword (little-endian), then issues
+  one write through the EE memory map's bridge write port. Drops
+  `in_ready` during the one-cycle emit for natural back-pressure.
+  Handles partial-quad on `in_last` via byte-enable masking. Exposes
+  `last_seen_o` — a level-held latch that rises when the final beat of
+  a transfer is accepted, so EE-side protocol combiners can gate on
+  "payload fully landed."
+- `sif_dma_ee_ack_peer_stub.sv` — protocol combiner for the first
+  IOP-driven combined control+data SIF milestone. Polarity mirror of
+  `sif_dma_ack_peer_stub`: observes the mailbox's EE side for an IOP
+  doorbell (SMFLG pending bit), gates on
+  `sif_dma_ee_ram_bridge_stub.last_seen_o`, and only then reads SMCOM
+  and echoes MSCOM + MSFLG=ACK back IOP-ward. One-shot. Explicitly NOT
+  an EE core — purely a composition of two existing SIF primitives.
+
+## Current status
+
+The SIF seam is feature-complete for staged bring-up in both directions.
+Storage, active peer, lifecycle/re-arm, negative-path, EE→IOP DMA, three
+classes of backpressure (start / mid-transfer / full-stop), EE-driven
+combined control+data gating, a reverse-direction (IOP→EE) data path
+with its own stall semantics, AND the matching IOP-driven combined
+control+data handshake are all proven end-to-end. Further SIF-only work
+would be symmetry-chasing rather than unlocking new architectural
+questions.
+
+## Deferred follow-ons (not gaps)
+
+These are known extension points, intentionally not pursued yet:
+
+- **Re-armable combined control+data handshakes.** Both directions are
+  currently one-shot; re-arm mostly composes pieces already proven
+  separately. Nice-to-have.
+- **Directional write-ownership + flag set/clear semantics.** Currently
+  both sides of the mailbox can write any register with plain replace
+  semantics; real PS2 has directional set/W1C rules.
+- **Real EE↔IOP coordination.** Arrives once an IOP-side execution
+  primitive exists that can observe SIF as "IOP behaviour," not as a
+  peer stub.
+
+## Scope boundary
+
+This directory owns the SIF register shell and DMA-visible coordination.
+It does **not** own:
+- IOP CPU execution (`rtl/iop/`, not yet created)
+- EE-side addressing / kseg stripping for SIF registers (memory-map work)
+- Interrupt routing to INTC on SIF transitions (Wave 3)