218. Mapper000 NROM

创建

第 218 / 356 · tests/chapter_02_rom_loading/test_218_mapper000_nrom.py

创建 emulator/cartridge/mapper000.py::Mapper000.read_prg，用于 NROM 的 CPU 地址映射。

此步骤存在的原因

NROM-128 将一个 16 KiB 存储体镜像到 $8000-$FFFF；NROM-256 则直接映射 32 KiB。把这种转换保留在映射器中，可以避免 Cartridge 变成硬件行为的载体。它使用了第 217 课暴露出的 PRG 和 CHR 负载。

在此课程边界下的建议实现

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]

不变量：只接受 CPU 地址 $8000-$FFFF，且 PRG 必须恰好是 16 或 32 KiB；仅在 16 KiB 情形下做镜像；保持 PRG/CHR 构造函数参数顺序不变。一个常见错误是直接用 CPU 地址索引 prg_rom，或者把这种转换实现在 Cartridge 上。read_chr、PPU 路由、CHR RAM、写入、镜像方式以及存储体切换均不在此步骤范围内。

此步骤范围之外

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.

运行本课

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

示例实现

在此课程边界下的建议实现

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]

查看测试代码test_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)

测试函数 (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