205. Gestor de flags: flag decimal

añadir soporte para el bit Decimal.

Lección 205 de 356 · tests/chapter_01_cpu/test_205_flags_handler_decimal_flag.py

Por qué existe este paso

En este paso, añade a `emulator/cpu/flags_handler.py los símbolos DECIMAL_FLAG, FlagsHandler.set_decimal_flag y FlagsHandler.get_decimal_flag`. El ayudante mantiene la manipulación del bit 3 dentro de la abstracción de estado necesaria para las siguientes operaciones de control de flags. La CPU de la NES conserva D aunque ADC/SBC no usen la aritmética BCD del 6502.

Implementación sugerida

DECIMAL_FLAG = 1 << 3

class FlagsHandler:
    def set_decimal_flag(self, enabled: bool):
        if enabled:
            self.cpu.p |= DECIMAL_FLAG
        else:
            self.cpu.p &= ~DECIMAL_FLAG

    def get_decimal_flag(self) -> bool:
        return bool(self.cpu.p & DECIMAL_FLAG)

Invariante: activar o desactivar D preserva todos los demás bits de P, especialmente el bit vecino Interrupt Disable. El error conceptual habitual es desactivar con `p &= DECIMAL_FLAG`, lo cual conserva D y destruye flags no relacionados.

Fuera de alcance: las funciones de instrucción y los mapeos de opcode corresponden a los pasos 206 y 207. No debe introducirse el comportamiento de modo decimal de ADC/SBC para la CPU de la NES.

Ejecutar esta lección

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

Implementación de ejemplo

Implementación sugerida

DECIMAL_FLAG = 1 << 3

class FlagsHandler:
    def set_decimal_flag(self, enabled: bool):
        if enabled:
            self.cpu.p |= DECIMAL_FLAG
        else:
            self.cpu.p &= ~DECIMAL_FLAG

    def get_decimal_flag(self) -> bool:
        return bool(self.cpu.p & DECIMAL_FLAG)

Ver código del testtest_205_flags_handler_decimal_flag.py

import inspect

from emulator.cpu.flags_handler import FlagsHandler
from tests.helpers import make_cpu


CARRY_FLAG = 1 << 0
ZERO_FLAG = 1 << 1
INTERRUPT_DISABLE_FLAG = 1 << 2
DECIMAL_FLAG = 1 << 3
OVERFLOW_FLAG = 1 << 6
NEGATIVE_FLAG = 1 << 7


def test_flags_handler_has_decimal_flag_helpers():
    """
    Objective:
    Add helpers for the Decimal flag.

    Required API:
        set_decimal_flag(enabled: bool)
        get_decimal_flag() -> bool

    Why:
    SED and CLD should not manipulate cpu.p directly. They should use
    FlagsHandler.
    """
    assert hasattr(FlagsHandler, "set_decimal_flag")
    assert hasattr(FlagsHandler, "get_decimal_flag")

    assert list(inspect.signature(FlagsHandler.set_decimal_flag).parameters) == [
        "self",
        "enabled",
    ]
    assert list(inspect.signature(FlagsHandler.get_decimal_flag).parameters) == ["self"]


def test_flags_handler_sets_and_clears_decimal_flag():
    """
    Objective:
    set_decimal_flag(True) sets bit 3.
    set_decimal_flag(False) clears bit 3.
    """
    cpu = make_cpu()

    cpu.flags.set_decimal_flag(True)
    assert (cpu.p & DECIMAL_FLAG) != 0
    assert cpu.flags.get_decimal_flag() is True

    cpu.flags.set_decimal_flag(False)
    assert (cpu.p & DECIMAL_FLAG) == 0
    assert cpu.flags.get_decimal_flag() is False


def test_clearing_decimal_flag_preserves_other_flags():
    """
    Objective:
    Clearing Decimal must not erase Carry, Zero, Interrupt Disable, Overflow, or
    Negative.

    Failure mode this catches:
        self.cpu.p &= DECIMAL_FLAG

    That keeps only the Decimal bit and clears everything else.
    """
    cpu = make_cpu()
    other_flags = CARRY_FLAG | ZERO_FLAG | INTERRUPT_DISABLE_FLAG | OVERFLOW_FLAG | NEGATIVE_FLAG
    cpu.p = other_flags | DECIMAL_FLAG

    cpu.flags.set_decimal_flag(False)

    assert (cpu.p & DECIMAL_FLAG) == 0
    assert (cpu.p & other_flags) == other_flags


def test_setting_decimal_flag_preserves_other_flags():
    """
    Objective:
    Setting Decimal must add bit 3 without damaging existing status flags.
    """
    cpu = make_cpu()
    other_flags = CARRY_FLAG | ZERO_FLAG | OVERFLOW_FLAG | NEGATIVE_FLAG
    cpu.p = other_flags

    cpu.flags.set_decimal_flag(True)

    assert (cpu.p & DECIMAL_FLAG) != 0
    assert (cpu.p & other_flags) == other_flags


def test_decimal_flag_is_independent_from_interrupt_disable_flag():
    """
    Objective:
    Decimal and Interrupt Disable are neighboring bits, but they are different
    flags.

        I flag = bit 2
        D flag = bit 3

    Setting or clearing one must not toggle the other.
    """
    cpu = make_cpu()

    cpu.flags.set_interrupt_disable_flag(True)
    assert cpu.flags.get_interrupt_disable_flag() is True
    assert cpu.flags.get_decimal_flag() is False

    cpu.flags.set_decimal_flag(True)
    assert cpu.flags.get_interrupt_disable_flag() is True
    assert cpu.flags.get_decimal_flag() is True

    cpu.flags.set_decimal_flag(False)
    assert cpu.flags.get_interrupt_disable_flag() is True
    assert cpu.flags.get_decimal_flag() is False

Funciones de test (5)

test_flags_handler_has_decimal_flag_helpers
test_flags_handler_sets_and_clears_decimal_flag
test_clearing_decimal_flag_preserves_other_flags
test_setting_decimal_flag_preserves_other_flags
test_decimal_flag_is_independent_from_interrupt_disable_flag