062. Instruction sbc

Добавляем базовую инструкцию SBC.

Урок 62 из 356 · tests/chapter_01_cpu/test_062_instruction_sbc.py

Файл для обновления

emulator/cpu/instructions.py

Символ для добавления

instructions.sbc

Зачем нужен этот шаг

SBC вводится как базовая инструкция вычитания, работающая со значением, до подключения какого-либо опкода. Флаг Carry в 6502 означает «нет заёма», поэтому вычитание можно реализовать как сложение восьмибитного дополнения операнда с 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 следует из знакового вычитания, а не из беззнакового заёма

Распространённое заблуждение

Необработанное ~value в Python отрицательно, поскольку целые числа не ограничены. Замаскируйте его через & 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