103. Instruction rol a 指令

实现针对累加器的 ROL。

第 103 / 356 · tests/chapter_01_cpu/test_103_instruction_rol_a.py

在本步骤中,以第 102 课中针对内存的 `rol` 为前置条件,只添加寄存器变体。分派工作推迟到第 104 课。

生产代码位置中的完整示例实现

`emulator/cpu/instructions.py::rol_a`::

def rol_a(cpu: CPU):
    value = cpu.a
    old_carry = int(cpu.flags.get_carry_flag())

    result = (value << 1) | old_carry
    result_8 = result & 0xFF

    # Set flags

    cpu.flags.set_carry_flag((value & 0b1000_0000) != 0)
    cpu.flags.set_zero_flag(result_8 == 0)
    cpu.flags.set_negative_flag((result_8 & 0b1000_0000) != 0)

    cpu.a = result_8

本步骤存在的原因

累加器模式没有有效内存地址,因此需要一个专门的原语,在写入 `cpu.a` 的同时保持相同的旋转语义。

不变量:先采样旧的 Carry 并将其送入第 0 位;原始 A 的第 7 位成为新的 Carry;A 被限制为 8 位;Z/N 描述新的 A;不会发生总线写入。

常见误解:`cpu.a 是一个值,而不是可以传给 rol` 的地址。这样做会修改地址 A 处的内存,而寄存器本身保持不变。

不在本步骤范围内:映射操作码 `0x2A` 是第 104 课,内存寻址模式是第 105-108 课,ROR 从第 109 课开始,时序/周期精度是之后的工作。

运行本课

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

示例实现

生产代码位置中的完整示例实现

def rol_a(cpu: CPU):
    value = cpu.a
    old_carry = int(cpu.flags.get_carry_flag())

    result = (value << 1) | old_carry
    result_8 = result & 0xFF

    # Set flags

    cpu.flags.set_carry_flag((value & 0b1000_0000) != 0)
    cpu.flags.set_zero_flag(result_8 == 0)
    cpu.flags.set_negative_flag((result_8 & 0b1000_0000) != 0)

    cpu.a = result_8

查看测试代码test_103_instruction_rol_a.py

from emulator.cpu.instructions import rol_a
from tests.helpers import NEGATIVE_FLAG, ZERO_FLAG, make_cpu


CARRY_FLAG = 1 << 0


def test_rol_a_rotates_accumulator_left_with_old_carry_clear():
    """Objective: old Carry=0 means new A bit 0 becomes 0."""
    cpu = make_cpu()
    cpu.a = 0b0000_0011

    rol_a(cpu)

    assert cpu.a == 0b0000_0110
    assert (cpu.p & CARRY_FLAG) == 0


def test_rol_a_rotates_accumulator_left_with_old_carry_set():
    """Objective: old Carry=1 is inserted into result bit 0."""
    cpu = make_cpu()
    cpu.p |= CARRY_FLAG
    cpu.a = 0b0000_0010

    rol_a(cpu)

    assert cpu.a == 0b0000_0101
    assert (cpu.p & CARRY_FLAG) == 0


def test_rol_a_sets_carry_from_old_accumulator_bit_7():
    """Objective: old A bit 7 becomes the new Carry flag."""
    cpu = make_cpu()
    cpu.a = 0b1000_0001

    rol_a(cpu)

    assert cpu.a == 0b0000_0010
    assert (cpu.p & CARRY_FLAG) != 0


def test_rol_a_sets_zero_flag_when_result_is_zero():
    """Objective: A=0x80 with old Carry=0 becomes 0x00 and sets Zero."""
    cpu = make_cpu()
    cpu.a = 0x80

    rol_a(cpu)

    assert cpu.a == 0x00
    assert (cpu.p & ZERO_FLAG) != 0
    assert (cpu.p & NEGATIVE_FLAG) == 0
    assert (cpu.p & CARRY_FLAG) != 0


def test_rol_a_sets_negative_flag_from_result_bit_7():
    """Objective: A=0x40 with old Carry=0 becomes 0x80 and sets Negative."""
    cpu = make_cpu()
    cpu.a = 0x40

    rol_a(cpu)

    assert cpu.a == 0x80
    assert (cpu.p & NEGATIVE_FLAG) != 0
    assert (cpu.p & ZERO_FLAG) == 0


def test_rol_a_does_not_write_rotated_result_to_memory():
    """Objective: ROL A writes to A only; it must not treat A as a memory address."""
    cpu = make_cpu()
    cpu.a = 0x20
    cpu.bus.write(0x0020, 0x99)

    rol_a(cpu)

    assert cpu.a == 0x40
    assert cpu.bus.read(0x0020) == 0x99

测试函数 (6)

test_rol_a_rotates_accumulator_left_with_old_carry_clear
test_rol_a_rotates_accumulator_left_with_old_carry_set
test_rol_a_sets_carry_from_old_accumulator_bit_7
test_rol_a_sets_zero_flag_when_result_is_zero
test_rol_a_sets_negative_flag_from_result_bit_7
test_rol_a_does_not_write_rotated_result_to_memory