Validación e Implementación de Cargas Inmediatas (LD r, d8)

Resumen

Después del diagnóstico que reveló que la pantalla estaba en blanco y LY estaba atascado en 0, se identificó que la causa raíz era que la CPU de C++ estaba devolviendo 0 ciclos cuando encontraba opcodes no implementados. Esto congelaba el tiempo de la máquina emulada, impidiendo que la PPU avanzara.

Aunque las instrucciones LD r, d8 (cargas inmediatas de 8 bits) ya estaban implementadas en el código C++, este paso documenta su importancia crítica y valida su funcionamiento completo mediante un test parametrizado que verifica las 7 instrucciones: LD B, d8, LD C, d8, LD D, d8, LD E, d8, LD H, d8, LD L, d8, y LD A, d8.

Estas instrucciones son fundamentales porque son las primeras que cualquier ROM ejecuta al iniciar: cargan valores inmediatos en los registros para inicializar el estado de la máquina. Sin ellas, la CPU no puede avanzar más allá de las primeras instrucciones del código del juego.

Concepto de Hardware

Las instrucciones LD r, d8 (Load register with immediate 8-bit value) son parte del conjunto de instrucciones más básico del LR35902 (CPU de Game Boy). Permiten cargar un valor constante de 8 bits directamente en un registro de 8 bits.

Formato de la Instrucción

Cada instrucción LD r, d8 consta de:

• Opcode (1 byte): Identifica la operación y el registro destino
• d8 (1 byte): El valor inmediato a cargar (0x00 - 0xFF)

Opcodes de LD r, d8

¿Por qué son Críticas?

Al iniciar cualquier ROM de Game Boy, el código de boot/inicialización siempre comienza ejecutando secuencias de instrucciones LD r, d8 para:

• Inicializar registros: Establecer valores de partida para B, C, D, E, H, L y A
• Configurar direcciones: Preparar pares de registros (HL, BC, DE) con direcciones de memoria iniciales
• Establecer constantes: Cargar valores mágicos, máscaras, o flags iniciales

Sin estas instrucciones implementadas, la CPU encuentra el primer LD r, d8 en la ROM, entra en el caso default del switch (opcode no implementado), devuelve 0 ciclos, y el tiempo de la máquina emulada se congela. Por eso el diagnóstico mostró que LY estaba atascado en 0: la PPU no recibía ciclos porque la CPU no estaba ejecutando instrucciones.

Timing

Todas las instrucciones LD r, d8 consumen 2 M-Cycles (8 T-Cycles):

• M-Cycle 1: Lectura del opcode (4 T-Cycles)
• M-Cycle 2: Lectura del byte inmediato d8 y escritura en el registro (4 T-Cycles)

El Program Counter (PC) avanza 2 bytes: el opcode y el valor inmediato.

Implementación

Las instrucciones LD r, d8 ya estaban implementadas en src/core/cpp/CPU.cpp dentro del método CPU::step(). Sin embargo, se mejoró la validación mediante un test parametrizado que verifica todas las 7 instrucciones de manera sistemática.

Código Implementado

Cada instrucción sigue el mismo patrón simple:

case 0x0E:  // LD C, d8
{
    uint8_t value = fetch_byte();  // Lee el siguiente byte (d8)
    regs_->c = value;              // Asigna al registro
    cycles_ += 2;                  // Acumula 2 M-Cycles
    return 2;                      // Retorna 2 M-Cycles
}

El método fetch_byte() se encarga de:

• Leer el byte de memoria en la dirección PC
• Incrementar PC automáticamente
• Manejar el wrap-around en 16 bits (PC se mantiene en el rango 0x0000-0xFFFF)

Test Parametrizado

Se añadió un test parametrizado usando pytest.mark.parametrize que valida todas las instrucciones LD r, d8 en una sola función:

@pytest.mark.parametrize("opcode,register_name,test_value", [
    (0x06, 'b', 0x33),  # LD B, d8
    (0x0E, 'c', 0x42),  # LD C, d8
    (0x16, 'd', 0x55),  # LD D, d8
    (0x1E, 'e', 0x78),  # LD E, d8
    (0x26, 'h', 0x9A),  # LD H, d8
    (0x2E, 'l', 0xBC),  # LD L, d8
    (0x3E, 'a', 0xDE),  # LD A, d8
])
def test_ld_register_immediate(self, opcode, register_name, test_value):
    """Valida que cada instrucción carga correctamente el valor inmediato."""
    # ... implementación del test

Este enfoque permite validar todas las instrucciones de manera sistemática y garantiza que cada una funciona correctamente:

• ✅ Carga el valor inmediato en el registro correcto
• ✅ Consume exactamente 2 M-Cycles
• ✅ Avanza PC en 2 bytes

Archivos Afectados

• src/core/cpp/CPU.cpp - Las instrucciones LD r, d8 ya estaban implementadas (líneas 364-419)
• tests/test_core_cpu_loads.py - Añadido test parametrizado test_ld_register_immediate para validar todas las instrucciones LD r, d8

Tests y Verificación

Se ejecutaron los tests para validar que todas las instrucciones LD r, d8 funcionan correctamente:

Comando Ejecutado

pytest tests/test_core_cpu_loads.py::TestLD_8bit_Immediate -v

Resultado

============================= test session starts =============================
platform win32 - Python 3.13.5, pytest-9.0.2, pluggy-1.6.0
collecting ... collected 9 items

tests/test_core_cpu_loads.py::TestLD_8bit_Immediate::test_ld_register_immediate[6-b-51] PASSED [ 11%]
tests/test_core_cpu_loads.py::TestLD_8bit_Immediate::test_ld_register_immediate[14-c-66] PASSED [ 22%]
tests/test_core_cpu_loads.py::TestLD_8bit_Immediate::test_ld_register_immediate[22-d-85] PASSED [ 33%]
tests/test_core_cpu_loads.py::TestLD_8bit_Immediate::test_ld_register_immediate[30-e-120] PASSED [ 44%]
tests/test_core_cpu_loads.py::TestLD_8bit_Immediate::test_ld_register_immediate[38-h-154] PASSED [ 55%]
tests/test_core_cpu_loads.py::TestLD_8bit_Immediate::test_ld_register_immediate[46-l-188] PASSED [ 66%]
tests/test_core_cpu_loads.py::TestLD_8bit_Immediate::test_ld_register_immediate[62-a-222] PASSED [ 77%]
tests/test_core_cpu_loads.py::TestLD_8bit_Immediate::test_ld_b_immediate PASSED [ 88%]
tests/test_core_cpu_loads.py::TestLD_8bit_Immediate::test_ld_hl_immediate PASSED [100%]

============================== 9 passed in 0.07s ==============================

Código del Test

El test parametrizado valida que cada instrucción:

@pytest.mark.parametrize("opcode,register_name,test_value", [
    (0x06, 'b', 0x33),  # LD B, d8
    (0x0E, 'c', 0x42),  # LD C, d8
    (0x16, 'd', 0x55),  # LD D, d8
    (0x1E, 'e', 0x78),  # LD E, d8
    (0x26, 'h', 0x9A),  # LD H, d8
    (0x2E, 'l', 0xBC),  # LD L, d8
    (0x3E, 'a', 0xDE),  # LD A, d8
])
def test_ld_register_immediate(self, opcode, register_name, test_value):
    """Valida que cada instrucción LD r, d8 funciona correctamente."""
    mmu = PyMMU()
    regs = PyRegisters()
    cpu = PyCPU(mmu, regs)
    
    regs.pc = 0x0100
    mmu.write(0x0100, opcode)
    mmu.write(0x0101, test_value)
    
    cycles = cpu.step()
    
    # Verificar que el registro tiene el valor correcto
    register_value = getattr(regs, register_name)
    assert register_value == test_value
    assert cycles == 2
    assert regs.pc == 0x0102

Validación de módulo compilado C++: Todos los tests pasan, confirmando que las instrucciones están correctamente implementadas en el código nativo C++ compilado.

Fuentes Consultadas

• Pan Docs: CPU Instruction Set - Sección de Load Instructions (LD r, n)
• Game Boy CPU Manual: Referencia de opcodes y timing de instrucciones

Integridad Educativa

Próximos Pasos

• [ ] Ejecutar una ROM y analizar qué opcodes se encuentran después de las primeras instrucciones LD r, d8
• [ ] Implementar las siguientes instrucciones más comunes que las ROMs necesitan (probablemente más instrucciones de carga, saltos, o aritmética)
• [ ] Continuar con un enfoque incremental: identificar opcodes faltantes → implementar → validar con tests → documentar
• [ ] Monitorear el progreso: verificar si LY comienza a avanzar cuando se implementan más instrucciones