The Stethoscope: Vital Signs of the Emulator

Summary

Upon final cleanup of the code, the screen appears green (empty), which is technically correct but functionally disappointing. To diagnose why the game is not displaying graphics without resorting to massive buffer-clogging logs, we implemented a status monitor in Python that prints vital signs (PC, LCDC, VRAM) once per second. This "stethoscope" will reveal to us if the CPU is stuck, if the graphics hardware is not configured, or if the graphics simply have not been copied yet.

Hardware Concept

In an emulator, when the screen appears completely green (Palette Color 0), it means that the renderer is working correctly (draws the background color) and the PPU is working (sending indices 0), but the problem is that the PPUonlysend zeros. This can happen for three main reasons:

1. LCDC Bit 0 off:The game has not yet enabled the background using the LCDC register (0xFF40). LCDC bit 0 controls whether the background is enabled.
2. Empty VRAM:The game has not copied graphics from ROM to VRAM (0x8000-0x9FFF). Tiles must be in VRAM before they can be rendered.
3. Empty TileMap:The game has not configured the TileMap (0x9800-0x9BFF) to indicate which tile to draw at each position on the screen.

Without massive logs, it is impossible to know if the CPU is executing code, if it is in an infinite loop, or if it is simply waiting for something. The "stethoscope" is a non-intrusive probe that prints key information every 60 frames (1 second) without affecting performance, allowing us to diagnose the status of the emulator in real time.

Implementation

Added a diagnostic block in the methodrun()ofviboy.pywhich runs every 60 frames (approximately 1 second). This diagnostic reads the following vital signs directly from the hardware:

• PC (Program Counter):Memory address where the CPU is running. If it doesn't change, the CPU is stuck in an infinite loop.
• LCDC (0xFF40):LCD control register. Bit 0 indicates whether the background is enabled. If it is 0x80 or 0x90 (bit 0 off), the game has disabled the background.
• TileMap[0x9904]:A byte of the TileMap where the Nintendo logo should be. If it is 0x00, the TileMap is empty and the game has not configured which tiles to draw.
• TileData[0x8010]:A byte of tile data where part of the logo should be. If it is 0x00, the VRAM is empty and the game has not copied the graphics.

Modified components

• src/viboy.py: Added diagnostic block in methodrun()inside the main loop, running every 60 frames.

Design decisions

Printing every 60 frames (1 second) was chosen to balance the usefulness of the diagnostic with the impact on performance. A more frequent diagnostic would clutter the console, while a less frequent one would not capture rapid changes. The diagnostic runs only when using the C++ core (main mode), with a fallback for Python mode.

Specific addresses (0x9904 for TileMap and 0x8010 for TileData) were chosen because they are typical locations where the Nintendo logo is stored during boot. However, these values ​​are only indicative; The main diagnosis is the PC and the LCDC.

Affected Files

• src/viboy.py- Added diagnostic block "The Stethoscope" in the methodrun()(lines ~819-840)

Tests and Verification

To validate the diagnosis, run the emulator and observe the console output:

python main.py roms/tetris.gb

Every second a line will appear with the format:

[VITAL] PC: 02B4 | LCDC: 91 | Map[9904]: 00 | Data[8010]: 00

Analysis of results:

• Case A (static PC):If the PC does not switch between lines, the CPU is in an infinite loop (logical deadlock).
• Case B (LCDC off):If LCDC is 0x90 or 0x80 (bit 0 off), the game has explicitly disabled the background and is waiting for something to turn it on.
• Case C (empty VRAM):If Map[9904] and Data[8010] are 0x00, the CPU is running but has NOT copied the graphics to VRAM.

This diagnosis will allow us to quickly identify the problem without the need to activate massive logs that saturate the buffer and break the connection with the AI ​​server.

Sources consulted

• Bread Docs:LCD Control Register (LCDC)- Bit 0 controls the background
• Bread Docs:Video RAM (VRAM)- Memory area for tiles and TileMaps
• Bread Docs:Tile Data- Tiles data structure

Educational Integrity

Next Steps

• [ ] Run the emulator and observe the diagnostic values
• [ ] Analyze the values ​​to determine if the CPU is running, if the LCDC is configured, and if the VRAM contains data
• [ ] Based on the analysis, implement corresponding fix (unlock CPU, configure LCDC, or check graphics copy)