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/hardware/ps2_feeder_app.md

@@ -0,0 +1,75 @@
+# ps2_feeder — HPS userspace command producer (Ch339)
+
+`tools/ps2_feeder.c` is a native HPS application that encodes structured drawing commands into the
+proven GS-feeder staging format and streams them to the FPGA over the existing HPS bridge
+(`/dev/mem` + `mmap`), using the **same** register protocol as the `ps2_feeder_*.sh` diagnostic
+anchors. The RTL and bridge protocol are unchanged — this is a host-side encoder + streamer that
+replaces hand-built `devmem` word lists with structured, validated commands.
+
+## Build (on the HPS / target, native gcc)
+
+```sh
+gcc -O2 -o ps2_feeder ps2_feeder.c
+```
+
+Portable C (stdint + mmap); builds the same on the board or a host for `--dump`/`--dry-run`.
+
+## Use
+
+```sh
+./ps2_feeder --list                       # built-in named scenes
+./ps2_feeder accum                         # stream one named scene (submit/go/wait)
+./ps2_feeder retrigger-a retrigger-b retrigger-a   # A -> B -> A, each cleanly retriggered
+./ps2_feeder -f scene.txt                  # stream scenes from a text file
+./ps2_feeder --dump accum                  # print the 256 staging words (no board access)
+./ps2_feeder --dry-run -f scene.txt        # encode + validate only, no board access
+./ps2_feeder --base 0x40000000 accum       # override bridge base (default 0x40000000)
+```
+
+Built-in scenes reproduce the proven Ch333–Ch338 fixtures **byte-for-byte**: `color-tri`,
+`native-rect`, `gouraud-tri`, `accum`, `retrigger-a`, `retrigger-b`, `zpersist-near`,
+`zpersist-far`, `zpersist-grad`.
+
+Per scene the app prints objective diagnostics: triangle/rect counts, staged words, expanded
+primitives, batch estimate, the hardware staged-address / records / wait-cycle readbacks, and
+completion. It polls feeder-ready before staging, after staging, and after GO — so it makes no host
+timing assumptions and honours the Ch337 whole-scene-drain contract for clean back-to-back scenes.
+Lists larger than the FIFO depth are handled by the RTL (Ch336 batching); the host just streams all
+words and waits for completion.
+
+## Scene file grammar
+
+One scene per `go` (and a trailing scene at EOF); `#` starts a comment; whitespace-separated:
+
+```
+tri      x0 y0 x1 y1 x2 y2  z  r g b                               # flat triangle
+trig     x0 y0 r0 g0 b0  x1 y1 r1 g1 b1  x2 y2 r2 g2 b2  z          # gouraud (per-vertex) triangle
+tritile  T z r g b                                                  # flat triangle filling grid tile T (0..15)
+rect     T z r g b                                                  # native rectangle in grid tile T
+tex0     TBP TBW TW TH TFX                                          # bind scene texture (Ch341)
+tritex   x0 y0 u0 v0  x1 y1 u1 v1  x2 y2 u2 v2  z  r g b            # textured triangle, per-vertex UV (needs tex0)
+persp                                                               # mark scene PERSPECTIVE (needs tex0)
+persptri x0 y0 s0 t0 q0  x1 y1 s1 t1 q1  x2 y2 s2 t2 q2  z  r g b   # perspective tri, fixed-point ST/Q (Ch342)
+sprite   x0 y0 x1 y1  u0 v0 u1 v1  r g b                            # textured + source-over alpha SPRITE (Ch345a; needs tex0)
+go                                                                  # submit accumulated scene; begin next
+```
+
+Coordinates are 12-bit screen pixels (0..4095); colors 0..255; `z` is the 32-bit GS Z (GEQUAL test,
+higher = nearer). Malformed, out-of-range, and oversized (> 256 staging words) scenes are rejected
+cleanly before any board access.
+
+**Ch345a — `sprite` (runtime textured-alpha SPRITE ingestion).** A `sprite` record draws the bound `tex0`
+texture (PSMCT32) over the screen rect `(x0,y0)-(x1,y1)` with affine per-corner UV, source-over alpha
+blended against the destination. The source alpha is the **texel's** alpha (TCC=1), NOT the `r g b` tint —
+the tint MODULATEs the texel color (pass `128 128 128` for identity). Sprite scenes set staging word0[33]
+(`sprite_mode`) and are exclusive with tris/rects/perspective (the host fails closed on a mixed scene).
+This is the Ch344-proven hardware subset; it is runtime SPRITE ingestion, not authentic-content ingestion.
+
+## Verification
+
+`tools/test_ps2_feeder.sh` compiles the app, proves every named scene's staging output is
+byte-equivalent to its golden `bake.py` fixture, and checks that malformed/oversized/out-of-range
+input is rejected. Run it on any host with gcc + python3 (no board needed).
+
+`docs/hardware/ps2_feeder_test.sh` (and the other `ps2_feeder_*.sh` scripts) remain the low-level
+`devmem` diagnostic anchors.