250. Excepción de lectura de paleta de PPUDATA

Implementa la excepción de lectura de paleta de PPUDATA ($2007).

Lección 250 de 356 · tests/chapter_03_ppu_memory_and_graphics_data/test_250_ppudata_palette_read_exception.py

Referencia

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

Archivo a actualizar

emulator/ppu/ppu.py

Constantes a añadir

PALETTE_START_ADDR = 0x3F00
PALETTE_END_ADDR = 0x3FFF

Por qué existe este paso

Las lecturas normales de PPUDATA se realizan con búfer

read $2007:
    return old ppu_data_buffer
    reload ppu_data_buffer from ppu_bus.read(vram_addr)
    increment vram_addr

Las lecturas de paleta son la excepción. Cuando vram_addr apunta a la memoria de paleta:

$3F00-$3FFF

la PPU devuelve el byte de paleta inmediatamente en lugar de devolver el búfer antiguo.

Detalle importante

El búfer antiguo se descarta igualmente. En las PPU normales de la NES, el búfer se recarga desde la memoria de nametable espejada tras la dirección de paleta:

$3F00 -> reload buffer from $2F00
$3F10 -> reload buffer from $2F10

Eso significa que las lecturas de paleta afectan a ambos

el valor devuelto a la CPU
el búfer interno ppu_data_buffer usado por futuras lecturas normales

Pseudocódigo de implementación sugerido, siguiendo el estilo explícito de comentarios:

PALETTE_START_ADDR = 0x3F00
PALETTE_END_ADDR = 0x3FFF

case 0x2007:  # PPU DATA read
    # Palette data is returned immediately.
    if PALETTE_START_ADDR <= self.vram_addr <= PALETTE_END_ADDR:
        value = self.ppu_bus.read(self.vram_addr)

        # Read buffer is discarded and reloaded from shadowed memory:
        # vram_addr - 0x1000
        # Example: 0x3F00 -> 0x2F00
        self.ppu_data_buffer = self.ppu_bus.read(self.vram_addr - 0x1000)
    else:
        # Normal PPUDATA reads return the old buffer first.
        value = self.ppu_data_buffer

        # Then the buffer is reloaded from current PPU memory.
        self.ppu_data_buffer = self.ppu_bus.read(self.vram_addr)

    increment = 32 if self.ctrl & CTRL_VRAM_INCREMENT_BY_32 else 1

    # Keep vram_addr in the 14-bit PPU address range.
    self.vram_addr = (self.vram_addr + increment) & 0x3FFF

    # Preserve self.data for old test compatibility/debugging.
    self.data = value
    return self.data

Fuera del alcance

espejado de la RAM de paleta, como $3F10 -> $3F00
valores de color de paleta precisos
renderizado

Ejecutar esta lección

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

Implementación de ejemplo

Las lecturas normales de PPUDATA se realizan con búfer

read $2007:
    return old ppu_data_buffer
    reload ppu_data_buffer from ppu_bus.read(vram_addr)
    increment vram_addr

Eso significa que las lecturas de paleta afectan a ambos

PALETTE_START_ADDR = 0x3F00
PALETTE_END_ADDR = 0x3FFF

case 0x2007:  # PPU DATA read
    # Palette data is returned immediately.
    if PALETTE_START_ADDR <= self.vram_addr <= PALETTE_END_ADDR:
        value = self.ppu_bus.read(self.vram_addr)

        # Read buffer is discarded and reloaded from shadowed memory:
        # vram_addr - 0x1000
        # Example: 0x3F00 -> 0x2F00
        self.ppu_data_buffer = self.ppu_bus.read(self.vram_addr - 0x1000)
    else:
        # Normal PPUDATA reads return the old buffer first.
        value = self.ppu_data_buffer

        # Then the buffer is reloaded from current PPU memory.
        self.ppu_data_buffer = self.ppu_bus.read(self.vram_addr)

    increment = 32 if self.ctrl & CTRL_VRAM_INCREMENT_BY_32 else 1

    # Keep vram_addr in the 14-bit PPU address range.
    self.vram_addr = (self.vram_addr + increment) & 0x3FFF

    # Preserve self.data for old test compatibility/debugging.
    self.data = value
    return self.data

Ver código del testtest_250_ppudata_palette_read_exception.py

from emulator.ppu.ppu import PALETTE_END_ADDR, PALETTE_START_ADDR, 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_declares_palette_read_range_constants():
    """
    Objective:
    Name the PPU palette address range used by the PPUDATA read exception.
    """
    assert PALETTE_START_ADDR == 0x3F00
    assert PALETTE_END_ADDR == 0x3FFF


def test_ppudata_palette_read_returns_palette_value_immediately():
    """
    Objective:
    Reading $2007 while vram_addr is in $3F00-$3FFF should return the palette
    byte immediately, not the old ppu_data_buffer.
    """
    ppu = PPU()
    ppu.ppu_data_buffer = 0x55
    ppu.ppu_bus.write(0x3F00, 0x0F)
    set_ppuaddr(ppu, 0x3F00)

    value = ppu.read_register(0x2007)

    assert value == 0x0F


def test_ppudata_palette_read_discards_old_buffer_and_reloads_shadowed_memory():
    """
    Objective:
    Palette reads should replace the old buffer with data from the shadowed
    address behind palette memory.

    Example:
        vram_addr = $3F00
        returned value comes from $3F00
        buffer reload comes from $2F00
    """
    ppu = PPU()
    ppu.ppu_data_buffer = 0x55
    ppu.ppu_bus.write(0x3F00, 0x0F)
    ppu.ppu_bus.write(0x2F00, 0xAA)
    set_ppuaddr(ppu, 0x3F00)

    value = ppu.read_register(0x2007)

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


def test_ppudata_palette_read_still_increments_vram_addr():
    """
    Objective:
    Palette reads still increment vram_addr after the read.
    """
    ppu = PPU()
    ppu.ppu_bus.write(0x3F00, 0x0F)
    set_ppuaddr(ppu, 0x3F00)

    ppu.read_register(0x2007)

    assert ppu.vram_addr == 0x3F01


def test_non_palette_ppudata_reads_remain_buffered():
    """
    Objective:
    The palette exception must not break normal buffered PPUDATA reads outside
    $3F00-$3FFF.
    """
    ppu = PPU()
    ppu.ppu_data_buffer = 0x55
    ppu.ppu_bus.write(0x2000, 0xAA)
    set_ppuaddr(ppu, 0x2000)

    value = ppu.read_register(0x2007)

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


def test_ppudata_palette_read_updates_data_compatibility_field():
    """
    Objective:
    Preserve self.data as the last PPUDATA value returned, even for palette
    immediate reads.
    """
    ppu = PPU()
    ppu.ppu_bus.write(0x3F00, 0x21)
    set_ppuaddr(ppu, 0x3F00)

    value = ppu.read_register(0x2007)

    assert value == 0x21
    assert ppu.data == 0x21

Funciones de test (6)

test_ppu_declares_palette_read_range_constants
test_ppudata_palette_read_returns_palette_value_immediately
test_ppudata_palette_read_discards_old_buffer_and_reloads_shadowed_memory
test_ppudata_palette_read_still_increments_vram_addr
test_non_palette_ppudata_reads_remain_buffered
test_ppudata_palette_read_updates_data_compatibility_field