IRQ Reality Check + CGB Palette Proof

Summary

This step implements advanced tracking mechanisms to verify the real behavior of the interrupts (IRQ) in DMG mode and the state of the CGB palettes. Implemented tracking of interrupts actually taken (interrupt_taken_counts), tracking of writes to IF/IE and HRAM[0xFFC5], and integrated into rom_smoke_0442.py with an always visible IRQReality section. DMG Key Result: IRQTaken_VBlank=2579 confirms that VBlank interrupts are being taken correctly, ruling out interrupt issues as the cause of the white screen. CGB key result: IdxNonZero=22910 but RgbNonWhite=0, confirming that the problem is in the rendering pipeline (palettes/mapping) rather than the tile fetch.

Hardware Concept

Interruptions Actually Taken: On the Game Boy, when an interrupt is pending (IF bit set) and the IME (Interrupt Master Enable) is active, the CPU must take the interrupt in the next instruction cycle. However, it is possible for the emulator to report that interrupts are "served" without them actually being taken. Tracking interrupts actually taken verifies that the CPU actually executes the interrupt handler code.

HRAM[0xFFC5]: Some games use HRAM[0xFFC5] as a flag to indicate that the VBlank handler has completed. Tracking writes to this location can confirm that the handler is running.

CGB pallets: In CGB mode, palettes are configured by writing to BGPI/OBPI (Palette Index) and then to BGPD/OBPD (Palette Data). If there are no writes to these locations, the game is using DMG palettes (BGP/OBP0/OBP1) instead of CGB.

Reference:Pan Docs - "Interrupts", "CGB Palettes", "Memory Map"

Implementation

Phase A: DMG IRQ Reality Check

A1-A2: Tracking of Interruptions Taken

It was implemented inCPU.hpp/CPU.cpp:

• interrupt_taken_counts_[5]: Counter of interrupts actually taken by type (VBlank, LCD-STAT, Timer, Serial, Joypad)
• IRQTraceEvent: Structure with detailed information of each interrupt (frame, PC before, vector, IE, IF before/after, IME, SP before/after, PC saved on stack)
• irq_trace_ring_[64]: Ring buffer of last 64 IRQ events

A3-A4: Tracking of Writes to IF/IE and HRAM[0xFFC5]

It was implemented inMMU.hpp/MMU.cpp:

• IFIETracking: Tracking of writes to0xFF0F(IF) and0xFFFF(IE) with PC, written value and applied value
• HRAMFFC5Tracking: Tracking of writes to0xFFC5with PC, written value and first write frame

A5: Cython Exposure

Getters were implemented incpu.pyxandmmu.pyx:

• get_interrupt_taken_counts(): Returns dictionary with counters per type
• get_irq_trace_ring(n): Return last n IRQ events
• get_if_ie_tracking(): Returns IF/IE tracking
• get_hram_ffc5_tracking(): Return HRAM tracking[0xFFC5]

A6: Integration in rom_smoke_0442.py

Section addedIRQRealityto the main snapshot (always visible, not only in AfterClear):

• Capture ofinterrupt_taken_counts
• Capture ofif_ie_tracking
• Capture ofhram_ffc5_tracking

Phase B: CGB Palette Proof

It was executedtetris_dx.gbcwithVIBOY_DEBUG_CGB_PALETTE_WRITES=1for 1200 frames. The snapshot already includedCGBPaletteWriteStats, palette0_decodeandbg_palette_nonwhite_entries(implemented in Step 0493).

Affected Files

• src/core/cpp/CPU.hpp- Added IRQTraceEvent, interrupt_taken_counts_, irq_trace_ring_
• src/core/cpp/CPU.cpp- Implemented tracking of taken interruptions and ring buffer
• src/core/cpp/MMU.hpp- Added IFIETracking, HRAMFFC5Tracking
• src/core/cpp/MMU.cpp- Implemented tracking of writes to IF/IE and HRAM[0xFFC5]
• src/core/cython/cpu.pxd- Structure and getter declarations
• src/core/cython/cpu.pyx- Implementation of Python getters
• src/core/cython/mmu.pxd- Structure and getter declarations
• src/core/cython/mmu.pyx- Implementation of Python getters
• tools/rom_smoke_0442.py- Integration of IRQReality section in main snapshot

Tests and Verification

Command executed (DMG):

export VIBOY_SIM_BOOT_LOGO=0
export VIBOY_POST_BOOT_DMG_PROFILE=B
export VIBOY_DEBUG_VRAM_WRITES=1
export VIBOY_DEBUG_DMG_TILE_FETCH=1
export VIBOY_DEBUG_PRESENT_TRACE=1
python3 -m tools.rom_smoke_0442 roms/tetris.gb --frames 3000

Results (Frame 2580):

• IRQTaken_VBlank=2579✅ (criterion: > 0)
• HRAM_FFC5_WriteCount=1✅ (criterion: >= 1)
• IF_WriteCount=5160
• IE_WriteCount=3
• VBlankServ=2579

Command executed (CGB):

export VIBOY_SIM_BOOT_LOGO=0
export VIBOY_DEBUG_CGB_PALETTE_WRITES=1
python3 -m tools.rom_smoke_0442 roms/tetris_dx.gbc --frames 1200

Results (Frame 600):

• IdxNonZero=22910✅ (criterion: > 0)
• RgbNonWhite=0❌ (criterion: > 0, not met - game uses DMG palettes)
• CGBPaletteWriteStats=BGPD_Writes=0 OBPD_Writes=0

Compiled C++ module validation:

python3 test_build.py
# Result: [SUCCESS] The build pipeline works correctly

Sources consulted

• Pan Docs: "Interrupts" - Interrupt Behavior in LR35902
• Pan Docs: "CGB Palettes" - Setting up CGB palettes
• Pan Docs: "Memory Map" - Memory Mapping and I/O Registers

Educational Integrity

Next Steps

• [ ] Investigate rendering pipeline: Since the interrupts work correctly, the problem is in the fetch/rendering of tiles or in the conversion of indices to RGB.
• [ ] Check DMG palette mapping: Although tetris_dx.gbc uses DMG palettes, the fact that RgbNonWhite=0 suggests that there may be a problem mapping indices to RGB colors.
• [ ] Analyze VRAM writes: The data shows that there are writes to VRAM (TiledataNonZeroB0=11000), but the framebuffer is still blank, suggesting a problem in the fetch or conversion.