188. Manejador de flags de interrupción y de break

añadir los ayudantes para las flags I, B y el bit no usado.

Lección 188 de 356 · tests/chapter_01_cpu/test_188_flags_handler_interrupt_and_break_flags.py

En este paso, define Break como el bit 4 y el bit no usado del estado apilado como el bit 5. Añade a `emulator/cpu/flags_handler.py`:

INTERRUPT_FLAG = 1 << 2
B_FLAG = 1 << 4
ONE_FLAG = 1 << 5

def set_interrupt_disable_flag(self, enabled: bool):
    if enabled:
        self.cpu.p |= INTERRUPT_FLAG
    else:
        self.cpu.p &= ~INTERRUPT_FLAG

def set_break_flag(self, enabled: bool):
    if enabled:
        self.cpu.p |= B_FLAG
    else:
        self.cpu.p &= ~B_FLAG

def set_one_flag(self, enabled: bool):
    if enabled:
        self.cpu.p |= ONE_FLAG
    else:
        self.cpu.p &= ~ONE_FLAG

def get_interrupt_disable_flag(self) -> bool:
    return bool(self.cpu.p & INTERRUPT_FLAG)

def get_break_flag(self) -> bool:
    return bool(self.cpu.p & B_FLAG)

def get_one_flag(self) -> bool:
    return bool(self.cpu.p & ONE_FLAG)

Por qué existe este paso

Nos estamos preparando para implementar BRK.

BRK es una instrucción de interrupción por software. Para implementarla con claridad, la CPU necesita ayudantes para dos flags de estado:

I flag -> Interrupt Disable, bit 2
B flag -> Break, bit 4
ONE flag -> unused/status bit 5 used in pushed status bytes

BRK las necesitará porque

activa la flag de Interrupt Disable después de entrar en el manejador de interrupción
apila un byte de estado con la flag de Break activada

Objetivo de diseño

Mantener la manipulación de bits dentro de FlagsHandler en lugar de repartir operaciones directas sobre los bits de cpu.p por todo el código de las instrucciones.

Terminología importante

Interrupt Disable flag:
    When set, maskable IRQ interrupts are disabled.

Break flag:
    Used to mark that the pushed status byte came from BRK.

Error común

No confundas el opcode BRK con la flag Break.

BRK opcode: 0x00, the instruction byte in memory
B flag:     bit 4 inside the status byte pushed to the stack
ONE flag:   bit 5, usually set in pushed status bytes

Justificación: los métodos de asignación con nombre centralizan operaciones independientes de lectura-modificación-escritura sobre P, y los métodos de lectura exponen valores booleanos. Invariantes: cada método de asignación cambia solo su bit; I, B, ONE y el resto de flags existentes permanecen independientes. Concepto erróneo: B y el bit siempre a uno del estado apilado no son el mismo bit, y el opcode $00 tampoco lo es.

Fuera de alcance: este paso no implementa BRK ni decide cuándo se activan los bits; eso son los pasos 189-190. RTI/PHP/PLP, el comportamiento de NMI, y los ayudantes de pila de la CPU quedan para trabajo posterior.

Ejecutar esta lección

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

Implementación de ejemplo

INTERRUPT_FLAG = 1 << 2
B_FLAG = 1 << 4
ONE_FLAG = 1 << 5

def set_interrupt_disable_flag(self, enabled: bool):
    if enabled:
        self.cpu.p |= INTERRUPT_FLAG
    else:
        self.cpu.p &= ~INTERRUPT_FLAG

def set_break_flag(self, enabled: bool):
    if enabled:
        self.cpu.p |= B_FLAG
    else:
        self.cpu.p &= ~B_FLAG

def set_one_flag(self, enabled: bool):
    if enabled:
        self.cpu.p |= ONE_FLAG
    else:
        self.cpu.p &= ~ONE_FLAG

def get_interrupt_disable_flag(self) -> bool:
    return bool(self.cpu.p & INTERRUPT_FLAG)

def get_break_flag(self) -> bool:
    return bool(self.cpu.p & B_FLAG)

def get_one_flag(self) -> bool:
    return bool(self.cpu.p & ONE_FLAG)

Ver código del testtest_188_flags_handler_interrupt_and_break_flags.py

import inspect

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


INTERRUPT_DISABLE_FLAG = 1 << 2
BREAK_FLAG = 1 << 4
ONE_FLAG = 1 << 5


def test_flags_handler_has_interrupt_disable_helpers():
    """
    Objective:
    Add helpers for the Interrupt Disable flag.

    Required API:
        set_interrupt_disable_flag(enabled: bool)
        get_interrupt_disable_flag() -> bool

    Why:
    BRK must set the Interrupt Disable flag after it begins interrupt handling.
    """
    assert hasattr(FlagsHandler, "set_interrupt_disable_flag")
    assert hasattr(FlagsHandler, "get_interrupt_disable_flag")

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


def test_flags_handler_has_break_flag_helpers():
    """
    Objective:
    Add helpers for the Break flag.

    Required API:
        set_break_flag(enabled: bool)
        get_break_flag() -> bool

    Why:
    BRK pushes a status byte with the Break flag set.
    """
    assert hasattr(FlagsHandler, "set_break_flag")
    assert hasattr(FlagsHandler, "get_break_flag")

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


def test_flags_handler_has_one_flag_helpers():
    """
    Objective:
    Add helpers for the ONE/unused status bit.

    Required API:
        set_one_flag(enabled: bool)
        get_one_flag() -> bool

    Why:
    BRK/PHP/NMI pushed status bytes should have bit 5 set even though this bit has
    no normal CPU behavior effect.
    """
    assert hasattr(FlagsHandler, "set_one_flag")
    assert hasattr(FlagsHandler, "get_one_flag")

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


def test_flags_handler_sets_and_clears_interrupt_disable_flag():
    """
    Objective:
    set_interrupt_disable_flag(True) sets bit 2.
    set_interrupt_disable_flag(False) clears bit 2.

    Mental model:
    The flag helper does not decide when interrupts should be disabled.
    Instructions decide the condition. The helper only changes the bit.
    """
    cpu = make_cpu()

    cpu.flags.set_interrupt_disable_flag(True)
    assert (cpu.p & INTERRUPT_DISABLE_FLAG) != 0
    assert cpu.flags.get_interrupt_disable_flag() is True

    cpu.flags.set_interrupt_disable_flag(False)
    assert (cpu.p & INTERRUPT_DISABLE_FLAG) == 0
    assert cpu.flags.get_interrupt_disable_flag() is False


def test_flags_handler_sets_and_clears_break_flag():
    """
    Objective:
    set_break_flag(True) sets bit 4.
    set_break_flag(False) clears bit 4.

    Why this matters for BRK:
    The pushed status byte must indicate that the interrupt came from BRK.
    """
    cpu = make_cpu()

    cpu.flags.set_break_flag(True)
    assert (cpu.p & BREAK_FLAG) != 0
    assert cpu.flags.get_break_flag() is True

    cpu.flags.set_break_flag(False)
    assert (cpu.p & BREAK_FLAG) == 0
    assert cpu.flags.get_break_flag() is False


def test_flags_handler_sets_and_clears_one_flag():
    """
    Objective:
    set_one_flag(True) sets bit 5.
    set_one_flag(False) clears bit 5.

    Why this matters:
    Bit 5 is forced into pushed status bytes, but it is distinct from the Break
    flag at bit 4.
    """
    cpu = make_cpu()

    cpu.flags.set_one_flag(True)
    assert (cpu.p & ONE_FLAG) != 0
    assert cpu.flags.get_one_flag() is True

    cpu.flags.set_one_flag(False)
    assert (cpu.p & ONE_FLAG) == 0
    assert cpu.flags.get_one_flag() is False


def test_interrupt_disable_and_break_helpers_preserve_other_flags():
    """
    Objective:
    Changing I or B must not accidentally damage other status flags.

    Failure mode this catches:
    A setter that assigns cpu.p directly, like cpu.p = INTERRUPT_DISABLE_FLAG,
    would erase existing flags such as Carry, Zero, Overflow, or Negative.
    """
    cpu = make_cpu()
    other_flags = 0b1100_0011
    cpu.p = other_flags

    cpu.flags.set_interrupt_disable_flag(True)
    cpu.flags.set_break_flag(True)

    assert (cpu.p & other_flags) == other_flags
    assert (cpu.p & INTERRUPT_DISABLE_FLAG) != 0
    assert (cpu.p & BREAK_FLAG) != 0

    cpu.flags.set_interrupt_disable_flag(False)
    cpu.flags.set_break_flag(False)

    assert (cpu.p & other_flags) == other_flags
    assert (cpu.p & INTERRUPT_DISABLE_FLAG) == 0
    assert (cpu.p & BREAK_FLAG) == 0


def test_interrupt_disable_and_break_flags_are_independent():
    """
    Objective:
    The I flag and B flag are different bits and must not toggle each other.

    Why:
    BRK needs both concepts, but they mean different things:
        I flag: disables maskable IRQ interrupts
        B flag: marks BRK in the pushed status byte
    """
    cpu = make_cpu()

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

    cpu.flags.set_break_flag(True)
    assert cpu.flags.get_interrupt_disable_flag() is True
    assert cpu.flags.get_break_flag() is True

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

Funciones de test (8)

test_flags_handler_has_interrupt_disable_helpers
test_flags_handler_has_break_flag_helpers
test_flags_handler_has_one_flag_helpers
test_flags_handler_sets_and_clears_interrupt_disable_flag
test_flags_handler_sets_and_clears_break_flag
test_flags_handler_sets_and_clears_one_flag
test_interrupt_disable_and_break_helpers_preserve_other_flags
test_interrupt_disable_and_break_flags_are_independent