218. Mapper000 nrom

crea

Lección 218 de 356 · tests/chapter_02_rom_loading/test_218_mapper000_nrom.py

crea emulator/cartridge/mapper000.py::Mapper000.read_prg para el mapeo de CPU de NROM.

Por qué existe este paso

NROM-128 refleja (mirror) un único banco de 16 KiB en $8000-$FFFF; NROM-256 mapea 32 KiB directamente. Mantener esta traducción en el mapper evita que Cartridge se convierta en comportamiento de hardware. Utiliza las cargas útiles de PRG y CHR expuestas en la lección 217.

Implementación sugerida en el límite de esta lección

from dataclasses import dataclass

PRG_ROM_START = 0x8000
PRG_ROM_END = 0xFFFF
NROM_128_SIZE = 16 * 1024
NROM_256_SIZE = 32 * 1024
CHR_ROM_SIZE = 8 * 1024


@dataclass(frozen=True)
class Mapper000:
    prg_rom: bytes
    chr_rom: bytes

    def read_prg(self, addr: int) -> int:
        if not (PRG_ROM_START <= addr <= PRG_ROM_END):
            raise ValueError(
                f"Address out of PRG ROM range: {addr:04X}"
            )
        if len(self.prg_rom) == NROM_128_SIZE:
            offset = (addr - PRG_ROM_START) % NROM_128_SIZE
        elif len(self.prg_rom) == NROM_256_SIZE:
            offset = addr - PRG_ROM_START
        else:
            raise ValueError(
                "Mapper000 supports only 16KB or 32KB PRG ROM"
            )
        return self.prg_rom[offset]

Invariantes: acepta solo direcciones de CPU $8000-$FFFF y exactamente 16 o 32 KiB de PRG; refleja solo en el caso de 16 KiB; conserva el orden del constructor de PRG/CHR. Un error común es indexar prg_rom directamente con la dirección de la CPU o implementar la traducción en Cartridge. read_chr, el enrutamiento hacia la PPU, la CHR RAM, las escrituras, el reflejo (mirroring) y el cambio de bancos quedan fuera de alcance para este paso.

Fuera de alcance para este paso

1. Lesson 219 adds `read_chr` for the PPU-side CHR range.
2. Lesson 220 adds mapper selection.
3. PPU routing, CHR RAM, writes, mirroring, and bank switching come later.

Ejecutar esta lección

uv run pytest tests/chapter_02_rom_loading/test_218_mapper000_nrom.py -v

Implementación de ejemplo

Implementación sugerida en el límite de esta lección

from dataclasses import dataclass

PRG_ROM_START = 0x8000
PRG_ROM_END = 0xFFFF
NROM_128_SIZE = 16 * 1024
NROM_256_SIZE = 32 * 1024
CHR_ROM_SIZE = 8 * 1024


@dataclass(frozen=True)
class Mapper000:
    prg_rom: bytes
    chr_rom: bytes

    def read_prg(self, addr: int) -> int:
        if not (PRG_ROM_START <= addr <= PRG_ROM_END):
            raise ValueError(
                f"Address out of PRG ROM range: {addr:04X}"
            )
        if len(self.prg_rom) == NROM_128_SIZE:
            offset = (addr - PRG_ROM_START) % NROM_128_SIZE
        elif len(self.prg_rom) == NROM_256_SIZE:
            offset = addr - PRG_ROM_START
        else:
            raise ValueError(
                "Mapper000 supports only 16KB or 32KB PRG ROM"
            )
        return self.prg_rom[offset]

Ver código del testtest_218_mapper000_nrom.py

import dataclasses
from pathlib import Path

import pytest

from emulator.cartridge.mapper000 import (
    CHR_ROM_SIZE,
    Mapper000,
    NROM_128_SIZE,
    NROM_256_SIZE,
    PRG_ROM_END,
    PRG_ROM_START,
)


def make_mapper(prg_rom: bytes) -> Mapper000:
    """Create Mapper000 with placeholder CHR ROM for PRG-focused tests."""
    chr_rom = bytes([0x00]) * CHR_ROM_SIZE
    return Mapper000(prg_rom=prg_rom, chr_rom=chr_rom)


def test_mapper000_file_and_constants_exist():
    """
    Step 1: define Mapper000 constants.

    Required constants:
        PRG_ROM_START = 0x8000
            First CPU address where cartridge PRG ROM is visible.

        PRG_ROM_END = 0xFFFF
            Last CPU address in the PRG ROM area.

        NROM_128_SIZE = 16 * 1024
            16KB PRG ROM case. This must be mirrored into $C000-$FFFF.

        NROM_256_SIZE = 32 * 1024
            32KB PRG ROM case. This maps directly across $8000-$FFFF.

    Why constants:
    Mapper code is address-heavy. Constants keep the mapping rules readable and
    prevent magic numbers from hiding the hardware model.
    """
    assert Path("emulator/cartridge/mapper000.py").exists()
    assert PRG_ROM_START == 0x8000
    assert PRG_ROM_END == 0xFFFF
    assert NROM_128_SIZE == 16 * 1024
    assert NROM_256_SIZE == 32 * 1024


def test_mapper000_class_exists_and_stores_prg_and_chr_rom():
    """
    Step 2: define Mapper000.

    Mapper000 should store PRG ROM and CHR ROM bytes.

    At this tutorial step, read_prg is the only behavior we need because the CPU
    bus will eventually ask the mapper how to read addresses $8000-$FFFF.

    CHR ROM is included now because the next test will add read_chr(addr) for
    future PPU pattern-table reads.

    Later tutorial steps may append optional mapper metadata while preserving these
    original fields and their constructor order.
    """
    assert dataclasses.is_dataclass(Mapper000)
    original_fields = ["prg_rom", "chr_rom"]
    field_names = list(Mapper000.__dataclass_fields__)

    assert field_names[: len(original_fields)] == original_fields
    assert hasattr(Mapper000, "read_prg")
    assert callable(Mapper000.read_prg)


def test_mapper000_16kb_prg_reads_lower_bank():
    """
    Objective:
    With 16KB PRG ROM, $8000 maps to PRG offset $0000.
    """
    prg_rom = bytes([0xAA]) + bytes([0x00]) * (NROM_128_SIZE - 1)
    mapper = make_mapper(prg_rom)

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


def test_mapper000_16kb_prg_mirrors_upper_bank():
    """
    Objective:
    With 16KB PRG ROM, $C000-$FFFF mirrors $8000-$BFFF.

    That means:
        $8000 and $C000 both map to PRG offset $0000.
    """
    prg_rom = bytes([0xAA]) + bytes([0x00]) * (NROM_128_SIZE - 1)
    mapper = make_mapper(prg_rom)

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


def test_mapper000_16kb_prg_reads_last_mirrored_byte():
    """
    Objective:
    With 16KB PRG ROM, $FFFF maps to PRG offset $3FFF.
    """
    prg_rom = bytes([0x00]) * (NROM_128_SIZE - 1) + bytes([0xEF])
    mapper = make_mapper(prg_rom)

    assert mapper.read_prg(0xBFFF) == 0xEF
    assert mapper.read_prg(0xFFFF) == 0xEF


def test_mapper000_32kb_prg_maps_directly():
    """
    Objective:
    With 32KB PRG ROM, $8000-$FFFF maps directly to offsets $0000-$7FFF.
    """
    prg_rom = bytearray(NROM_256_SIZE)
    prg_rom[0x0000] = 0x11
    prg_rom[0x4000] = 0x22
    prg_rom[0x7FFF] = 0x33
    mapper = make_mapper(bytes(prg_rom))

    assert mapper.read_prg(0x8000) == 0x11
    assert mapper.read_prg(0xC000) == 0x22
    assert mapper.read_prg(0xFFFF) == 0x33


def test_mapper000_rejects_addresses_outside_prg_rom_range():
    """
    Objective:
    Mapper000 should only answer CPU PRG ROM reads in $8000-$FFFF.
    """
    mapper = make_mapper(bytes([0x00]) * NROM_128_SIZE)

    with pytest.raises(ValueError, match="Address out of PRG ROM range"):
        mapper.read_prg(0x7FFF)


def test_mapper000_rejects_unsupported_prg_rom_size():
    """
    Objective:
    Mapper000 supports only NROM-128 and NROM-256 PRG sizes.
    """
    mapper = make_mapper(bytes([0x00]) * 123)

    with pytest.raises(ValueError, match="Mapper000 supports only 16KB or 32KB PRG ROM"):
        mapper.read_prg(0x8000)

Funciones de test (8)

test_mapper000_file_and_constants_exist
test_mapper000_class_exists_and_stores_prg_and_chr_rom
test_mapper000_16kb_prg_reads_lower_bank
test_mapper000_16kb_prg_mirrors_upper_bank
test_mapper000_16kb_prg_reads_last_mirrored_byte
test_mapper000_32kb_prg_maps_directly
test_mapper000_rejects_addresses_outside_prg_rom_range
test_mapper000_rejects_unsupported_prg_rom_size