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/sif.md

@@ -0,0 +1,45 @@
+# SIF Contract
+
+Status: `Draft`
+
+## Purpose
+
+Define the communication contract between EE and IOP.
+
+## Owns
+
+- SIF register behavior visible on both sides,
+- mailbox/flag exchange,
+- DMA-linked data movement endpoints,
+- synchronization semantics required by BIOS and basic software.
+
+## Inputs
+
+- EE-side register writes and DMA requests,
+- IOP-side register writes and DMA requests,
+- reset and interrupt-state changes.
+
+## Outputs
+
+- flag and mailbox visibility on both sides,
+- DMA endpoint readiness/traffic,
+- trace events.
+
+## Questions to lock
+
+- What minimum SIF behavior is required before BIOS reaches meaningful IOP boot?
+- Can early milestones use a narrower command subset?
+- How will SIF traces be correlated between EE and IOP timelines?
+
+## Allowed early stubs
+
+- mailbox/flag-only implementation,
+- reduced DMA payload path,
+- synchronous fake acknowledgements for platform smoke tests.
+
+## Required debug visibility
+
+- MSCOM/SMCOM writes,
+- flag transitions,
+- SIF DMA starts/completions,
+- mismatched or stalled handshakes.