retroDE_ps2/docs/ch435_frame_fbmsk_lightbuffer_closeout.md

Ch435 — FRAME.FBMSK light-buffer alpha

Root cause

The Ch434 current-frame light chain was structurally correct but the second draw of the CT32 conversion stage, draw 195973, has FRAME.FBMSK=0xff000000. The scheduler previously discarded that field when relocating the framebuffer, and the external LPDDR color path had no byte-mask transport. Draw 195973 therefore replaced alpha across the full 256x256 target instead of preserving the alpha produced by draw 195957. Feeding that incorrect all-128 alpha target through the remaining ping-pong passes made the integrated frame much too dark.

Static fidelity result

The first correction was an asset-boundary reconstruction. It retained alpha 128 on the 20,861 lit texels and alpha zero on the 44,675 black texels, then propagated that target through draws 196087, 196108, 196129, 196167, and 196177. The resulting 311-epoch zsrt139f52 replay passed production simulation and the DE25-Nano runtime gates with zero drops, overflows, AXI errors, Z mismatches, or color mismatches.

The board framebuffer is byte-identical to simulation at SHA-256 d0047677371a0f6e4e319458926f604a8599c92baaf34d09b8e1fd452e31662b. Its mapped mean RGB (26.38, 23.32, 21.19) is close to the PCSX2 frame mean (28.47, 23.54, 21.33), and the booth, lamp, rabbit, bench, and character are all readable. This supersedes the over-dark f49 result and is the live HDMI asset baseline. The remaining dominant visual defect is spatial speckle and edge noise, not global brightness.

Native RTL repair

The production path now carries a four-bit byte enable derived from FRAME.FBMSK with each fragment:

• the fixture generator preserves the captured upper 32 FRAME bits and rejects masks that are not byte-granular;
• the raster wrapper converts each 00 mask byte to an enabled write byte and each ff byte to a preserved destination byte;
• the request FIFO and color-align RAM carry the byte enable across the GS to EMIF path;
• partial opaque writes use the same ordered destination-read/modify/write path as alpha blends;
• the color stage merges disabled bytes from the destination after either the GS ALPHA equation or opaque source selection.

The directed color-blend regression preserves destination alpha with BE=0111, producing 0x8024180c. The 1,500-fragment Z/color regression also passes with zero errors.

The regenerated authentic two-draw fixture zsrt139l3f contains ff000000000a0000 in draw 195973's FRAME header. Its registered-gradient simulation passes 22 epochs and 131,072 fragments with zero drops, overflows, AXI errors, Z mismatches, or color mismatches. Most importantly, the native 256x256 output is byte-identical in all 65,536 words to the static corrected target: 44,675 black/alpha-zero texels and 20,861 lit/alpha-128 texels.

Accepted fit

The owner-controlled Quartus 26.1 GUI compile completed successfully on 2026-07-19. The accepted RBF is 4,112,384 bytes with SHA-256 55b23b94f51f1aab271d91aa4fa766561c044b9633146f25f4242b431f6ce902. All signoff classes are nonnegative:

• EMIF setup WNS +0.083 ns, TNS 0.000 ns;
• 25 MHz design setup WNS +6.324 ns, TNS 0.000 ns;
• hold minimum 0.000 ns, with zero TNS;
• recovery minimum +1.074 ns;
• removal minimum +0.017 ns;
• minimum-pulse-width minimum +0.200 ns.

Final resources are 38,387 / 46,800 ALMs (82%), 5,327,792 / 7,331,840 block-memory bits (73%), 344 / 358 RAM blocks (96%), and 160 / 376 DSP blocks (43%).

Hardware acceptance

The RBF checksum was verified on the DE25-Nano and core_loader.sh loaded it successfully; fpga0 reported operating. The authentic 22-epoch zsrt139l3f fixture then passed every texture CRC, staging, fresh-drain, and zero-drop gate. Its 307,200-word framebuffer has SHA-256 e2b9f847fb64f5dbc70f112df91c6fccc54bf439138f772927150ff99aa026ce, byte-identical to production simulation. The native target contains exactly 20,861 lit/alpha-128 pixels and 44,675 black/alpha-zero pixels in its 256x256 region, proving that draw 195973 preserves the destination alpha byte on silicon.

The complete 311-epoch f52 scene was then replayed on the same RBF. All epochs completed with zero fragment drops and its framebuffer remained byte-identical to simulation at SHA-256 d0047677371a0f6e4e319458926f604a8599c92baaf34d09b8e1fd452e31662b. HDMI therefore ends on the readable f52 scene. The accepted artifact is now the board's standard /home/terasic/cores/retroDE_ps2.core.rbf; the previous artifact is retained as retroDE_ps2.pre_ch435.core.rbf.