262. Вспомогательные функции стека CPU и импорты флагов

Отрефакторить поддержку прерываний CPU вокруг общих флагов и вспомогательных функций стека.

Урок 262 из 356 · tests/chapter_04_ppu_timing_and_vblank/test_262_cpu_stack_helpers_and_flag_imports.py

Файлы для обновления

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

Зачем нужен этот шаг

Перед реализацией и тестированием CPU.interrupt_nmi() ядру CPU нужны два небольших шага очистки:

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

Это шаг рефакторинга и вспомогательных функций, а ещё не тест поведения прерывания NMI.

Важный контекст

Старые тесты CPU часто объявляли локальные константы флагов. Это было допустимо, пока глава о CPU строилась постепенно. Теперь, когда прерываниям нужна корректная обработка байта состояния, общим источником истины должно стать:

emulator/cpu/flags_handler.py

Корректная раскладка битов состояния

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

Правило стека

push:
    write to $0100 | S
    decrement S

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

Пример предлагаемой реализации

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)

Почему pop_stack добавляется сейчас: CPU.interrupt_nmi() нужна только push_stack, но соответствующим тестам и будущей чистке кода прерываний CPU также понадобится явная вспомогательная функция для извлечения из стека. Добавление обеих вспомогательных функций сразу делает инвариант стека явным ещё до тестирования поведения NMI.

Выходит за рамки

поведение CPU.interrupt_nmi()
обработка запроса NMI от PPU
прерывания IRQ/APU/маппера
перевод всех старых стековых инструкций на эти вспомогательные функции

Запустить этот урок

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

Пример реализации

Корректная раскладка битов состояния

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

Пример предлагаемой реализации

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)

Показать код тестаtest_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

Тестовые функции (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