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>

references/supplemental/sony_official_docs.md

@@ -0,0 +1,56 @@
+# Official Sony Documentation
+
+Codex's pass leaned on `ps2tek` as the low-level reference. `ps2tek` is
+excellent but community-compiled. For register semantics where authority
+matters, the two original Sony manuals below sit one layer closer to silicon.
+
+## GS User's Manual v6.0
+
+- Primary register reference for the Graphics Synthesizer.
+- Covers the privileged register block at `0x12000000`: `PMODE`, `SMODE1/2`,
+  `SYNCH1/2`, `SYNCHV`, `SRFSH`, `DISPFB1/2`, `DISPLAY1/2`, `EXTBUF`,
+  `EXTDATA`, `EXTWRITE`, `BGCOLOR`, `CSR`, `IMR`, `BUSDIR`, `SIGLBLID`.
+- Covers GS-internal host-visible registers (PRIM, PRMODE, RGBAQ, ST, UV, XYZ,
+  TEX0/1, CLAMP, FOG, TRXPOS, TRXREG, TRXDIR, etc.) and their packet forms.
+- Authoritative for PCRTC output-side behavior that `ps2tek` summarizes.
+
+Location: `GS Users Manual` — https://usermanual.wiki/Pdf/GSUsersManual.1012076781/html
+
+Suggested use: primary reference for any GIF/GS implementation work. When
+`ps2tek` and this manual disagree on a register detail, defer to the manual.
+
+## VU User's Manual
+
+- Official reference for VU0 and VU1.
+- Defines the dual-pipeline 64-bit doubleword instruction format (upper +
+  lower pipe).
+- Defines register files: 32 × 128-bit VF, 16 × 16-bit VI.
+- Defines VU memories: VU0 has 4 KiB MicroMem0 + 4 KiB VU Mem0; VU1 has
+  16 KiB MicroMem1 + 16 KiB VU Mem1.
+- Defines the two execution modes: micro mode (VU as standalone microprogram
+  engine) and macro mode (VU0 as EE COP2; VU1 usually in micro).
+- Covers VIF-to-VU interaction enough to interpret microprogram upload paths.
+
+Location: `VU User's Manual (Emotion Engine Vector Operation Unit Guide)` —
+https://studylib.net/doc/25815876/vuusersmanual.158394566
+
+Suggested use: primary reference for VIF/VU workstream (Codex workstream 4).
+Re-read before locking any instruction-decode or pipeline-timing decision.
+
+## Why these matter for FPGA planning
+
+- Emulator source trees encode *one interpretation* of Sony's hardware. When
+  the RTL has to behave like silicon at a cycle or packet level, the original
+  manuals are the tiebreaker.
+- Several non-GS "hacks" in PCSX2 exist because the emulator's floating-point
+  behavior diverges from the VU/EE spec. Reading the manual clarifies which of
+  those are true hardware quirks vs. emulator workarounds — a distinction that
+  matters more for FPGA than for software emulation.
+
+## Caveats
+
+- Both manuals are Sony confidential documents that leaked years ago. They are
+  the authoritative source on register semantics but were never officially
+  published. Treat them as technical reference, not as a licensing document.
+- Version drift: the GS manual is v6.0 in the linked copy. Late-silicon
+  revisions may not be covered exhaustively.