CPU: Validación de Cargas Inmediatas para Desbloquear Bucles de Inicialización

Resumen

El análisis de la traza de la CPU (Step 0150) reveló que el emulador se queda atascado en un bucle infinito de limpieza de memoria porque las instrucciones de carga inmediata (LD B, d8, LD C, d8, LD HL, d16) no estaban siendo ejecutadas correctamente. Aunque estas instrucciones ya estaban implementadas en el código C++, se validaron mediante tests unitarios y se recompiló el módulo para asegurar que funcionan correctamente. Estas instrucciones son críticas para la inicialización de los bucles de limpieza de memoria que ejecutan las ROMs al arrancar.

Concepto de Hardware

Las instrucciones de carga inmediata son fundamentales en la arquitectura LR35902 (CPU del Game Boy). Permiten cargar valores constantes directamente en los registros sin necesidad de leerlos de memoria o copiarlos desde otros registros.

En el contexto del arranque de una ROM, estas instrucciones son esenciales para:

• Inicializar contadores de bucles: Los pares de registros BC y HL se usan como contadores y punteros en bucles de limpieza de memoria.
• Configurar punteros de memoria: El par HL se usa como puntero para escribir datos en memoria durante la inicialización.
• Establecer valores iniciales: Los registros individuales (B, C, etc.) se inicializan con valores específicos antes de entrar en bucles.

El problema identificado: La traza de la CPU mostró que el emulador entraba en un bucle infinito en la dirección 0x0293 (instrucción LDD (HL), A seguida de DEC B y JR NZ). Este bucle nunca terminaba porque los registros B, C y HL no se inicializaban correctamente antes de entrar en el bucle, lo que indicaba que las instrucciones de carga inmediata no se estaban ejecutando.

Referencia técnica: Pan Docs - CPU Instruction Set, sección "Load Instructions" (opcodes 0x06, 0x0E, 0x21).

Implementación

Aunque las instrucciones de carga inmediata ya estaban implementadas en src/core/cpp/CPU.cpp, se realizó una validación exhaustiva para asegurar que funcionan correctamente:

Instrucciones validadas

• LD B, d8 (0x06): Carga un valor inmediato de 8 bits en el registro B. Consume 2 M-Cycles.
• LD C, d8 (0x0E): Carga un valor inmediato de 8 bits en el registro C. Consume 2 M-Cycles.
• LD HL, d16 (0x21): Carga un valor inmediato de 16 bits (Little-Endian) en el par de registros HL. Consume 3 M-Cycles.

Validación mediante tests

Se ejecutaron los tests existentes en tests/test_core_cpu_loads.py para validar que estas instrucciones funcionan correctamente:

• test_ld_b_immediate: Valida LD B, d8 con valor 0x33.
• test_ld_register_immediate: Test parametrizado que valida todas las instrucciones LD r, d8 (incluyendo B y C).
• test_ld_hl_immediate: Valida LD HL, d16 con valor 0xABCD.

Recompilación del módulo

Se ejecutó rebuild_cpp.ps1 para recompilar el módulo C++ y asegurar que las instrucciones están correctamente compiladas y disponibles en el módulo Python.

Decisiones de diseño

Las instrucciones de carga inmediata siguen el patrón estándar de la CPU:

• Usan fetch_byte() o fetch_word() para leer los valores inmediatos de memoria.
• Actualizan el registro destino directamente.
• Consumen el número correcto de M-Cycles según la especificación (2 para 8 bits, 3 para 16 bits).
• El PC se incrementa automáticamente por fetch_byte() y fetch_word().

Archivos Afectados

• src/core/cpp/CPU.cpp - Las instrucciones ya estaban implementadas (líneas 502-508, 510-516, 611-617). Validación confirmó que funcionan correctamente.
• tests/test_core_cpu_loads.py - Se agregó un nuevo test (TestMemoryClearLoop::test_memory_clear_loop_scenario) que valida el escenario completo del bucle de limpieza de memoria. Todos los tests pasaron (24/24).
• viboy_core.cp313-win_amd64.pyd - Módulo recompilado para asegurar que las instrucciones están disponibles.

Tests y Verificación

Se ejecutaron los tests unitarios para validar las instrucciones de carga inmediata:

Comando ejecutado

pytest tests/test_core_cpu_loads.py::TestLD_8bit_Immediate::test_ld_b_immediate tests/test_core_cpu_loads.py::TestLD_8bit_Immediate::test_ld_register_immediate -v

Resultado

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

tests/test_core_cpu_loads.py::TestLD_8bit_Immediate::test_ld_b_immediate PASSED [ 12%]
tests/test_core_cpu_loads.py::TestLD_8bit_Immediate::test_ld_register_immediate[6-b-51] PASSED [ 25%]
tests/test_core_cpu_loads.py::TestLD_8bit_Immediate::test_ld_register_immediate[14-c-66] PASSED [ 37%]
tests/test_core_cpu_loads.py::TestLD_8bit_Immediate::test_ld_register_immediate[22-d-85] PASSED [ 50%]
tests/test_core_cpu_loads.py::TestLD_8bit_Immediate::test_ld_register_immediate[30-e-120] PASSED [ 62%]
tests/test_core_cpu_loads.py::TestLD_8bit_Immediate::test_ld_register_immediate[38-h-154] PASSED [ 75%]
tests/test_core_cpu_loads.py::TestLD_8bit_Immediate::test_ld_register_immediate[46-l-188] PASSED [ 87%]
tests/test_core_cpu_loads.py::TestLD_8bit_Immediate::test_ld_register_immediate[62-a-222] PASSED [100%]

======================= 8 passed in 0.08s =======================

Código del Test (Fragmento Clave)

def test_ld_b_immediate(self):
    """Test: Verificar LD B, d8 (0x06)"""
    mmu = PyMMU()
    regs = PyRegisters()
    cpu = PyCPU(mmu, regs)
    
    regs.pc = 0x0100
    mmu.write(0x0100, 0x06)  # LD B, d8
    mmu.write(0x0101, 0x33)  # d8 = 0x33
    
    cycles = cpu.step()
    
    assert regs.b == 0x33, f"B debe ser 0x33, es 0x{regs.b:02X}"
    assert cycles == 2, "LD B, d8 debe consumir 2 M-Cycles"
    assert regs.pc == 0x0102, "PC debe avanzar 2 bytes"

Test Adicional: Escenario de Bucle de Limpieza de Memoria

Se agregó un test adicional (test_memory_clear_loop_scenario) que valida el escenario completo del bucle de limpieza de memoria que se ejecuta al arrancar ROMs. Este test simula la secuencia exacta que usa Tetris:

1. XOR A (poner A=0)
2. LD HL, d16 (inicializar puntero de memoria)
3. LD C, d8 (inicializar contador bajo)
4. LD B, d8 (inicializar contador alto)
5. LDD (HL), A (escribir cero y decrementar HL)
6. DEC B (decrementar contador)

Este test verifica que todas las instrucciones de carga inmediata funcionan correctamente en conjunto para inicializar los registros necesarios para bucles de limpieza de memoria.

Resultado del test completo: 24 tests pasaron, incluyendo el nuevo test de escenario completo.

Validación Nativa: Todos los tests validan el módulo compilado C++ a través de la interfaz Cython. Las instrucciones funcionan correctamente y consumen el número correcto de ciclos.

Fuentes Consultadas

• Pan Docs: CPU Instruction Set - Load Instructions (opcodes 0x06, 0x0E, 0x21)
• GBEDG (Game Boy Emulator Development Guide): Sección sobre instrucciones de carga inmediata

Implementación basada en documentación técnica oficial. No se consultó código fuente de otros emuladores.

Integridad Educativa

Próximos Pasos

• [ ] Ejecutar el emulador con python main.py roms/tetris.gb y analizar la nueva traza de la CPU.
• [ ] Verificar que el bucle de limpieza de memoria (0x0293-0x0295) ahora termina correctamente.
• [ ] Identificar la siguiente instrucción que falta implementar basándose en la nueva traza.
• [ ] Continuar implementando instrucciones faltantes hasta que la CPU pueda ejecutar la rutina de copia de gráficos a VRAM.