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