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>

docs/contracts/iop.md

@@ -0,0 +1,60 @@
+# IOP Contract
+
+Status: `Draft`
+
+## Purpose
+
+Define the separate I/O Processor subsystem as an explicit peer block, not an
+afterthought.
+
+## Owns
+
+- IOP CPU execution,
+- IOP-local RAM/I/O decode,
+- IOP interrupt intake,
+- IOP DMAC channels and their peripheral-facing coordination points,
+- BIOS-side IOP boot sequencing behavior, including `IOPBOOT`,
+  `IOPBTCONF`-driven module loading, and early module-init-visible progress as
+  seen from the IOP side.
+
+## Inputs
+
+- clocks/resets,
+- BIOS/boot vectors,
+- SIF signaling,
+- IOP DMA/peripheral responses,
+- interrupt sources from IOP-side peripherals.
+
+## Outputs
+
+- IOP memory/I/O requests,
+- DMA requests,
+- SIF activity,
+- debug trace events.
+
+## Questions to lock
+
+- How early do we expect a real IOP boot path versus a stubbed acknowledgement
+  model?
+- Which IOP peripherals must exist before the BIOS path becomes meaningful?
+- Will PS1-compatibility-only behavior be ignored initially?
+- Which IOP DMAC channels must exist for the first BIOS-progress milestone?
+
+## Allowed early stubs
+
+- minimal boot-progress IOP stub,
+- fake module-load acknowledgements for ultra-early scaffolding,
+- reduced DMA interaction for trace-first bring-up.
+
+## Required debug visibility
+
+- PC stream,
+- interrupt events,
+- IOP DMAC channel activity,
+- SIF mailbox/flag transitions,
+- module-load progress markers if detectable.
+
+## Clarification
+
+- BIOS/firmware storage and address visibility belong to the memory contract.
+- BIOS-driven IOP boot behavior belongs here.