Fix: Segmentation Fault in PPU - Signed Addressing

Summary

Fixed aSegmentation Faultcritical that occurred when running Tetris (and probably other games) when the PPU tried to render the background. The problem had two main causes: (1)incorrect calculation of tile addresses with signed addressing(used base 0x8800 instead of 0x9000) and (2)lack of validation of VRAM rangesthat allowed out-of-bounds access. Extensive validations were implemented and the calculation formula was corrected according to Pan Docs.

Hardware Concept

The Game Boy has two addressing modes for tiles in VRAM, controlled by bit 4 of the LCDC register (0xFF40):

• Unsigned Addressing (LCDC bit 4 = 1): The tile IDs range from 0-255, and the tiles are stored from 0x8000. Formula:tile_addr = 0x8000 + (tile_id * 16)
• Signed Addressing (LCDC bit 4 = 0): The tile IDs range from -128 to 127 (interpreted as int8_t), and thetile 0 is at 0x9000, not at 0x8800. Formula:tile_addr = 0x9000 + (signed_tile_id * 16)

CRITICAL: In signed addressing, although LCDC bit 4 indicates that the base is 0x8800, tile 0 (signed_tile_id = 0) is physically at 0x9000. This means that:

• Tile -128 → Address 0x9000 + (-128 * 16) = 0x9000 - 0x800 =0x8800
• Tile 0 → Address 0x9000 + (0 * 16) =0x9000
• Tile 127 → Address 0x9000 + (127 * 16) = 0x9000 + 0x7F0 =0x97F0

VRAM occupies the range 0x8000-0x9FFF (8KB). Any access outside this range causes a Segmentation Fault in C++.

Fountain: Pan Docs - VRAM Tile Data, LCD Control Register (LCDC)

Implementation

Fixed two problems in the methodPPU::render_scanline():

1. Correction of Address Calculation with Signed Addressing

Problem: The code usedtile_data_base(0x8800) to calculate addresses with signed addressing, which is incorrect. Tile 0 must be at 0x9000.

Previous code (incorrect):

if (signed_addressing) {
    int8_t signed_tile_id = static_cast<int8_t>(tile_id);
    tile_addr = tile_data_base + (static_cast<int16_t>(signed_tile_id) * 16);
}

Fixed code:

if (signed_addressing) {
    // Signed: tile_id as int8_t, tile 0 is at 0x9000
    // NOTE: When signed_addressing is true, tile_data_base is 0x8800,
    // but tile 0 is at 0x9000, not 0x8800.
    // Formula: 0x9000 + (signed_tile_id * 16)
    int8_t signed_tile_id = static_cast<int8_t>(tile_id);
    tile_addr = 0x9000 + (static_cast<int16_t>(signed_tile_id) * 16);
}

2. VRAM Range Validation

Added extensive validations to prevent out-of-bounds access:

• Tile base address validation: Check thattile_addris at 0x8000-0x9FFF
• Tile line direction validation: Check thattile_addr + tile_y_offset * 2andtile_addr + tile_y_offset * 2 + 1are inside VRAM
• Safe behavior: If any validation fails, color 0 (transparent) is used instead of causing a crash

// CRITICAL: Validate that the tile address is within VRAM (0x8000-0x9FFF)
if (tile_addr < VRAM_START || tile_addr > VRAM_END) {
    framebuffer_[line_start_index + x] = 0;
    continue;
}

// Validate that the address of the tile line is also within VRAM
uint16_t tile_line_addr = tile_addr + tile_y_offset * 2;
if (tile_line_addr > VRAM_END || (tile_line_addr + 1) > VRAM_END) {
    framebuffer_[line_start_index + x] = 0;
    continue;
}

Modified components

• src/core/cpp/PPU.cpp: Methodrender_scanline()corrected with correct calculation of signed addressing and VRAM range validations

Design decisions

• Safe behavior on errors: Instead of crashing, color 0 (transparent) is used when there is invalid access. This allows the emulator to continue running even if there is corrupted data in VRAM.
• Comprehensive validation: Both the base address of the tile and the address of the specific line to be read are validated. This prevents out-of-bounds access even with complex calculations.

Affected Files

• src/core/cpp/PPU.cpp- Correction of address calculation with signed addressing and addition of VRAM range validations inrender_scanline()

Tests and Verification

Validation by actual execution:

• test ROM: roms/tetris.gb(Original Game Boy Tetris)
• Previous behavior: Immediate Segmentation Fault when starting the game
• Expected behavior: The game should start without crashes and display the screen correctly

test command:

python main.py roms/tetris.gb

C++ Compiled Module Validation: The fix requires recompilation of the C++ module with:

python setup.py build_ext --inplace

Note: This fix corrects a critical bug that prevented games from running. Validation will be done by running Tetris and verifying that Segmentation Fault does not occur.

Sources consulted

• Bread Docs: VRAM Tile Data, LCD Control Register (LCDC) - Section on signed vs unsigned addressing of tiles
• Bread Docs: Memory Map - VRAM Range (0x8000-0x9FFF)
• Stack Trace of the error: Identified that the crash occurred inPPU::render_scanline()line 753viboy.py(call toself._ppu.step())

Educational Integrity

Next Steps

• [ ] Recompile C++ module and test with Tetris to verify that the Segmentation Fault is resolved
• [ ] Try with other ROMs (Mario, Pokémon) to verify that the fix is ​​general
• [ ] Continue with the implementation of Window and Sprite rendering on the C++ PPU
• [ ] Optimize performance if validations cause significant overhead