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

Hard Reset and Radioactive Marker

Date:2025-12-22 StepID:0242 State: draft

Summary

Analysis of the Sniper log (Step 0241) reveals an absurd sequence of instructions in `0x2B20`: multiple executions of `LD (nn), SP` (opcode `0x08`) mixed with meaningless arithmetic operations. This suggests that the CPU is executing **data ("garbage")** instead of valid code, or that we are suffering from a persistence issue for old compiled binaries on Windows. A "radioactive marker" (very visible printf) is implemented inside the `case 0x08` to confirm that we are running the correct version of the C++ code and not a cached DLL/PYD.

Hardware Concept

Binary Persistence Problem in Windows: On Windows systems, Python can cache compiled extensions (`.pyd` or `.dll` files) in memory or in the working directory. If the C++ source code is modified but the cache is not properly cleared, Python may continue to use the old version of the binary, causing unexpected behavior or "ghosting" of older code.

Radioactive Marker (Canary Debugging): It is a debugging technique that involves adding a highly visible marker (such as a `printf` with a single message) at a specific point in the code to confirm that the correct version is running. If the marker appears in the logs, we confirm that the new code is running. If it doesn't appear but the behavior suggests it should run, then there is a cache or compilation issue.

Hard Reset: It consists of manually removing all build artifacts (`build/` folders, `.pyd`, `.dll`, `.so` files) before recompiling. This ensures that there are no residues from previous builds that could interfere with the new version.

Implementation

A radioactive marker (very visible printf) is added inside the `case 0x08` in `CPU.cpp` to confirm that the opcode is being executed with the correct version of the code.

Modified components

src/core/cpp/CPU.cpp: Added radioactive marker in `case 0x08`.

Design decisions

The marker is placedat the beginningof `case 0x08`, before any other operation, so that it is executed immediately when the opcode is detected. The message is very visible (`!!! RUNNING OPCODE 0x08 IN C++!!!`) so that it is easy to identify in the logs, even if there is a lot of output.

Important note: This flag is temporary and should be removed once we confirm that we are running the correct version of the code. `printf`s slow down execution, especially if executed frequently.

Code added

case 0x08: // LD (nn), SP
    {
        // --- Step 0242: RADIOACTIVE MARKER ---
        // DEBUG: Confirm actual execution of the fix
        // This printf is a "canary" to verify that we are executing
        // the correct version of the C++ code and not a cached DLL/PYD.
        printf("!!! RUNNING OPCODE 0x08 IN C++ !!!\n");
        // ---------------------------------------
        
        uint16_t addr = fetch_word();
        mmu_->write(addr, regs_->sp & 0xFF);
        mmu_->write(addr + 1, (regs_->sp >> 8) & 0xFF);
        cycles_ += 5;
        return 5;
    }

Hard Reset Instructions

To ensure that there are no previous build artifacts:

Close all Python terminals: Close any PowerShell or CMD window that is running Python or the emulator.
Delete `build/` folder: If it exists, manually delete the `build/` folder from the project.
Delete `.pyd` files: Find and delete any `.pyd` files in the project root (ex: `viboy_core*.pyd`).
Recompile: Run `.\rebuild_cpp.ps1` to recompile from scratch.
Execute: Run `python main.py roms/tetris.gb` and observe the logs.

Affected Files

src/core/cpp/CPU.cpp- Added radioactive marker in `case 0x08`
docs/logbook/entries/2025-12-22__0242__hard-reset-radioactive-marker.html- Log entry

Tests and Verification

To validate this implementation, you must:

Perform Hard Reset:
- Close all Python terminals.
- Manually delete the `build/` folder if it exists.
- Delete any `.pyd` files in the project root.
Recompile the C++ extension:
```
.\rebuild_cpp.ps1
```
Run the emulator with Tetris:
```
python main.py roms/tetris.gb
```
Analyze the logs:
- If you see`!!! RUNNING OPCODE 0x08 IN C++!!!`mixed with the Sniper logs: We confirm that the code is real. The CPU is executing that sequence. The problem is HOW we got there (a previous incorrect jump).
- YeahNOyou see the message but Sniper says `OP:08`: The binary was not updated. We are running an old ghost version. We need to do a more aggressive Hard Reset or verify that the build completed successfully.

Current status: Pending execution and log analysis.

Sources consulted

Bread Docs:Game Boy Pan Docs- General architecture reference LR35902
Python documentation:Extending Python on Windows- Management of compiled extensions on Windows

Note: This implementation is a standard debugging technique to verify the execution of compiled code.

Educational Integrity

What I Understand Now

Cache problem in Windows: Python can cache compiled extensions, causing old code to run even after recompiling. This is especially problematic on Windows with `.pyd` files.
Radioactive Tracer: Adding a highly visible marker at a specific point in the code confirms that the correct version is running. It is a standard debugging technique to verify the execution of compiled code.
Hard Reset: Manually removing all build artifacts before recompiling ensures that no residue from previous builds remains.
Analysis of Anomalous Sequences: If the log shows an absurd sequence of instructions (such as multiple `LD(nn), SP` in a short loop), it may indicate that we are executing data instead of code, or that there is a misalignment problem caused by a previous incorrect compilation.

What remains to be confirmed

Marker Execution: Does the message `!!! appear? RUNNING OPCODE 0x08 IN C++!!!` in the logs? This will confirm that we are running the correct version of the code.
Origin of Misalignment: If the marker appears but the sequence is still absurd, the problem is that the CPU incorrectly jumped to a data zone. We need to investigate what caused that jump.
Binary Persistence: If the bookmark does not appear, we confirm that there is a cache problem. We need to do a more aggressive Hard Reset or check the build settings.

Hypotheses and Assumptions

Main hypothesis: The absurd sequence problem may be caused by:

An earlier incorrect jump that took the CPU to an area of data (graphs, tables) instead of code.
A binary cache issue on Windows that is running an old version of the code where the `0x08` opcode was not implemented correctly.
A misalignment caused by a previous incorrect implementation of the `0x08` opcode (e.g. if it previously consumed 1 byte instead of 3, the PC would have advanced incorrectly).

The radioactive tracer will tell us which of these hypotheses is correct.

Next Steps

[ ] Perform Hard Reset: Close terminals, delete `build/` and `.pyd` files.
[ ] Recompile the C++ extension with the radioactive marker.
[ ] Run Tetris and capture the logs.
[ ] Analyze if the message `!!! RUNNING OPCODE 0x08 IN C++!!!`.
[ ] If it appears: Confirm that the code is real and investigate the origin of the incorrect jump.
[ ] If it does not appear: Do a more aggressive Hard Reset or check the build configuration.
[ ] Once confirmed, delete the radioactive marker so as not to slow down the execution.