retroDE_ps2/docs/ch318-lpddr-fb-bringup.md

Ch318 — LPDDR framebuffer write/readback: board bring-up

ONE bitstream. All test controls are runtime, via HPS bridge registers — no rebuild to go disabled → canary → full. Defaults are safe: arm OFF, canary ON, base 0x80000000. The booted core writes nothing to LPDDR until the HPS arms it.

Runnable script

docs/hardware/ps2_lpddr_test.sh (same style as ps2_status.sh; bridge base defaults to 0x40000000, busybox devmem):

./ps2_lpddr_test.sh            # read-only LPDDR status (safe)
./ps2_lpddr_test.sh --canary   # arm canary, verify 32 B vs expected, PASS/FAIL, auto-disarm
./ps2_lpddr_test.sh --full     # arm full frame, hash 8 KiB vs expected md5, PASS/FAIL, auto-disarm
./ps2_lpddr_test.sh --disarm   # force disarm (LPDDR_CTRL=0x2)

The manual register/dd reference below is what the script automates.

Build

QSF (already set): GS_TILE_PSMCT16FB_DEMO=1 + GS_LPDDR_FB=1 (plus the usual GS_RMW_DEMO). Build/load the .rbf once. That's the only build.

HPS bridge register map (new in Ch318)

Offsets are relative to the PS2 HPS-bridge base — the same base retrodesd already uses to reach CORE_ID/OSD_CTRL/INPUT_P1 on this core (the HPS2FPGA bridge window). 32-bit accesses.

Offset	Name	R/W	Meaning
0x018	LPDDR_CTRL	RW	bit0 = arm (1 = permit AXI writes), bit1 = canary (1 = write only the 32-byte top line). Reset = 0x2 (disarmed, canary).
0x01C	LPDDR_FB_BASE	RW	LPDDR byte base address. Reset = 0x8000_0000.
0x02C	LPDDR_STATUS	R	bit0 = idle, bit1 = bresp error seen, bit2 = FIFO overflow seen.
0x030	LPDDR_BYTES	R	total bytes written.
0x034	LPDDR_BURSTS	R	total 32-byte bursts issued.

The framebuffer itself is read from physical LPDDR 0x8000_0000 (the f2sdram AXI address is the HPS physical address — the qsys slave maps a flat 4 GiB), which is the reserved region from /proc/iomem (below Linux System RAM at 0x82000000 — safe).

Canary test (32-byte write, deterministic)

1. Confirm defaults: read LPDDR_CTRL (expect 0x2), LPDDR_FB_BASE (expect 0x8000_0000).
2. Baseline: sudo dd if=/dev/mem bs=1 skip=2147483648 count=32 2>/dev/null | hexdump -C
3. Arm in canary mode: write LPDDR_CTRL = 0x3 (arm=1, canary=1).
4. Re-read the 32 bytes (same dd). Expect the top scanline (PSMCT16 green = 0x8200): 00 82 00 82 00 82 00 82 00 82 00 82 00 82 00 82 (×2 lines = 32 bytes).
5. Optional: read LPDDR_BURSTS (advancing) + LPDDR_STATUS (bit1/bit2 = 0). PASS = bytes changed baseline → the 00 82 pattern (fabric reached LPDDR at the expected physical address). Then disarm: write LPDDR_CTRL = 0x2.

Full-frame test (8 KiB)

1. Arm full: write LPDDR_CTRL = 0x1 (arm=1, canary=0).
2. sudo dd if=/dev/mem bs=4096 skip=524288 count=2 2>/dev/null | md5sum Expect 3b12baffc00bb6419fa66272c75b2cc7 (the exact sim image).
3. Confirm LPDDR_STATUS bits 1,2 = 0 (no bresp/FIFO errors). Disarm when done (0x2).

Notes

• 0x80000000 = 2147483648 bytes; skip=524288 blocks × 4096 = same address.
• Never read/write 0x82000000–0xBFFFFFFF (live Linux RAM).
• If a hardened kernel blocks /dev/mem to the reserved region, use the same devmem/mmap path the existing runtime uses; if a readback looks stale, it's CPU caching of that address — read uncached.
• Scanout from LPDDR is Ch319 — start only after this write/readback passes.