249. Búfer de lectura de PPUDATA

Implementa el comportamiento de lectura con búfer de PPUDATA ($2007).

Lección 249 de 356 · tests/chapter_03_ppu_memory_and_graphics_data/test_249_ppudata_read_buffer.py

Referencia

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

Archivo a actualizar

emulator/ppu/ppu.py

Estado a añadir

ppu_data_buffer: int = 0

Por qué existe este paso

PPUDATA no es un registro simple normal. Es un puerto visible para la CPU hacia la memoria de la PPU. En la mayoría de las lecturas de memoria de la PPU, la NES devuelve el búfer de lectura interno antiguo y después recarga ese búfer desde la dirección actual de memoria de la PPU.

Comportamiento normal de lectura con búfer

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

Esto significa que la primera lectura suele devolver datos antiguos/obsoletos del búfer, y la segunda lectura devuelve el byte que se cargó con la primera lectura.

Ejemplo

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

Campo de compatibilidad/depuración

El modelo anterior del tutorial tenía data como un valor simple de PPUDATA. Conserva self.data como campo de compatibilidad/depuración que contiene el valor devuelto por la última

lectura de PPUDATA, pero el comportamiento real debería usar

ppu_data_buffer
ppu_bus.read(vram_addr)

Pseudocódigo de implementación sugerido

@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

Nota importante para el futuro

Las lecturas de paleta de $3F00-$3FFF son una excepción en el hardware real. Devuelven el byte de paleta inmediatamente en lugar de devolver el valor retardado del búfer. Esa excepción no se implementa de forma intencionada en este test.

Fuera del alcance

excepción de lectura de paleta
precisión de la RAM de paleta
escrituras de PPUDATA, ya probadas anteriormente

Ejecutar esta lección

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

Implementación de ejemplo

Comportamiento normal de lectura con búfer

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

Ejemplo

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

Pseudocódigo de implementación sugerido

@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

Ver código del testtest_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)

Funciones de test (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