211. CPU 跟踪格式化器

添加 `emulator/debug/cpu_trace.py::format_cpu_trace`。

第 211 / 356 · tests/chapter_01_cpu/test_211_cpu_trace_formatter.py

此步骤存在的原因

在此步骤中，添加一个格式化器，在与 ROM 日志比对之前提供可观测性，同时不将调试与 CPU 执行耦合在一起。它输出的每一行都报告下一条 PC/操作码，以及执行前的 A、X、Y、P、S 寄存器值：

8000 A9 A:00 X:00 Y:00 P:04 S:FD

建议实现

from __future__ import annotations
from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from emulator.cpu.cpu import CPU


def format_cpu_trace(cpu: CPU):
    opcode = cpu.bus.read(cpu.pc)
    return f"{cpu.pc:04X} {opcode:02X} A:{cpu.a:02X} X:{cpu.x:02X} Y:{cpu.y:02X} P:{cpu.p:02X} S:{cpu.s:02X}"

不变量：格式化仅执行一次不推进地址的总线读取，返回大写、固定宽度的十六进制字段，并且保持 PC、寄存器和标志位不变。不要使用 CPU.fetch_byte()，也不要调用 CPU.step()；两者都会把观测与执行混为一谈，而且 fetch_byte() 会推进 PC。范围之外：ROM 与卡带支持属于后续编号的步骤。

运行本课

uv run pytest tests/chapter_01_cpu/test_211_cpu_trace_formatter.py -v

示例实现

建议实现

from __future__ import annotations
from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from emulator.cpu.cpu import CPU


def format_cpu_trace(cpu: CPU):
    opcode = cpu.bus.read(cpu.pc)
    return f"{cpu.pc:04X} {opcode:02X} A:{cpu.a:02X} X:{cpu.x:02X} Y:{cpu.y:02X} P:{cpu.p:02X} S:{cpu.s:02X}"

查看测试代码test_211_cpu_trace_formatter.py

import inspect
from pathlib import Path

from emulator.debug.cpu_trace import format_cpu_trace
from tests.helpers import load_program, make_cpu_with_rom, write_reset_vector


def test_cpu_trace_file_exists_inside_emulator_debug():
    """
    Objective:
    Create the trace formatter in emulator/debug/cpu_trace.py.

    Why here:
    Debug tracing is observability, not CPU execution logic. Keeping it outside
    cpu.py prevents tracing concerns from coupling to instruction behavior.
    """
    assert Path("emulator/debug/cpu_trace.py").exists()


def test_format_cpu_trace_function_exists_and_takes_cpu():
    """Objective: expose format_cpu_trace(cpu) as a small read-only formatter."""
    assert callable(format_cpu_trace)
    assert list(inspect.signature(format_cpu_trace).parameters) == ["cpu"]


def test_format_cpu_trace_outputs_minimal_cpu_state_before_execution():
    """
    Objective:
    Trace should show the opcode at current PC and CPU registers before step().
    """
    cpu, bus, rom = make_cpu_with_rom()
    write_reset_vector(rom, 0x8000)
    load_program(rom, 0x8000, [0xA9, 0x42])

    cpu.reset()
    cpu.a = 0x00
    cpu.x = 0x11
    cpu.y = 0x22
    cpu.p = 0x04
    cpu.s = 0xFD

    trace = format_cpu_trace(cpu)

    assert trace == "8000 A9 A:00 X:11 Y:22 P:04 S:FD"


def test_format_cpu_trace_is_read_only():
    """
    Objective:
    Formatting a trace must not mutate CPU state.

    Failure mode this catches:
    Calling cpu.fetch_byte() inside the trace formatter would increment PC.
    """
    cpu, bus, rom = make_cpu_with_rom()
    write_reset_vector(rom, 0x8000)
    load_program(rom, 0x8000, [0xEA])

    cpu.reset()
    cpu.a = 0x12
    cpu.x = 0x34
    cpu.y = 0x56
    cpu.p = 0x78
    cpu.s = 0x9A

    before = (cpu.pc, cpu.a, cpu.x, cpu.y, cpu.p, cpu.s)
    format_cpu_trace(cpu)
    after = (cpu.pc, cpu.a, cpu.x, cpu.y, cpu.p, cpu.s)

    assert after == before


def test_format_cpu_trace_changes_after_cpu_step_because_cpu_state_changed():
    """
    Objective:
    Trace does not execute instructions, but it should reflect state changes made
    by normal CPU.step() calls.

    Program:
        LDA #$42
        NOP
    """
    cpu, bus, rom = make_cpu_with_rom()
    write_reset_vector(rom, 0x8000)
    load_program(rom, 0x8000, [0xA9, 0x42, 0xEA])

    cpu.reset()

    first_trace = format_cpu_trace(cpu)
    cpu.step()
    second_trace = format_cpu_trace(cpu)

    assert first_trace == "8000 A9 A:00 X:00 Y:00 P:04 S:FD"
    assert second_trace == "8002 EA A:42 X:00 Y:00 P:04 S:FD"

测试函数 (5)

test_cpu_trace_file_exists_inside_emulator_debug
test_format_cpu_trace_function_exists_and_takes_cpu
test_format_cpu_trace_outputs_minimal_cpu_state_before_execution
test_format_cpu_trace_is_read_only
test_format_cpu_trace_changes_after_cpu_step_because_cpu_state_changed