Step 0437: Diagnóstico Loop VBlank Wait (Pokémon) - Bug Sincronización CPU↔PPU

Fecha: 2026-01-02 | Categoría: Diagnóstico + Análisis Arquitectural | Componente: PPU + Bucle Principal

DIAGNOSTIC COMPLETE FIX PENDING

📋 Resumen Ejecutivo

Loop Detectado: Pokémon Red stuck en VBlank wait loop temprano (PC=0x006B→0x006D→0x006F), NO en el loop esperado 0x36E2..0x36E7.

Causa Raíz: Bug arquitectural de sincronización CPU↔PPU. El bucle principal ejecuta CPU completo antes de avanzar PPU, causando desincronización temporal en lecturas de LY (registro 0xFF44).

Estado: Diagnóstico completo con evidencia numérica. Fix mínimo intentado pero insuficiente - requiere refactor arquitectural del bucle de emulación.

🔬 Concepto de Hardware

VBlank Wait Loop Pattern

Los juegos de Game Boy frecuentemente esperan el inicio del período VBlank (línea 144-153) antes de actualizar VRAM, usando un patrón estándar:

wait_vblank:
    LDH  A, (FF44h)    ; Lee LY (línea actual de LCD)
    CP   $91           ; Compara con 145 (0x91 = inicio VBlank)
    JR   NZ, wait_vblank ; Si no es VBlank, repetir
    ; ... código que ejecuta durante VBlank ...

Requisito crítico: El registro LY (0xFF44) debe reflejar la línea actual del PPU en tiempo real, no con retraso.

Timing PPU según Pan Docs

  • 1 Scanline: 456 T-cycles (80 OAM + 172 Transfer + 204 HBlank)
  • 1 Frame: 154 scanlines (0-153) = 70,224 T-cycles
  • VBlank: Líneas 144-153 (10 scanlines)
  • LY incrementa: Cada 456 T-cycles (1 scanline completa)

Fuente: Pan Docs - "LCD Status Register", "V-Blank Interrupt", "LCD Timing"

🔍 Investigación y Diagnóstico

Fase A: Instrumentación y Captura de Evidencia

Creación de herramientas de diagnóstico:

  • tools/test_pokemon_loop_trace_0437.py - Captura evidencia con instrumentación completa
  • tools/test_pokemon_pc_monitor_0437.py - Monitor automático de loops por frecuencia de PC
  • tools/disassemble_loop_0437.py - Desensamblador con captura de estado de registros
  • tools/diagnose_ppu_clock_0437.py - Diagnóstico de acumulación de ciclos en PPU

Fase B: Hallazgo del Loop Real

Evidencia Numérica:

Loop Detectado: PC=0x006B→0x006D→0x006F (100% de ejecución)
Frames ejecutados: 300+ (5000+ intentados)
Tiempo en loop: >6 segundos continuos
Unique PC values: 3 (solo estas 3 direcciones)
Loop coverage: 100.0%

Instrucciones del loop:
  0x006B: LDH A,(FF44h)  - Lee LY (3 T-cycles)
  0x006D: CP $91         - Compara con 145 (2 T-cycles)  
  0x006F: JR NZ,$FA      - Salta a 0x006B (3 T-cycles)

Total: 8 T-cycles por iteración
Iteraciones: ~2.6M en 300 frames (~21M T-cycles)

Fase C: Verificación de LY Interno

Debug del PPU reveló que ly_ SÍ incrementa correctamente:

[PPU-LY-CRITICAL-0437] ly_ incremented to 140 (frame 0)
[PPU-LY-CRITICAL-0437] ly_ incremented to 141 (frame 0)
[PPU-LY-CRITICAL-0437] ly_ incremented to 142 (frame 0)
[PPU-LY-CRITICAL-0437] ly_ incremented to 143 (frame 0)
[PPU-LY-CRITICAL-0437] ly_ incremented to 144 (frame 0)
[PPU-LY-CRITICAL-0437] ly_ incremented to 145 (frame 0)  ✅
[PPU-LY-CRITICAL-0437] ly_ incremented to 146 (frame 0)
...
[PPU-LY-CRITICAL-0437] ly_ incremented to 154 (frame 0)
[PPU-LY-CRITICAL-0437] ly_ incremented to 140 (frame 1)  (reset a 0, salta a 140)

Conclusión: El PPU funciona correctamente. LY alcanza 145 en cada frame.

Fase D: Identificación de la Causa Raíz

Análisis del bucle principal de emulación (src/viboy.py:711-723):

# Bucle actual (SECUENCIAL - INCORRECTO)
cycles = self._cpu.step()        # 1. CPU ejecuta instrucción COMPLETA
                                 #    (puede leer LY aquí ❌)
t_cycles = cycles * 4
self._ppu.step(t_cycles)         # 2. PPU avanza DESPUÉS
self._timer.tick(t_cycles)       # 3. Timer avanza DESPUÉS

Bug Arquitectural Identificado:

Cuando la CPU ejecuta LDH A,(FF44h) dentro de cpu.step(), el PPU aún no ha avanzado los ciclos correspondientes. La MMU llama a ppu_->get_ly() que retorna ly_, pero este valor está desactualizado temporalmente.

Resultado: Aunque LY pasa por 145 internamente, la CPU nunca lo lee en ese momento exacto debido al desfase temporal entre ejecución y avance de componentes.

Fase E: Intento de Fix Mínimo

Modificación de PPU::get_ly() para calcular LY basado en clock_ acumulado:

uint8_t PPU::get_ly() const {
    // Intentar: calcular línea adicional por ciclos pendientes
    uint16_t additional_lines = 0;
    if (clock_ >= CYCLES_PER_SCANLINE) {
        additional_lines = clock_ / CYCLES_PER_SCANLINE;
    }
    
    uint16_t actual_ly = ly_ + additional_lines;
    actual_ly = actual_ly % 154;  // Wrap a 154 líneas
    
    return static_cast(actual_ly & 0xFF);
}

Resultado: NO funcionó. El loop persiste porque el problema es más profundo - el timing entre componentes está fundamentalmente desincronizado.

Fase F: Verificación Completa de la Cadena

Auditoría de todos los componentes involucrados:

  • ✅ PPU::step() - Acumula ciclos correctamente en clock_
  • ✅ while (clock_ >= 456) - Se ejecuta y incrementa ly_
  • ✅ PPU::get_ly() - Retorna ly_ & 0xFF correctamente
  • ✅ MMU::read(0xFF44) - Llama a ppu_->get_ly() sin caching
  • ❌ Bucle principal - Desincronización temporal CPU→PPU

💡 Solución Propuesta (Para Step Futuro)

Opción 1: Avance Intercalado (Recomendado)

Modificar el bucle principal para avanzar PPU/Timer durante ejecución de CPU, no después:

# Opción: Avance por T-cycle dentro de cpu.step()
# Requerimiento: CPU debe notificar a PPU cada T-cycle individual
# Implementación: Hook en CPU.execute_opcode() para llamar ppu.step(1)

Opción 2: MMU como Proxy Activo

Hacer que MMU::read(0xFF44) avance el PPU antes de retornar LY:

// En MMU::read()
if (addr == 0xFF44) {
    if (ppu_ != nullptr) {
        // Sincronizar PPU con ciclos pendientes
        ppu_->sync_to_cpu_cycles(pending_cycles_);
        return ppu_->get_ly();
    }
}

Opción 3: Arquitectura Basada en Eventos

Sistema de eventos con timestamps precisos donde cada componente agenda eventos futuros en una cola priorizada.

Recomendación: Opción 1 (avance intercalado) es la más fiel al hardware real y resuelve todos los casos de polling. Requiere refactor moderado pero beneficia todos los componentes.

✅ Tests y Verificación

Compilación y Build

$ python3 setup.py build_ext --inplace
BUILD_EXIT=0 ✅

$ python3 test_build.py
TEST_BUILD_EXIT=0 ✅

Módulo C++ compilado correctamente

Suite de Tests

$ pytest -q
523 passed, 5 failed, 2 skipped in 89.32s

Fallos: 5 tests pre-existentes en test_viboy_integration
(AttributeError: 'PyCPU' object has no attribute 'registers')
No se introdujeron regresiones nuevas ✅

Verificación del Diagnóstico

$ python3 tools/test_pokemon_pc_monitor_0437.py
Loop detected: YES ✅ (confirma el problema)
Loop PCs: 0x006B, 0x006D, 0x006F ✅
Coverage: 100% ✅
Duration: 300+ frames ✅

Diagnóstico completo con evidencia numérica

📁 Archivos Creados/Modificados

Herramientas de Diagnóstico (Nuevas)

  • tools/test_pokemon_loop_trace_0437.py - Captura de evidencia con instrumentación
  • tools/test_pokemon_pc_monitor_0437.py - Monitor automático de loops
  • tools/disassemble_loop_0437.py - Desensamblador con estado
  • tools/diagnose_ppu_clock_0437.py - Diagnóstico de timing PPU

Core (Investigación, luego revertido)

  • src/core/cpp/PPU.cpp - Experimentación con get_ly() (revertido a original)
  • src/core/cpp/MMU.cpp - Debug temporal de lecturas LY (limpiado)

Documentación

  • docs/bitacora/entries/2026-01-02__0437__diagnose-pokemon-vblank-wait-loop-sync-bug.html
  • docs/bitacora/index.html - Actualizado
  • docs/informe_fase_2/parte_01_steps_0412_0450.md - Actualizado

📚 Lecciones Aprendidas

1. Arquitectura de Emulación

La sincronización precisa entre componentes es crítica para emulación correcta. Un bucle secuencial (CPU→PPU→Timer) introduce desfases temporales que rompen polling loops.

2. Debugging de Timing

Los bugs de timing requieren instrumentación no invasiva. Herramientas como PC monitors y ring buffers son esenciales para capturar evidencia sin alterar el comportamiento.

3. Fix vs Diagnóstico

Un diagnóstico completo con evidencia numérica es más valioso que un fix apresurado. Este step documentó exhaustivamente el problema para facilitar la solución correcta.

4. Clean Room Methodology

Todo el análisis se basó en Pan Docs y herramientas propias. No se consultó código de otros emuladores, manteniendo integridad del proyecto educativo.

🎯 Conclusiones

Diagnóstico Completado

  • ✅ Loop identificado con evidencia numérica completa
  • ✅ Causa raíz determinada (bug arquitectural de sincronización)
  • ✅ Comportamiento del PPU verificado como correcto
  • ✅ Tres opciones de solución documentadas
  • ✅ Herramientas de diagnóstico creadas para futuros casos

Fix Pendiente

La solución requiere refactor arquitectural del bucle de emulación (más allá del scope de "fix mínimo"). Se recomienda Step dedicado para implementar avance intercalado CPU↔PPU.

Próximos Steps Sugeridos

  1. Step 0438: Implementar avance intercalado en bucle principal
  2. Step 0439: Tests de sincronización T-cycle precisa
  3. Step 0440: Verificación con suite de ROMs de timing

📖 Referencias