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

Debug: Extension of CPU Trace to 500 Instructions

Date:2025-12-20 StepID:0154 State: 🔍 DRAFT

Summary

Analysis of Step 0153 confirmed that the Z flag fix works correctly, but revealed that the ROM initialization routine contains multiple nested cleanup loops. The current trace of 200 instructions is insufficient to observe what happens after all of these loops terminate. Increased the CPU trace limit from 200 to 500 instructions to capture a much larger observation window and be able to see the execution sequence following the initialization loops.

Hardware Concept

Game Boy ROMs run complex initialization routines upon booting. These routines not only clean a single memory area, but perform multiple sequential operations:

  • WRAM Cleanup:Clearing working memory (0xC000-0xDFFF).
  • HRAM Cleaning:High speed memory erase (0xFF80-0xFFFE).
  • Hardware register initialization:PPU configuration (LCDC, BGP, etc.).
  • Interrupt settings:Establishing vectors and enabling interrupts.

Each of these operations can involve nested loops that consume hundreds of instructions. In order to observe the full behavior of the CPU during initialization, we need a trace long enough to capture not only the cleanup loops, but also the instructions that follow after they finish.

The trace boundary is a diagnostic tool that allows us to "zoom out" and see the big picture of the execution, rather than getting stuck in the details of a single loop.

Implementation

The constant was changedDEBUG_INSTRUCTION_LIMITin the filesrc/core/cpp/CPU.cppto increase the limit of traced instructions from 200 to 500.

Modified components

  • CPU.cpp:Increase ofDEBUG_INSTRUCTION_LIMITfrom 200 to 500.

Change made

The change is simple but effective: increasing the trace limit allows us to capture more instructions in the diagnostic output, which will help us identify what happens after the initialization loops finish.

// Static variables for diagnostic logging
static int debug_instruction_counter = 0;
// Increase the limit to see beyond the cleanup loops
static const int DEBUG_INSTRUCTION_LIMIT = 500;

Affected Files

  • src/core/cpp/CPU.cpp- Increase ofDEBUG_INSTRUCTION_LIMITfrom 200 to 500.

Tests and Verification

This change does not require specific unit tests, as it only modifies the diagnostic logging limit. Validation will be carried out through:

  • Recompiling C++ module:Execute.\rebuild_cpp.ps1to recompile with the new limit.
  • Running the emulator:Executepython main.py roms/tetris.gbto generate the new extended trace.
  • Trace analysis:Examine the 500 captured instructions to identify what happens after the initialization loops.

Expected result:The trace should show the first 500 instructions executed, including the cleanup loops and the instructions that follow after they finish. This will allow us to identify the next opcode that we must implement so that the game can continue running.

Sources consulted

  • Analysis of Step 0153: Confirmation of multiple loops nested in initialization routines.
  • Behavior observed in CPU traces: Games execute complex initialization sequences.

Note: This change is purely diagnostic and does not require hardware-specific technical documentation.

Educational Integrity

What I Understand Now

  • Complex initialization routines:ROMs run multiple nested loops during initialization, not just one.
  • Importance of trace limit:A limit that is too low can hide critical information about the behavior of the CPU.
  • Debugging strategy:Increasing the trace limit is a valid technique to "zoom out" and see the big picture.

What remains to be confirmed

  • Extended trace content:We need to see what instructions appear after the initialization loops.
  • Next critical opcode:Identify what instruction needs to be implemented so that the game can continue.
  • Hardware configuration:Check if the game tries to write to I/O registers (LCDC, BGP, etc.) after initialization.

Hypotheses and Assumptions

Main hypothesis:After the cleanup loops finish, the game should start configuring the hardware, especially the PPU registers. We hope to see instructions likeLDH (n), A(0xE0) writing to registers like0xFF40(LCDC) or0xFF47(BGP).

Next Steps

  • [ ] Recompile the C++ module with the new trace limit.
  • [ ] Run the emulator with the Tetris ROM and capture the complete trace of 500 instructions.
  • [ ] Analyze the trace to identify what happens after the initialization loops.
  • [ ] Identify the first unimplemented or suspicious opcode that appears in the trace.
  • [ ] Implement the following critical opcode to unlock game progress.