retroDE_ps2/docs/ch397_lpddr_alpha_plan.md

Ch397 — 224139 LPDDR alpha integration plan

Established state

• zsrt139a2 is the current live 640x480 opaque board composite from the matching 224139 capture: six epochs, 98,163 written pixels, zero board drops.
• The first in-bounds blended draw family is PSMT8 perspective triangles (idx31075+, TBP=13824, CBP=14282, 128x128, PRIM.ABE=1).
• Its recorded ALPHA_1 state is 0x0000008000000062; this is a generic selector/FIX blend, not the existing source-over-only shortcut.

Implemented cut (local RTL)

The current SH3 renderer sends final opaque pixels directly to gs_lpddr_zc_emit. Its full-frame colour lives only in LPDDR, while the existing combined triangle alpha path reads destination colour from BRAM. Therefore a full-frame alpha implementation must extend the LPDDR emitter:

1. carry ABE plus ALPHA selector/FIX metadata with each fragment packet;
2. issue a single-pixel colour read after a Z-pass (or immediately for a non-Z alpha fragment);
3. apply the existing gs_alpha_blend generic selector equation in the emitter's AXI domain;
4. enqueue that blended colour through the existing colour writer, preserving the ordered scene-marker drain contract.

Implemented in the local RTL:

• gs_lpddr_zc_emit now carries {ABE,A,B,C,D,FIX} through its request and colour-align FIFOs;
• gs_lpddr_color_blend bypasses opaque pixels and, for ABE pixels, reads the containing 256-bit LPDDR beat, selects the addressed 32-bit lane, invokes generic gs_alpha_blend, and emits the ordered write payload;
• gs_lpddr_rd_arb has a fifth client for that destination read, below scanout and Z/reload traffic;
• the real raster wrapper forwards the per-primitive alpha snapshot.

make -C sim tb_gs_lpddr_color_blend passes the actual 0x62 selector pattern: source 0x80402010 over destination 0x40203020 produces 0x80001010 (Cd - Cs, clamped), proving the LPDDR read lane and blend datapath together.

The complete three-epoch integration replay is exact: 102,493 fragments, 102,479 Z passes, three ordered drains, zero drops/overflows/BRESP errors, Z 0/307200 mismatches, and color 0/51525 mismatches. The final 640x480 simulation framebuffer is sh3_zsrt139a3_sim_fb.mem (SHA-256 a331fd9d68aaccb35310051ad9091f6c02acafcc4b86391cecedaea8f08ce28f).

Timing closure and deploy artifact (2026-07-15)

The first alpha fit exposed the destination-read/blend arithmetic as an unregistered 310 MHz cone. The final implementation uses a registered shift/add blend engine (no new DSPs), a registered generic async-FIFO write port, and registered request-head control. The last 42 ps setup family was the staged scene-marker bit feeding the color-align RAM write enable; fragment valid and marker valid are now separate registered controls, removing that decode from color writes.

The final Quartus 25.3.1 build is signoff-clean: setup +0.012 ns, hold 0.000 ns, zero setup TNS, and synthesis/fit/STA/assembler all completed with zero errors. The split loader artifact is output_files/retroDE_ps2.core.rbf, SHA-256 f921f0bcde7fc9a8fe01bf39166327101e6dcbf0faf68398082207c8498ca349. build_quartus.sh now explicitly runs post_flow.tcl after its direct quartus_asm step, because direct assembler invocation does not dispatch the QSF post-flow hook by itself.

The RBF and all zsrt139a3 host assets were copied to the DE25 and SHA-checked. The first runtime load hit an SDM service-buffer timeout and left configfs in an uninterruptible write. A controlled remote reboot restored network ping, but SSH had not restarted at closeout time; a physical power cycle is the remaining prerequisite before retrying the load and taking the board FB dump.

First silicon run and request-FIFO correction (2026-07-16)

The authoritative Quartus 26.1 GUI RBF loaded successfully and all three texture uploads, readback CRCs, runtime palettes, staging counts, Z preclear, and zero-drop checks passed. The render itself did not drain: epoch 0 reached 36,958 framebuffer beats after 120 seconds and frame_drained remained low. The resulting interrupted composite was 298,888/307,200 pixels equal to the simulation framebuffer, with 8,312 mismatches caused by rebinding texture and palette state while old fragments were still executing.

Root cause was the Ch397 timing cut in generic gs_async_fifo: the allocation pointer was published to the read clock when the write was accepted, one writer cycle before the staged RAM write committed. The production request FIFO crosses a 40 MHz writer into a roughly 310 MHz reader, so the consumer could observe the pointer about 19 ns before the data existed and replay stale RAM entries. The earlier FIFO regression used a faster writer than reader and therefore did not exercise this CDC ordering failure.

The FIFO now maintains separate allocation and commit pointers. Full accounting uses allocation, while only the pointer advanced by an actual staged RAM commit crosses into the reader. A production-ratio stress test (40 MHz write, 312.5 MHz read) transfers 3,284/3,284 ordered words with zero duplicates/drops. The full zsrt139a3 integration replay remains exact: 102,493 fragments, all three drains, zero drops/errors, and Z/color scoreboards at zero mismatches. This correction is ready for the owner-controlled Quartus 26.1 GUI compile and subsequent silicon rerun.

Corrected FIFO silicon acceptance (2026-07-16)

The owner-controlled Quartus 26.1 GUI compile completed successfully. The final fit used 37,153/46,800 ALMs and 284/358 RAM blocks; setup slack was +0.064 ns, hold slack was 0.000 ns, and every reported TNS was zero. The fresh split RBF is output_files/retroDE_ps2.core.rbf, 3,915,776 bytes, SHA-256 a1adf0a706465709e3078dedc053433e34807a40a57733c1cd2e14c9d64461fa. Its hash was checked again on the DE25 before core_loader.sh loaded it, and fpga0 reported operating.

The corrected request FIFO is now proven on silicon. Epochs 0, 1, and 2 completed with 54, 68, and 10 records respectively; all texture CRC, runtime palette, staging, Z-preclear, and zero-drop gates passed. The 10-record alpha epoch is short enough for frame_drained to clear and rise entirely between HPS bridge polls, so the host now accepts that missed-low case only if both the new per-GO record count and framebuffer-beat count prove forward progress. A one-second low-observation window replaces the old 120-second delay; the full board run now completes in about 23 seconds with rc=0.

The final board framebuffer and simulation framebuffer are byte-for-byte identical across all 307,200 PSMCT32 words (zero mismatches), both with SHA-256 a331fd9d68aaccb35310051ad9091f6c02acafcc4b86391cecedaea8f08ce28f.

First acceptance scope

The generated zsrt139a3 fixture carries two opaque setup epochs followed by authentic blended draw 32391 (10 triangles, safely within the 2048-word staging limit). The six-draw family remains the next scale-up target; its first four draws exceed that current staging window and must be split across ordered epochs before board replay. Do not claim frame fidelity until the subset is locally replayed and board-read back against its own trace.