DMG VBlank Handler Proof + HRAM[0xFFC5] Semantics + Boot-Skip A/B Test

Summary

This Step implements extensive CPU and MMU instrumentation to diagnose why DMG games (specificallytetris.gb) do not display visual content, even though CGB games work correctly. Added detailed tracking of IRQ (VBlank), RETI, HRAM[0xFFC5], and IF/IE, along with an improved DMG v2 classifier. The results of the A/B test (SIM_BOOT_LOGO=0 vs 1) show that the problemnot related to boot logo skip, since both cases produce identical results:VRAM_TILEDATA_ZERO, IRQTaken_VBlank=0, HRAM_FFC5_WriteCount=0.

Hardware Concept

Game Boy outages: When an interrupt is triggered on the Game Boy:

1. CPU checks if IME is enabled and if there are active bits in IF & IE
2. If met, IME is disabled, the current PC is pushed, and the corresponding vector is jumped (0x40 for VBlank, 0x48 for LCD, etc.)
3. The handler must end with RETI, which restores IME and returns to the interrupted code

Detailed tracking allows you to verify that the vector is correct, the PC is correctly saved on the stack, IME is disabled correctly, and the handler terminates with RETI.

RETI (Return from Interrupt): RETI is a special instruction that pops the PC from the stack (restores the interrupted PC) and enables IME (allows new interrupts). It is equivalent toPOP PC + EI, but atomic.

HRAM[0xFFC5]: HRAM[0xFFC5] is an address in High RAM (0xFF80-0xFFFE) that some DMG games use as a synchronization or communication flag between the main code and the interrupt handlers. If the game waits for a specific value to be written to this address during the VBlank handler, and it is not written, the game could be stuck waiting.

IF (Interrupt Flag, 0xFF0F): Register indicating which interrupts are pending (bits 0-4: VBlank, LCD, Timer, Serial, Joypad). It is written to clear flags (bit=1 to clear).

IE (Interrupt Enable, 0xFFFF): Register indicating which interrupts are enabled (bits 0-4).

Reference: Pan Docs - Interrupts, LR35902 Instruction Set, Memory Map

Implementation

Phase A: VBlank Handler Proof ✅

A1) Real IRQTrace (Expanded):

• Expansion ofIRQTraceEventwith additional fields:
  • pc_after: PC after jumping to vector
  • vector_addr: Interrupt vector address (0x40, 0x48, 0x50, 0x58, 0x60)
  • sp_before, sp_after: Stack pointer before and after the push
  • ime_before, ime_after: IME status before and after service
  • ie, if_before, if_after: IE and IF values ​​before and after
  • irq_type: IRQ Type (VBlank, LCD, Timer, Serial, Joypad)
  • opcode_at_vector: First opcode in the vector (for debugging)
• Capture inCPU::handle_interrupts(): All fields before and after the IRQ service are captured

A2) RETI Tracking:

• New structureRETITraceEvent:
  • frame: Frame in which RETI was executed
  • pc: PC where RETI was run
  • return_addr: Return address (read from stack)
  • ime_after: IME status after RETI (must be 1)
  • sp_before, sp_after: Stack pointer before and after
• Ring buffer of 64 events inCPU
• Capture in opcodeRETI(0xD9): All fields are captured during execution

A3) HRAM[0xFFC5] "Flag Semantics":

• Expansion ofHRAMFFC5Tracking:
  • write_count_total: Total writes to 0xFFC5
  • write_count_in_irq_vblank: Writes during IRQ VBlank (placeholder for now)
  • first_write_frame: Frame of the first write
  • Ring bufferFFC5WriteEvent(last 8 writes):frame, pc, value
• Capture inMMU::write()whenaddr == 0xFFC5

A5) IF/IE Correctness Proof:

• Expansion ofIFIETracking:
  • if_write_history_: Ring buffer of last 5 writes to IF (0xFF0F)
  • ie_write_history_: Ring buffer of last 5 writes to IE (0xFFFF)
  • Each entry contains:pc, written(written value),applied(value applied after write)
• Capture inMMU::write()whenaddr == 0xFF0Feitheraddr == 0xFFFF

Phase B: DMG Progress Proof ✅

B1) "AfterClear+Progress" Snapshot:

• New feature_classify_dmg_quick_v2():
  • Classifies DMG state using CPU and MMU metrics:
    • pc_hotspot_top1: most frequent PC (indicates loops)
    • irq_taken_vblank: Counter of VBlank IRQs taken (from the new tracking)
    • reti_count: Counter of RETIs executed
    • hram_ffc5_last_value, hram_ffc5_write_count_total, hram_ffc5_write_count_in_vblank: HRAM Metrics[0xFFC5]
    • lcdc, status, ly: LCD status
    • vram_tiledata_nz, vram_tilemap_nz: Non-zero bytes in VRAM
  • Classification categories:
    • WAITING_ON_FFC5: HRAM[0xFFC5] never written, game waiting
    • IRQ_TAKEN_BUT_NO_RETI: IRQ taken but no RETI
    • IRQ_OK_BUT_FLAG_NOT_SET: IRQ and RETI OK, but flag is not written
    • VRAM_TILEDATA_ZERO: VRAM tiledata empty (root cause)
    • OK_BUT_WHITE: Everything OK but white framebuffer
• Integration ingenerate_snapshot(): Section addedDMGQuickClassifierV2to the snapshot

Phase C: Cython Exposure ✅

Files: src/core/cython/cpu.pxd, src/core/cython/cpu.pyx, src/core/cython/mmu.pyx

• cpu.pxd: Declaration ofRETITraceEventstruct
• cpu.pyx: Methodsget_reti_trace_ring()andget_reti_count()to expose RETI tracking
• mmu.pyx: Updateget_hram_ffc5_tracking()andget_if_ie_tracking()to include the new fields (write_ring, if_write_history, ie_write_history)

Affected Files

• src/core/cpp/CPU.hpp- Expansion ofIRQTraceEvent, new structureRETITraceEvent, new methodsget_reti_trace_ring()andget_reti_count()
• src/core/cpp/CPU.cpp- Implementation of expanded IRQ and RETI tracking
• src/core/cpp/MMU.hpp- Expansion ofHRAMFFC5TrackingandIFIETrackingwith ring buffers
• src/core/cpp/MMU.cpp- Implementation of extended tracking of HRAM[0xFFC5] and IF/IE
• src/core/cython/cpu.pxd- Declaration ofRETITraceEvent
• src/core/cython/cpu.pyx- Methods to expose RETI tracking
• src/core/cython/mmu.pyx- Update of methods to expose expanded tracking
• tools/rom_smoke_0442.py- New feature_classify_dmg_quick_v2()and snapshot integration

Tests and Verification

Compilation:

python setup.py build_ext --inplace

✅ Successful build without errors

Running ROMs:

# tetris.gb (SIM_BOOT_LOGO=0)
export VIBOY_SIM_BOOT_LOGO=0
python3 tools/rom_smoke_0442.py roms/tetris.gb --frames 1200 > /tmp/viboy_0500_tetris_boot0.log

# tetris.gb (SIM_BOOT_LOGO=1)
export VIBOY_SIM_BOOT_LOGO=1
python3 tools/rom_smoke_0442.py roms/tetris.gb --frames 1200 > /tmp/viboy_0500_tetris_boot1.log

# pkmn.gb (SIM_BOOT_LOGO=0)
export VIBOY_SIM_BOOT_LOGO=0
python3 tools/rom_smoke_0442.py roms/pkmn.gb --frames 1200 > /tmp/viboy_0500_pkmn.log

A/B Test Results (tetris.gb):

• SIM_BOOT_LOGO=0:
  • DMGQuickClassifier=VRAM_TILEDATA_ZERO
  • VBlankReq=1139, VBlankServ=1139(IRQs are processed)
  • IRQTaken_VBlank=0(⚠️ tracking does not detect IRQs)
  • HRAM_FFC5_WriteCount=0(never written)
  • VRAM_Regions_TiledataNZ=0, VRAM_Regions_TilemapNZ=1024(tilemap OK, tiledata empty)
• SIM_BOOT_LOGO=1:
  • Identical resultsto SIM_BOOT_LOGO=0
  • Conclusion:The problemIt is NOT related to the boot logo skip

Results for pkmn.gb:

• DMGQuickClassifier=VRAM_TILEDATA_ZERO
• VBlankReq=1141, VBlankServ=147(less IRQs served)
• IRQTaken_VBlank=0(⚠️ tracking does not detect IRQs)
• VRAM_Regions_TiledataNZ=0, VRAM_Regions_TilemapNZ=2048(tilemap OK, tiledata empty)

Key findings:

• ✅ A/B Test: Both cases (SIM_BOOT_LOGO=0 and 1) produce identical results → The problem is not in the boot logo skip
• ⚠️ IRQ Tracking Bug: IRQTaken_VBlank=0butVBlankServ=1139→ The new tracking is not working correctly (possible bug)
• 🔍 VRAM Tiledata: Consistent across all ROMs →VRAM_Regions_TiledataNZ=0(root cause)
• ✅ HRAM[0xFFC5]: Tetris.gb is never written → It is not the cause of the crash

Sources consulted

• Pan Docs: Interrupts, LR35902 Instruction Set, Memory Map, VRAM Access Restrictions
• GBEDG: Interrupt Handling, VBlank Timing

Educational Integrity

Next Steps

• [ ] Fix IRQ Tracking Bug: Verify and correctly implement the counterirq_taken_vblank_inCPU::handle_interrupts()
• [ ] VRAM Write Tracking: Instrument tracking of writes to VRAM tiledata (0x8000-0x97FF) to check for failed write attempts
• [ ] VRAM Access Restrictions: Verify that we are respecting the VRAM access restrictions (only during HBlank and VBlank, not during OAM Scan and Pixel Transfer)
• [ ] DMA Tracking: Instrument DMA tracking (0xFF46) to check for data transfers that do not complete correctly
• [ ] Timing Verification: Verify that the VRAM access timing matches the real hardware (PPU modes, machine cycles)