253. PPU 总线的名称表 VRAM 地址映射

实现 PpuBus 的名称表 VRAM 地址映射。

第 253 / 356 · tests/chapter_03_ppu_memory_and_graphics_data/test_253_ppu_bus_nametable_vram_mapping.py

参考资料

https://www.nesdev.org/wiki/PPU_memory_map
https://www.nesdev.org/wiki/PPU_nametables

需要更新的文件

emulator/bus/ppu_bus.py

需要添加的常量

NAMETABLE_START = 0x2000
NAMETABLE_END = 0x3EFF
NAMETABLE_SIZE = 0x0800

什么是名称表?名称表是背景布局内存。它不存储像素,而是存储图块编号,告诉 PPU 在背景的每个位置要绘制哪个 CHR 图块。

简单示例

PPU memory $2000 contains $24

含义

the top-left background cell uses CHR tile index $24

PPU 暴露出四个逻辑上的 1KB 名称表区域

$2000-$23FF
$2400-$27FF
$2800-$2BFF
$2C00-$2FFF

$3000-$3EFF 范围镜像了 $2000-$2EFF。

教程简化

目前先使用现有的大型 VRAM 后备存储,将名称表地址归一化到一个简单的 2KB 窗口内。暂时不要创建独立的名称表 RAM 对象。

建议的实现示例

NAMETABLE_START = 0x2000
NAMETABLE_END = 0x3EFF
NAMETABLE_SIZE = 0x0800

def normalize_nametable_addr(self, addr: int) -> int:
    if 0x3000 <= addr <= 0x3EFF:
        addr -= 0x1000

    index = (addr - NAMETABLE_START) % NAMETABLE_SIZE
    return NAMETABLE_START + index

def read(self, addr: int) -> int:
    addr = addr & PPU_ADDRESS_MASK

    if CHR_START <= addr <= CHR_END:
        ...

    if NAMETABLE_START <= addr <= NAMETABLE_END:
        return self.vram.read(self.normalize_nametable_addr(addr))

    if PALETTE_START <= addr <= PALETTE_END:
        ...

    return self.vram.read(addr)

不在本步骤范围内

卡带的水平/垂直镜像
四屏镜像
属性表的解读
渲染
把名称表存储从大型 VRAM 后备中分离出去

运行本课

uv run pytest tests/chapter_03_ppu_memory_and_graphics_data/test_253_ppu_bus_nametable_vram_mapping.py -v

示例实现

需要添加的常量

NAMETABLE_START = 0x2000
NAMETABLE_END = 0x3EFF
NAMETABLE_SIZE = 0x0800

建议的实现示例

NAMETABLE_START = 0x2000
NAMETABLE_END = 0x3EFF
NAMETABLE_SIZE = 0x0800

def normalize_nametable_addr(self, addr: int) -> int:
    if 0x3000 <= addr <= 0x3EFF:
        addr -= 0x1000

    index = (addr - NAMETABLE_START) % NAMETABLE_SIZE
    return NAMETABLE_START + index

def read(self, addr: int) -> int:
    addr = addr & PPU_ADDRESS_MASK

    if CHR_START <= addr <= CHR_END:
        ...

    if NAMETABLE_START <= addr <= NAMETABLE_END:
        return self.vram.read(self.normalize_nametable_addr(addr))

    if PALETTE_START <= addr <= PALETTE_END:
        ...

    return self.vram.read(addr)

查看测试代码test_253_ppu_bus_nametable_vram_mapping.py

from emulator.bus.ppu_bus import NAMETABLE_END, NAMETABLE_SIZE, NAMETABLE_START, PpuBus


def test_ppu_bus_declares_nametable_mapping_constants():
    """
    Objective:
    Name the PPU nametable range and the current 2KB backing window size.
    """
    assert NAMETABLE_START == 0x2000
    assert NAMETABLE_END == 0x3EFF
    assert NAMETABLE_SIZE == 0x0800


def test_ppu_bus_can_read_back_direct_nametable_address_write():
    """
    Objective:
    The first nametable address should be readable and writable through PpuBus.
    """
    bus = PpuBus()

    bus.write(0x2000, 0x24)

    assert bus.read(0x2000) == 0x24


def test_second_2kb_nametable_area_wraps_to_current_backing_window():
    """
    Objective:
    In this simplified 2KB model, $2800 wraps to $2000.

    This is not final cartridge mirroring behavior. It is the current tutorial
    model for keeping nametable storage inside the large VRAM backing.
    """
    bus = PpuBus()

    bus.write(0x2800, 0x55)

    assert bus.read(0x2000) == 0x55
    assert bus.read(0x2800) == 0x55


def test_end_of_logical_nametable_range_wraps_inside_2kb_window():
    """
    Objective:
    $2FFF maps to the last byte of the current 2KB nametable window: $27FF.
    """
    bus = PpuBus()

    bus.write(0x2FFF, 0x66)

    assert bus.read(0x27FF) == 0x66
    assert bus.read(0x2FFF) == 0x66


def test_3000_nametable_mirror_maps_to_2000():
    """
    Objective:
    $3000-$3EFF mirrors $2000-$2EFF. The first mirror address maps to $2000.
    """
    bus = PpuBus()

    bus.write(0x3000, 0x77)

    assert bus.read(0x2000) == 0x77
    assert bus.read(0x3000) == 0x77


def test_last_nametable_mirror_address_maps_through_2kb_window():
    """
    Objective:
    $3EFF first mirrors to $2EFF, then the current 2KB model maps that to $26FF.
    """
    bus = PpuBus()

    bus.write(0x3EFF, 0x88)

    assert bus.read(0x26FF) == 0x88
    assert bus.read(0x3EFF) == 0x88


def test_palette_range_remains_separate_from_nametable_range():
    """
    Objective:
    $3F00 is palette memory, not a nametable mirror.

    This protects the route order:
        CHR -> nametable -> palette
    """
    bus = PpuBus()

    bus.write(0x3000, 0x11)
    bus.write(0x3F00, 0x22)

    assert bus.read(0x2000) == 0x11
    assert bus.read(0x3F00) == 0x22

测试函数 (7)

test_ppu_bus_declares_nametable_mapping_constants
test_ppu_bus_can_read_back_direct_nametable_address_write
test_second_2kb_nametable_area_wraps_to_current_backing_window
test_end_of_logical_nametable_range_wraps_inside_2kb_window
test_3000_nametable_mirror_maps_to_2000
test_last_nametable_mirror_address_maps_through_2kb_window
test_palette_range_remains_separate_from_nametable_range