216. 解析 iNES ROM

添加

第 216 / 356 · tests/chapter_02_rom_loading/test_216_parse_ines_rom.py

添加 emulator/cartridge/ines.py::parse_ines_rom。

此步骤存在的原因

该函数把文件头中的声明转化为干净的 PRG/CHR 切片，使后续的 Cartridge 与映射器代码无需理解 iNES 文件头或训练器偏移量。它用到了第 212-215 课的全部格式常量和解析器模型。

建议实现

def parse_ines_rom(data: bytes) -> INesRom:
    header = parse_ines_header(data)
    prg_size = header.prg_rom_banks * PRG_ROM_BANK_SIZE
    chr_size = header.chr_rom_banks * CHR_ROM_BANK_SIZE
    prg_start = INES_HEADER_SIZE + (
        TRAINER_SIZE if header.has_trainer else 0
    )
    prg_end = prg_start + prg_size
    chr_start = prg_end
    chr_end = chr_start + chr_size
    if len(data) < chr_end:
        raise ValueError(
            "iNES data is too short for declared PRG/CHR ROM"
        )
    return INesRom(
        header=header,
        prg_rom=data[prg_start:prg_end],
        chr_rom=data[chr_start:chr_end],
    )

不变量：尺寸来自存储体数量；PRG 紧跟在文件头和可选的 512 字节训练器之后开始；CHR 紧接在 PRG 之后；并且在切片之前，所有声明的字节都必须实际存在。不要依赖 Python 切片对过短数据的宽容处理，否则会悄无声息地接受一个被截断的镜像文件。

此步骤范围之外

1. Extra trailing-byte policy and CHR RAM allocation are not introduced here.
2. Lesson 217 constructs a `Cartridge` from this parser result.
3. Lessons 218-220 add mapper behavior and mapper selection.

运行本课

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

示例实现

建议实现

def parse_ines_rom(data: bytes) -> INesRom:
    header = parse_ines_header(data)
    prg_size = header.prg_rom_banks * PRG_ROM_BANK_SIZE
    chr_size = header.chr_rom_banks * CHR_ROM_BANK_SIZE
    prg_start = INES_HEADER_SIZE + (
        TRAINER_SIZE if header.has_trainer else 0
    )
    prg_end = prg_start + prg_size
    chr_start = prg_end
    chr_end = chr_start + chr_size
    if len(data) < chr_end:
        raise ValueError(
            "iNES data is too short for declared PRG/CHR ROM"
        )
    return INesRom(
        header=header,
        prg_rom=data[prg_start:prg_end],
        chr_rom=data[chr_start:chr_end],
    )

查看测试代码test_216_parse_ines_rom.py

import importlib

import pytest


def make_ines_data(
    prg_banks=1,
    chr_banks=1,
    flags_6=0x00,
    flags_7=0x00,
    trainer=None,
    prg_byte=0xAA,
    chr_byte=0xBB,
):
    ines = importlib.import_module("emulator.cartridge.ines")

    header = bytearray(16)
    header[0:4] = b"NES\x1A"
    header[4] = prg_banks
    header[5] = chr_banks
    header[6] = flags_6
    header[7] = flags_7

    prg = bytes([prg_byte]) * (prg_banks * ines.PRG_ROM_BANK_SIZE)
    chr_ = bytes([chr_byte]) * (chr_banks * ines.CHR_ROM_BANK_SIZE)

    if trainer is None:
        trainer = b""

    return bytes(header) + trainer + prg + chr_


def test_parse_ines_rom_function_exists():
    """Objective: expose parse_ines_rom(data)."""
    ines = importlib.import_module("emulator.cartridge.ines")

    assert hasattr(ines, "parse_ines_rom")
    assert callable(ines.parse_ines_rom)


def test_parse_ines_rom_extracts_prg_and_chr_sections():
    """
    Objective:
    Extract PRG ROM and CHR ROM according to header bank counts.
    """
    ines = importlib.import_module("emulator.cartridge.ines")
    data = make_ines_data(prg_banks=1, chr_banks=1, prg_byte=0xAA, chr_byte=0xBB)

    rom = ines.parse_ines_rom(data)

    assert rom.header.prg_rom_banks == 1
    assert rom.header.chr_rom_banks == 1
    assert len(rom.prg_rom) == ines.PRG_ROM_BANK_SIZE
    assert len(rom.chr_rom) == ines.CHR_ROM_BANK_SIZE
    assert rom.prg_rom == bytes([0xAA]) * ines.PRG_ROM_BANK_SIZE
    assert rom.chr_rom == bytes([0xBB]) * ines.CHR_ROM_BANK_SIZE


def test_parse_ines_rom_supports_multiple_prg_banks():
    """
    Objective:
    Header byte 4 is a PRG bank count. Two banks means 32KB of PRG ROM.
    """
    ines = importlib.import_module("emulator.cartridge.ines")
    data = make_ines_data(prg_banks=2, chr_banks=1)

    rom = ines.parse_ines_rom(data)

    assert len(rom.prg_rom) == 2 * ines.PRG_ROM_BANK_SIZE


def test_parse_ines_rom_skips_trainer_when_present():
    """
    Objective:
    If flags_6 bit 2 is set, skip the 512-byte trainer before PRG ROM.
    """
    ines = importlib.import_module("emulator.cartridge.ines")
    trainer = bytes([0xCC]) * ines.TRAINER_SIZE
    data = make_ines_data(
        flags_6=0b0000_0100,
        trainer=trainer,
        prg_byte=0xAA,
        chr_byte=0xBB,
    )

    rom = ines.parse_ines_rom(data)

    assert rom.header.has_trainer is True
    assert rom.prg_rom[0] == 0xAA
    assert rom.chr_rom[0] == 0xBB
    assert 0xCC not in rom.prg_rom[:16]


def test_parse_ines_rom_rejects_data_shorter_than_declared_sections():
    """
    Objective:
    If the header declares PRG/CHR bytes that are missing, reject the file.
    """
    ines = importlib.import_module("emulator.cartridge.ines")
    data = make_ines_data(prg_banks=1, chr_banks=1)
    truncated = data[:-1]

    with pytest.raises(ValueError, match="iNES data is too short for declared PRG/CHR ROM"):
        ines.parse_ines_rom(truncated)


def test_parse_ines_rom_returns_header_and_sections_together():
    """
    Objective:
    parse_ines_rom should return INesRom(header, prg_rom, chr_rom), not loose
    values.
    """
    ines = importlib.import_module("emulator.cartridge.ines")
    data = make_ines_data(prg_banks=1, chr_banks=1, flags_6=0x20, flags_7=0x40)

    rom = ines.parse_ines_rom(data)

    assert isinstance(rom, ines.INesRom)
    assert isinstance(rom.header, ines.INesHeader)
    assert rom.header.mapper_number == 0x42

测试函数 (6)

test_parse_ines_rom_function_exists
test_parse_ines_rom_extracts_prg_and_chr_sections
test_parse_ines_rom_supports_multiple_prg_banks
test_parse_ines_rom_skips_trainer_when_present
test_parse_ines_rom_rejects_data_shorter_than_declared_sections
test_parse_ines_rom_returns_header_and_sections_together