062. SBC 指令

添加核心 SBC 指令。

第 62 / 356 · tests/chapter_01_cpu/test_062_instruction_sbc.py

要更新的文件

emulator/cpu/instructions.py

要添加的符号

instructions.sbc

为什么需要这一步

SBC 在接入任何操作码之前，先把减法作为一种基于数值的核心指令引入。6502 的 Carry 标志表示“无借位”，因此减法可以通过将操作数的八位补码与 Carry 相加来实现。

完整示例实现

# emulator/cpu/instructions.py
def sbc(cpu: CPU, value: int):
    carry = int(cpu.flags.get_carry_flag())
    a = cpu.a
    value_inverted = (~value) & 0xFF
    result = a + value_inverted + carry
    result_8 = result & 0xFF

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

重要不变量

Carry 置位时只减去 value；Carry 清零时会多减一
A 被缩减为最终的八位结果
当且仅当无借位时 Carry 才被置位
Zero 和 Negative 反映最终的八位结果
Overflow 反映有符号减法，而非无符号借位

常见误解

Python 中 ~value 的原始结果是一个负数，因为整数没有位数限制。相加之前要用 & 0xFF 对它做掩码处理；另外，不要把 Carry 当作常规的借位比特。

范围之外

每个 SBC 操作码处理函数和操作码表条目
在 sbc 内部取操作数或选择寻址模式
十进制模式运算和周期时序

参考

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

运行本课

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

示例实现

完整示例实现

# emulator/cpu/instructions.py
def sbc(cpu: CPU, value: int):
    carry = int(cpu.flags.get_carry_flag())
    a = cpu.a
    value_inverted = (~value) & 0xFF
    result = a + value_inverted + carry
    result_8 = result & 0xFF

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

查看测试代码test_062_instruction_sbc.py

import inspect

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


def test_sbc_instruction_exists():
    """
    Objective:
    Create in instructions.py:
        def sbc(cpu, value):
            ...

    Implementation shape:
        carry = int(cpu.flags.get_carry_flag())
        a = cpu.a
        value_inverted = (~value) & 0xFF
        result = a + value_inverted + carry
        result_8 = result & 0xFF

        cpu.flags.set_carry_flag(result > 0xFF)
        cpu.flags.set_zero_flag(result_8 == 0)
        cpu.flags.set_negative_flag((result_8 & 0x80) != 0)

        overflow = ((result_8 ^ a) & (result_8 ^ value_inverted) & 0x80) != 0
        cpu.flags.set_overflow_flag(overflow)

        cpu.a = result_8
    """
    assert hasattr(instructions, "sbc")
    assert callable(instructions.sbc)
    assert list(inspect.signature(instructions.sbc).parameters) == ["cpu", "value"]


def test_sbc_subtracts_value_when_carry_is_set():
    """
    Objective:
    If Carry is set, SBC subtracts only the value.

    Mental model:
        SBC = A - value - (1 - Carry)

    Example:
        A = 0x10
        value = 0x01
        Carry = 1
        result = 0x0F
    """
    cpu = make_cpu()
    cpu.a = 0x10
    cpu.flags.set_carry_flag(True)

    instructions.sbc(cpu, 0x01)

    assert cpu.a == 0x0F
    assert cpu.flags.get_carry_flag() is True
    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_sbc_subtracts_extra_one_when_carry_is_clear():
    """
    Objective:
    If Carry is clear, SBC subtracts value + 1.

    This is the confusing part:
    Carry clear means there is a borrow.

    Example:
        A = 0x10
        value = 0x01
        Carry = 0
        result = 0x0E
    """
    cpu = make_cpu()
    cpu.a = 0x10
    cpu.flags.set_carry_flag(False)

    instructions.sbc(cpu, 0x01)

    assert cpu.a == 0x0E
    assert cpu.flags.get_carry_flag() is True


def test_sbc_clears_carry_flag_when_borrow_happens():
    """
    Objective:
    Carry flag is clear when subtraction needs a borrow.

    Example:
        A = 0x00
        value = 0x01
        Carry = 1

    Math:
        0x00 - 0x01 = -1

    8-bit result:
        0xFF

    Carry:
        clear, because borrow happened.
    """
    cpu = make_cpu()
    cpu.a = 0x00
    cpu.flags.set_carry_flag(True)

    instructions.sbc(cpu, 0x01)

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


def test_sbc_sets_zero_flag_when_8_bit_result_is_zero():
    """
    Objective:
    Zero flag follows the final 8-bit result.

    Example:
        A = 0x01
        value = 0x01
        Carry = 1
        result = 0x00
    """
    cpu = make_cpu()
    cpu.a = 0x01
    cpu.flags.set_carry_flag(True)

    instructions.sbc(cpu, 0x01)

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


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

    Example:
        A = 0x00
        value = 0x01
        Carry = 1
        result = 0xFF

    0xFF has bit 7 active, so Negative is set.
    """
    cpu = make_cpu()
    cpu.a = 0x00
    cpu.flags.set_carry_flag(True)

    instructions.sbc(cpu, 0x01)

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


def test_sbc_sets_overflow_on_signed_positive_minus_negative_overflow():
    """
    Objective:
    Overflow is set when signed subtraction cannot fit in 8 bits.

    Example:
        A = 0x7F   # +127
        value = 0xFF  # -1 signed
        Carry = 1

    Signed math:
        +127 - (-1) = +128

    +128 cannot fit in signed 8-bit, so Overflow is set.

    With inverted-value implementation:
        value_inverted = (~value) & 0xFF
        overflow = ((result_8 ^ A) & (result_8 ^ value_inverted) & 0x80) != 0
    """
    cpu = make_cpu()
    cpu.a = 0x7F
    cpu.flags.set_carry_flag(True)

    instructions.sbc(cpu, 0xFF)

    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_sbc_sets_overflow_on_signed_negative_minus_positive_overflow():
    """
    Objective:
    Overflow is also set when a negative minus a positive becomes positive.

    Example:
        A = 0x80      # -128 signed
        value = 0x01  # +1 signed
        Carry = 1

    Signed math:
        -128 - +1 = -129

    -129 cannot fit in signed 8-bit, so Overflow is set.
    Final 8-bit result is 0x7F.
    """
    cpu = make_cpu()
    cpu.a = 0x80
    cpu.flags.set_carry_flag(True)

    instructions.sbc(cpu, 0x01)

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


def test_sbc_clears_overflow_when_signed_result_fits():
    """
    Objective:
    Overflow is clear when the signed result fits.

    Example:
        A = 0x10
        value = 0x01
        Carry = 1
        result = 0x0F
    """
    cpu = make_cpu()
    cpu.a = 0x10
    cpu.flags.set_carry_flag(True)
    cpu.flags.set_overflow_flag(True)

    instructions.sbc(cpu, 0x01)

    assert cpu.a == 0x0F
    assert cpu.flags.get_overflow_flag() is False


def test_sbc_masks_python_inverted_value_to_8_bits():
    """
    Objective:
    The implementation must not use raw Python ~value directly.

    Python behavior:
        ~0x01 == -2

    NES 8-bit behavior expected:
        ~0x01 should behave like 0xFE

    Required implementation idea:
        value_inverted = (~value) & 0xFF

    This test is a proof case:
        A = 0x10
        value = 0x01
        Carry = 1
        result must be 0x0F
    """
    cpu = make_cpu()
    cpu.a = 0x10
    cpu.flags.set_carry_flag(True)

    instructions.sbc(cpu, 0x01)

    assert cpu.a == 0x0F

测试函数 (10)

test_sbc_instruction_exists
test_sbc_subtracts_value_when_carry_is_set
test_sbc_subtracts_extra_one_when_carry_is_clear
test_sbc_clears_carry_flag_when_borrow_happens
test_sbc_sets_zero_flag_when_8_bit_result_is_zero
test_sbc_sets_negative_flag_from_bit_7_of_8_bit_result
test_sbc_sets_overflow_on_signed_positive_minus_negative_overflow
test_sbc_sets_overflow_on_signed_negative_minus_positive_overflow
test_sbc_clears_overflow_when_signed_result_fits
test_sbc_masks_python_inverted_value_to_8_bits