retroDE_ps2/docs/hardware/ps2_feeder_app.md

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)

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

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