205. 标志处理器 Decimal 标志

添加 Decimal 位支持。

第 205 / 356 · tests/chapter_01_cpu/test_205_flags_handler_decimal_flag.py

本步骤存在的原因

在本步骤中，添加 `emulator/cpu/flags_handler.py 中的符号 DECIMAL_FLAG、FlagsHandler.set_decimal_flag 以及 FlagsHandler.get_decimal_flag`。该辅助函数将第 3 位的操作保留在状态抽象层内，供后续的标志控制操作使用。尽管 ADC/SBC 并不使用 6502 的 BCD 运算，NES CPU 仍然保留了 D 位。

建议实现

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)

不变式：设置或清除 D 位会保留 P 中的所有其他位，尤其是相邻的 Interrupt Disable 位。常见的误解是使用 `p &= DECIMAL_FLAG` 来清除，这会保留 D 位并破坏无关的标志。

范围之外：指令函数和操作码映射属于步骤 206 和 207。不得为 NES CPU 引入 Decimal 模式的 ADC/SBC 行为。

运行本课

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

示例实现

建议实现

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)

查看测试代码test_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

测试函数 (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