267. CPU.step devuelve ciclos

Hacer que CPU.step() devuelva los ciclos base de instrucción.

Lección 267 de 356 · tests/chapter_04_ppu_timing_and_vblank/test_267_cpu_step_returns_cycles.py

Referencia

https://www.nesdev.org/wiki/Visual6502wiki/6502_all_256_Opcodes

Archivos a actualizar

emulator/cpu/cpu.py

Por qué existe este paso

El emulador ahora tiene una tabla OPCODE_CYCLES independiente. El siguiente puente de temporización es que CPU.step() devuelva el conteo de ciclos base del opcode que ejecutó.

Esto prepara la forma futura de Console.step():

cpu_cycles = cpu.step()
ppu.step(cpu_cycles * 3)
console.consume_nmi_if_requested()

¿Qué es un conteo de ciclos base de instrucción? Un conteo de ciclos base de instrucción es el número normal de ciclos de CPU que un opcode toma antes de que se añadan penalizaciones dinámicas.

Ejemplos mínimos

NOP implied      opcode $EA -> 2 cycles
LDA immediate   opcode $A9 -> 2 cycles
JSR absolute    opcode $20 -> 6 cycles

Concepto erróneo común

Los ciclos no son lo mismo que los bytes leídos. JSR ocupa 3 bytes pero toma 6 ciclos. No cuentes ciclos dentro de fetch_byte().

Ejemplo de implementación sugerido

from emulator.cpu.opcodes import OPCODE_CYCLES, OPCODE_TABLE


class CPU:
    ...

    def step(self) -> int:
        opcode = self.fetch_byte()
        handler = OPCODE_TABLE.get(opcode)
        if handler is None:
            raise NotImplementedError(f"Opcode {opcode:02X} not implemented")

        handler(self)
        return OPCODE_CYCLES[opcode]

Por qué esto evita una gran refactorización

OPCODE_TABLE sigue siendo el mapeo existente de opcode a manejador. OPCODE_CYCLES es una tabla de metadatos paralela. Las pruebas antiguas de comportamiento de instrucciones deberían seguir pasando porque CPU.step() sigue ejecutando el mismo manejador.

Limitación importante

Esto devuelve solo ciclos base. La temporización dinámica está intencionalmente fuera de alcance aquí:

branch taken penalties
branch page-cross penalties
indexed load page-cross penalties

Esos deberían modelarse después como un paso separado.

Fuera de alcance

refactorizar OPCODE_TABLE en entradas de dataclass
añadir ciclos a fetch_byte()
Console.step()
avance de la PPU por ciclos de CPU * 3
ciclos extra dinámicos

Ejecutar esta lección

uv run pytest tests/chapter_04_ppu_timing_and_vblank/test_267_cpu_step_returns_cycles.py -v

Implementación de ejemplo

Por qué existe este paso

cpu_cycles = cpu.step()
ppu.step(cpu_cycles * 3)
console.consume_nmi_if_requested()

Ejemplo de implementación sugerido

from emulator.cpu.opcodes import OPCODE_CYCLES, OPCODE_TABLE


class CPU:
    ...

    def step(self) -> int:
        opcode = self.fetch_byte()
        handler = OPCODE_TABLE.get(opcode)
        if handler is None:
            raise NotImplementedError(f"Opcode {opcode:02X} not implemented")

        handler(self)
        return OPCODE_CYCLES[opcode]

Ver código del testtest_267_cpu_step_returns_cycles.py

import pytest

from emulator.cpu.opcodes import OPCODE_CYCLES
from tests.helpers import load_program, make_cpu_with_rom


def test_cpu_step_returns_nop_base_cycles():
    """
    Objective:
    CPU.step() returns the base cycle count for the opcode it executes.

    Example:
        NOP implied is opcode $EA and takes 2 CPU cycles.
    """
    cpu, _bus, rom = make_cpu_with_rom()
    load_program(rom, 0x8000, [0xEA])
    cpu.pc = 0x8000

    cycles = cpu.step()

    assert cycles == 2
    assert cycles == OPCODE_CYCLES[0xEA]
    assert cpu.pc == 0x8001


def test_cpu_step_returns_cycles_and_still_executes_instruction_behavior():
    """
    Objective:
    Returning cycles must not replace instruction behavior. The opcode handler
    still runs exactly as before.

    Example:
        LDA #$42 is opcode sequence $A9 $42.
        It loads A with $42 and returns 2 cycles.
    """
    cpu, _bus, rom = make_cpu_with_rom()
    load_program(rom, 0x8000, [0xA9, 0x42])
    cpu.pc = 0x8000

    cycles = cpu.step()

    assert cycles == 2
    assert cycles == OPCODE_CYCLES[0xA9]
    assert cpu.a == 0x42
    assert cpu.pc == 0x8002


def test_cpu_step_returns_different_cycles_for_different_opcodes():
    """
    Objective:
    CPU.step() should return opcode-specific timing, not a constant value.

    Example:
        JSR absolute is opcode $20 and takes 6 CPU cycles.
    """
    cpu, _bus, rom = make_cpu_with_rom()
    load_program(rom, 0x8000, [0x20, 0x00, 0x90])
    cpu.pc = 0x8000
    cpu.s = 0xFD

    cycles = cpu.step()

    assert cycles == 6
    assert cycles == OPCODE_CYCLES[0x20]
    assert cpu.pc == 0x9000


def test_cpu_step_still_raises_for_unknown_opcode():
    """
    Objective:
    Adding cycle returns must not make unsupported opcodes silently executable.

    Example:
        $02 is not implemented in the current OPCODE_TABLE. It should still raise
        NotImplementedError instead of returning OPCODE_CYCLES[$02].
    """
    cpu, _bus, rom = make_cpu_with_rom()
    load_program(rom, 0x8000, [0x02])
    cpu.pc = 0x8000

    with pytest.raises(NotImplementedError, match="Opcode 02 not implemented"):
        cpu.step()


def test_cpu_step_does_not_use_fetch_count_as_cycle_count():
    """
    Objective:
    Guard the mental model: cycles come from opcode metadata, not from how many
    bytes were fetched.

    Example:
        JSR absolute fetches 3 instruction bytes but takes 6 CPU cycles.
    """
    cpu, _bus, rom = make_cpu_with_rom()
    load_program(rom, 0x8000, [0x20, 0x00, 0x90])
    cpu.pc = 0x8000
    cpu.s = 0xFD

    cycles = cpu.step()

    assert cpu.pc == 0x9000
    assert cycles == 6
    assert cycles != 3

Funciones de test (5)

test_cpu_step_returns_nop_base_cycles
test_cpu_step_returns_cycles_and_still_executes_instruction_behavior
test_cpu_step_returns_different_cycles_for_different_opcodes
test_cpu_step_still_raises_for_unknown_opcode
test_cpu_step_does_not_use_fetch_count_as_cycle_count