265. Console 消费 PPU 的 NMI 请求

把 Console 建模为消费 PPU NMI 请求的协调者。

第 265 / 356 · tests/chapter_04_ppu_timing_and_vblank/test_265_console_consumes_ppu_nmi_request.py

参考资料

https://www.nesdev.org/wiki/CPU_interrupts
https://www.nesdev.org/wiki/PPU_registers#Vblank_NMI

需要创建的文件

emulator/console.py

此步骤存在的原因

模拟器现在已经具备了实现 VBlank NMI 所需的两个独立机制

PPU mechanism:
    PPU enters VBlank and sets ppu.nmi_requested = True

CPU mechanism:
    CPU.interrupt_nmi() pushes PC/status and jumps through $FFFA/$FFFB

现在我们需要一个小型协调器,把这两个机制连接起来,同时不让 CPU 和 PPU 直接相互依赖。

什么是 Console?Console 是未来最顶层的模拟 NES 主机。随着时间推移,它可以拥有并协调如下子系统:

CPU
PPU
cartridge/mapper
controllers
APU/audio
frame stepping

在当前阶段,Console 从很小的规模开始。它的第一个任务只是消费一次 PPU 的 NMI 请求,并调用 CPU.interrupt_nmi()。

正确的职责划分

PPU:
    produces nmi_requested

CPU:
    implements interrupt_nmi()

Console:
    connects the PPU signal to the CPU mechanism

重要的架构规则

不要把 PPU 的所有权放进 CPU 里。CPU 不应该去询问 PPU 是否有 NMI 待处理,那会在 CPU 执行和视频硬件之间造成隐藏的耦合。

最小实现示例

from dataclasses import dataclass

from emulator.cpu.cpu import CPU
from emulator.ppu.ppu import PPU


@dataclass
class Console:
    cpu: CPU
    ppu: PPU

    def consume_nmi_if_requested(self) -> None:
        if not self.ppu.nmi_requested:
            return

        self.ppu.nmi_requested = False
        self.cpu.interrupt_nmi()

在之后的时序测试中会引入的未来形态

class Console:
    ...

    def step(self) -> None:
        cpu_cycles = self.cpu.step()
        self.ppu.step(cpu_cycles * 3)
        self.consume_nmi_if_requested()

本文件不测试 Console.step()。CPU/PPU 的时序集成会在 CPU.step() 返回指令周期数之后,作为单独的一步进行测试。

常见误解

由于 NMI 是由 PPU 引起的,可能会觉得让 CPU 拥有 PPU 是很自然的做法。请避免这样做。CPU 只是接收中断信号,不应该拥有视频设备。

不在本步骤范围内

CPU/PPU 的周期比例
Console.step()
渲染
手柄
APU/音频
精确的 NMI 延迟

运行本课

uv run pytest tests/chapter_04_ppu_timing_and_vblank/test_265_console_consumes_ppu_nmi_request.py -v

示例实现

最小实现示例

from dataclasses import dataclass

from emulator.cpu.cpu import CPU
from emulator.ppu.ppu import PPU


@dataclass
class Console:
    cpu: CPU
    ppu: PPU

    def consume_nmi_if_requested(self) -> None:
        if not self.ppu.nmi_requested:
            return

        self.ppu.nmi_requested = False
        self.cpu.interrupt_nmi()

在之后的时序测试中会引入的未来形态

class Console:
    ...

    def step(self) -> None:
        cpu_cycles = self.cpu.step()
        self.ppu.step(cpu_cycles * 3)
        self.consume_nmi_if_requested()

查看测试代码test_265_console_consumes_ppu_nmi_request.py

from dataclasses import is_dataclass

from emulator.console import Console
from emulator.cpu.cpu import CPU
from emulator.ppu.ppu import PPU
from tests.helpers import make_cpu_with_rom


def write_nmi_vector(rom, addr: int) -> None:
    """
    Install the NMI vector in FakeROM for CPU.interrupt_nmi().

    CPU address $FFFA maps to FakeROM offset $7FFA because CpuBus maps
    $8000-$FFFF to program_rom offsets $0000-$7FFF.
    """
    rom.write(0x7FFA, addr & 0xFF)
    rom.write(0x7FFB, (addr >> 8) & 0xFF)


def make_console_with_fake_rom():
    """
    Build a coherent small console for NMI tests.

    Important:
    Use the PPU already owned by cpu.bus. That keeps this test close to the real
    emulator shape where CPU register accesses and Console coordination should be
    observing the same PPU instance.
    """
    cpu, bus, rom = make_cpu_with_rom()
    ppu = bus.ppu
    return Console(cpu=cpu, ppu=ppu), cpu, ppu, rom


def test_console_is_small_machine_coordinator_for_cpu_and_ppu():
    """
    Objective:
    Console starts as a small coordinator that stores CPU and PPU references.
    """
    assert is_dataclass(Console)

    console, cpu, ppu, _rom = make_console_with_fake_rom()

    assert console.cpu is cpu
    assert console.ppu is ppu
    assert isinstance(console.cpu, CPU)
    assert isinstance(console.ppu, PPU)


def test_console_exposes_nmi_consumption_method():
    """
    Objective:
    Console exposes the boundary method that connects PPU NMI requests to CPU NMI
    handling.
    """
    assert hasattr(Console, "consume_nmi_if_requested")
    assert callable(Console.consume_nmi_if_requested)


def test_console_does_nothing_when_ppu_has_no_nmi_request():
    """
    Objective:
    If ppu.nmi_requested is False, Console must not interrupt the CPU.
    """
    console, cpu, ppu, rom = make_console_with_fake_rom()
    write_nmi_vector(rom, 0xC000)
    cpu.pc = 0x8123
    cpu.s = 0xFD
    ppu.nmi_requested = False

    console.consume_nmi_if_requested()

    assert cpu.pc == 0x8123
    assert cpu.s == 0xFD
    assert ppu.nmi_requested is False


def test_console_consumes_ppu_nmi_request_and_interrupts_cpu():
    """
    Objective:
    When ppu.nmi_requested is True, Console calls CPU.interrupt_nmi() and clears
    the request.

    Example:
        PPU request: nmi_requested = True
        NMI vector:  $FFFA/$FFFB -> $C000
        CPU before:  PC = $8123
        CPU after:   PC = $C000
        PPU after:   nmi_requested = False
    """
    console, cpu, ppu, rom = make_console_with_fake_rom()
    write_nmi_vector(rom, 0xC000)
    cpu.pc = 0x8123
    cpu.s = 0xFD
    ppu.nmi_requested = True

    console.consume_nmi_if_requested()

    assert cpu.pc == 0xC000
    assert cpu.s == 0xFA
    assert ppu.nmi_requested is False


def test_console_consumes_each_ppu_nmi_request_only_once():
    """
    Objective:
    A single PPU NMI request should produce at most one CPU NMI.

    Why this matters:
    If Console forgot to clear ppu.nmi_requested, every coordinator check would
    interrupt the CPU again from the same stale request.
    """
    console, cpu, ppu, rom = make_console_with_fake_rom()
    write_nmi_vector(rom, 0xC000)
    cpu.pc = 0x8123
    cpu.s = 0xFD
    ppu.nmi_requested = True

    console.consume_nmi_if_requested()
    pc_after_first_consume = cpu.pc
    stack_after_first_consume = cpu.s

    console.consume_nmi_if_requested()

    assert cpu.pc == pc_after_first_consume
    assert cpu.s == stack_after_first_consume
    assert ppu.nmi_requested is False


def test_console_keeps_cpu_and_ppu_coupling_out_of_subsystems():
    """
    Objective:
    Document the desired dependency direction.

    Console may import CPU and PPU because it coordinates the machine. CPU should
    not need to import PPU just to handle NMI, and PPU should not call CPU directly.

    This test checks behavior through the public coordinator instead of adding a
    CPU -> PPU dependency.
    """
    console, cpu, ppu, rom = make_console_with_fake_rom()
    write_nmi_vector(rom, 0x9000)
    cpu.pc = 0x8000
    cpu.s = 0xFD

    ppu.nmi_requested = True
    console.consume_nmi_if_requested()

    assert cpu.pc == 0x9000
    assert ppu.nmi_requested is False

测试函数 (6)

test_console_is_small_machine_coordinator_for_cpu_and_ppu
test_console_exposes_nmi_consumption_method
test_console_does_nothing_when_ppu_has_no_nmi_request
test_console_consumes_ppu_nmi_request_and_interrupts_cpu
test_console_consumes_each_ppu_nmi_request_only_once
test_console_keeps_cpu_and_ppu_coupling_out_of_subsystems