PPU Icarus/GTKWave testbench (issue #390)

Regression testbench for the DMG-CPU PPU gate netlists (HDL/soc/ppu1.v, HDL/soc/ppu2.v) run with Icarus Verilog + GTKWave.

Files

Coverage

Functional-block coverage (per wiki/soc/ppu1.md and wiki/soc/ppu2.md)

Legend: ✅ verified by a passing test · 🟡 partially verified / dev · ⬜ open (blocked, see waves.md "Research handoff").

Details, wave images (incl. waves/tb_ppu_sprite_e2e.png, round 30) and the research handoff are in waves.md; the status snapshot and author checklist are in STATUS.md.

Reproducing the waves

The VCD files and .run binaries are git-ignored - they are produced by the tests. To regenerate everything from a clean clone:

# 0) (optional) regenerate the bus-model variants from the merged netlist
python3 gen_weakbus.py                 # ppu2_weakbus.v + ppu2_m2only.v
# 1) run the tests (each dumps <test>.vcd; the suite uses ppu2_weakbus.v)
./run_all.sh                           # fast suite; add tb_ppu_frame for the slow full-frame test
# 1b) sprite e2e (dev, uses ppu2_m2only.v): see the compile line in tb_ppu_sprite_e2e.v header
# 2) open the traces in GTKWave (v3.3.128 save files)
gtkwave tb_ppu_regs.gtkw               # etc. (files are committed, VCDs must exist)
# 3) re-render the wave PNGs (needs the vcd2png.py renderer)
python3 vcd2png.py tb_ppu_regs.vcd waves/tb_ppu_regs.png --cfg waves_cfg_regs.json ...

The .gtkw save files and the PNGs in waves/ are committed, so a fresh clone shows the documentation immediately; re-running the tests refreshes the VCDs behind them.

Related tooling

The adapted Icarus/GTKWave skill for future DMG-CPU testbenches (APU, MMIO, ...) lives in HDL/soc/icarus/gtkwave-skill.md.

Bus modelling (testbench)

The precharged inverse-hold buses of the PPU are simulated with dynamic-bus semantics (issue #390, round 27):

• The six PPU2 oa-chain nodes (w497/w146/w500/w554/w641/w49) are modelled as discharge-only + keepers: the notif0 mux groups become open-drain (dmg_notif0_od in bus_weak_cells.v) and a pullup holds the precharge level, so overlapping enables no longer drive the node to x. Applied by gen_weakbus.py → generated ppu2_weakbus.v (used in all PPU test compiles instead of ppu2_merged.v). This is a simulator bus model only - HDL/soc/ppu2.v is NOT modified.

• gen_weakbus.py also generates ppu2_m2only.v (round 30): the 18 non-scan oa-chain drivers are disabled while ppu_mode2 is high, so the mode-2 scan address is stable/even and the sprite path runs end to end (tb_ppu_sprite_e2e, dev). Used by that test; the regression suite uses ppu2_weakbus.v.

• The OAM macro pads (n_oama/n_oamb) are inverse-hold: precharge keepers + discharge-only pads in oam_ram.v (round 26).

Residual x: oa is clean in mode 2 and idle on the ppu2_m2only.v model; on plain ppu2_weakbus.v it can still read x in mode 3 (sprite compare / store re-fetch phase, bus unused for the BG pixel stream).

Notes

• HDL/soc/dmglib.v needed one bug fix for simulation: dmg_notif0/1 (inverting tristates on the precharged "inverse-hold" buses) were written as x = ~x (a self-referential combinational loop that never drives the bus); the correct inverting-tristate body is x = ~a while enabled.

• The PPU CPU interface uses true-value data on the d bus: read-back drivers are notif0 fed from the register latches' nq, so the wire gets the register value; register latches capture the wire value directly.

• Write strobes: PPU2 decodes the CPU access (soc_wr + address + ffxx) and produces ppu_rd/ppu_wr, which gate PPU1's register latches. The CPU model keeps data valid ~8 ns after the strobe falls (real bus hold time), otherwise the level-sensitive register latches race the bus precharge.