289. $4014 处的 OAMDMA

在 CPU 地址 $4014 处实现 OAMDMA。

第 289 / 356 · tests/chapter_06_rom_startup_preparation/test_289_oamdma_4014.py

待更新文件

emulator/bus/cpu_bus.py

为什么需要这一步

真实的 NES 游戏通常会先在 CPU 内存中准备好精灵字节，然后触发 OAMDMA 把这些字节复制到 PPU OAM 中。即使在还没有实现精灵渲染的情况下，这个复制机制也很重要，因为它能让真实 ROM 的启动代码继续运行，并为未来的精灵渲染器提供真实的 OAM 数据。

什么是 OAM？OAM 指对象属性内存（Object Attribute Memory），它是 PPU 中 256 字节的精灵内存：

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 个字节复制到 PPU OAM 中。

最小示例

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) 目前应保持不支持。

范围之外

精灵渲染
精灵优先级
精灵透明度
精灵 0 命中
精灵溢出
513/514 个 CPU 周期的 DMA 停顿时序
手柄 $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