249. Ppudata 读取缓冲区

实现 PPUDATA ($2007) 的缓冲读取行为。

第 249 / 356 · tests/chapter_03_ppu_memory_and_graphics_data/test_249_ppudata_read_buffer.py

参考资料

https://www.nesdev.org/wiki/PPU_registers#PPUDATA

要更新的文件

emulator/ppu/ppu.py

要添加的状态

ppu_data_buffer: int = 0

为什么需要这一步

PPUDATA 不是普通的简单寄存器。它是一个通向 PPU 内存的 CPU 可见端口。对于大多数 PPU 内存读取,NES 会返回旧的内部读取缓冲区,然后再从当前的 PPU 内存地址重新加载该缓冲区。

正常的缓冲读取行为

read $2007:
    value = ppu_data_buffer
    ppu_data_buffer = ppu_bus.read(vram_addr)
    vram_addr += increment
    return value

这意味着第一次读取通常返回的是过时/陈旧的缓冲区数据,而第二次读取返回的是由第一次读取所加载的那个字节。

示例

ppu_bus[$2000] = $AA
ppu_bus[$2001] = $BB
ppu_data_buffer = $00
vram_addr = $2000

read $2007 -> returns $00, buffer becomes $AA, vram_addr becomes $2001
read $2007 -> returns $AA, buffer becomes $BB, vram_addr becomes $2002

兼容/调试字段

较早的教程模型曾把 data 当作一个简单的 PPUDATA 值。请把 self.data 保留为一个兼容/调试字段,其中包含最近一次

PPUDATA 读取所返回的值,但真实的行为应当使用

ppu_data_buffer
ppu_bus.read(vram_addr)

建议的实现伪代码

@dataclass
class PPU:
    ...
    data: int = 0  # Compatibility/debug: last PPUDATA value
    ppu_data_buffer: int = 0

    def read_register(self, addr: int) -> int:
        match addr:
            ...
            case 0x2007:
                value = self.ppu_data_buffer
                self.ppu_data_buffer = self.ppu_bus.read(self.vram_addr)

                increment = 32 if self.ctrl & CTRL_VRAM_INCREMENT_BY_32 else 1
                self.vram_addr = (self.vram_addr + increment) & 0x3FFF

                # Preserve old compatibility/debug field.
                self.data = value
                return self.data

关于未来的重要说明

在真实硬件上,从 $3F00-$3FFF 进行的调色板读取是一个例外。这类读取会立即返回调色板字节,而不是返回延迟的缓冲区值。本测试有意不实现该例外。

超出范围

调色板读取例外
调色板 RAM 精度
PPUDATA 写入,此前已测试过

运行本课

uv run pytest tests/chapter_03_ppu_memory_and_graphics_data/test_249_ppudata_read_buffer.py -v

示例实现

正常的缓冲读取行为

read $2007:
    value = ppu_data_buffer
    ppu_data_buffer = ppu_bus.read(vram_addr)
    vram_addr += increment
    return value

示例

ppu_bus[$2000] = $AA
ppu_bus[$2001] = $BB
ppu_data_buffer = $00
vram_addr = $2000

read $2007 -> returns $00, buffer becomes $AA, vram_addr becomes $2001
read $2007 -> returns $AA, buffer becomes $BB, vram_addr becomes $2002

建议的实现伪代码

@dataclass
class PPU:
    ...
    data: int = 0  # Compatibility/debug: last PPUDATA value
    ppu_data_buffer: int = 0

    def read_register(self, addr: int) -> int:
        match addr:
            ...
            case 0x2007:
                value = self.ppu_data_buffer
                self.ppu_data_buffer = self.ppu_bus.read(self.vram_addr)

                increment = 32 if self.ctrl & CTRL_VRAM_INCREMENT_BY_32 else 1
                self.vram_addr = (self.vram_addr + increment) & 0x3FFF

                # Preserve old compatibility/debug field.
                self.data = value
                return self.data

查看测试代码test_249_ppudata_read_buffer.py

from emulator.ppu.ppu import CTRL_VRAM_INCREMENT_BY_32, PPU


def set_ppuaddr(ppu: PPU, addr: int) -> None:
    """Set PPU.vram_addr through the public $2006 two-write interface."""
    ppu.write_register(0x2006, (addr >> 8) & 0xFF)
    ppu.write_register(0x2006, addr & 0xFF)


def test_ppu_has_ppudata_read_buffer():
    """
    Objective:
    Add the internal PPUDATA read buffer.
    """
    assert "ppu_data_buffer" in PPU.__dataclass_fields__

    ppu = PPU()

    assert ppu.ppu_data_buffer == 0


def test_first_ppudata_read_returns_old_buffer_and_loads_memory_value():
    """
    Objective:
    The first normal PPUDATA read should return the old buffer, then load the
    buffer from PPU memory at vram_addr.

    This test uses $2000, not palette range $3F00-$3FFF, to avoid the future
    palette read exception.
    """
    ppu = PPU()
    ppu.ppu_bus.write(0x2000, 0xAA)
    set_ppuaddr(ppu, 0x2000)

    value = ppu.read_register(0x2007)

    assert value == 0x00
    assert ppu.ppu_data_buffer == 0xAA


def test_second_ppudata_read_returns_value_loaded_by_previous_read():
    """
    Objective:
    The second normal PPUDATA read should return the value loaded into the buffer
    by the first read.
    """
    ppu = PPU()
    ppu.ppu_bus.write(0x2000, 0xAA)
    ppu.ppu_bus.write(0x2001, 0xBB)
    set_ppuaddr(ppu, 0x2000)

    assert ppu.read_register(0x2007) == 0x00
    assert ppu.read_register(0x2007) == 0xAA
    assert ppu.ppu_data_buffer == 0xBB


def test_ppudata_read_increments_vram_addr_by_one_when_increment_bit_is_clear():
    """
    Objective:
    PPUDATA reads increment vram_addr just like PPUDATA writes.

    With PPUCTRL bit 2 clear, the increment is 1.
    """
    ppu = PPU()
    ppu.write_register(0x2000, 0x00)
    set_ppuaddr(ppu, 0x2000)

    ppu.read_register(0x2007)

    assert ppu.vram_addr == 0x2001


def test_ppudata_read_increments_vram_addr_by_32_when_increment_bit_is_set():
    """
    Objective:
    With PPUCTRL bit 2 set, PPUDATA reads increment vram_addr by 32.
    """
    ppu = PPU()
    ppu.write_register(0x2000, CTRL_VRAM_INCREMENT_BY_32)
    set_ppuaddr(ppu, 0x2000)

    ppu.read_register(0x2007)

    assert ppu.vram_addr == 0x2020


def test_ppudata_read_updates_data_as_compatibility_debug_field():
    """
    Objective:
    Preserve `data` as the last value returned by PPUDATA for old tests and easy
    debugging.

    Important:
    `data` is not the real source of PPUDATA reads anymore. The real source is
    ppu_data_buffer and ppu_bus.read(vram_addr).
    """
    ppu = PPU()
    ppu.ppu_data_buffer = 0xCC
    set_ppuaddr(ppu, 0x2000)

    value = ppu.read_register(0x2007)

    assert value == 0xCC
    assert ppu.data == 0xCC


def test_ppudata_read_wraps_vram_addr_to_14_bit_ppu_address_space():
    """
    Objective:
    vram_addr should stay inside $0000-$3FFF after PPUDATA reads.
    """
    ppu = PPU()
    ppu.write_register(0x2000, CTRL_VRAM_INCREMENT_BY_32)
    set_ppuaddr(ppu, 0x3FF0)

    ppu.read_register(0x2007)

    assert ppu.vram_addr == ((0x3FF0 + 32) & 0x3FFF)

测试函数 (7)

test_ppu_has_ppudata_read_buffer
test_first_ppudata_read_returns_old_buffer_and_loads_memory_value
test_second_ppudata_read_returns_value_loaded_by_previous_read
test_ppudata_read_increments_vram_addr_by_one_when_increment_bit_is_clear
test_ppudata_read_increments_vram_addr_by_32_when_increment_bit_is_set
test_ppudata_read_updates_data_as_compatibility_debug_field
test_ppudata_read_wraps_vram_addr_to_14_bit_ppu_address_space