Fix: Fix PPU Creation in Cython Wrapper to Resolve Null Pointer

Summary

The diagnosis of Step 0141 revealed that theSegmentation Faultit happenedbeforefor any code to be executed withinrender_scanline(), which confirmed that the problem was in the Cython wrapper: the pointer to the C++ PPU object was null (nullptr). Builder fixed__cinit__ofPyPPUinppu.pyxadding diagnostic logs, robust checks, and explicit error handling to ensure that the C++ PPU instance is created correctly.

Hardware Concept

In a hybrid Python/C++ emulator, creating C++ objects from Python requires a Cython wrapper that acts as a bridge between both worlds. The Cython wrapper maintains a raw C++ pointer (cdef PPU* _ppu) that points to the actual instance of the object in C++ memory.

When Python calls a wrapper method (ex:ppu.step()), Cython translates the call to a direct invocation of the C++ method (ex:self._ppu.step()). If the pointer_ppuisNULL(null), trying to call a method on a null pointer causes aSegmentation Faultimmediate,beforethat any code within the C++ method can be executed.

The Cython builder (__cinit__) is responsible for creating the C++ instance usingnew PPU(...)and assign the resulting pointer toself._ppu. If this process fails silently or does not execute correctly, the pointer is left inNULLand all subsequent calls will fail with a crash.

Implementation

Builder fixed__cinit__ofPyPPUinsrc/core/cython/ppu.pyxto ensure the correct creation of the C++ instance and add security layers that prevent future silent crashes.

Modified components

• src/core/cython/ppu.pyx: Builder__cinit__enhanced with diagnostic logs and robust verifications
• src/core/cython/ppu.pyx: Destroyer__dealloc__improved with logs and explicit assignment ofNULL

Changes applied

1. Builder__cinit__improved:

• Added diagnostic logs withprint()to track the creation of the object
• Explicit verification thatmmu_wrapperdon't beNone
• Explicitly extracting the raw C++ pointer from the MMU wrapper:cdef mmu.MMU* mmu_ptr = (<PyMMU>mmu_wrapper)._mmu
• Verifying that the MMU pointer is not null before creating the PPU
• Explicit verification afternew PPU(mmu_ptr)to ensure that the assignment was successful
• Throwing descriptive exceptions (ValueError, MemoryError) if something goes wrong

2. Destroyer__dealloc__improved:

• Added diagnostic logs to track object release
• Explicit assignment ofNULLafter releasing the object to avoid dangling pointers

Key code

def __cinit__(self, PyMMU mmu_wrapper):
    print("[PyPPU __cinit__] Creating PPU instance in C++...")
    
    # Verify that mmu_wrapper is not None
    if mmu_wrapper is None:
        raise ValueError("PyPPU: mmu_wrapper cannot be None")
    
    # Extract the raw C++ pointer from the MMU wrapper
    cdef mmu.MMU* mmu_ptr = (<PyMMU>mmu_wrapper)._mmu
    
    # Security check: Make sure the MMU pointer is not null
    if mmu_ptr == NULL:
        raise ValueError("An attempt was made to create PyPPU with an invalid MMU wrapper (null pointer).")
    
    # --- CRITICAL LINE ---
    # Create the PPU instance in C++ and assign the pointer
    self._ppu = new ppu.PPU(mmu_ptr)
    
    # Security check: Make sure the creation was successful
    if self._ppu == NULL:
        raise MemoryError("Memory allocation for the PPU in C++ failed.")
    
    print("[PyPPU __cinit__] C++ PPU instance created successfully.")

Affected Files

• src/core/cython/ppu.pyx- Improved constructor and destructor with robust logs and checks

Tests and Verification

Diagnostic validation (Step 0141):

• The fact that the messageprintfof Step 0141 was never executed confirmed that the crash occurred in the call to the method itself, not within it.
• This definitely indicated that the pointerself._ppuin the Cython wrapper it was null.

Next check (pending recompile):

• Recompile the C++ module:.\rebuild_cpp.ps1
• Run the emulator:python main.py roms/tetris.gb
• Verify that the diagnostic logs appear:[PyPPU __cinit__] Creating PPU instance in C++...
• Verify that theSegmentation Faulthas disappeared
• Verify that rendering is working correctly

Sources consulted

• Cython Documentation:https://cython.readthedocs.io/- Memory and pointer management in Cython
• Cython Best Practices: Constructors and Destructors with C++ Objects

Educational Integrity

Next Steps

• [ ] Recompile the C++ module with.\rebuild_cpp.ps1
• [ ] Run the emulator and verify that the diagnostic logs appear
• [ ] Confirm that theSegmentation Faulthas disappeared
• [ ] Verify that rendering is working correctly
• [ ] If everything works, delete the production diagnostic logs (keep only in debug mode)