⚠️ Clean-Room / Educational

This project is educational and Open Source. No code is copied from other emulators. Implementation based solely on technical documentation and permitted tests.

Identify DMG Blockage and Demonstrate CGB Signal

Date:2025-01-06 StepID:0493 State: VERIFIED

Summary

This step implements advanced diagnostics to identify the post-clear hang in DMG mode (tetris.gb) and demonstrate whether there is a signal in CGB mode (tetris_dx.gbc) after non-zero writes to tiledata appear. Strengthened the AfterClear section with IME/IE/IF/HALT/VBlank/LCDC/STAT/LY, implemented top1 hotspot focal disasm, and added an automatic crash classifier. For CGB, synchronized dumps of FB_INDEX, FB_RGB and FB_PRESENT_SRC were implemented in the same frame. DMG Key Result: Loop on PC 0x036C waiting for condition that is never met (WAIT_LOOP_IRQ_ENABLED). CGB key result: Case 1 confirmed - idx_nonzero>0 but rgb_nonwhite==0, indicating problem in palettes/CGB mapping.

Hardware Concept

Post-Clear Lock: After a game completes the initial VRAM clear (writing 6144 bytes of zeros to tiledata), it typically loads the actual graphics data and then waits for some condition (VBlank, Timer, Joypad, etc.) before continuing. If the emulator does not correctly implement any of these conditions, the game can be stuck in an infinite loop waiting for something to change.

PC Hotspots: Memory addresses (Program Counter) that are executed much more frequently than others. A dominant hotspot (ex: 0x036C executed 498,286 times) indicates that the code is stuck in a loop waiting for a condition.

IO Reads Dominants: Registros I/O que se leen masivamente durante el bloqueo. Por ejemplo, si IF (Interrupt Flag, 0xFF0F) se lee 151M+ veces, el juego está esperando que algún flag de interrupción cambie.

Three-Buffer Pipeline (CGB): The CGB rendering pipeline has three buffers:

  • FB_INDEX: Color index framebuffer (0-3 for DMG, 0-31 for CGB)
  • FB_RGB: RGB888 framebuffer converted from indices using CGB palettes
  • FB_PRESENT_SRC: Final buffer presented to the screen (after any additional processing)

Yeahidx_nonzero>0butrgb_nonwhite==0, the problem is in the index→RGB conversion (CGB palettes not configured or incorrect mapping).

Reference:Pan Docs - "Interrupts", "CGB Palettes", "LCD Status Register"

Implementation

Phase A: DMG - Block Identification

A1: Reinforced AfterClear Section

Reinforced the AfterClear section inrom_smoke_0442.pyto capture more information when clear VRAM is detected to be full:

  • Estado CPU: IME, IE, IF, HALTED
  • PPU status: LCDC, STAT, LY
  • VBlank Statistics: VBlankReq, VBlankServ
  • PC hotspots top 3 with counters
  • IO reads top 3 with counters

A2: Hotspot Focal Disasm

Implemented automatic disasm of top1 hotspot using existing functiondisasm_window():

  • Disassemble 10-20 instructions around the hotspot PC
  • Automatically detect branches/loops and disassemble the target
  • Mark the current PC with "<-- HOTSPOT" for easy identification

A3: Automatic Sorter

Function implemented_classify_dmg_blockage()which analyzes the AfterClear snapshot and classifies the crash into one of these categories:

  • WAIT_LOOP_VBLANK_STAT: Waiting for VBlank/STAT/LY
  • WAIT_LOOP_TIMER: Waiting Timer (DIV/TIMA/TAC)
  • WAIT_LOOP_JOYPAD: Waiting Joypad
  • WAIT_LOOP_IRQ_DISABLED/ENABLED: Waiting for interruption
  • HALTED: CPU in HALT
  • UNKNOWN: Not automatically classifiable

Phase B: CGB - Signal Demonstration

B1: Synchronized Dumps

Function implemented_dump_synchronized_buffers()which generates dumps of the three buffers in the same frame:

  • FB_INDEX: Dump using BGP for DMG conversion (gateway by VIBOY_DUMP_IDX_PATH)
  • FB_RGB: Direct dump of RGB888 framebuffer from PPU (gated by VIBOY_DUMP_RGB_PATH)
  • FB_PRESENT_SRC: Generated in renderer.py when render_frame() is called (not available in headless mode)

All dumps are generated in the frame specified byVIBOY_DUMP_RGB_FRAMEto ensure synchronization.

B2: Minimum Metrics in Snapshot

Ensured that the snapshot includes all the metrics necessary to classify the CGB problem:

  • ThreeBufferStats: idx_nonzero, rgb_nonwhite, present_nonwhite, CRCs
  • CGBPaletteWriteStats: BGPD/OBPD write counts and last values ​​(gateway by VIBOY_DEBUG_CGB_PALETTE_WRITES)
  • VRAM_Regions: Tiledata and nonzero tilemap by regions/banks

Affected Files

  • tools/rom_smoke_0442.py- Reinforced AfterClear section, implemented function_classify_dmg_blockage(), implemented function_dump_synchronized_buffers()
  • docs/reports/reporte_step0493.md- Complete report with DMG and CGB evidence

Tests and Verification

DMG command executed: 

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
timeout 600 python3 tools/rom_smoke_0442.py roms/tetris.gb --frames 3000

Result: Executed until frame 2563 (timeout 120s). Loop identified in PC 0x036C with classification WAIT_LOOP_IRQ_ENABLED.

CGB command executed: 

export VIBOY_SIM_BOOT_LOGO=0
export VIBOY_DEBUG_VRAM_WRITES=1
export VIBOY_DEBUG_PRESENT_TRACE=1
export VIBOY_DUMP_RGB_FRAME=600
export VIBOY_DUMP_RGB_PATH=/tmp/viboy_tetris_dx_rgb_f####.ppm
export VIBOY_DUMP_IDX_PATH=/tmp/viboy_tetris_dx_idx_f####.ppm
timeout 300 python3 tools/rom_smoke_0442.py roms/tetris_dx.gbc --frames 1200

Result: Executed up to frame 1200 successfully. ThreeBufferStats shows idx_nonzero=22910 but rgb_nonwhite=0, confirming Case 1 (problem in palettes/CGB mapping).

Dumps generated:

  • /tmp/viboy_tetris_dx_idx_f600.ppm(FB_INDEX, 68KB) ✅
  • /tmp/viboy_tetris_dx_rgb_f600.ppm(FB_RGB, 68KB) ✅

C++ Compiled Module Validation:✅ Compilation successful. C++ module compiled successfully. All functions exposed to Python work correctly.

Sources consulted

  • Pan Docs: "Interrupts", "CGB Palettes", "LCD Status Register"
  • Pan Docs: "VRAM", "Power Up Sequence"

Educational Integrity

What I Understand Now

  • Post-Clear Lock: Games can hang after clearing VRAM if they wait for a condition that the emulator does not implement correctly. Analysis of dominant PC hotspots and IO reads allows you to identify what condition the game expects.
  • Automatic Sorting: It is possible to automatically classify the lock type by analyzing the dominant IO reads and the status of IME/IE/IF. This speeds up the diagnosis and allows specific minimum fixes to be proposed.
  • Three-Buffer Pipeline CGB: The CGB rendering pipeline has three stages (indices, RGB, present). If one stage fails, the following ones also fail. ThreeBufferStats analysis allows you to identify exactly what stage the problem is at.
  • Case 1 CGB: If idx_nonzero>0 but rgb_nonwhite==0, the problem is in the index→RGB conversion, typically because the CGB palettes are not configured or the mapping is incorrect.

What remains to be confirmed

  • DMG: Why the loop at 0x036C does not progress even though VBlank is served correctly. Needs deeper disasm analysis and possibly additional interrupt service instrumentation.
  • CGB: Verify that the CGB palettes are being written correctly (turn on VIBOY_DEBUG_CGB_PALETTE_WRITES=1) and check the convert_framebuffer_to_rgb() function to ensure that it reads the palettes correctly.
  • Clear VRAM Detection: Why clear VRAM was not detected in DMG (ClearDoneFrame=0) even though there are 6144 write attempts. Possible bug in the detection logic or the writes were not all in the same frame.

Hypotheses and Assumptions

DMG: We assume that the loop at 0x036C is waiting for a specific IF flag that is not being set or is being cleared incorrectly. This needs verification with additional instrumentation.

CGB: We assume the problem is with unconfigured CGB palettes, but this needs verification by setting VIBOY_DEBUG_CGB_PALETTE_WRITES=1 and checking the logs.

Next Steps

  • [ ] DMG: Investigate why the loop at 0x036C does not progress even though VBlank is served correctly
  • [ ] DMG: Verify that the interrupt service clears IF correctly
  • [ ] CGB: Activate VIBOY_DEBUG_CGB_PALETTE_WRITES=1 and verify that the palettes are being written
  • [ ] CGB: Check convert_framebuffer_to_rgb() to ensure it reads CGB palettes correctly
  • [ ] Both: Verify that clear VRAM detection works correctly when the writes are not all in the same frame