288. APU 音频寄存器空操作

在 CpuBus 上为 APU/音频寄存器添加明确的空操作行为。

第 288 / 356 · tests/chapter_06_rom_startup_preparation/test_288_apu_audio_register_noop.py

待更新文件

emulator/bus/cpu_bus.py

为什么需要这一步

真实的 NES ROM 在启动期间通常会访问 APU/音频寄存器。音频超出了本教程当前的范围，但如果每次访问音频寄存器都崩溃，手动 ROM 实验就会在我们能够观察到 CPU/PPU/手柄行为之前提前停止。

这一步教授的是有意为之的空操作

recognized address + documented out-of-scope behavior

而不是一套广泛的伪硬件实现。

什么是 APU？APU，即音频处理单元，是 NES 中负责声音生成的硬件模块。CPU 通过内存映射寄存器控制它。

最小示例

CPU writes $4000
    real NES: configure pulse channel audio
    this tutorial for now: accept the write and produce no sound

常见的误解

"If the emulator accepts APU writes, APU is implemented."

不是。在这一步中，APU/音频被明确视为超出范围。模拟器只是避免在这些地址上崩溃。

建议的实现示例

def read(self, addr: int) -> int:
    ...

    # APU/audio registers are intentionally out of scope.
    if 0x4000 <= addr <= 0x4013:
        return 0
    if addr == 0x4015:
        return 0

    # Controller port 2 / expansion input is also out of scope for now.
    # Returning 0 means "no controller-2 buttons pressed" in this simplified model.
    if addr == 0x4017:
        return 0

    ...

def write(self, addr: int, value: int) -> None:
    ...

    # APU/audio registers are intentionally out of scope.
    if 0x4000 <= addr <= 0x4013:
        return
    if addr == 0x4015:
        return

    # $4017 writes control the APU frame counter on the NES.
    # Audio/APU timing is intentionally out of scope, so this is a no-op.
    if addr == 0x4017:
        return

    ...

为什么是这些地址

$4000-$4013
    APU sound-channel registers

$4015
    APU status/control register

$4017
    Writes: APU frame counter register, intentionally no-op for now.
    Reads: controller port 2 / expansion input, intentionally returns 0 for now.

重要的排除项

$4014 is OAMDMA, not audio.
    Writing $02 to $4014 should later copy CPU $0200-$02FF into PPU OAM.
    Do not swallow it as an APU no-op.

$4016 is controller port 1, not audio.
    It will be implemented intentionally in the controller chapter.
    Do not fake it by returning 0 here.

范围之外

实际的声音生成
APU 定时器/包络/扫频/长度计数器
IRQ/帧计数器时序
OAMDMA $4014
手柄 $4016
从 $4017 读取的手柄端口 2/扩展输入
对所有不支持的 I/O 地址进行广泛的兜底处理

运行本课

uv run pytest tests/chapter_06_rom_startup_preparation/test_288_apu_audio_register_noop.py -v

示例实现

建议的实现示例

def read(self, addr: int) -> int:
    ...

    # APU/audio registers are intentionally out of scope.
    if 0x4000 <= addr <= 0x4013:
        return 0
    if addr == 0x4015:
        return 0

    # Controller port 2 / expansion input is also out of scope for now.
    # Returning 0 means "no controller-2 buttons pressed" in this simplified model.
    if addr == 0x4017:
        return 0

    ...

def write(self, addr: int, value: int) -> None:
    ...

    # APU/audio registers are intentionally out of scope.
    if 0x4000 <= addr <= 0x4013:
        return
    if addr == 0x4015:
        return

    # $4017 writes control the APU frame counter on the NES.
    # Audio/APU timing is intentionally out of scope, so this is a no-op.
    if addr == 0x4017:
        return

    ...

查看测试代码test_288_apu_audio_register_noop.py

import pytest

from emulator.bus.cpu_bus import CpuBus
from emulator.memory.fake_rom import FakeROM


def test_apu_audio_register_writes_are_explicit_noops():
    """
    Objective:
    Writes to the current out-of-scope APU/audio register set should be accepted
    without raising.

    This keeps real-ROM startup experiments from failing only because the ROM
    initializes audio.
    """
    bus = CpuBus(program_rom=FakeROM())

    for addr in [0x4000, 0x4001, 0x400F, 0x4013, 0x4015, 0x4017]:
        bus.write(addr, 0xAB)


def test_apu_audio_register_reads_return_deterministic_zero():
    """
    Objective:
    Reads from out-of-scope APU/audio/controller-2-adjacent registers return a
    deterministic value.

    Returning 0 is intentionally simple. For $4017 reads, it means controller port 2
    is currently modeled as "no buttons pressed" rather than fully implemented.
    """
    bus = CpuBus(program_rom=FakeROM())

    for addr in [0x4000, 0x4001, 0x400F, 0x4013, 0x4015, 0x4017]:
        assert bus.read(addr) == 0


def test_oamdma_4014_is_not_swallowed_by_apu_noop():
    """
    Objective:
    $4014 belongs to OAMDMA, not APU/audio.

    After the OAMDMA step exists, writes to $4014 should perform the DMA copy.
    The important invariant from this APU/audio step is that $4014 is not treated
    as an audio no-op.

    Reads from $4014 remain unsupported because OAMDMA is a write-triggered
    register in this tutorial.
    """
    bus = CpuBus(program_rom=FakeROM())

    for offset in range(256):
        bus.write(0x0200 + offset, offset)

    bus.write(0x4014, 0x02)

    assert list(bus.ppu.oam) == list(range(256))

    with pytest.raises(ValueError, match="Unsupported CPU bus read: 4014"):
        bus.read(0x4014)


def test_unknown_io_address_still_raises_instead_of_catch_all_noop():
    """
    Objective:
    The no-op must be explicit, not a broad catch-all for every unsupported I/O
    address.

    This keeps missing hardware visible during debugging.
    """
    bus = CpuBus(program_rom=FakeROM())

    with pytest.raises(ValueError, match="Unsupported CPU bus write: 4020"):
        bus.write(0x4020, 0x55)

    with pytest.raises(ValueError, match="Unsupported CPU bus read: 4020"):
        bus.read(0x4020)


def test_existing_ram_routing_still_works_after_apu_noop_step():
    """
    Objective:
    Adding APU/audio no-op handling must not disturb existing RAM routing.
    """
    bus = CpuBus(program_rom=FakeROM())

    bus.write(0x0002, 0x44)

    assert bus.read(0x0002) == 0x44
    assert bus.read(0x0802) == 0x44  # internal RAM mirror


def test_existing_ppu_register_routing_still_works_after_apu_noop_step():
    """
    Objective:
    Adding APU/audio no-op handling must not disturb PPU register routing.
    """
    bus = CpuBus(program_rom=FakeROM())

    bus.write(0x2000, 0x80)

    assert bus.ppu.ctrl == 0x80


def test_existing_prg_rom_routing_still_works_after_apu_noop_step():
    """
    Objective:
    Adding APU/audio no-op handling must not disturb test PRG ROM routing.
    """
    rom = FakeROM()
    rom.write(0x0000, 0xEA)
    bus = CpuBus(program_rom=rom)

    assert bus.read(0x8000) == 0xEA

测试函数 (7)

test_apu_audio_register_writes_are_explicit_noops
test_apu_audio_register_reads_return_deterministic_zero
test_oamdma_4014_is_not_swallowed_by_apu_noop
test_unknown_io_address_still_raises_instead_of_catch_all_noop
test_existing_ram_routing_still_works_after_apu_noop_step
test_existing_ppu_register_routing_still_works_after_apu_noop_step
test_existing_prg_rom_routing_still_works_after_apu_noop_step