Does the Game Progress? Does VBlank exist? Is VRAM Full?

Summary

Diagnosis of why ROMs continue to show white/black screens (framebuffer flat) even though the PPU does render (confirmed in 0467/0468). Implemented minimal gated instrumentation to diagnose if the problem is unsolicited/served VBlank interrupt or blocked VRAM writes. Added IRQ counters (vblank_irq_requested_count and vblank_irq_serviced_count) exposed to Python, per-frame snapshot in rom_smoke_0442.py (every 60 frames), and clean-room test for VBlank interrupt. Actual validation with 4 ROMs (tetris.gb, pkmn.gb, tetris_dx.gbc, mario.gbc) revealed that CGB games do not enable VBlank interrupt in IE (0xFFFF bit0), causing that although the PPU requests the interrupt, the CPU does not serve it.

Hardware Concept

On the Game Boy, interrupts are the primary mechanism for synchronizing the game with the hardware. The VBlank interrupt occurs when the PPU completes a frame (LY reaches 144) and is critical for games to progress, as many games use HALT and wait for VBlank to wake up.

IE Register (0xFFFF - Interrupt Enable): Indicates which interrupts are enabled. Bit 0 = VBlank interrupt. If IE bit0 = 0, although the PPU requests the interrupt (IF bit0 = 1), the CPU will not serve it.

IF Register (0xFF0F - Interrupt Flag): Indicates which interrupts are pending. Bit 0 = VBlank interrupt. It is activated when the PPU requests the interruption (LY=144).

IME (Interrupt Master Enable): Global flag that enables/disables all interrupts. If IME=0, even if IE and IF have active bits, the CPU will not serve interrupts.

VBlank Interrupt Flow:

1. PPU reaches LY=144 → requests VBlank interrupt (IF bit0 = 1)
2. If IE bit0 = 1 and IME = 1 → CPU serves the interrupt (jumps to vector 0x0040)
3. CPU clears IF bit0 and disables IME temporarily
4. The game runs the VBlank handler (updates graphics, logic, etc.)
5. RETI restores IME and returns to main code

Fountain: Pan Docs - Interrupts, V-Blank Interrupt

Implementation

Minimal gated instrumentation was implemented to diagnose the black/white screen problem. Instrumentation includes IRQ counters and per-frame snapshots with key metrics.

Phase A – IRQ Counters

Added static file-level counters to track how many times VBlank interrupt is requested and served:

• PPU.cpp: Counter `vblank_irq_requested_count` (static uint32_t) that is incremented when PPU requests VBlank interrupt (LY=144)
• CPU.cpp: Exposing existing counter `irq_vblank_services_` using getter `get_vblank_irq_serviced_count()`
• PPU.hpp/CPU.hpp: Public getters `get_vblank_irq_requested_count()` and `get_vblank_irq_serviced_count()`
• Cython (.pxd/.pyx): Getters exposed to Python for access from diagnostic tools

Phase B - Snapshot by Frame

Modified `rom_smoke_0442.py` to print snapshot every 60 frames (or frames 0, 1, 2) with the following metrics:

• PC, IME, HALTED
• IE, IF (interrupt registers)
• VBlankReq, VBlankServ (IRQ counters)
• TilemapNZ_9800_RAW, TilemapNZ_9C00_RAW (unrestricted RAW counting)
• VRAMNZ_RAW (VRAM RAW count)
• LCDC, STAT, LY (PPU registers)

Phase C - Clean-Room Test

Created `tests/test_vblank_interrupt_served_0469.py` with 2 tests:

• test_vblank_interrupt_requested: Verify that PPU requests VBlank interrupt when LY=144
• test_vblank_interrupt_served: Check which CPU serves VBlank interrupt when IME is active

Design decisions

Static counters: Static file-level counters were used instead of instance members because each ROM runs in a new process (python3 tools/rom_smoke_0442.py rom...), so they reset automatically. If multiple ROMs are run in the same process in the future, reset_irq_counters() would need to be added or converted to per-instance members.

Snapshot every 60 frames: To avoid saturating the context, snapshots are printed every 60 frames (or frames 0, 1, 2 for initial diagnosis). This provides enough granularity without generating massive logs.

Affected Files

• src/core/cpp/PPU.cpp- Added vblank_irq_requested_count static counter and getter implementation
• src/core/cpp/PPU.hpp- Added getter get_vblank_irq_requested_count()
• src/core/cpp/CPU.cpp- Added get_vblank_irq_serviced_count() getter implementation
• src/core/cpp/CPU.hpp- Added getter get_vblank_irq_serviced_count()
• src/core/cython/ppu.pxd- Added get_vblank_irq_requested_count() declaration
• src/core/cython/ppu.pyx- Added Python wrapper get_vblank_irq_requested_count()
• src/core/cython/cpu.pxd- Added get_vblank_irq_serviced_count() declaration
• src/core/cython/cpu.pyx- Added Python wrapper get_vblank_irq_serviced_count()
• tools/rom_smoke_0442.py- Added snapshot every 60 frames with IRQ and VRAM metrics
• tests/test_vblank_interrupt_served_0469.py- Test clean-room to verify VBlank interrupt end-to-end

Tests and Verification

Command executed: pytest -q tests/test_vblank_interrupt_served_0469.py tests/test_bg_tilemap_base_and_scroll_0464.py

Result: 5 passed in 1.62s

Test Code:

def test_vblank_interrupt_requested(self):
    """Test 1: Verify that PPU requests VBlank interrupt when LY=144."""
    self.mmu.write(0xFFFF, 0x01) # IE bit0 = VBlank enabled
    for _ in range(3):
        self.run_one_frame()
    vblank_req = self.ppu.get_vblank_irq_requested_count()
    assert vblank_req > 0, f"PPU did not request any VBlank interrupt (vblank_req={vblank_req})"

def test_vblank_interrupt_served(self):
    """Test 2: Verify which CPU VBlank interrupt serves when enabled."""
    self.mmu.write(0xFFFF, 0x01) # IE bit0 = VBlank enabled
    self.cpu.ime = True # Enable IME
    for _ in range(5):
        self.run_one_frame()
    vblank_serv = self.cpu.get_vblank_irq_serviced_count()
    assert vblank_serv > 0, f"CPU did not serve any VBlank interrupt (vblank_serv={vblank_serv})"

Native Validation: Compiled C++ module validation using IRQ counters exposed to Python.

Real Validation with ROMs: rom_smoke_0442.py was executed with 4 ROMs (tetris.gb, pkmn.gb, tetris_dx.gbc, mario.gbc) for 240 frames each, generating snapshots every 60 frames. The logs were saved in /tmp/viboy_0469_*.log for later analysis.

Diagnostic Results

4 ROMs were analyzed with the 6 key metrics per ROM:

Diagnosis Conclusion

Dominant cause identified: CGB games (tetris_dx.gbc, mario.gbc)DO NOT enable VBlank interrupt in IE (0xFFFF bit0). Although the PPU correctly requests the interrupt (VBlankReq > 0), the CPU does not serve it because IE bit0 = 0.

Evidence:

• tetris_dx.gbc: IE=0x00 in all snapshots (frame 0, 60, 120, 180). IF=0x01 (interrupt pending) but VBlankServ=0 (never served).
• mario.gbc: IE=0x00 in all snapshots. IF=0x03 (VBlank + STAT pending) but VBlankServ=0.
• tetris.gb: IE=0x01/0x09 (bit0 active), VBlankReq ≈ VBlankServ → IRQ works correctly.
• pkmn.gb: IE=0x0D (bit0 active), VBlankReq > VBlankServ (offset) because IME is temporarily disabled.

Key Snapshots

tetris.gb - Frame 60: PC=0x036C IME=1 IE=0x09 IF=0x00 VBlankReq=59 VBlankServ=59 TilemapNZ_9800=1024

pkmn.gb - Frame 60: PC=0x614D IME=1 IE=0x0D IF=0x00 VBlankReq=61 VBlankServ=58 TilemapNZ_9800=1024 TilemapNZ_9C00=1024

tetris_dx.gbc - Frame 60: PC=0x1305 IME=0 IE=0x00 IF=0x01 VBlankReq=61 VBlankServ=0 TilemapNZ_9800=0

mario.gbc - Frame 60: PC=0x12A0 IME=0 IE=0x00 IF=0x03 VBlankReq=61 VBlankServ=0 TilemapNZ_9800=1024 TilemapNZ_9C00=1024

Sources consulted

• Bread Docs:Interrupts- V-Blank Interrupt, IE Register, IF Register
• Bread Docs:CPU Registers and Flags- IME (Interrupt Master Enable)

Educational Integrity

Next Steps

• [ ] Step 0470: Investigate why CGB games don't enable IE bit0. Check if there is a bug in IE initialization for CGB games or if the CGB boot ROM should enable IE.
• [ ] Step 0470: If it is expected behavior (the game enables IE later), check when it does it and why it doesn't do it in the first 240 frames.
• [ ] Step 0470: Investigate PC stuck at tetris.gb (0x036C) - is it an infinite game loop or an emulation bug?
• [ ] Step 0470: Check IME behavior in pkmn.gb - is it normal for it to be temporarily disabled?