PPU2

Role in the SoC

PPU2 is the "object / OAM" half of the PPU. The two PPU blocks are split as follows (see also PPU1):

• PPU1: the BG/WIN part of the pipeline, the pixel serializers, the palettes and the pixel mux, the LCD driver interface, the H/V counters, the register decode and most of the PPU registers.
• PPU2 (this page): the OAM side: PPU2 is the only master of the OAM RAM block (in HDL/soc/dmgcpu.v the nets oa, n_oam_rd, n_oama_wr, n_oamb_wr, n_oama, n_oamb, oam_bl_pch run exclusively between PPU2 and OAM). The CPU never touches OAM directly — PPU2 performs every CPU OAM access on its behalf.

The netlist shows the following split of duties:

1. The CPU-visible scroll registers SCY ($FF42) and SCX ($FF43) physically live in PPU2 (two 8-bit latchr_comp banks). PPU1 receives only the low three SCX bits back as FF43_D0..2 for its SCX fine-scroll counter. The register access indicators ff42/ff43 are produced by PPU1's decoder and consumed here.
2. PPU2 computes the scroll-adjusted line/column arithmetic (V + SCY) and (H + SCX) with two 8-bit ripple adders and drives the shared VRAM-address bus nma with the map row/column (and the vertical fine offset) during the BG tile-map / tile-data fetch windows.
3. PPU2 contains the whole mode-2 OAM scan engine (scan counter, capture latches, port A/B control) and the 10-slot sprite store that keeps, per selected sprite of the current line: an 8-bit field (the port-A byte), a 6-bit field (the registered OAM scan address — "which OAM entry"), and a 4-bit field used by the X-position logic.
4. PPU2 generates the PPU clocks (ppu_clk = cclk, n_ppu_clk), the PPU hard reset (n_ppu_hard_reset = !n_reset2), the ppu_rd/ppu_wr strobes consumed by PPU1 and MMIO (they simply re-drive soc_rd/soc_wr), plus h_restart, ppu_mode2, stop_oam_eval and the per-object outputs obj_color, obj_prio, sprite_x_flip, sprite_x_match consumed by PPU1's sprite pixel path.
5. PPU2 arbitrates the OAM port data among three writers (the CPU data bus d, the VRAM→OAM DMA md bus, and the Arbiter's oam_din), and routes OAM read data back to the CPU on d.

The netlist is a flat gate-level Verilog: 973 cells, 153 assign statements, 67 ports (the only hierarchical cell is the const cell g527 producing w69 = 0 and w149 = 1). The cell inventory:

Signals

Netlist

Annotated Design

Functional blocks

The netlist is organized into the following functional blocks (instance numbers refer to HDL/soc/ppu2.v):

1. SCY / SCX registers

PPU2 does not decode a[3:0] for the scroll registers — PPU1's decoder produces the access indicators ff42/ff43 (PPU1 g789/g796), and PPU2 simply gates them with the SoC strobes:

Read-back is done by notif0 tristates enabled by !w144/!w203 fed from the latch nqs: e.g. for d0 g424 (SCY) and g348 (SCX), so the bus voltage equals the register value (inverse-hold convention).

2. Scroll adders and the nma (VRAM-address) drive

Two 8-bit ripple adders compute the scroll-adjusted position:

• V + SCY (g971 half-adder + g590–g594, g603, g604): operands = V-counter bits + SCY latch q bits. Sum bits w808..w182.
• H + SCX (g973 half-adder + g587–g589, g605–g608): operands = H-counter bits + SCX latch q bits. Sum bits 0–2 are discarded (s of g973/g608/g589 unconnected — only carries propagate): the SCX fine scroll is handled in PPU1's 3-bit fine counter fed with FF43_D0..2. Sum bits 3–7 continue into the nma drive.

PPU2 then drives the shared VRAM-address bus nma (via notif0, inverse-hold) on non-window lines:

So the BG tile-map address is assembled by PPU2 from (V+SCY)>>3 (row, ×32, nma[9:5]) and (H+SCX)>>3 (column, nma[4:0]) during tm_cy, and the tile-data fine vertical offset (V+SCY)&7 (×2, nma[3:1]) during bp_cy. PPU1's own nma drivers (its TM/TD counters) complete the addresses (tile-map base select, tile index, byte parity). The exact per-cycle alignment of the two drivers is confirmed by the joint testbench (waves).

3. Port-B adder (the OAM "Y test")

The eight latchnq_comp g204–g250 (enable w120) capture the OAM port B byte (through the port latches g733–g748). Their nq outputs feed the full-adder row g595–g602 whose other operand is the inverted V counter — i.e. this adder tests the sprite Y position against the current line (Y − V-type range test). The results (w68/w543/w438/w479/w473/w476/w485/w482) drive the entry-selection logic and read-back muxes.

Interpretation: during the mode-2 scan port B carries the sprite Y byte and the adder performs the per-entry Y-range test (16/32 rows depending on FF40_D2 OBJ size); only entries in range are eligible for the store. Port A carries the attribute byte (bits 7/5/4 → obj_prio/sprite_x_flip/obj_color), which is fixed by wiring. (The byte↔port mapping depends on the OAM macro; see Open questions.)

4. Mode-2 OAM scan engine

ppu_mode2 = w100 & !dma_run (g576/g139), where w100 is the q of the nor_latch g954:

• set by w98 (dffr g612, clk oam_addr_ck, d = vclk2 & !vbl) — the OAM-address-clock edge that follows PPU1's line clock, outside VBlank;
• reset by !n_ppu_reset | stop_oam_eval.

Scan address. The live address comes from the ripple counter g621(g625(g619(g614(g627(g626)) (dffr, base clock w647, reset w650 = n_ppu_reset & !h_restart); during mode 2 its outputs are muxed onto oa (group w518 = !ppu_mode2, oa[1] = 0). Six dffrnq_comp g938–g943 (clk oam_addr_ck) register the current oa value; their nq outputs are the registered OAM scan address that mode 3 reuses (block 7). stop_oam_eval (= !w860) fires from a small state machine on g631/g632 when the scan-address counter finishes.

h_restart (= !w713) is the mode-2 start re-timed on the opposite oam_addr_ck phase (g609, w99): it ends PPU1's H counter and clears PPU2's own line state (w410 = !h_restart resets the slot walker).

OAM read/precharge. The OAM read strobe n_oam_rd and the port-latch capture enable (w165) are asserted during mode-2 read clocks (ppu_mode2 & oam_rd_ck), during mode-3 OAM re-reads (oam_mode3_nrd) and during CPU FExx reads (fexx & ppu_rd & !clk6). oam_bl_pch (w58) combines the DMA/fexx precharge disable, PPU1's mode-3 precharge and the mode-2 X-attribute latch clock; note w314 (the attribute-stage latch enable) equals oam_bl_pch — the attribute stage captures exactly between OAM drive phases ("X-attribute latch" window).

5. OAM port and address muxes

OAM write data (n_oama/n_oamb) has three mutually exclusive sources:

Write strobes: n_oama_wr = !(w125 & w508), n_oamb_wr = !(w125 & !w508) with w125 = (fexx & w888 & ppu_wr) | oam_dma_wr and port select w508 = !dma_a[0] (while dma_run), else constant. So VRAM→OAM DMA alternates the ports with the source-address parity, and CPU OAM writes always target one fixed port (the CPU-facing port B).

oa address mux — four sources per bit (buffered by g68–g73/g526):

CPU OAM read return: the port latches hold the last OAM word; bufif0 banks drive the selected port byte onto d (select from cpu_vram_oam_rd + port parity). So CPU OAM reads also go through PPU2.

6. Sprite-store capture stage

Per OAM word access, 16 dmg_latch g733–g748 (enable w165 = OAM read active) capture the entire n_oama[7:0] + n_oamb[7:0] buses. Two follower stages select the interesting bytes:

1. g204–g250 (enable w120): capture the port B byte (Y) — feeds the port-B adder (block 3).
2. g203–g267 (enable w314 = oam_bl_pch): capture the port A byte. Three nq outputs are module outputs:

The eight attribute bits are inverted (g7/g60/g65/g67/g78/g79/g150/g928) into the nets w413/w415/w431/w433/w294/w325/w590/w594 — the common data input of all ten 8-bit store banks.

7. The 10-slot sprite store

Each of the 10 slots = one 8-bit latchr_comp bank (reset by the slot's in-use flag, i.e. an unclaimed slot stays cleared) + one 6-bit latchnq_comp bank + one 4-bit latchnq_comp bank, all capturing from shared buses. The three banks of a slot share one master enable net (e.g. master w321 → 8-bit en w77, 6-bit en w247, 4-bit en w251):

Slot enable decode. A bank captures only while the slot master is low, i.e. on OAM read-clock pulses when the mode-2 state is current and the store window is open (w852 = oam_rd_ck & w209 & w816, w223 = !w852). The per-slot selection decodes the four state bits of the per-line sprite-slot walker g610/g633/g629/g634 (ripple-clocked, reset !h_restart) — ten NAND4 g889–g898 with OR trees produce the ten slot terms.

Per-slot in-use flags. Ten dffr g611–g628 (clock obj_prio_ck, async reset w371) capture whether each slot is claimed; each flag, OR-ed, feeds the async reset of the slot's 8-bit bank: an unclaimed slot is held cleared, a claimed one can hold data.

Contents (per slot):

• the 8-bit field = the current port-A (attribute) byte captured during the scan;
• the 6-bit field = the registered OAM scan address (which OAM entry the sprite came from), placed on the shared bus w213/w279/w284/w323/w347/w487 by notif0 groups enabled in mode 3 (from g938–g943 nqs);
• the 4-bit field (nets w66/w257/w259/w310) = extra per-sprite data from the port-B arithmetic, used by the X-position logic.

The store behaves like a rotating array whose write/read schedule (which scan address lands in which slot, the 10-sprite limit) is confirmed by simulation.

8. Sprite compare (mode 3)

All q outputs of the 8-bit banks feed dmg_xor rows whose second operand is a reference byte derived from the H counter (e.g. slot 0: g770/g771/g828–g831/g840/g841 comparing stored bits against !h7..!h0). Per slot the XORs merge in two nibbles (nor4 pairs g899–g918) and a nand3 gated by w332 = FF40_D1(OBJ enable) & ppu_mode3 produces the per-slot byte-match flag (g920–g927, g969, g970).

sprite_x_match = w804 | w767 (g875), where the two NAND5 g961/g962 collect the ten per-slot flag terms (five each).

The flag terms also enable the read-back notif0 groups that place particular slots' stored data onto the shared 6/4-bit buses (and from there onto oa in mode 3 via the group w444, plus extra XORs g765/g825/g846/g847 comparing the 4-bit field against the captured n_oama[6]).

Interpretation: in mode 3 the ten stored fields are matched against the running LX value so the store is searched for the sprite starting at the current X; on a match the 6-bit OAM-address field is re-driven onto oa, the OAM is re-read (tile/attributes for PPU1's fetch), and the object pixel stream (obj_color/obj_prio/sprite_x_flip) is presented to PPU1. The exact semantics of the stored byte vs the LX reference are an open question (see below) — resolved by the sprite testbench.

9. Clock and reset generation

Note: the PPU dot clock is the external complement clock cclk — PPU2 does not divide clk6 for the PPU (that division happens in PPU1's OAM-clock block, ppu1.md block 13, which feeds PPU2 the oam_addr_ck/oam_rd_ck/oam_xattr_latch_cck/obj_prio_ck pulses).

10. DMA / CPU-OAM access summary

• VRAM→OAM DMA (vram_to_oam): data = md → OAM ports; write strobes from oam_dma_wr; destination = dma_a[7:1]; port parity = dma_a[0]; n_vram_to_oam output to the Arbiter.
• CPU OAM write: data = d; strobe fexx & !(dma_run|ppu_mode2|mode3-qualified) & ppu_wr; address = a[7:1].
• CPU OAM read: PPU2 asserts n_oam_rd with the CPU address, captures the OAM word and drives the selected port byte onto d.
• oam_din: a third write-data path (w140 = !dma_addr_ext) used when the Arbiter holds the DMA data (DMA from external memory sources).

Clock domains

Map

OAM SRAM ground truth (@msinger's cell reference)

From the DMG-CPU cells reference ("SRAM", Variant A is used in HRAM and OAM):

• The DMG-CPU B die has four SRAM instances: HRAM, Wave RAM and 2× OAM — i.e. OAM is physically two SRAM macros (matching the two PPU2 ports n_oama/n_oamb).

• The macro is built from 6T cells with dynamic NMOS read/write: bit lines are precharged to 1 (BL_PCH, active low) before every access; a read drives the data pad to D = ~bit (a stored 0 pulls the pad high), so the "inverse-hold" values seen on n_oama/n_oamb are the real macro behaviour (~mem in the testbench model is correct).

• Rows are selected by address bits A2 and up; A0/A1 select one of four byte columns inside a row. For OAM (40 entries × 4 bytes = 160 bytes) the natural mapping is: word line = OAM entry (40 rows), columns = the four bytes of the entry. The macro access granularity is therefore one byte (row + 2 column bits), while the testbench uses PPU2's 7-bit oa[7:1] word interface (bit 0 unused) with two 8-bit data ports - the exact column/byte<->port encoding inside the 2×OAM macros still needs the schematic pages (the repo OAM module is an empty stub).

Testbench state of the sprite store (round 6)

The behavioural OAM model (HDL/soc/icarus/ppu/oam_ram.v: two ports over 80 16-bit words, port B = even bytes, bitline hold) removed the earlier mode-3 overrun: with OBJ enabled the mode-2/3 line rhythm is now normal. The sprite store still never claims a slot because the per-slot in-use dffr g611–g628 are clocked by obj_prio_ck (input from PPU1), and in the simulated lines obj_prio_ck = ~(w239|w240) (ppu1 g494/g832) never pulses (w239 = nq of g286, w240 = nand3 g751 over the sprite-process FFs g322/g287/g314): PPU1's sprite-clock domain (mode-3 fetch/prio FFs clocked off w596 = ppu_clk / w815, ring g282–g285/g316/g317/g319) does not start without the corresponding PPU2 store/handshake state. Mapping that handshake is the next research step.

Suspected netlist issues (reported to the author, NOT fixed here)

Per the issue workflow, suspected problems in ppu1.v/ppu2.v are reported rather than patched in this repository:

1. PPU2 scan-address register has no reset (ppu2.v:2089-2094, g938–g943, six dffrnq_comp, clk w648 = oam_addr_ck): their async reset nr1 is hard-wired to w149 (const g527.q1 = 1), i.e. they are never reset. In the testbench they power up deterministic (dmglib dffrnq_comp declares initial val = 0) but can clock in x from the scan-counter data (g942/g943 hold x during the whole mode-2 scan). The no-reset "init-0" probe (round 22, tb_ppu_ring_init0) pins them to 0 even when clocked with x - the scan register then reads a defined 010000 every line, yet the Y-test AND6 and the store window w852 still never open. So the missing reset is a real silicon concern (undetermined power-up, no garbage recovery), not the cause of the inert store path (see waves.md).

2. PPU1 g652 looks like a second LCDC.D7 latch next to g656: reported round 9: during mode 2 the oa scan group (n_ena w518 = on g419, ppu2.v:1570) !ppu_mode2) and the port-B-adder const group (n_ena w475 = !w476) can be **enabled simultaneously** when the Y-test sum bitw476is 1 vs the port-B const group (g421, ppu2.v:1572) - (observed directly, waves.md), driving the sameoanodes to opposite rails. On a static full-drive model this is contentionx; check whether these twooamux phases are supposed to be separated in time (dynamic precharge/evaluate) or whether one of the enable terms is wrong.g652(latchr_comp, enaw84= the $FF40 write enable, d =w79= D7, nresw82= same reset family) drivesw149, which is read only by dffrg305, whileg656(same ena/d/reset) drivesw81= LCDC.7. Probably an intentional copy for layout, but it is undocumented (wiki/soc/ppu1.md` lists the LCDC bank as g649–g657).

Open questions

• OAM bus idle/precharge state. The behavioural testbench shows that internal precharge nodes of the OAM port-select decode (e.g. w863/ w508, the oa const groups g419/g421) only resolve if the macro never lets the bitlines float: with the current macro model the n_oama_wr/n_oamb_wr strobes and part of the oa mux ride x during idle. CPU OAM writes do land with word address a[7:1] on both port lanes (observed with a bitline-hold macro), but the byte↔port layout and the precharge-phase timing need the schematic-level OAM macro timing (the repo OAM module HDL/soc/oam.v is an empty stub).

• The OAM port A/B mapping was tested both ways (A = even byte and A = odd byte of the 16-bit word) with the sprite testbench: the mode-2 scan cadence and the attribute-capture x-half-cycles are identical in both layouts, so the byte↔port mapping alone does not explain the residual x; it must be combined with the real precharge/capture phase timing.

• The exact byte ↔ OAM-port mapping (port A = attribute byte, port B = Y byte, CPU port B, DMA parity alternation) needs confirmation with the OAM model; the repo OAM netlist is a stub (HDL/soc/oam.v).

• The sprite-compare semantics: the stored 8-bit field is matched against the H counter in mode 3 — whether the port-A byte read during the scan is literally the sprite X (making the names obj_color/obj_prio/sprite_x_flip re-examinable at the PPU1 boundary) or the equality gates serve a different scheduling function. A line with known OAM contents (sprite testbench) will pin this down.
• The exact slot↔OAM-entry↔enable schedule (which of the 40 scan addresses land in which of the 10 slots, and how the "10 maximum" is enforced).
• stop_oam_eval count: the exact scan-address value that terminates mode 2 (decode w493).
• Polarity conventions of the precharged buses and of n_oam_rd/oam_bl_pch/ppu_mode2/stop_oam_eval/h_restart inferred here need waveform confirmation.
• The port-B Y-range test bounds (16/32 rows for 8×8 / 8×16 sprites via FF40_D2).
• The mode-3 sprite re-fetch protocol: order of the oa groups w444 vs w475 and how PPU1's sp_bp_cys/ma0 close the sprite VRAM-fetch addresses.

References

• HDL/soc/ppu2.v — analysed netlist (module PPU2).
• HDL/soc/dmgcpu.v — top-level wiring (PPU2 ↔ OAM exclusivity, ppu_rd/ppu_wr/ppu_clk fan-out).
• HDL/soc/arb.v, HDL/soc/oam.v — Arbiter / OAM (stub) cross-checks.
• HDL/soc/ppu1.v & wiki/soc/ppu1.md — sibling block analysis and PPU1↔PPU2 handshake.
• DMG-CPU Schematics by @msinger — schematic pages for cross-checking the blocks above.
• PPU testbench: HDL/soc/icarus/ppu (Readme, waves in HDL/soc/icarus/ppu/waves.md).