⚠️ 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.

VRAM Sensor for Diagnostics

Date:2025-12-18 StepID:0064 State: draft

Summary

Implemented a "VRAM Sensor" that calculates the checksum of all bytes in the VRAM (0x8000-0x9FFF) and shows it in the emulator's heartbeat. This diagnosis Allows you to determine if the white screen issue is due to empty VRAM (all zeros) or to graphical data that is not rendering correctly.

Hardware Concept

VRAM (Video RAM) is the memory dedicated to storing the Game Boy's graphic data. It occupies the address range 0x8000-0x9FFF (8KB). In this memory are stored:

  • Tiles (tiles):Pixel data that makes up the graphics (backgrounds, sprites).
  • Tile Maps:Indices that indicate which tile to draw in each position.
  • Attribute Maps (CGB):Color and priority attributes (Game Boy Color only).

If the VRAM is completely empty (all zeros), the screen will be white regardless how the renderer works. If the VRAM contains data but the screen is still white, the The problem is in the renderer (decoding of tiles, palettes, offsets, layers).

Fountain:Pan Docs - Memory Map, VRAM Access Restrictions

Implementation

Added a public methodget_vram_checksum()in classMMUwhich calculates the sum of all bytes in the range 0x8000-0x9FFF. This value is displayed in the emulator heartbeat every 60 frames (≈1 second).

Components created/modified

  • MMU.get_vram_checksum():Method that sums all bytes of VRAM (0x8000-0x9FFF).
  • Viboy.run():Modified to includeVRAM_SUMon the heartbeat usingprint()to ensure visibility.
  • main.py:Added option--verboseto activate INFO logging level.

Design decisions

A simple checksum was chosen instead of a more complex hash because:

  • It is fast to calculate (does not affect performance).
  • It is enough to distinguish between empty VRAM (sum=0) and VRAM with data (sum>0).
  • Does not require additional dependencies.

CRITICAL - Heartbeat Visibility:Initially the heartbeat used onlylogger.info(), but the default logging level is atWARNING, so the messages were not displayed. was addedprint()in addition tologger.info()to ensure that the heartbeat is always visible on the console, regardless of the configured logging level. This is essential for diagnosis.

The checksum is displayed on the heartbeat along with other diagnostic indicators (FPS, number of writes to VRAM) to facilitate analysis.

Affected Files

  • src/memory/mmu.py- Added methodget_vram_checksum()
  • src/viboy.py- Modified heartbeat to showVRAM_SUMwearingprint()to ensure visibility
  • main.py- Added option--verboseto activate log level INFO

Tests and Verification

This is a diagnostic change, not new functionality. No tests required units, but the emulator must be run with a ROM to verify that the sensor works correctly.

Manual execution required:

  • Command: python main.py pkmn.gb(eitherpython main.py pkmn.gb --verbosefor more detail)
  • Around:Windows 10, Python 3.10+
  • Success Criterion:The heartbeat should be displayed on the console every second withVRAM_SUM=Xwhere X is an integer.
  • Interpretation:
    • YeahVRAM_SUM=0: VRAM is empty. The problem is either in the CPU (failed copy loop) or in the MBC (reads zeros from the cartridge).
    • YeahVRAM_SUM > 0(ex: 45032): There is graphic data. The problem is in the Renderer (palettes, offsets, layers).

Note:The sensor result will be displayed on the console when the emulator run the heartbeat (every 60 frames ≈ 1 second). The heartbeat usesprint()to ensure visibility even if the logging level is at WARNING. The user must run the emulator and observe the value ofVRAM_SUMon the console.

Sources consulted

Educational Integrity

What I Understand Now

  • Binary diagnosis:The white screen problem can have two fundamental causes: empty VRAM or faulty renderer. The VRAM checksum allows us to distinguish between the two.
  • VRAM as graphics store:The VRAM contains the pixel data (tiles) and the maps that indicate where to draw them. If it is empty, there is nothing to render.
  • Heartbeat as a diagnostic tool:The periodic heartbeat is ideal for displaying diagnostic metrics without cluttering the logs.

What remains to be confirmed

  • Expected value of VRAM_SUM:I don't know what value the checksum should have when a game has correctly loaded its graphics. This will be determined by running the emulator and observing the value.
  • Graphics loading timing:I don't know when exactly the game should have loaded the graphics into VRAM. It may need to run for several seconds before VRAM fills.

Hypotheses and Assumptions

Main hypothesis:If the emulator runs smoothly (without errors on the console) but the screen is white, the problem is binary: either the VRAM is empty (CPU/MBC do not load data) or the renderer does not draw correctly the data that is in VRAM.

The VRAM sensor will allow you to confirm or refute this hypothesis immediately.

Next Steps

  • [ ] Run the emulator withpkmn.gband observe the value ofVRAM_SUMin the heartbeat.
  • [ ] YeahVRAM_SUM=0: Investigate why the CPU is not loading data into VRAM (copy loop, MBC, etc.).
  • [ ] YeahVRAM_SUM > 0: Investigate the renderer (decoding tiles, palettes, offsets, layers).
  • [ ] Document the expected value ofVRAM_SUMwhen a game has successfully loaded its graphics.