289. OAMDMA 4014

Реализовать OAMDMA по адресу CPU $4014.

Урок 289 из 356 · tests/chapter_06_rom_startup_preparation/test_289_oamdma_4014.py

Файл для обновления

emulator/bus/cpu_bus.py

Зачем нужен этот шаг

Реальные игры для NES обычно подготавливают байты спрайтов в памяти CPU, а затем запускают OAMDMA, чтобы скопировать эти байты в OAM PPU. Даже до появления рендеринга спрайтов этот механизм копирования важен, поскольку он позволяет коду запуска реальных ROM продолжать работу и предоставляет будущему рендереру спрайтов реальные данные OAM.

Что такое OAM? OAM означает Object Attribute Memory. Это 256-байтная память спрайтов PPU:

64 sprites * 4 bytes each = 256 bytes

Каждая запись спрайта имеет форму

byte 0: Y position
byte 1: tile index
byte 2: attributes
byte 3: X position

Что такое OAMDMA? OAMDMA — это механизм записи на шине CPU. Запись одного байта по адресу $4014 выбирает страницу памяти CPU и копирует все 256 байтов этой страницы в OAM PPU.

Минимальный пример

CPU writes $02 to $4014

Это означает

copy CPU $0200-$02FF -> PPU.oam[0x00-0xFF]

Пример предлагаемой реализации

def write(self, addr: int, value: int) -> None:
    ...

    # OAMDMA: copy one CPU page into PPU OAM.
    if addr == 0x4014:
        page_start = (value & 0xFF) << 8

        for offset in range(256):
            self.ppu.oam[offset] = self.read(page_start + offset)

        return

    ...

Важная деталь

OAMDMA должен читать данные через CpuBus.read(), а не напрямую из «сырой» RAM. Источник — адресное пространство CPU. Большинство игр используют страницы вроде $0200-$02FF, но использование чтений через шину сохраняет корректность механизма и избавляет от будущих переработок.

Распространённое заблуждение

"OAMDMA means sprites are rendered."

Нет. На этом шаге байты только копируются в PPU.oam. Декодирование/рендеринг спрайтов появится позже.

Поведение при чтении

В рамках этого курса $4014 — это регистр, срабатывающий только на запись. CpuBus.read($4014) пока должен оставаться неподдерживаемым.

Вне рамок этого шага

рендеринг спрайтов
приоритет спрайтов
прозрачность спрайтов
sprite 0 hit
переполнение спрайтов
тайминг задержки DMA в 513/514 циклов CPU
контроллер $4016

Запустить этот урок

uv run pytest tests/chapter_06_rom_startup_preparation/test_289_oamdma_4014.py -v

Пример реализации

Пример предлагаемой реализации

def write(self, addr: int, value: int) -> None:
    ...

    # OAMDMA: copy one CPU page into PPU OAM.
    if addr == 0x4014:
        page_start = (value & 0xFF) << 8

        for offset in range(256):
            self.ppu.oam[offset] = self.read(page_start + offset)

        return

    ...

Показать код тестаtest_289_oamdma_4014.py

import pytest

from emulator.bus.cpu_bus import CpuBus
from emulator.memory.fake_rom import FakeROM


def test_oamdma_4014_copies_256_bytes_from_selected_cpu_page_to_ppu_oam():
    """
    Objective:
    Writing a page number to $4014 copies exactly one 256-byte CPU memory page into
    PPU OAM.

    Example:
        write $02 to $4014
        copy CPU $0200-$02FF -> PPU.oam[0x00-0xFF]
    """
    bus = CpuBus(program_rom=FakeROM())

    for offset in range(256):
        bus.write(0x0200 + offset, offset ^ 0x5A)

    bus.write(0x4014, 0x02)

    assert list(bus.ppu.oam) == [(offset ^ 0x5A) for offset in range(256)]


def test_oamdma_source_page_is_value_shifted_left_by_8():
    """
    Objective:
    The value written to $4014 selects the high byte of the source address.

    Writing $03 means source page $0300-$03FF, not $0003-$0102.
    """
    bus = CpuBus(program_rom=FakeROM())

    for offset in range(256):
        bus.write(0x0200 + offset, 0x22)
        bus.write(0x0300 + offset, 0x33)

    bus.write(0x4014, 0x03)

    assert all(value == 0x33 for value in bus.ppu.oam)


def test_oamdma_reads_source_bytes_through_cpu_bus_read():
    """
    Objective:
    OAMDMA source reads should go through CpuBus.read().

    This matters because OAMDMA reads from CPU address space, not only raw internal
    RAM. This test uses RAM mirroring to prove bus behavior is used:

        source page $0800-$08FF mirrors internal RAM $0000-$00FF
    """
    bus = CpuBus(program_rom=FakeROM())

    for offset in range(256):
        bus.write(0x0000 + offset, (offset + 7) & 0xFF)

    bus.write(0x4014, 0x08)

    assert list(bus.ppu.oam) == [((offset + 7) & 0xFF) for offset in range(256)]


def test_oamdma_overwrites_all_oam_bytes():
    """
    Objective:
    DMA writes all 256 OAM bytes. It should not only update the first sprite entry
    or stop early.
    """
    bus = CpuBus(program_rom=FakeROM())
    bus.ppu.oam[:] = bytes([0xEE]) * 256

    for offset in range(256):
        bus.write(0x0400 + offset, offset)

    bus.write(0x4014, 0x04)

    assert bus.ppu.oam[0] == 0x00
    assert bus.ppu.oam[1] == 0x01
    assert bus.ppu.oam[254] == 0xFE
    assert bus.ppu.oam[255] == 0xFF
    assert list(bus.ppu.oam) == list(range(256))


def test_oamdma_read_4014_remains_unsupported():
    """
    Objective:
    $4014 is implemented as a write-triggered DMA register in this tutorial.

    A CPU read from $4014 should not pretend to return meaningful DMA state.
    """
    bus = CpuBus(program_rom=FakeROM())

    with pytest.raises(ValueError, match="Unsupported CPU bus read: 4014"):
        bus.read(0x4014)


def test_apu_audio_noop_still_works_after_oamdma_step():
    """
    Objective:
    OAMDMA $4014 should coexist with the previous APU/audio no-op step.

    The nearby audio addresses remain recognized out-of-scope no-ops.
    $4017 remains simplified too: writes are APU frame-counter no-ops, while reads
    return 0 for out-of-scope controller port 2 / expansion input.
    """
    bus = CpuBus(program_rom=FakeROM())

    bus.write(0x4000, 0x12)
    bus.write(0x4013, 0x34)
    bus.write(0x4015, 0x56)
    bus.write(0x4017, 0x78)

    assert bus.read(0x4000) == 0
    assert bus.read(0x4013) == 0
    assert bus.read(0x4015) == 0
    assert bus.read(0x4017) == 0


def test_oamdma_only_copies_bytes_and_does_not_render_sprites():
    """
    Objective:
    This step transfers sprite data into PPU.oam only. It should not add sprite
    rendering as a hidden side effect.

    Rendering sprites will be a later explicit tutorial step.
    """
    bus = CpuBus(program_rom=FakeROM())

    for offset in range(256):
        bus.write(0x0200 + offset, offset)

    bus.write(0x4014, 0x02)

    assert not hasattr(bus.ppu, "render_sprites")

Тестовые функции (7)

test_oamdma_4014_copies_256_bytes_from_selected_cpu_page_to_ppu_oam
test_oamdma_source_page_is_value_shifted_left_by_8
test_oamdma_reads_source_bytes_through_cpu_bus_read
test_oamdma_overwrites_all_oam_bytes
test_oamdma_read_4014_remains_unsupported
test_apu_audio_noop_still_works_after_oamdma_step
test_oamdma_only_copies_bytes_and_does_not_render_sprites