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

WRAM Writer Profiler

Date:2025-12-23 StepID:0246 State: draft

Summary

Analysis of Step 0245 revealed a puzzling result:zero activity detected. This partially contradicts Step 0244 (which did see `0xFD` writes), suggesting that the emulator may be entering the wait loop before reaching the write, or it the parsing script leaked too much.

The net conclusion is that the gameNOuses DMA (`FF46`) nor reads HRAM (`FF8D`) to copy it. However, the gameSEEKSdata in WRAM and it hangs because it is empty.

This Step implements aWRAM writes profilerwhich records the first 100 writes to the range `0xC000-0xDFFF` to determine if memory is being initialized at all, or if it remains completely virgin (only zeros).

Hardware Concept

TheWork RAM (WRAM)on the Game Boy is an 8KB memory region located in the range `0xC000-0xDFFF`. This memory is used by games to store state variables, temporary buffers, and work data during execution.

During the startup of a game, typically ainitialization routinewhich copies data from the cartridge (ROM) to the WRAM. This routine can be:

  • Bulk copy routine (memcpy): Move blocks of data from ROM to WRAM.
  • Variable initialization routine: Write specific values to addresses specificities of WRAM.
  • Cleaning routine: Fills the WRAM with zeros or default values.

If the WRAM remains empty (full of zeros), it means thatthat copy routine never happenedor wrote zeros. This may be due to:

  • HeProgram Counter (PC)took a wrong path before reaching the copy `CALL`.
  • The initialization routine failed silently.
  • The emulator completely skipped the memory initialization phase.

Fountain:Pan Docs - "Memory Map", "Work RAM (WRAM)"

Implementation

A write profiler is implemented in WRAM that records the first 100 writes in the range `0xC000-0xDFFF`. This profiler will allow us to determine:

  • Scenario A (Total Silence): No writes to WRAM detected.Diagnosis:The CPU skips initialization. The 'PC' takes a wrong path before to reach the copy `CALL`.
  • Scenario B (Writes detected): Writes to WRAM are detected.Analysis:If the values ​​are all `00`, it is a cleanup routine (`XOR A`). If the values ​​are varied (`12`, `F0`, `FD`), it is a data copy routine.

Components created/modified

  • src/core/cpp/MMU.cpp: Added instrumentation block in `MMU::write` to record the first 100 writes to WRAM. Steps instrumentation removed 0244 and 0245 to clean up the noise.

Design decisions

100 write limit:Registration is limited to the first 100 writings to avoid flooding the console output and maintain emulator performance. This number is enough to determine if the memory is being initialized or remains blank.

WRAM Range (0xC000-0xDFFF):Filters by logical address, including Echo RAM if redirected, but the filter is applied before the redirect to maintain consistency.

Cleaning of previous instrumentation:Instrumentation blocks removed of Steps 0244 and 0245 to reduce noise in the logs and facilitate the analysis of the results.

Affected Files

  • src/core/cpp/MMU.cpp- Added write profiler in WRAM (Step 0246). Removed instrumentation from Steps 0244 and 0245.

Tests and Verification

Verification is performed by running the emulator and observing the console output:

  1. Recompilation: .\rebuild_cpp.ps1
  2. Execution: python main.py roms/tetris.gb
  3. Observation:The console is observed to detect messages[WRAM-WRITE]

Expected results:

  • Scenario A (Total Silence): No messages seen[WRAM-WRITE]. This confirms that the CPU is skipping initialization.
  • Scenario B (Writes detected): Messages are seen[WRAM-WRITE #N]with addresses and values. This confirms that the memory is being initialized, but we need analyze the values to determine if they are valid data or zeros.

Compiled C++ module validation:The profiler is implemented directly in the C++ code of the MMU, so it requires recompilation to activate. The instrumentation is runs in the critical memory write loop, so it must be efficient to not degrade emulator performance.

Sources consulted

Educational Integrity

What I Understand Now

  • Memory initialization routine:Game Boy games typically run an initialization routine that copies data from ROM to WRAM at startup of the execution. If this routine is not executed, the WRAM remains empty and the game can get hung up looking for data that never existed.
  • Memory profiling:Instrumenting writes to memory is a technique effective for diagnosing initialization problems. When recording the first writings, we can determine if the memory is being initialized or remains virgin.

What remains to be confirmed

  • Profiler results:We need to run the emulator and see if writes to WRAM are detected. If they are not detected, we will confirm that the CPU skips the initialization. If detected, we will analyze the values to determine if they are data valid or zeros.
  • PC Execution Path:If no writes are detected, we will need trace the Program Counter to determine why the initialization routine is not execute.

Hypotheses and Assumptions

Main hypothesis:The game should be running a copy routine massive (`memcpy` type) that moves blocks of data from the Cartridge (ROM) to the RAM of work (WRAM) at startup. If the WRAM is empty, it means that that copy routine will never occurred or wrote zeros.

Assumption:We assume that the limit of 100 writes is enough to determine if memory is being initialized. If the game writes more than 100 times to WRAM during initialization, we will lose information, but the first 100 writes should be sufficient to diagnose the problem.

Next Steps

  • [ ] Run the emulator and observe the output of the WRAM profiler
  • [ ] Analyze the results: Are writes detected? What values ​​are written?
  • [ ] If no writes are detected: Trace the Program Counter to determine why initialization routine does not execute
  • [ ] If writes are detected but they are zeros: Investigate why the copy routine writes zeros instead of valid data
  • [ ] If writes with varying values are detected: Confirm that the memory is being initializing correctly and look for the problem elsewhere