220. Фабрика mapper

Создайте фабрику mapper.

Урок 220 из 356 · tests/chapter_02_rom_loading/test_220_mapper_factory.py

Файл для создания

emulator/cartridge/mapper_factory.py

Функция для реализации

create_mapper(cartridge: Cartridge)

Зачем нужен этот шаг

Объект Cartridge хранит факты, загруженные из ROM

Cartridge(prg_rom, chr_rom, mapper_number)

Но CPU/PPU не обращаются напрямую к сырым байтам PRG/CHR. Они обращаются через mapper, потому что mapper — это аппаратура картриджа, транслирующая адреса эмулятора в смещения ROM.

Текущий поток

raw .nes bytes
    -> Cartridge.from_ines_bytes(data)
    -> create_mapper(cartridge)
    -> Mapper000(prg_rom, chr_rom)

Обязанности фабрики

проверять cartridge.mapper_number
создавать правильный объект mapper
явно завершаться с ошибкой для неподдерживаемых mapper

Чего фабрика НЕ должна делать

разбирать байты iNES
выполнять трансляцию адресов CPU
знать о маршрутизации CpuBus
изменять Cartridge

Ожидаемая форма реализации

from emulator.cartridge.cartridge import Cartridge
from emulator.cartridge.mapper000 import Mapper000


def create_mapper(cartridge: Cartridge):
    if cartridge.mapper_number == 0:
        return Mapper000(
            prg_rom=cartridge.prg_rom,
            chr_rom=cartridge.chr_rom,
        )

    raise ValueError(f"Unsupported mapper: {cartridge.mapper_number}")

Почему это отделено от CpuBus

CpuBus должна маршрутизировать чтения и записи. Она не должна становиться ответственной за каждое правило выбора mapper картриджа. Хранение создания mapper здесь снижает связанность до того, как мы интегрируем поддерживаемые картриджем чтения PRG ROM в шину.

Запустить этот урок

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

Пример реализации

Ожидаемая форма реализации

from emulator.cartridge.cartridge import Cartridge
from emulator.cartridge.mapper000 import Mapper000


def create_mapper(cartridge: Cartridge):
    if cartridge.mapper_number == 0:
        return Mapper000(
            prg_rom=cartridge.prg_rom,
            chr_rom=cartridge.chr_rom,
        )

    raise ValueError(f"Unsupported mapper: {cartridge.mapper_number}")

Показать код тестаtest_220_mapper_factory.py

from pathlib import Path

import pytest

from emulator.cartridge.cartridge import Cartridge
from emulator.cartridge.mapper000 import CHR_ROM_SIZE, Mapper000, NROM_128_SIZE
from emulator.cartridge.mapper_factory import create_mapper


def test_mapper_factory_file_exists():
    """
    Objective:
    Create emulator/cartridge/mapper_factory.py.

    Why:
    Mapper construction is a small policy decision: mapper number 0 means
    Mapper000, mapper number 1 will later mean something else, and so on.
    """
    assert Path("emulator/cartridge/mapper_factory.py").exists()


def test_create_mapper_exists_and_is_callable():
    """
    Objective:
    Expose create_mapper(cartridge).

    The caller should not need to know which concrete mapper class corresponds
    to each mapper number.
    """
    assert callable(create_mapper)


def test_create_mapper_returns_mapper000_for_mapper_number_zero():
    """
    Objective:
    Mapper number 0 should create Mapper000 / NROM.

    This is the simplest NES cartridge mapping and the only mapper supported at
    this tutorial stage.
    """
    cartridge = Cartridge(
        prg_rom=bytes([0xEA]) * NROM_128_SIZE,
        chr_rom=bytes([0x00]) * CHR_ROM_SIZE,
        mapper_number=0,
    )

    mapper = create_mapper(cartridge)

    assert isinstance(mapper, Mapper000)


def test_create_mapper_preserves_prg_and_chr_rom_data():
    """
    Objective:
    The factory must pass both PRG ROM and CHR ROM into Mapper000 unchanged.

    Why this matters:
    PRG ROM will be used by CPU bus reads in $8000-$FFFF.
    CHR ROM will be used later by PPU pattern-table reads in $0000-$1FFF.
    """
    prg_rom = bytes([0xA9]) * NROM_128_SIZE
    chr_rom = bytes([0xBB]) * CHR_ROM_SIZE
    cartridge = Cartridge(
        prg_rom=prg_rom,
        chr_rom=chr_rom,
        mapper_number=0,
    )

    mapper = create_mapper(cartridge)

    assert mapper.prg_rom == prg_rom
    assert mapper.chr_rom == chr_rom


def test_create_mapper_rejects_unsupported_mapper_number():
    """
    Objective:
    Unsupported mappers should fail loudly.

    Why:
    If the emulator silently treats an unsupported mapper as Mapper000, games may
    run with incorrect memory mapping. That kind of bug is hard to debug because
    the CPU may execute plausible but wrong bytes.
    """
    cartridge = Cartridge(
        prg_rom=bytes([0x00]) * NROM_128_SIZE,
        chr_rom=bytes([0x00]) * CHR_ROM_SIZE,
        mapper_number=1,
    )

    with pytest.raises(ValueError, match="Unsupported mapper: 1"):
        create_mapper(cartridge)

Тестовые функции (5)

test_mapper_factory_file_exists
test_create_mapper_exists_and_is_callable
test_create_mapper_returns_mapper000_for_mapper_number_zero
test_create_mapper_preserves_prg_and_chr_rom_data
test_create_mapper_rejects_unsupported_mapper_number