263. Enrutamiento de escritura PRG en el bus de la CPU

Enrutar escrituras en el espacio PRG de la CPU a través del mapper antes de las pruebas de NMI de la CPU.

Lección 263 de 356 · tests/chapter_04_ppu_timing_and_vblank/test_263_cpu_bus_prg_write_routing.py

Archivos a actualizar

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

Por qué existe este paso

La siguiente prueba de interrupción de la CPU necesitará colocar los bytes del vector NMI en

$FFFA = NMI vector low byte
$FFFB = NMI vector high byte

Esas direcciones se encuentran dentro del área PRG de la CPU

$8000-$FFFF

Antes de probar CPU.interrupt_nmi(), necesitamos que el comportamiento de escritura del bus de la CPU en ese rango sea explícito y seguro.

¿Qué es el enrutamiento de escritura PRG? El enrutamiento de escritura PRG significa que CpuBus no modifica directamente los bytes de la ROM del cartucho. En su lugar, las escrituras en $8000-$FFFF se reenvían al mapper del cartucho:

CpuBus.write($8000-$FFFF, value)
    -> mapper.write_prg(addr, value)

Ejemplo mínimo

CPU writes $8000 = $12
CpuBus calls mapper.write_prg($8000, $12)
Mapper000/NROM ignores it because it has no PRG write registers
Later mappers may treat the same write as a bank-switch command

Concepto erróneo común

Escribir en $8000 no significa que la CPU cambie bytes de la ROM. En cartuchos reales, las escrituras en este rango normalmente son ignoradas por placas simples o interpretadas como señales de control del mapper por placas más avanzadas.

Separación importante

Real cartridge path:
    CpuBus.write($8000-$FFFF) -> mapper.write_prg(...)

Tutorial FakeROM path:
    CpuBus.write($8000-$FFFF) -> FakeROM.write(addr - $8000, value)

La ruta FakeROM es solo una conveniencia para la configuración de pruebas. Permite que las próximas pruebas de interrupciones instalen bytes de vector en $FFFA/$FFFB sin hacer que la PRG ROM real de Mapper000 sea escribible.

Ejemplos de implementación sugeridos

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

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

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

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

class Mapper000:
    def write_prg(self, addr: int, value: int) -> None:
        if not (PRG_ROM_START <= addr <= PRG_ROM_END):
            raise ValueError(f"Address out of PRG ROM range: {addr:04X}")

        # Mapper000/NROM has no writable PRG registers.
        # Real hardware ignores writes to PRG ROM space, so we ignore them too.
        return

class CpuBus:
    def write(self, addr: int, value: int) -> None:
        ...

        if 0x8000 <= addr <= 0xFFFF:
            if self.mapper is not None:
                self.mapper.write_prg(addr, value)
                return

            if self.program_rom is not None:
                self.program_rom.write(addr - 0x8000, value)
                return

        raise ValueError(f"Unsupported CPU bus write: {addr:04X}")

Fuera de alcance

Comportamiento de CPU.interrupt_nmi()
Consumo de la solicitud NMI de la PPU por la CPU
Conmutación de bancos Mapper001/MMC
Hacer que la PRG ROM real sea escribible

Ejecutar esta lección

uv run pytest tests/chapter_04_ppu_timing_and_vblank/test_263_cpu_bus_prg_write_routing.py -v

Implementación de ejemplo

Ejemplos de implementación sugeridos

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

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

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

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

class Mapper000:
    def write_prg(self, addr: int, value: int) -> None:
        if not (PRG_ROM_START <= addr <= PRG_ROM_END):
            raise ValueError(f"Address out of PRG ROM range: {addr:04X}")

        # Mapper000/NROM has no writable PRG registers.
        # Real hardware ignores writes to PRG ROM space, so we ignore them too.
        return

class CpuBus:
    def write(self, addr: int, value: int) -> None:
        ...

        if 0x8000 <= addr <= 0xFFFF:
            if self.mapper is not None:
                self.mapper.write_prg(addr, value)
                return

            if self.program_rom is not None:
                self.program_rom.write(addr - 0x8000, value)
                return

        raise ValueError(f"Unsupported CPU bus write: {addr:04X}")

Ver código del testtest_263_cpu_bus_prg_write_routing.py

from emulator.bus.cpu_bus import CpuBus
from emulator.cartridge.mapper000 import (
    CHR_ROM_SIZE,
    Mapper000,
    NROM_128_SIZE,
    NROM_256_SIZE,
)
from emulator.cartridge.mapper_interface import MapperInterface
from emulator.memory.fake_rom import FakeROM


class FakeMapperForPrgWrites:
    """Small test double that records PRG write calls from CpuBus."""

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

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

    def write_prg(self, addr: int, value: int) -> None:
        self.write_prg_calls.append((addr, value))

    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:
        raise AssertionError("write_chr is not used by this test")


def make_mapper000(prg_rom: bytes | None = None) -> Mapper000:
    """Create a minimal official Mapper000-style mapper."""
    if prg_rom is None:
        prg_rom = bytes([0xEA]) * NROM_256_SIZE

    return Mapper000(
        prg_rom=prg_rom,
        chr_rom=bytes([0x00]) * CHR_ROM_SIZE,
    )


def test_mapper_interface_requires_write_prg_method():
    """
    Objective:
    Mappers expose write_prg so CpuBus can delegate writes in $8000-$FFFF.
    """
    assert hasattr(MapperInterface, "write_prg")

    mapper = make_mapper000()

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


def test_mapper000_ignores_valid_prg_writes_without_changing_prg_data():
    """
    Objective:
    Official Mapper000/NROM has PRG ROM, not PRG RAM or PRG write registers.
    Valid writes in $8000-$FFFF are ignored for real-ROM compatibility.

    Example:
        STA $8000 should not mutate the byte returned by read_prg($8000).
    """
    prg_rom = bytes([0xAA]) + bytes([0x00]) * (NROM_256_SIZE - 1)
    mapper = make_mapper000(prg_rom=prg_rom)

    before = mapper.read_prg(0x8000)

    mapper.write_prg(0x8000, 0x12)

    after = mapper.read_prg(0x8000)
    assert before == 0xAA
    assert after == 0xAA


def test_mapper000_valid_prg_write_to_mirrored_16kb_rom_is_also_ignored():
    """
    Objective:
    The ignore rule applies to the whole PRG address range, including the mirrored
    upper bank in NROM-128.

    Example:
        With 16KB PRG ROM, $C000 mirrors $8000. A write to $C000 still must not
        mutate the underlying PRG ROM byte.
    """
    prg_rom = bytes([0x55]) + bytes([0x00]) * (NROM_128_SIZE - 1)
    mapper = make_mapper000(prg_rom=prg_rom)

    mapper.write_prg(0xC000, 0x99)

    assert mapper.read_prg(0x8000) == 0x55
    assert mapper.read_prg(0xC000) == 0x55


def test_mapper000_rejects_prg_writes_outside_prg_range_with_range_error():
    """
    Objective:
    Mapper000 ignores valid PRG-space writes, but it should still reject addresses
    outside $8000-$FFFF because those addresses do not belong to Mapper000 PRG.
    """
    mapper = make_mapper000()

    try:
        mapper.write_prg(0x7FFF, 0x12)
    except ValueError as error:
        assert "Address out of PRG ROM range" in str(error)
    else:
        raise AssertionError("Expected Mapper000.write_prg to reject address $7FFF")


def test_cpu_bus_delegates_prg_space_writes_to_mapper_when_mapper_exists():
    """
    Objective:
    CpuBus should route $8000-$FFFF writes to mapper.write_prg when a mapper is
    attached.

    This keeps future mapper behavior possible:
        Mapper000: ignore valid PRG writes
        MMC1/MMC3: use PRG writes as bank-switch or IRQ control signals
    """
    mapper = FakeMapperForPrgWrites()
    bus = CpuBus()
    bus.mapper = mapper

    bus.write(0x8000, 0x12)
    bus.write(0xFFFA, 0x34)
    bus.write(0xFFFF, 0x56)

    assert mapper.write_prg_calls == [
        (0x8000, 0x12),
        (0xFFFA, 0x34),
        (0xFFFF, 0x56),
    ]


def test_cpu_bus_fake_rom_path_can_prepare_nmi_vector_bytes():
    """
    Objective:
    In the tutorial FakeROM path, CpuBus.write can prepare bytes in $8000-$FFFF.
    This is needed before CPU.interrupt_nmi() tests.

    Example:
        CPU interrupt code reads the NMI vector from $FFFA/$FFFB.
        This test setup writes those vector bytes through CpuBus using FakeROM.

    Address translation:
        $FFFA on CPU bus -> FakeROM offset $7FFA
        $FFFB on CPU bus -> FakeROM offset $7FFB
    """
    rom = FakeROM()
    bus = CpuBus(program_rom=rom)

    bus.write(0xFFFA, 0x34)
    bus.write(0xFFFB, 0x12)

    assert bus.read(0xFFFA) == 0x34
    assert bus.read(0xFFFB) == 0x12
    assert rom.read(0x7FFA) == 0x34
    assert rom.read(0x7FFB) == 0x12


def test_cpu_bus_uses_mapper_in_preference_to_fake_rom_when_mapper_exists():
    """
    Objective:
    If a mapper is attached, PRG-space writes belong to the mapper path. This
    protects real cartridge behavior from accidentally becoming FakeROM behavior.
    """
    rom = FakeROM()
    mapper = FakeMapperForPrgWrites()
    bus = CpuBus(program_rom=rom)
    bus.mapper = mapper

    bus.write(0x8000, 0xAB)

    assert mapper.write_prg_calls == [(0x8000, 0xAB)]
    assert rom.read(0x0000) == 0x00

Funciones de test (7)

test_mapper_interface_requires_write_prg_method
test_mapper000_ignores_valid_prg_writes_without_changing_prg_data
test_mapper000_valid_prg_write_to_mirrored_16kb_rom_is_also_ignored
test_mapper000_rejects_prg_writes_outside_prg_range_with_range_error
test_cpu_bus_delegates_prg_space_writes_to_mapper_when_mapper_exists
test_cpu_bus_fake_rom_path_can_prepare_nmi_vector_bytes
test_cpu_bus_uses_mapper_in_preference_to_fake_rom_when_mapper_exists