197. 指令 php

实现 PHP 行为。

第 197 / 356 · tests/chapter_01_cpu/test_197_instruction_php.py

在本步骤中，只修改 `emulator/cpu/instructions.py，添加 php(cpu)。前置条件：FlagsHandler.set_break_flag` 已存在。

本步骤存在的原因

PHP 把带有模拟器 Break 标记置位的 P 压入栈，然后从当前 CPU 状态中清除这个临时标记。和所有入栈操作一样，它会先写入 $0100 | S，再递减这个 8 位的 S。

建议实现

def php(cpu: CPU):
    cpu.flags.set_break_flag(True)
    cpu.flags.set_one_flag(True)
    cpu.bus.write(STACK_BASE | cpu.s, cpu.p)
    cpu.flags.set_break_flag(False)
    cpu.flags.set_one_flag(False)
    cpu.s = (cpu.s - 1) & 0xFF

不变量：保留所有原有的状态位；在压入栈的副本中置位 Break 和 ONE；之后从实时的 P 中清除这两位；先写入再递减，并对 S 做环绕处理；不要根据这个状态字节推导 Z 或 N。

常见误解：PHP 之后 `cpu.p` 中的 Break 位并不会因为压入栈的字节里置位了它，就一直保持启用状态。

范围之外：注册操作码 $08 属于第 198 步。日后对压栈状态字节规则的任何改动都属于它们各自的编号步骤。

运行本课

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

示例实现

建议实现

def php(cpu: CPU):
    cpu.flags.set_break_flag(True)
    cpu.flags.set_one_flag(True)
    cpu.bus.write(STACK_BASE | cpu.s, cpu.p)
    cpu.flags.set_break_flag(False)
    cpu.flags.set_one_flag(False)
    cpu.s = (cpu.s - 1) & 0xFF

查看测试代码test_197_instruction_php.py

from emulator.cpu.instructions import php
from tests.helpers import make_cpu


CARRY_FLAG = 1 << 0
ZERO_FLAG = 1 << 1
INTERRUPT_DISABLE_FLAG = 1 << 2
BREAK_FLAG = 1 << 4
ONE_FLAG = 1 << 5
OVERFLOW_FLAG = 1 << 6
NEGATIVE_FLAG = 1 << 7
STACK_BASE = 0x0100


def test_php_pushes_processor_status_to_current_stack_address():
    """Objective: PHP writes status to $0100 | S before changing S."""
    cpu = make_cpu()
    cpu.s = 0xFD
    cpu.p = CARRY_FLAG | ZERO_FLAG

    php(cpu)

    pushed_status = cpu.bus.read(STACK_BASE | 0xFD)
    assert (pushed_status & CARRY_FLAG) != 0
    assert (pushed_status & ZERO_FLAG) != 0


def test_php_pushes_status_with_break_flag_set():
    """
    Objective:
    PHP pushes a copy of P with the Break flag set.

    The Break flag here describes the saved status byte, not a normal long-lived
    CPU flag in this emulator model.
    """
    cpu = make_cpu()
    cpu.s = 0xFD
    cpu.p = 0x00

    php(cpu)

    pushed_status = cpu.bus.read(STACK_BASE | 0xFD)
    assert (pushed_status & BREAK_FLAG) != 0
    assert (pushed_status & ONE_FLAG) != 0


def test_php_clears_break_flag_from_cpu_state_after_push():
    """
    Objective:
    PHP should not leave Break set in cpu.p after the push finishes.
    """
    cpu = make_cpu()
    cpu.s = 0xFD
    cpu.p = 0x00

    php(cpu)

    pushed_status = cpu.bus.read(STACK_BASE | 0xFD)
    assert (pushed_status & BREAK_FLAG) != 0
    assert (pushed_status & ONE_FLAG) != 0
    assert cpu.flags.get_break_flag() is False
    assert cpu.flags.get_one_flag() is False


def test_php_decrements_stack_pointer_after_push():
    """Objective: PHP pushes one byte, so S decreases by 1."""
    cpu = make_cpu()
    cpu.s = 0xFD
    cpu.p = 0x00

    php(cpu)

    assert cpu.s == 0xFC


def test_php_stack_pointer_wraps_to_8_bits():
    """Objective: S is an 8-bit stack pointer and wraps after decrementing."""
    cpu = make_cpu()
    cpu.s = 0x00
    cpu.p = CARRY_FLAG

    php(cpu)

    pushed_status = cpu.bus.read(STACK_BASE | 0x00)
    assert (pushed_status & CARRY_FLAG) != 0
    assert (pushed_status & BREAK_FLAG) != 0
    assert (pushed_status & ONE_FLAG) != 0
    assert cpu.s == 0xFF


def test_php_preserves_non_break_cpu_flags_after_push():
    """
    Objective:
    PHP is a stack operation. It should not damage existing status flags.

    Break is special here: it is temporarily set for the pushed copy, then
    cleared from CPU state again.
    """
    cpu = make_cpu()
    cpu.s = 0xFD
    cpu.p = CARRY_FLAG | ZERO_FLAG | INTERRUPT_DISABLE_FLAG | OVERFLOW_FLAG | NEGATIVE_FLAG
    expected_cpu_p = cpu.p

    php(cpu)

    assert cpu.p == expected_cpu_p


def test_php_does_not_update_zero_or_negative_flags_from_status_value():
    """
    Objective:
    PHP does not compute flags. It only pushes a status byte.

    Even if the pushed byte has bit 7 set, PHP must not reinterpret that as a
    new Negative result.
    """
    cpu = make_cpu()
    cpu.s = 0xFD
    cpu.p = CARRY_FLAG
    cpu.flags.set_zero_flag(False)
    cpu.flags.set_negative_flag(False)

    php(cpu)

    assert cpu.flags.get_zero_flag() is False
    assert cpu.flags.get_negative_flag() is False

测试函数 (7)

test_php_pushes_processor_status_to_current_stack_address
test_php_pushes_status_with_break_flag_set
test_php_clears_break_flag_from_cpu_state_after_push
test_php_decrements_stack_pointer_after_push
test_php_stack_pointer_wraps_to_8_bits
test_php_preserves_non_break_cpu_flags_after_push
test_php_does_not_update_zero_or_negative_flags_from_status_value