254. Enrutamiento de escritura de CHR en el mapper

Implementa el enrutamiento de escrituras de CHR a través del mapper.

Lección 254 de 356 · tests/chapter_03_ppu_memory_and_graphics_data/test_254_mapper_chr_write_routing.py

Referencia

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

Archivos a modificar

emulator/cartridge/mapper_interface.py
emulator/cartridge/mapper000.py
emulator/bus/ppu_bus.py

¿Qué es la memoria CHR? La memoria CHR es de donde la PPU lee los bytes de patrón de tile. El rango de direcciones de la PPU $0000-$1FFF es el área de CHR.

Ejemplo simple

PPU reads $0000
mapper returns the first byte of CHR ROM

Para el Mapper000/NROM oficial en este tutorial, la CHR es ROM, por lo que las escrituras se rechazan.

Por qué existe este paso

PpuBus solo debería enrutar direcciones. No debería decidir si las escrituras de CHR son legales. Esa política pertenece al mapper.

Reparto correcto de responsabilidades

PpuBus.write($0000-$1FFF, value)
    -> mapper.write_chr(addr, value)

Mapper000.write_chr(addr, value)
    -> rejects writes because official Mapper000 CHR ROM is read-only

Ejemplo de implementación sugerida

class MapperInterface(Protocol):
    def read_prg(self, addr: int) -> int:
        ...

    def read_chr(self, addr: int) -> int:
        ...

    def write_chr(self, addr: int, value: int) -> None:
        ...

class Mapper000:
    def write_chr(self, addr: int, value: int) -> None:
        if not (CHR_ROM_START <= addr <= CHR_ROM_END):
            raise ValueError(f"Address out of CHR ROM range: {addr:04X}")

        raise ValueError("CHR ROM is read-only for official Mapper000")

class PpuBus:
    def write(self, addr: int, value: int) -> None:
        addr = addr & PPU_ADDRESS_MASK

        if CHR_START <= addr <= CHR_END:
            if self.mapper is not None:
                self.mapper.write_chr(addr, value)
                return

            self.vram.write(addr, value)
            return

Fuera de alcance

soporte de CHR RAM
variantes no oficiales/homebrew del Mapper000 con CHR RAM escribible
conmutación de bancos del mapper
renderizado de tiles de CHR

Ejecutar esta lección

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

Implementación de ejemplo

Ejemplo de implementación sugerida

class MapperInterface(Protocol):
    def read_prg(self, addr: int) -> int:
        ...

    def read_chr(self, addr: int) -> int:
        ...

    def write_chr(self, addr: int, value: int) -> None:
        ...

class Mapper000:
    def write_chr(self, addr: int, value: int) -> None:
        if not (CHR_ROM_START <= addr <= CHR_ROM_END):
            raise ValueError(f"Address out of CHR ROM range: {addr:04X}")

        raise ValueError("CHR ROM is read-only for official Mapper000")

class PpuBus:
    def write(self, addr: int, value: int) -> None:
        addr = addr & PPU_ADDRESS_MASK

        if CHR_START <= addr <= CHR_END:
            if self.mapper is not None:
                self.mapper.write_chr(addr, value)
                return

            self.vram.write(addr, value)
            return

Ver código del testtest_254_mapper_chr_write_routing.py

import pytest

from emulator.bus.ppu_bus import PpuBus
from emulator.cartridge.mapper000 import CHR_ROM_SIZE, Mapper000


class FakeMapperForChrWrites:
    """Small test double that records CHR write calls from PpuBus."""

    def __init__(self):
        self.write_chr_calls = []

    def read_prg(self, addr: int) -> int:
        raise AssertionError("read_prg is not used by this test")

    def read_chr(self, addr: int) -> int:
        raise AssertionError("read_chr is not used by this test")

    def write_chr(self, addr: int, value: int) -> None:
        self.write_chr_calls.append((addr, value))


def make_mapper000() -> Mapper000:
    """Create a minimal official Mapper000-style mapper with 8KB CHR ROM."""
    return Mapper000(
        prg_rom=bytes([0xEA]) * (16 * 1024),
        chr_rom=bytes([0x00]) * CHR_ROM_SIZE,
    )


def test_mapper_interface_requires_write_chr_method():
    """
    Objective:
    Mappers expose a write_chr method so PpuBus can delegate CHR writes.
    """
    mapper = make_mapper000()

    assert hasattr(mapper, "write_chr")
    assert callable(mapper.write_chr)


def test_mapper000_rejects_chr_rom_writes_inside_valid_chr_range():
    """
    Objective:
    Official Mapper000/NROM uses CHR ROM in this tutorial, so valid CHR writes are
    rejected as read-only.
    """
    mapper = make_mapper000()

    with pytest.raises(ValueError, match="CHR ROM is read-only"):
        mapper.write_chr(0x0000, 0x12)


def test_mapper000_rejects_chr_writes_outside_chr_range_with_range_error():
    """
    Objective:
    Mapper000 should still validate the CHR address range before applying its
    read-only policy.
    """
    mapper = make_mapper000()

    with pytest.raises(ValueError, match="Address out of CHR ROM range"):
        mapper.write_chr(0x2000, 0x12)


def test_ppu_bus_delegates_chr_writes_to_mapper_when_mapper_exists():
    """
    Objective:
    PpuBus should route CHR writes to mapper.write_chr instead of deciding CHR
    write legality itself.
    """
    mapper = FakeMapperForChrWrites()
    bus = PpuBus(mapper=mapper)

    bus.write(0x0007, 0xAB)

    assert mapper.write_chr_calls == [(0x0007, 0xAB)]


def test_ppu_bus_masks_chr_write_address_before_delegating_to_mapper():
    """
    Objective:
    PpuBus owns 14-bit PPU address normalization before routing the access.

    Example:
        $4007 masked by $3FFF becomes $0007
    """
    mapper = FakeMapperForChrWrites()
    bus = PpuBus(mapper=mapper)

    bus.write(0x4007, 0xCD)

    assert mapper.write_chr_calls == [(0x0007, 0xCD)]


def test_ppu_bus_without_mapper_still_allows_local_chr_vram_write():
    """
    Objective:
    Keep the early no-cartridge tutorial path working: without a mapper, CHR-area
    writes still use the local PpuBus VRAM backing.
    """
    bus = PpuBus(mapper=None)

    bus.write(0x0000, 0xEF)

    assert bus.read(0x0000) == 0xEF

Funciones de test (6)

test_mapper_interface_requires_write_chr_method
test_mapper000_rejects_chr_rom_writes_inside_valid_chr_range
test_mapper000_rejects_chr_writes_outside_chr_range_with_range_error
test_ppu_bus_delegates_chr_writes_to_mapper_when_mapper_exists
test_ppu_bus_masks_chr_write_address_before_delegating_to_mapper
test_ppu_bus_without_mapper_still_allows_local_chr_vram_write