262. Helpers de pila de la CPU e importación de flags

Refactorizar el soporte de interrupciones de la CPU en torno a flags compartidos y helpers de pila.

Lección 262 de 356 · tests/chapter_04_ppu_timing_and_vblank/test_262_cpu_stack_helpers_and_flag_imports.py

Archivos a actualizar

emulator/cpu/cpu.py
emulator/cpu/flags_handler.py

Por qué existe este paso

Antes de implementar y probar CPU.interrupt_nmi(), el núcleo de la CPU necesita dos pequeñas piezas de limpieza:

1. CPU should import status flag constants from flags_handler.py.
2. CPU should expose stack helpers for interrupt code:
    push_stack(value)
    pop_stack() -> int

Este es un paso de refactorización/helpers, no la prueba del comportamiento de la interrupción NMI todavía.

Contexto importante

Las pruebas antiguas de la CPU a menudo declaraban constantes de flags locales. Eso estaba bien mientras el capítulo de la CPU se construía de forma incremental. Ahora que las interrupciones necesitan un manejo correcto del byte de estado, la fuente de verdad compartida debe ser:

emulator/cpu/flags_handler.py

Disposición correcta de los bits de estado

CARRY_FLAG      = 1 << 0
ZERO_FLAG       = 1 << 1
INTERRUPT_FLAG  = 1 << 2
DECIMAL_FLAG    = 1 << 3
B_FLAG          = 1 << 4
ONE_FLAG        = 1 << 5
OVERFLOW_FLAG   = 1 << 6
NEGATIVE_FLAG   = 1 << 7

Regla de la pila

push:
    write to $0100 | S
    decrement S

pop/pull:
    increment S
    read from $0100 | S

Ejemplo de implementación sugerido

from emulator.cpu.flags_handler import (
    B_FLAG,
    INTERRUPT_FLAG,
    NEGATIVE_FLAG,
    ONE_FLAG,
    ZERO_FLAG,
)

STACK_BASE = 0x0100

class CPU:
    ...

    def push_stack(self, value: int) -> None:
        self.bus.write(STACK_BASE | self.s, value & 0xFF)
        self.s = (self.s - 1) & 0xFF

    def pop_stack(self) -> int:
        self.s = (self.s + 1) & 0xFF
        return self.bus.read(STACK_BASE | self.s)

Por qué se añade pop_stack ahora: CPU.interrupt_nmi() solo necesita push_stack, pero las pruebas correspondientes y la futura limpieza de interrupciones de la CPU necesitan también un helper de extracción claro. Añadir ambos helpers juntos hace explícita la invariante de la pila antes de probar el comportamiento de NMI.

Fuera de alcance

Comportamiento de CPU.interrupt_nmi()
consumo de la solicitud NMI de la PPU
interrupciones IRQ/APU/mapper
refactorización de cada instrucción antigua de pila para usar estos helpers

Ejecutar esta lección

uv run pytest tests/chapter_04_ppu_timing_and_vblank/test_262_cpu_stack_helpers_and_flag_imports.py -v

Implementación de ejemplo

Disposición correcta de los bits de estado

CARRY_FLAG      = 1 << 0
ZERO_FLAG       = 1 << 1
INTERRUPT_FLAG  = 1 << 2
DECIMAL_FLAG    = 1 << 3
B_FLAG          = 1 << 4
ONE_FLAG        = 1 << 5
OVERFLOW_FLAG   = 1 << 6
NEGATIVE_FLAG   = 1 << 7

Ejemplo de implementación sugerido

from emulator.cpu.flags_handler import (
    B_FLAG,
    INTERRUPT_FLAG,
    NEGATIVE_FLAG,
    ONE_FLAG,
    ZERO_FLAG,
)

STACK_BASE = 0x0100

class CPU:
    ...

    def push_stack(self, value: int) -> None:
        self.bus.write(STACK_BASE | self.s, value & 0xFF)
        self.s = (self.s - 1) & 0xFF

    def pop_stack(self) -> int:
        self.s = (self.s + 1) & 0xFF
        return self.bus.read(STACK_BASE | self.s)

Ver código del testtest_262_cpu_stack_helpers_and_flag_imports.py

from emulator.cpu import cpu as cpu_module
from emulator.cpu.cpu import CPU
from emulator.cpu.flags_handler import (
    B_FLAG,
    CARRY_FLAG,
    DECIMAL_FLAG,
    INTERRUPT_FLAG,
    NEGATIVE_FLAG,
    ONE_FLAG,
    OVERFLOW_FLAG,
    ZERO_FLAG,
)
from tests.helpers import make_cpu


def test_cpu_uses_shared_status_flag_constants_from_flags_handler():
    """
    Objective:
    CPU interrupt code should use the corrected shared status flag constants from
    flags_handler.py, not stale local definitions.
    """
    assert CARRY_FLAG == 1 << 0
    assert ZERO_FLAG == 1 << 1
    assert INTERRUPT_FLAG == 1 << 2
    assert DECIMAL_FLAG == 1 << 3
    assert B_FLAG == 1 << 4
    assert ONE_FLAG == 1 << 5
    assert OVERFLOW_FLAG == 1 << 6
    assert NEGATIVE_FLAG == 1 << 7

    assert cpu_module.B_FLAG is B_FLAG
    assert cpu_module.ONE_FLAG is ONE_FLAG
    assert cpu_module.INTERRUPT_FLAG is INTERRUPT_FLAG


def test_cpu_declares_stack_base_constant():
    """
    Objective:
    Name the 6502 stack page used by CPU stack helpers.
    """
    assert cpu_module.STACK_BASE == 0x0100


def test_cpu_has_push_and_pop_stack_helpers():
    """
    Objective:
    CPU exposes shared stack helpers for interrupt code.
    """
    assert hasattr(CPU, "push_stack")
    assert callable(CPU.push_stack)
    assert hasattr(CPU, "pop_stack")
    assert callable(CPU.pop_stack)


def test_push_stack_writes_to_stack_page_and_decrements_stack_pointer():
    """
    Objective:
    push_stack writes to $0100 | S first, then decrements S.
    """
    cpu = make_cpu()
    cpu.s = 0xFD

    cpu.push_stack(0xAB)

    assert cpu.bus.read(0x01FD) == 0xAB
    assert cpu.s == 0xFC


def test_push_stack_masks_written_value_to_one_byte():
    """
    Objective:
    CPU stack stores bytes, so push_stack masks values to the low 8 bits.
    """
    cpu = make_cpu()
    cpu.s = 0xFD

    cpu.push_stack(0x1AB)

    assert cpu.bus.read(0x01FD) == 0xAB


def test_pop_stack_increments_stack_pointer_before_reading():
    """
    Objective:
    pop_stack follows 6502 pull behavior: increment S first, then read.
    """
    cpu = make_cpu()
    cpu.s = 0xFC
    cpu.bus.write(0x01FD, 0xCD)

    value = cpu.pop_stack()

    assert value == 0xCD
    assert cpu.s == 0xFD


def test_push_then_pop_stack_round_trips_value_and_restores_stack_pointer():
    """
    Objective:
    A value pushed to the stack should be read back by pop_stack, restoring S to
    its original value.
    """
    cpu = make_cpu()
    cpu.s = 0x80

    cpu.push_stack(0x42)
    value = cpu.pop_stack()

    assert value == 0x42
    assert cpu.s == 0x80


def test_stack_helpers_wrap_stack_pointer_to_8_bits():
    """
    Objective:
    S is an 8-bit stack pointer, so push/pop wrap around within page $0100.
    """
    cpu = make_cpu()
    cpu.s = 0x00

    cpu.push_stack(0x99)

    assert cpu.bus.read(0x0100) == 0x99
    assert cpu.s == 0xFF

    value = cpu.pop_stack()

    assert value == 0x99
    assert cpu.s == 0x00

Funciones de test (8)

test_cpu_uses_shared_status_flag_constants_from_flags_handler
test_cpu_declares_stack_base_constant
test_cpu_has_push_and_pop_stack_helpers
test_push_stack_writes_to_stack_page_and_decrements_stack_pointer
test_push_stack_masks_written_value_to_one_byte
test_pop_stack_increments_stack_pointer_before_reading
test_push_then_pop_stack_round_trips_value_and_restores_stack_pointer
test_stack_helpers_wrap_stack_pointer_to_8_bits