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

@@ -0,0 +1,40 @@
+# rtl/dmac
+
+EE DMAC. Matches `docs/contracts/dmac.md`.
+
+## Wave 2 / Wave 2.5 contents
+
+- `dmac_reg_stub.sv` — channel-2-focused register shell + single-transfer
+  state machine. Wave 2.5 revision is memory-backed: DMAC now issues real
+  memory reads via the `mem_rd_*` port (connected directly to
+  `ee_ram_stub` in the current topology; routing through
+  `ee_memory_map_stub` is deferred). State flow: IDLE → FETCH_WAIT →
+  ACTIVE_SEND → DONE. MADR is the real fetch source address.
+  See `docs/wave25_memory_backed_dma_plan.md`.
+
+  **EE-core chapter 3** added a CPU write path: the EE memory map's
+  new `ee_dmac_ch2_wr_*` port drives `reg_wr_en` / `reg_offset` /
+  `reg_wr_data`, so the EE core can program MADR/QWC/CHCR from a
+  MIPS bootstrap via `SW`.
+
+  **EE-core chapter 4** added a CPU read path (`reg_rd_en` /
+  `reg_rd_data` / `reg_rd_valid`, 1-cycle latency) plus a DONE_COUNT
+  monotonic counter at offset 0x40. CHCR/MADR/QWC/TADR read back
+  their stored values; DONE_COUNT increments each time the state
+  machine enters S_DONE. The EE map forwards CPU reads in the same
+  DMAC window through a new `ee_dmac_ch2_rd_*` pair, so software
+  can now poll CHCR.start or compare DONE_COUNT before/after a
+  transfer without needing INTC.
+
+## Explicit non-goals (Wave 2 / 2.5)
+
+- Multi-channel arbitration or fairness.
+- Chain mode (normal / chain / interleaved transfer modes).
+- Stall / ring / suspend semantics.
+- Interrupt routing to INTC.
+- QWC > 1 multi-beat transfers (state machine is shaped for it; initial
+  signoff is QWC == 1 per Wave 2.5 plan).
+- Routing through `ee_memory_map_stub` (current topology is direct to
+  `ee_ram_stub`).
+
+Each of these is a future-wave concern, not a stub-plan shortcut.