retroDE_ps2/docs/decisions/0006-vram-roadmap.md

# Decision 0006: VRAM Roadmap

Status: `In progress` — Ch251.4 near-term rescue applied, longer-term work
queued.

## Context

The Ch251 hardware demo build (`de25_nano_psmct32_raster_demo_top`) failed the
Quartus Fitter on Agilex 5 with **516 / 358 M20K** (144%). The Fitter resource
report attributed ~410 M20Ks to two replicated `vram_bram_stub` banks:

```
u_demo|u_vram|mem_rtl_0   Logical Size: 4194304 bits   M20K blocks: 204.800
u_demo|u_vram|mem_rtl_1   Logical Size: 4194304 bits   M20K blocks: 204.800
```

Root cause: `vram_bram_stub` exposes **1 write + 2 independent read ports**.
An M20K block has at most two physical ports total (and at most one write
port). To honour 1W + 2R, Quartus replicates the entire storage so each read
port gets its own simple-dual-port BRAM, with the write fanned to both copies.
True dual-port would not have rescued this — TDP still gives only 2 physical
ports, not 3.

The two read ports serve distinct clients:

- **read** — PCRTC scanout (every pixel)
- **read2** — PSMT4 RMW old-byte read on the rasterizer write path

The Ch251 build draws PSMCT32 sprites only. The PSMT4 RMW pipe is wired but
never fires (`is_t4_emit` stays low), so read2 is dead weight on hardware.

## Decision (Near-Term — Ch251.4)

Add a parameter `ENABLE_READ2` to `vram_bram_stub`:

- Default `1` keeps every simulation TB and every PSMT4-exercising path
  byte-identical.
- Hardware top (`de25_nano_psmct32_raster_demo_top`) overrides to `0`. When
  disabled, the read2 always_ff branch contains **no reference** to `mem`,
  so Quartus infers a single 1W+1R simple-dual-port BRAM (~205 M20Ks at
  512 KiB) instead of two replicas (~410 M20Ks).

This is a **scoped hardware-demo build profile**, not a general fix. It is
correct only as long as the hardware build is PSMCT32 (or any non-PSMT4
format). Any future hardware build that exercises PSMT4 RMW must either
re-enable read2 (and accept the M20K cost) or first land the long-term
architecture below.

## Decision (Long-Term)

Before the GS path expands beyond PSMCT32 on hardware (PSMT4 RMW, broader
format coverage, or a larger framebuffer), replace the replicated-multi-read
VRAM with one of:

1. **Arbitrated TDP VRAM scheduler** — one TDP backing memory. Port A serves
   PCRTC reads with priority; port B serves the writer / RMW path. PSMT4 RMW
   becomes multi-cycle and may stall raster writes. This is the most correct
   long-term FPGA shape.

2. **Line-buffer scanout** — PCRTC reads short bursts into a small line
   FIFO/line-buffer once per scanline, freeing the VRAM ports for writes for
   the rest of the line. More complex but closer to a scalable video
   architecture.

3. **Bank/tile partitioning** — split VRAM by banks so different clients
   typically hit different banks. Still needs conflict handling. Useful as a
   later optimization, not as the first replacement.

Eventually larger memory surfaces (≥ a few MiB of true PS2 VRAM, or the
32 MiB main RAM) will need SDRAM/HPS/DDR-backed storage with tiled BRAM
caches; the all-M20K convenience model does not scale.

## Triggers — when to revisit (Ch252)

Re-open this decision and land one of the long-term options above when
**any** of the following becomes true on a hardware build:

1. **PSMT4 RMW returns to the rasterizer write path on hardware.** Any
   GS draw flow that consults `is_t4_emit` needs the second VRAM read
   port live, which re-introduces the replication cost.

2. **More than one VRAM read client during scanout.** The current
   profile is one read client (PCRTC). A second simultaneous read
   consumer — texture cache fetch, CLUT sampler from VRAM, secondary
   display window, anything that races PCRTC for read bandwidth —
   recreates the 1W+nR shape that forced Quartus replication in the
   first place.

3. **VRAM_BYTES grows beyond the current 512 KiB profile.** 512 KiB
   already costs ~205 M20Ks per replica at Agilex 5 packing. Any
   expansion (larger framebuffer, multi-format scratch space, texture
   storage) at the current replicated shape exceeds the device budget.

A simulation/elaboration tripwire in `vram_bram_stub.sv` fires
(`$display` + `$fatal`) when `ENABLE_READ2 = 1` **and**
`BYTES >= 262_144` (256 KiB). 256 KiB is not magical — it is the
threshold above which replicated VRAM becomes a board-level
architectural decision rather than a casual parameter flip. The
tripwire is a loud canary in lint / sim; the **real protection is the
board-top parameter profile**.

## Consequences

- Ch251 ships on hardware with the read2-strip build profile. The
  bring-up runbook documents the override so anyone reading it later sees
  the explicit trade-off.
- Simulation regressions stay byte-identical (default `ENABLE_READ2 = 1`).
- Any chapter that re-enables PSMT4 on hardware **must** land an arbitrated
  / line-buffered VRAM design first. Surfacing this as a decision record
  keeps it from quietly slipping when scope expands.
- The Ch251 failure was a warning shot about VRAM strategy, not a fundamental
  blocker on the PS2 core. Actual 512 KiB framebuffer storage is ~205 M20Ks;
  the over-budget portion was the second full copy.