thejayman77
ec82764bef
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>
76 lines
4.4 KiB
Markdown
76 lines
4.4 KiB
Markdown
# 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.
|