⚠️ Clean-Room / Educativo

Este proyecto es educativo y Open Source. No se copia código de otros emuladores. Implementación basada únicamente en documentación técnica y tests permitidas.

Debug: Extensión del Trazado de CPU a 500 Instrucciones

Fecha: 2025-12-20 Step ID: 0154 Estado: 🔍 DRAFT

Resumen

El análisis del Step 0153 confirmó que el fix del flag Z funciona correctamente, pero reveló que la rutina de inicialización de la ROM contiene múltiples bucles de limpieza anidados. La traza actual de 200 instrucciones es insuficiente para observar qué ocurre después de que todos estos bucles terminan. Se aumentó el límite de traza de la CPU de 200 a 500 instrucciones para capturar una ventana de observación mucho más amplia y poder ver la secuencia de ejecución que sigue a los bucles de inicialización.

Concepto de Hardware

Las ROMs de Game Boy ejecutan rutinas de inicialización complejas al arrancar. Estas rutinas no solo limpian una única área de memoria, sino que realizan múltiples operaciones secuenciales:

  • Limpieza de WRAM: Borrado de la memoria de trabajo (0xC000-0xDFFF).
  • Limpieza de HRAM: Borrado de la memoria de alta velocidad (0xFF80-0xFFFE).
  • Inicialización de registros de hardware: Configuración de la PPU (LCDC, BGP, etc.).
  • Configuración de interrupciones: Establecimiento de vectores y habilitación de interrupciones.

Cada una de estas operaciones puede involucrar bucles anidados que consumen cientos de instrucciones. Para poder observar el comportamiento completo de la CPU durante la inicialización, necesitamos una traza lo suficientemente larga como para capturar no solo los bucles de limpieza, sino también las instrucciones que siguen después de que estos terminan.

El límite de traza es una herramienta de diagnóstico que nos permite "alejar el zoom" y ver el panorama completo de la ejecución, en lugar de quedarnos atascados en los detalles de un solo bucle.

Implementación

Se modificó la constante DEBUG_INSTRUCTION_LIMIT en el archivo src/core/cpp/CPU.cpp para aumentar el límite de instrucciones trazadas de 200 a 500.

Componentes modificados

  • CPU.cpp: Aumento de DEBUG_INSTRUCTION_LIMIT de 200 a 500.

Cambio realizado

El cambio es simple pero efectivo: aumentar el límite de traza nos permite capturar más instrucciones en la salida de diagnóstico, lo que nos ayudará a identificar qué ocurre después de que los bucles de inicialización terminan. 

// Variables estáticas para logging de diagnóstico
static int debug_instruction_counter = 0;
// Aumentamos el límite para ver más allá de los bucles de limpieza
static const int DEBUG_INSTRUCTION_LIMIT = 500;

Archivos Afectados

  • src/core/cpp/CPU.cpp - Aumento de DEBUG_INSTRUCTION_LIMIT de 200 a 500.

Tests y Verificación

Este cambio no requiere tests unitarios específicos, ya que solo modifica el límite de logging de diagnóstico. La validación se realizará mediante:

  • Recompilación del módulo C++: Ejecutar .\rebuild_cpp.ps1 para recompilar con el nuevo límite.
  • Ejecución del emulador: Ejecutar python main.py roms/tetris.gb para generar la nueva traza extendida.
  • Análisis de la traza: Examinar las 500 instrucciones capturadas para identificar qué ocurre después de los bucles de inicialización.

Resultado esperado: La traza debería mostrar las primeras 500 instrucciones ejecutadas, incluyendo los bucles de limpieza y las instrucciones que siguen después de que estos terminan. Esto nos permitirá identificar el siguiente opcode que debemos implementar para que el juego pueda continuar su ejecución.

Fuentes Consultadas

  • Análisis del Step 0153: Confirmación de múltiples bucles anidados en rutinas de inicialización.
  • Comportamiento observado en trazas de CPU: Los juegos ejecutan secuencias complejas de inicialización.

Nota: Este cambio es puramente de diagnóstico y no requiere documentación técnica específica del hardware.

Integridad Educativa

Lo que Entiendo Ahora

  • Rutinas de inicialización complejas: Las ROMs ejecutan múltiples bucles anidados durante la inicialización, no solo uno.
  • Importancia del límite de traza: Un límite demasiado bajo puede ocultar información crítica sobre el comportamiento de la CPU.
  • Estrategia de debugging: Aumentar el límite de traza es una técnica válida para "alejar el zoom" y ver el panorama completo.

Lo que Falta Confirmar

  • Contenido de la traza extendida: Necesitamos ver qué instrucciones aparecen después de los bucles de inicialización.
  • Siguiente opcode crítico: Identificar qué instrucción falta implementar para que el juego pueda continuar.
  • Configuración de hardware: Verificar si el juego intenta escribir en registros de I/O (LCDC, BGP, etc.) después de la inicialización.

Hipótesis y Suposiciones

Hipótesis principal: Después de que los bucles de limpieza terminan, el juego debería empezar a configurar el hardware, especialmente los registros de la PPU. Esperamos ver instrucciones como LDH (n), A (0xE0) escribiendo en registros como 0xFF40 (LCDC) o 0xFF47 (BGP).

Próximos Pasos

  • [ ] Recompilar el módulo C++ con el nuevo límite de traza.
  • [ ] Ejecutar el emulador con la ROM de Tetris y capturar la traza completa de 500 instrucciones.
  • [ ] Analizar la traza para identificar qué ocurre después de los bucles de inicialización.
  • [ ] Identificar el primer opcode no implementado o sospechoso que aparece en la traza.
  • [ ] Implementar el siguiente opcode crítico para desbloquear el progreso del juego.