retroDE_ps2/docs/ch357_zsched_integer_xy_closeout.md

Ch357 ZSCHED integer-XY closeout

This note pins the persistent-Z ZSCHED signoff contract after the float-oracle mismatch was isolated.

Contract

• The RTL renderer consumes integer screen coordinates from XYZ2. gs_stub.sv takes the integer X/Y fields and has no GS 12.4 subpixel raster path in this milestone.
• The ZSCHED fixture generator also emits integer XYZ2 coordinates via quant_xy before packing vertices. The subpixel geometry from the dump is not present in the feeder data.
• Therefore the signoff reference maps must use the same quantized XY vertices. For ZSCHED, gs_make_sh3_scheduler_fixture.py defaults --authz --tag zsched to integer-XY reference. Use --float-ref-xy only as a report-only fidelity-debt diagnostic.

Canonical fixture emit:

make -C sim sh3_zsched_fixture

Equivalent explicit command:

python3 tools/gs_make_sh3_scheduler_fixture.py \
  --draw-list 8634,12757,145742 --authz --tag zsched \
  --pscale auto,auto,384 --xy-quant round,round,round --ref-xy-quant --emit

Current Gates

• tb_top_psmct32_sh3_zsched gates the integer-XY oracle at the documented 90% MULTI <=1 texel reciprocal floor.
• tb_top_psmct32_sh3_zrop replays the captured fragment trace through the clamp16 persistent-Z scoreboard.
• tb_top_psmct32_sh3_zint drives the real raster into the persistent-Z/color LPDDR path and gates zero fragment drops.
• sh3_zsched_board_compare regenerates the fragment trace and zint framebuffer dump, requires the pulled board framebuffer to match zint byte-for-byte, then replays emitted fragment colors through clamp16 GEQUAL and requires exact framebuffer color agreement.
• These three targets are now prerequisites of the default make -C sim run.

Measured integer-XY fixture result: ALL=20227/21645 (93.4%), MULTI=7111/7587 (93.7%), with tb_top_psmct32_sh3_zsched PASS. The old float-XY diagnostic stayed below the 90% MULTI floor because it compared against geometry that the hardware was not fed.

Measured board readback result from the refreshed fixture: sh3_zsched_board_fb.mem and sh3_zsched_zint_fb.mem both hash to acd4076dfe3843a384f8fa885613484c5e62a9bbcbb5dff4d5bf78b168a22e2f; cmp reports no byte differences. --owner replay-color also reports 53760/53760 (100.00%) exact for both board and zint, with 50184 replayed fragments, 29937 Z-pass updates, and 21590 covered pixels.

Board Readback

After a board dump:

sudo ./ps2_sh3_sched --zbuf sh3_zsched_epochs.txt --dump-fb sh3_zsched_board_fb.mem
scp terasic@192.168.50.161:~/sh3_zsched_board_fb.mem sim/data/top_psmct32_raster_demo/
python3 tools/gs_fb_to_png.py sim/data/top_psmct32_raster_demo/sh3_zsched_board_fb.mem \
  sim/data/top_psmct32_raster_demo/sh3_zsched_board_fb.png 256 210 3
make -C sim sh3_zsched_board_compare

Optional oracle diagnostic maps:

make -C sim tb_top_psmct32_sh3_zsched
python3 tools/analyze_zsched_fb.py sim/data/top_psmct32_raster_demo/sh3_zsched_board_fb.mem \
  --owner replay-color --frags sim/traces/rtl/zsched_frags.txt
python3 tools/analyze_zsched_fb.py sim/data/top_psmct32_raster_demo/sh3_zsched_board_fb.mem \
  --owner replay --frags sim/traces/rtl/zsched_frags.txt --maps

The --owner replay texture/refmap radius score and sh3_zsched_board_fb_*oracle_*.png images are diagnostic only. The hard hardware-vs-RTL readback gate is make -C sim sh3_zsched_board_compare; the hard emitted-fragment content check is --owner replay-color.