Ceasefire: The Final Execution

Summary

The "Sniper" surgical debug (Step 0223) confirmed that the CPU was working correctly. The V-Blank Waiting Loop (LY< 144) es comportamiento normal del hardware. La aparente congelación se debía a la latencia introducida por los logs de consola. Se retiró toda la instrumentación de debug (Francotirador y Estetoscopio) para permitir que el emulador ejecute a velocidad nativa (60 FPS) y supere los bucles de espera en una fracción de segundo.

Hardware Concept

On the real Game Boy, the CPU runs at 4.19 MHz, which means that a full frame (144 visible lines + 10 V-Blank) is completed in approximately 16 milliseconds. During initialization, many games wait for V-Blank before copying graphics to VRAM because it is the only "safe" time when the PPU is not actively reading VRAM.

The typical V-Blank wait loop is:

loop:
    LDH A, (0xFF44) ; Read LY (current line)
    CP 0x90 ; Compare to 144 (V-Blank)
    JR NZ, loop ; If not 144, repeat

This loop is completely normal and runs in a fraction of a second on real hardware. However, when we add console logs (`printf`) inside the loop, each instruction takes milliseconds to print, making the normally 16ms loop turn into minutes. This creates the illusion that the emulator is "frozen" when in reality it is running correctly, just in super-slow motion.

The solution is to remove all debug instrumentation from the critical emulation loop. C++ code must run without console I/O to maintain native performance. Once the emulator runs at real speed, the wait loops complete instantly and the game proceeds normally.

Implementation

Removed all debug instrumentation from the critical emulation loop:

Modified components

• CPU.cpp: Removed the "Sniper" block (Step 0223) that printed logs when PC was at 0x02B0-0x02C0. The include of ` was also commented`.
• viboy.py: Commented on the "Stethoscope" block (Step 0222) that printed vital signs every 60 frames.

Design decisions

We chose to comment out the code rather than remove it completely to facilitate future debugging if necessary. The comments explain why the instrumentation was removed and what confirmed the diagnosis.

Golden rule:In the critical emulation loop (CPU's `step()` method), there should be no console I/O. Any log must be outside the loop or be conditional and very limited.

Affected Files

• src/core/cpp/CPU.cpp- Removed Sniper block and commented cstdio include
• src/viboy.py- Commented Stethoscope block

Tests and Verification

Final cleaning validation:

• Recompilation:Execute.\rebuild_cpp.ps1to recompile the Cython extension without the logs.
• Execution:Executepython main.py roms/tetris.gband verify that:
  • No logs appear[SNIPER]on the console
  • No logs appear[VITAL]on the console
  • The game loads and displays the Tetris copyright screen (or the Nintendo logo falling)
  • The emulator maintains a stable 60 FPS
• Visual validation:Confirm that the graphics load correctly and the game is playable (although no sound yet).

Expected result:The emulator should run at native speed, completing V-Blank wait loops in milliseconds instead of minutes, allowing the game to proceed normally to loading and displaying graphics.

Sources consulted

• Bread Docs:System Clock, Timing, LCD Timing
• Bread Docs:V-Blank Interrupt, LY Register

Educational Integrity

Next Steps

• [ ] Implement APU (Audio Processing Unit) - Channel 1 (Square Wave with Sweep)
• [ ] Implement APU - Channel 2 (Square Wave with Envelope)
• [ ] Implement APU - Channel 3 (Wave RAM)
• [ ] Implement APU - Channel 4 (LFSR Noise)
• [ ] Channel mix and output at 44100Hz/48000Hz
• [ ] Audio Sync with Emulation (Ring Buffer)