267. CPU.step() 返回周期数

让 CPU.step() 返回基本指令周期数。

第 267 / 356 · tests/chapter_04_ppu_timing_and_vblank/test_267_cpu_step_returns_cycles.py

参考资料

https://www.nesdev.org/wiki/Visual6502wiki/6502_all_256_Opcodes

需要更新的文件

emulator/cpu/cpu.py

此步骤存在的原因

模拟器现在已经有了独立的 OPCODE_CYCLES 表。下一步的时序桥接是让 CPU.step() 返回它所执行的操作码的基本周期数。

这为未来的 Console.step() 形态做准备:

cpu_cycles = cpu.step()
ppu.step(cpu_cycles * 3)
console.consume_nmi_if_requested()

什么是基本指令周期数?基本指令周期数是指在加上任何动态惩罚周期之前,一个操作码通常需要的 CPU 周期数。

最小示例

NOP implied      opcode $EA -> 2 cycles
LDA immediate   opcode $A9 -> 2 cycles
JSR absolute    opcode $20 -> 6 cycles

常见误解

周期数和取指的字节数并不相同。JSR 占 3 个字节,却需要 6 个周期。不要在 fetch_byte() 内部计算周期数。

建议的实现示例

from emulator.cpu.opcodes import OPCODE_CYCLES, OPCODE_TABLE


class CPU:
    ...

    def step(self) -> int:
        opcode = self.fetch_byte()
        handler = OPCODE_TABLE.get(opcode)
        if handler is None:
            raise NotImplementedError(f"Opcode {opcode:02X} not implemented")

        handler(self)
        return OPCODE_CYCLES[opcode]

为什么这样做能避免大规模重构

OPCODE_TABLE 仍然是原有的操作码到处理函数的映射。OPCODE_CYCLES 是一张并行的元数据表。旧的指令行为测试应该能够继续通过,因为 CPU.step() 仍然执行的是同一个处理函数。

重要限制

这里只返回基本周期数。动态时序在这一步中特意排除在外:

branch taken penalties
branch page-cross penalties
indexed load page-cross penalties

这些应该在之后作为单独的一步来建模。

不在本步骤范围内

把 OPCODE_TABLE 重构为数据类条目
在 fetch_byte() 中加入周期数
Console.step()
按 CPU 周期数 * 3 来推进 PPU
动态的额外周期

运行本课

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

示例实现

此步骤存在的原因

cpu_cycles = cpu.step()
ppu.step(cpu_cycles * 3)
console.consume_nmi_if_requested()

建议的实现示例

from emulator.cpu.opcodes import OPCODE_CYCLES, OPCODE_TABLE


class CPU:
    ...

    def step(self) -> int:
        opcode = self.fetch_byte()
        handler = OPCODE_TABLE.get(opcode)
        if handler is None:
            raise NotImplementedError(f"Opcode {opcode:02X} not implemented")

        handler(self)
        return OPCODE_CYCLES[opcode]

查看测试代码test_267_cpu_step_returns_cycles.py

import pytest

from emulator.cpu.opcodes import OPCODE_CYCLES
from tests.helpers import load_program, make_cpu_with_rom


def test_cpu_step_returns_nop_base_cycles():
    """
    Objective:
    CPU.step() returns the base cycle count for the opcode it executes.

    Example:
        NOP implied is opcode $EA and takes 2 CPU cycles.
    """
    cpu, _bus, rom = make_cpu_with_rom()
    load_program(rom, 0x8000, [0xEA])
    cpu.pc = 0x8000

    cycles = cpu.step()

    assert cycles == 2
    assert cycles == OPCODE_CYCLES[0xEA]
    assert cpu.pc == 0x8001


def test_cpu_step_returns_cycles_and_still_executes_instruction_behavior():
    """
    Objective:
    Returning cycles must not replace instruction behavior. The opcode handler
    still runs exactly as before.

    Example:
        LDA #$42 is opcode sequence $A9 $42.
        It loads A with $42 and returns 2 cycles.
    """
    cpu, _bus, rom = make_cpu_with_rom()
    load_program(rom, 0x8000, [0xA9, 0x42])
    cpu.pc = 0x8000

    cycles = cpu.step()

    assert cycles == 2
    assert cycles == OPCODE_CYCLES[0xA9]
    assert cpu.a == 0x42
    assert cpu.pc == 0x8002


def test_cpu_step_returns_different_cycles_for_different_opcodes():
    """
    Objective:
    CPU.step() should return opcode-specific timing, not a constant value.

    Example:
        JSR absolute is opcode $20 and takes 6 CPU cycles.
    """
    cpu, _bus, rom = make_cpu_with_rom()
    load_program(rom, 0x8000, [0x20, 0x00, 0x90])
    cpu.pc = 0x8000
    cpu.s = 0xFD

    cycles = cpu.step()

    assert cycles == 6
    assert cycles == OPCODE_CYCLES[0x20]
    assert cpu.pc == 0x9000


def test_cpu_step_still_raises_for_unknown_opcode():
    """
    Objective:
    Adding cycle returns must not make unsupported opcodes silently executable.

    Example:
        $02 is not implemented in the current OPCODE_TABLE. It should still raise
        NotImplementedError instead of returning OPCODE_CYCLES[$02].
    """
    cpu, _bus, rom = make_cpu_with_rom()
    load_program(rom, 0x8000, [0x02])
    cpu.pc = 0x8000

    with pytest.raises(NotImplementedError, match="Opcode 02 not implemented"):
        cpu.step()


def test_cpu_step_does_not_use_fetch_count_as_cycle_count():
    """
    Objective:
    Guard the mental model: cycles come from opcode metadata, not from how many
    bytes were fetched.

    Example:
        JSR absolute fetches 3 instruction bytes but takes 6 CPU cycles.
    """
    cpu, _bus, rom = make_cpu_with_rom()
    load_program(rom, 0x8000, [0x20, 0x00, 0x90])
    cpu.pc = 0x8000
    cpu.s = 0xFD

    cycles = cpu.step()

    assert cpu.pc == 0x9000
    assert cycles == 6
    assert cycles != 3

测试函数 (5)

test_cpu_step_returns_nop_base_cycles
test_cpu_step_returns_cycles_and_still_executes_instruction_behavior
test_cpu_step_returns_different_cycles_for_different_opcodes
test_cpu_step_still_raises_for_unknown_opcode
test_cpu_step_does_not_use_fetch_count_as_cycle_count