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

@@ -0,0 +1,71 @@
+# DMAC Contract
+
+Status: `Draft`
+
+## Purpose
+
+Define the EE DMA controller as a first-class subsystem with explicit channel
+behavior and traceability.
+
+## Owns
+
+- channel register state,
+- channel start/stop logic,
+- priority / scheduling policy,
+- interrupt generation,
+- transfer-side coordination to VIF, GIF, SIF, IPU, and scratchpad-related
+  endpoints.
+
+## EE channels in scope
+
+- ch0 VIF0
+- ch1 VIF1
+- ch2 GIF
+- ch3 IPU_FROM
+- ch4 IPU_TO
+- ch5 SIF0
+- ch6 SIF1
+- ch7 SIF2
+- ch8 SPR_FROM
+- ch9 SPR_TO
+
+## Inputs
+
+- CPU writes to DMAC registers,
+- memory responses,
+- endpoint ready/busy signals,
+- reset/interrupt masking controls.
+
+## Outputs
+
+- memory read/write traffic,
+- endpoint transfers,
+- stall/busy signals,
+- interrupt status updates,
+- channel-level trace events.
+
+## Questions to lock
+
+- What is the minimum channel set for first visible output?
+- How much of stall/ring behavior is required before BIOS or homebrew becomes
+  meaningful?
+- Will the internal datapath be modeled around 128-bit transfers from day one?
+
+## Allowed early stubs
+
+- channel register file with no data movement,
+- one-channel functional path for GIF-first testing,
+- simplified arbitration before full priority behavior.
+
+## Required debug visibility
+
+- per-channel start/stop,
+- source/destination context,
+- transfer counts,
+- interrupts,
+- blocked-on-endpoint reasons.
+
+## First meaningful milestone
+
+- ch2 GIF path can move a known-good packet stream from memory into a GS/GIF
+  test endpoint while producing deterministic traces.