062. Instruction sbc

Añadir la instrucción central SBC.

Lección 62 de 356 · tests/chapter_01_cpu/test_062_instruction_sbc.py

Archivo a actualizar

emulator/cpu/instructions.py

Símbolo a añadir

instructions.sbc

Por qué existe este paso

SBC introduce la resta como instrucción central basada en valores antes de conectar ningún opcode. En el 6502, la flag de Carry significa "sin préstamo", por lo que la resta puede implementarse como la suma del complemento de ocho bits del operando más Carry.

Implementación de ejemplo completa

# 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

Invariantes importantes

con Carry activado se resta solo value; con Carry desactivado se resta uno adicional
A se reduce al resultado final de ocho bits
Carry se activa exactamente cuando no se produce préstamo
Zero y Negative siguen el resultado final de ocho bits
Overflow sigue la resta con signo, no el préstamo sin signo

Concepto erróneo común

El ~value sin procesar de Python es negativo porque los enteros no tienen límite. Enmascáralo con & 0xFF antes de sumar; tampoco trates Carry como un bit de préstamo convencional.

Fuera de alcance

todos los manejadores de opcode de SBC y las entradas de la tabla de opcodes
obtener operandos o seleccionar modos de direccionamiento dentro de sbc
la aritmética en modo decimal y la temporización de ciclos

Referencia

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

Ejecutar esta lección

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

Implementación de ejemplo

Implementación de ejemplo completa

# 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

Ver código del testtest_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

Funciones de test (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