071. 指令 inc

添加 INC 指令原语。

第 71 / 356 · tests/chapter_01_cpu/test_071_instruction_inc.py

在本步骤中,只添加 emulator/cpu/instructions.py:inc。操作码导入、处理函数和表条目属于第 072-075 课。

本步骤存在的原因

INC 是一个内存读-改-写操作。将运算逻辑保留在单一指令原语中,可以让后续各个寻址模式处理函数只负责解析地址,再委托给相同的变更和标志位行为。

在 emulator/cpu/instructions.py 中的建议实现,插入到 sbc 之后:

def inc(cpu: CPU, address: int):
    value = cpu.bus.read(address)
    result = value + 1
    result_8 = result & 0xFF

    # Set flags
    cpu.flags.set_negative_flag((result_8 & 0b1000_0000) != 0)
    cpu.flags.set_zero_flag(result_8 == 0)

    # Set value on address
    cpu.bus.write(address, result_8)

不变量:address 是一个有效地址,而不是操作数值;字节通过 cpu.bus 进行读取和写入;掩码运算提供 8 位环绕;Zero 和 Negative 反映掩码后的结果;Carry、Overflow 以及 A/X/Y 保持不变。

常见误解:不要递增 A,也不要把 cpu.bus.read(address) 传给 inc。INC 自己负责内存的读取,并把结果写回同一地址。

范围之外:操作码接线不属于第 071 步;零页到绝对-X 的集成将在第 072-075 课中进行。

运行本课

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

示例实现

本步骤存在的原因

def inc(cpu: CPU, address: int):
    value = cpu.bus.read(address)
    result = value + 1
    result_8 = result & 0xFF

    # Set flags
    cpu.flags.set_negative_flag((result_8 & 0b1000_0000) != 0)
    cpu.flags.set_zero_flag(result_8 == 0)

    # Set value on address
    cpu.bus.write(address, result_8)

查看测试代码test_071_instruction_inc.py

import inspect

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


def test_inc_instruction_exists():
    """
    Objective:
    Create in instructions.py:
        def inc(cpu, address):
            ...

    Implementation shape:
        value = cpu.bus.read(address)
        result = value + 1
        result_8 = result & 0xFF

        cpu.bus.write(address, result_8)
        cpu.flags.set_zero_flag(result_8 == 0)
        cpu.flags.set_negative_flag((result_8 & 0x80) != 0)

    Important:
    INC receives an address, not a value.
    INC modifies memory, not A/X/Y directly.
    """
    assert hasattr(instructions, "inc")
    assert callable(instructions.inc)
    assert list(inspect.signature(instructions.inc).parameters) == ["cpu", "address"]


def test_inc_reads_memory_adds_one_and_writes_back():
    """
    Objective:
    inc(cpu, address) must increment the value stored at that address.

    Example:
    RAM[$0010] is 0x41.
    After INC, RAM[$0010] becomes 0x42.
    """
    cpu = make_cpu()
    cpu.bus.write(0x0010, 0x41)

    instructions.inc(cpu, 0x0010)

    assert cpu.bus.read(0x0010) == 0x42


def test_inc_wraps_from_ff_to_zero_and_sets_zero_flag():
    """
    Objective:
    INC works with 8-bit values.

    Example:
    0xFF + 1 becomes 0x00.
    Zero flag is set.
    """
    cpu = make_cpu()
    cpu.bus.write(0x0010, 0xFF)

    instructions.inc(cpu, 0x0010)

    assert cpu.bus.read(0x0010) == 0x00
    assert (cpu.p & ZERO_FLAG) != 0
    assert (cpu.p & NEGATIVE_FLAG) == 0


def test_inc_sets_negative_flag_when_result_has_bit_7_active():
    """
    Objective:
    INC updates the Negative flag from bit 7 of the result.

    Example:
    0x7F + 1 becomes 0x80.
    0x80 has bit 7 active, so Negative flag is set.
    """
    cpu = make_cpu()
    cpu.bus.write(0x0010, 0x7F)

    instructions.inc(cpu, 0x0010)

    assert cpu.bus.read(0x0010) == 0x80
    assert (cpu.p & NEGATIVE_FLAG) != 0
    assert (cpu.p & ZERO_FLAG) == 0


def test_inc_does_not_change_carry_or_overflow_flags():
    """
    Objective:
    INC only updates Zero and Negative flags.

    It must not modify Carry or Overflow.
    """
    cpu = make_cpu()
    cpu.bus.write(0x0010, 0x01)
    cpu.flags.set_carry_flag(True)
    cpu.flags.set_overflow_flag(True)

    instructions.inc(cpu, 0x0010)

    assert cpu.bus.read(0x0010) == 0x02
    assert cpu.flags.get_carry_flag() is True
    assert cpu.flags.get_overflow_flag() is True

测试函数 (5)

test_inc_instruction_exists
test_inc_reads_memory_adds_one_and_writes_back
test_inc_wraps_from_ff_to_zero_and_sets_zero_flag
test_inc_sets_negative_flag_when_result_has_bit_7_active
test_inc_does_not_change_carry_or_overflow_flags