053. 指令 adc

添加与寻址方式无关的 ADC 指令。

第 53 / 356 · tests/chapter_01_cpu/test_053_instruction_adc.py

要更新的文件

emulator/cpu/instructions.py

要创建的符号

instructions.adc(cpu, value)

为什么需要这一步

ADC 是算术行为，而不是操作数解码。它接收已由操作码处理函数解析好的值，将其连同传入的 Carry 一起加到 A 上，把结果截断为一个字节，并通过测试 052 的 FlagsHandler 更新 C、Z、N 和 V。

完整示例实现

# emulator/cpu/instructions.py
def adc(cpu, value: int):
    carry = int(cpu.flags.get_carry_flag())
    old_a = cpu.a
    total = old_a + value + carry
    result = total & 0xFF

    cpu.flags.set_carry_flag(total > 0xFF)
    cpu.flags.set_zero_flag(result == 0)
    cpu.flags.set_negative_flag((result & 0x80) != 0)
    overflow = (result ^ old_a) & (result ^ value) & 0x80
    cpu.flags.set_overflow_flag(overflow != 0)
    cpu.a = result

重要不变量

在任何标志位被修改之前先读取传入的 Carry
A 只保存完整和的低八位
Carry 报告无符号溢出；Overflow 报告有符号溢出
Zero 和 Negative 由截断后的结果得出
上文未提到的标志位以及 X/Y 寄存器保持不变

常见误区

Carry 与 Overflow 不可互换。Carry 来自无符号和的第 8 位，而 Overflow 则出现在同号操作数产生符号相反结果的时候。

范围之外

所有 ADC 寻址模式处理函数及操作码表条目
SBC 与十进制模式算术
周期计数

参考

https://www.nesdev.org/wiki/Instruction_reference#ADC

运行本课

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

示例实现

完整示例实现

# emulator/cpu/instructions.py
def adc(cpu, value: int):
    carry = int(cpu.flags.get_carry_flag())
    old_a = cpu.a
    total = old_a + value + carry
    result = total & 0xFF

    cpu.flags.set_carry_flag(total > 0xFF)
    cpu.flags.set_zero_flag(result == 0)
    cpu.flags.set_negative_flag((result & 0x80) != 0)
    overflow = (result ^ old_a) & (result ^ value) & 0x80
    cpu.flags.set_overflow_flag(overflow != 0)
    cpu.a = result

查看测试代码test_053_instruction_adc.py

import inspect

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


def test_adc_instruction_exists():
    """
    Objective:
    Create in instructions.py:
        def adc(cpu, value):
            ...

    What it does:
    - Read the current Carry flag.
    - Add A + value + carry.
    - Store only the low 8 bits in A.
    - Update flags: C, Z, N, V.

    Example:
        A = 0x01
        value = 0x02
        Carry = 0
        result = 0x03
    """
    assert hasattr(instructions, "adc")
    assert callable(instructions.adc)
    assert list(inspect.signature(instructions.adc).parameters) == ["cpu", "value"]


def test_adc_adds_value_to_register_a_without_carry_in():
    """
    Objective:
    ADC must add value to register A.

    Example:
    A is 0x10.
    value is 0x05.
    Carry is clear.
    A becomes 0x15.
    """
    cpu = make_cpu()
    cpu.a = 0x10
    cpu.flags.set_carry_flag(False)

    instructions.adc(cpu, 0x05)

    assert cpu.a == 0x15
    assert cpu.flags.get_carry_flag() is False
    assert cpu.flags.get_zero_flag() is False
    assert cpu.flags.get_negative_flag() is False
    assert cpu.flags.get_overflow_flag() is False


def test_adc_includes_carry_in():
    """
    Objective:
    ADC must include the old Carry flag in the addition.

    Example:
    A is 0x10.
    value is 0x05.
    Carry is set.
    A becomes 0x16.
    """
    cpu = make_cpu()
    cpu.a = 0x10
    cpu.flags.set_carry_flag(True)

    instructions.adc(cpu, 0x05)

    assert cpu.a == 0x16


def test_adc_sets_carry_flag_when_result_is_bigger_than_8_bits():
    """
    Objective:
    If the full result is greater than 0xFF, Carry flag must be set.

    Example:
    0xFF + 0x01 = 0x100.
    A stores only 0x00.
    Carry is set.
    Zero is set.
    """
    cpu = make_cpu()
    cpu.a = 0xFF
    cpu.flags.set_carry_flag(False)

    instructions.adc(cpu, 0x01)

    assert cpu.a == 0x00
    assert cpu.flags.get_carry_flag() is True
    assert cpu.flags.get_zero_flag() is True
    assert cpu.flags.get_negative_flag() is False


def test_adc_sets_negative_flag_from_bit_7_of_8_bit_result():
    """
    Objective:
    Negative flag follows bit 7 of the 8-bit result.

    Example:
    0x40 + 0x40 = 0x80.
    Bit 7 is active, so Negative is set.
    """
    cpu = make_cpu()
    cpu.a = 0x40
    cpu.flags.set_carry_flag(False)

    instructions.adc(cpu, 0x40)

    assert cpu.a == 0x80
    assert cpu.flags.get_negative_flag() is True


def test_adc_sets_overflow_flag_on_signed_positive_overflow():
    """
    Objective:
    Overflow flag is set when signed addition overflows.

    Reference formula:
        (result ^ A) & (result ^ value) & 0x80

    Example:
    0x7F is +127.
    0x01 is +1.
    0x7F + 0x01 = 0x80.

    As signed 8-bit numbers, +127 + +1 cannot fit.
    Overflow is set.
    """
    cpu = make_cpu()
    cpu.a = 0x7F
    cpu.flags.set_carry_flag(False)

    instructions.adc(cpu, 0x01)

    assert cpu.a == 0x80
    assert cpu.flags.get_overflow_flag() is True
    assert cpu.flags.get_negative_flag() is True
    assert cpu.flags.get_carry_flag() is False


def test_adc_sets_overflow_flag_on_signed_negative_overflow():
    """
    Objective:
    Overflow also happens when two negative numbers produce a positive result.

    Example:
    0x80 is -128 as signed 8-bit.
    0x80 + 0x80 = 0x00 with Carry.
    Signed result cannot fit, so Overflow is set.
    """
    cpu = make_cpu()
    cpu.a = 0x80
    cpu.flags.set_carry_flag(False)

    instructions.adc(cpu, 0x80)

    assert cpu.a == 0x00
    assert cpu.flags.get_carry_flag() is True
    assert cpu.flags.get_zero_flag() is True
    assert cpu.flags.get_overflow_flag() is True
    assert cpu.flags.get_negative_flag() is False


def test_adc_clears_overflow_when_signs_are_different():
    """
    Objective:
    Adding values with different signs does not create signed overflow.

    Example:
    0x7F is positive.
    0xFF is negative (-1 as signed 8-bit).
    Result is 0x7E.
    Overflow is clear.
    """
    cpu = make_cpu()
    cpu.a = 0x7F
    cpu.flags.set_carry_flag(False)
    cpu.flags.set_overflow_flag(True)

    instructions.adc(cpu, 0xFF)

    assert cpu.a == 0x7E
    assert cpu.flags.get_overflow_flag() is False
    assert cpu.flags.get_carry_flag() is True

测试函数 (8)

test_adc_instruction_exists
test_adc_adds_value_to_register_a_without_carry_in
test_adc_includes_carry_in
test_adc_sets_carry_flag_when_result_is_bigger_than_8_bits
test_adc_sets_negative_flag_from_bit_7_of_8_bit_result
test_adc_sets_overflow_flag_on_signed_positive_overflow
test_adc_sets_overflow_flag_on_signed_negative_overflow
test_adc_clears_overflow_when_signs_are_different