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 — это не обычный простой регистр. Это видимый для CPU порт в память PPU. Для большинства операций чтения памяти 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