053. Instrucción adc

Añadir la instrucción ADC independiente del modo de direccionamiento.

Lección 53 de 356 · tests/chapter_01_cpu/test_053_instruction_adc.py

Archivo a actualizar

emulator/cpu/instructions.py

Símbolo a crear

instructions.adc(cpu, value)

Por qué existe este paso

ADC es comportamiento aritmético, no decodificación de operandos. Acepta el valor ya resuelto por un manejador de opcode, lo suma a A junto con el Carry entrante, trunca el resultado a un byte y actualiza C, Z, N y V mediante el FlagsHandler del test 052.

Implementación de ejemplo completa

# 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

Invariantes importantes

el Carry entrante se lee antes de cambiar ninguna bandera
A almacena solo los ocho bits menos significativos de la suma completa
Carry indica desbordamiento sin signo; Overflow indica desbordamiento con signo
Zero y Negative se derivan del resultado truncado
las banderas no mencionadas arriba y los registros X/Y permanecen sin cambios

Concepto erróneo habitual

Carry y Overflow no son intercambiables. Carry proviene del bit 8 de la suma sin signo, mientras que Overflow ocurre cuando operandos del mismo signo producen un resultado de signo opuesto.

Fuera de alcance

todos los manejadores de modo de direccionamiento de ADC y las entradas de la tabla de opcodes
SBC y la aritmética en modo decimal
la contabilidad de ciclos

Referencia

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

Ejecutar esta lección

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

Implementación de ejemplo

Implementación de ejemplo completa

# 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

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

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