288. No-op de registro de audio de la apu

Añadir un comportamiento explícito de no-op para los registros de APU/audio en CpuBus.

Lección 288 de 356 · tests/chapter_06_rom_startup_preparation/test_288_apu_audio_register_noop.py

Archivo a actualizar

emulator/bus/cpu_bus.py

Por qué existe este paso

Las ROMs reales del NES suelen acceder a los registros de APU/audio durante el arranque. El audio está fuera del alcance actual de este tutorial, pero fallar en cada acceso a un registro de audio hace que los experimentos manuales con ROMs se detengan antes de poder observar el comportamiento de CPU/PPU/mando.

Este paso enseña un no-op intencionado

recognized address + documented out-of-scope behavior

no una implementación amplia de hardware simulado.

¿Qué es la APU? La APU, o Unidad de Procesamiento de Audio, es el bloque de hardware del NES responsable de generar sonido. La CPU la controla mediante registros mapeados en memoria.

Ejemplo mínimo

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

Concepto erróneo común

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

No. En este paso, la APU/audio se reconoce explícitamente como fuera de alcance. El emulador solo evita fallar en esas direcciones.

Ejemplo de implementación sugerida

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

    ...

Por qué estas direcciones

$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.

Exclusiones importantes

$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.

Fuera de alcance

generación de sonido real
temporizadores/envolventes/barrido/contadores de longitud de la APU
temporización de IRQ/contador de fotogramas
OAMDMA $4014
mando $4016
lecturas de entrada de expansión/puerto de mando 2 desde $4017
gestión genérica para todas las direcciones de E/S no soportadas

Ejecutar esta lección

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

Implementación de ejemplo

Ejemplo de implementación sugerida

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

    ...

Ver código del testtest_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

Funciones de test (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