325. Cartridge 保留镜像信息

在 Cartridge 中保留已解码的名称表镜像元数据。

第 325 / 356 · tests/chapter_12_mirroring/test_325_cartridge_preserves_mirroring.py

需要更新的文件

emulator/cartridge/cartridge.py

该步骤存在的原因

第 324 步通过以下方式解码了 iNES flags 6 第 0 位

INesHeader.is_vertical_mirroring

该信息必须在解析后继续保留,以便之后的 mapper 和 PpuBus 步骤能够选择正确的名称表地址映射。

本步骤的元数据传递路径

iNES flags 6
    -> INesHeader.is_vertical_mirroring
    -> Cartridge.is_vertical_mirroring

建议的实现改动

@dataclass
class Cartridge:
    prg_rom: bytes
    chr_rom: bytes
    mapper_number: int
    chr_ram: bytearray | None = None

    # --- NEW LINE ---
    is_vertical_mirroring: bool = False
    # --- END NEW LINE ---


@classmethod
def from_ines_bytes(cls, data: bytes) -> "Cartridge":
    ines_rom = parse_ines_rom(data)

    return cls(
        prg_rom=ines_rom.prg_rom,
        chr_rom=ines_rom.chr_rom,
        mapper_number=ines_rom.header.mapper_number,

        # --- NEW LINE ---
        is_vertical_mirroring=ines_rom.header.is_vertical_mirroring,
        # --- END NEW LINE ---
    )

为什么要追加一个带默认值的字段?历史上的教程代码直接使用三个或四个位置参数来构造 Cartridge。追加一个带默认值的字段可以保留这些构造方式,同时允许已解析的 ROM 提供真实的元数据。

含义

False -> horizontal mirroring
True  -> vertical mirroring

不在本步骤范围内

修改 Mapper000
修改 MapperInterface
修改 mapper_factory
修改 PpuBus 的名称表映射
四屏镜像
卷动
商业 ROM 测试夹具

运行本课

uv run pytest tests/chapter_12_mirroring/test_325_cartridge_preserves_mirroring.py -v

示例实现

建议的实现改动

@dataclass
class Cartridge:
    prg_rom: bytes
    chr_rom: bytes
    mapper_number: int
    chr_ram: bytearray | None = None

    # --- NEW LINE ---
    is_vertical_mirroring: bool = False
    # --- END NEW LINE ---


@classmethod
def from_ines_bytes(cls, data: bytes) -> "Cartridge":
    ines_rom = parse_ines_rom(data)

    return cls(
        prg_rom=ines_rom.prg_rom,
        chr_rom=ines_rom.chr_rom,
        mapper_number=ines_rom.header.mapper_number,

        # --- NEW LINE ---
        is_vertical_mirroring=ines_rom.header.is_vertical_mirroring,
        # --- END NEW LINE ---
    )

查看测试代码test_325_cartridge_preserves_mirroring.py

from emulator.cartridge.cartridge import Cartridge
from emulator.cartridge.ines import INES_MAGIC


def make_ines_rom(
    flags_6: int,
    prg_banks: int = 1,
    chr_banks: int = 1,
) -> bytes:
    """Build a synthetic iNES ROM with valid PRG and CHR payload sizes."""
    header = bytes([
        *INES_MAGIC,
        prg_banks,
        chr_banks,
        flags_6,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
    ])
    prg_rom = bytes([0xEA] * (prg_banks * 16 * 1024))
    chr_rom = bytes([0x00] * (chr_banks * 8 * 1024))
    return header + prg_rom + chr_rom


def test_direct_cartridge_construction_defaults_to_horizontal_mirroring():
    """
    Objective:
    Existing direct constructors remain valid, and a missing mirroring argument uses
    the flags-bit-clear interpretation: horizontal.
    """
    cartridge = Cartridge(
        prg_rom=bytes([0xEA]),
        chr_rom=bytes([0x00]),
        mapper_number=0,
    )

    assert cartridge.is_vertical_mirroring is False


def test_direct_cartridge_construction_can_request_vertical_mirroring():
    """
    Objective:
    Synthetic tests and future cartridge builders can explicitly provide vertical
    mirroring metadata.
    """
    cartridge = Cartridge(
        prg_rom=bytes([0xEA]),
        chr_rom=bytes([0x00]),
        mapper_number=0,
        is_vertical_mirroring=True,
    )

    assert cartridge.is_vertical_mirroring is True


def test_old_fourth_positional_argument_still_represents_chr_ram():
    """
    Objective:
    Appending mirroring metadata must not reinterpret the historical fourth
    positional argument.
    """
    chr_ram = bytearray(8 * 1024)

    cartridge = Cartridge(
        bytes([0xEA]),
        bytes(),
        0,
        chr_ram,
    )

    assert cartridge.chr_ram is chr_ram
    assert cartridge.is_vertical_mirroring is False


def test_horizontal_ines_header_produces_horizontal_cartridge():
    """
    Objective:
    iNES flags 6 bit 0 clear should remain False after the ROM becomes a Cartridge.
    """
    cartridge = Cartridge.from_ines_bytes(
        make_ines_rom(flags_6=0b0000_0000)
    )

    assert cartridge.is_vertical_mirroring is False


def test_vertical_ines_header_produces_vertical_cartridge():
    """
    Objective:
    iNES flags 6 bit 0 set should remain True after the ROM becomes a Cartridge.
    """
    cartridge = Cartridge.from_ines_bytes(
        make_ines_rom(flags_6=0b0000_0001)
    )

    assert cartridge.is_vertical_mirroring is True


def test_mirroring_propagation_preserves_existing_cartridge_data():
    """
    Objective:
    Adding metadata must not alter PRG ROM, CHR ROM, or mapper decoding.
    """
    data = make_ines_rom(
        flags_6=0b0010_0001,
        prg_banks=1,
        chr_banks=1,
    )

    cartridge = Cartridge.from_ines_bytes(data)

    assert cartridge.mapper_number == 2
    assert len(cartridge.prg_rom) == 16 * 1024
    assert len(cartridge.chr_rom) == 8 * 1024
    assert cartridge.is_vertical_mirroring is True


def test_new_metadata_is_appended_after_historical_cartridge_fields():
    """
    Objective:
    Preserve the positional compatibility invariant without freezing Cartridge
    against additional optional metadata in later tutorial steps.
    """
    field_names = list(Cartridge.__dataclass_fields__)
    historical_prefix = [
        "prg_rom",
        "chr_rom",
        "mapper_number",
        "chr_ram",
    ]

    assert field_names[: len(historical_prefix)] == historical_prefix
    assert "is_vertical_mirroring" in field_names[len(historical_prefix):]

测试函数 (7)

test_direct_cartridge_construction_defaults_to_horizontal_mirroring
test_direct_cartridge_construction_can_request_vertical_mirroring
test_old_fourth_positional_argument_still_represents_chr_ram
test_horizontal_ines_header_produces_horizontal_cartridge
test_vertical_ines_header_produces_vertical_cartridge
test_mirroring_propagation_preserves_existing_cartridge_data
test_new_metadata_is_appended_after_historical_cartridge_fields