Fix Mínimo y Verificable para IE (0xFFFF)

Resumen

Implementación de instrumentación microscópica para diagnosticar el bug de persistencia/lectura de IE (0xFFFF) identificado en Step 0470. En Step 0470 observamos IEWrite>0 y IE leído=0 sostenido → bug en persistencia/lectura de IE. Se añadió instrumentación en MMU::write() y MMU::read() para rastrear writes y reads de IE, incluyendo PC, timestamp, y valores. Se creó test clean-room para verificar readback inmediato. ✅ Test básico pasa confirmando que write/read funciona en caso simple.

Concepto de Hardware

El registro IE (0xFFFF - Interrupt Enable) es un registro único y persistente en la Game Boy. NO tiene casos especiales, NO tiene gating por modos DMG/CGB, y NO debe ser sobrescrito automáticamente. Cuando el juego escribe a 0xFFFF, el valor DEBE persistir en memory_[0xFFFF] hasta que el juego escriba un nuevo valor.

Framing Correcto del Problema: En Step 0470 observamos IEWrite>0 y IE leído=0 sostenido → bug en persistencia/lectura de IE. Esto NO significa "los juegos no habilitan IE" (eso ya quedó superado en Step 0470). El problema es que los writes SÍ ocurren (IEWrite>0) pero IE siempre se lee como 0x00, indicando que:

1. (A) memory_[0xFFFF] no se escribe: MMU::write(0xFFFF, v) no persiste (no guarda en memory_[0xFFFF])
2. (B) MMU::read(0xFFFF) devuelve 0 por error: Mapeo equivocado / rama CGB / "uninitialized"
3. (C) Algo pisa IE=0 repetidamente: Algún reset/boot/init escribe memory_[0xFFFF] = 0x00 después de cada write del juego

Regla Fundamental: 0xFFFF debe ser un registro único (IE), persistente, sin gating por modos. No hay casos especiales que intercepten o modifiquen writes a 0xFFFF después de que se escriban.

Fuente: Pan Docs - Interrupt Enable Register (IE), Memory Map

Implementación

Se implementó instrumentación microscópica para rastrear writes y reads de IE, permitiendo identificar exactamente dónde se pierde el valor (write vs read).

Fase A - Instrumentación Microscópica (Gated)

Se añadieron variables estáticas y instrumentación en MMU::write() y MMU::read() para rastrear writes y reads de IE:

• MMU.cpp: Variables estáticas adicionales:
  • last_ie_write_pc (uint16_t): PC del último write a IE
  • last_ie_write_timestamp (uint32_t): Timestamp del último write (contador de writes)
  • last_ie_read_value (uint8_t): Último valor leído de IE
  • ie_read_count (uint32_t): Contador de lecturas de IE
• MMU::write(): Cuando addr == 0xFFFF, se guardan last_ie_write_pc, last_ie_write_timestamp
• MMU::read(): Cuando addr == 0xFFFF, se guarda last_ie_read_value, se incrementa ie_read_count, y si VIBOY_DEBUG_PPU=1 y hay writes pero el valor leído es 0x00, se loggea [IE-DROP] con información de write/read
• MMU.hpp: Getters públicos get_last_ie_write_value(), get_last_ie_write_pc(), get_last_ie_read_value(), get_ie_read_count()
• Cython (.pxd/.pyx): Wrappers Python para los nuevos getters

Fase B - Test Clean-Room "Readback Inmediato"

Se creó tests/test_ie_write_persists_0471.py para verificar que writes a IE persisten correctamente:

• test_ie_write_readback_immediate_dmg: Caso 1 (DMG path) - Escribe IE = 0x1F, lee IE → debe ser 0x1F, escribe IE = 0x00, lee IE → debe ser 0x00. Verifica contadores y valores.
• test_ie_write_readback_immediate_cgb: Caso 2 (CGB path) - Similar a Caso 1 pero forzando modo CGB. Verifica que writes persisten en CGB también.
• test_ie_write_readback_multiple_cycles: Verifica que IE persiste a través de múltiples writes/reads (0x01, 0x03, 0x07, 0x0F, 0x1F, 0x00).

Fase C - Verificación del Código

Se verificó que memory_[addr] = value; se ejecuta después de todos los casos especiales (línea 2658 en MMU.cpp). El test básico pasa, confirmando que write/read funciona en caso simple. NO se identificó bug obvio en el código; el problema podría estar en ejecución de ROMs reales o en algún componente que sobrescribe IE después de writes del juego.

Fase D - Actualización de rom_smoke

Se actualizó tools/rom_smoke_0442.py para incluir las nuevas métricas en snapshots:

• last_ie_write_value (IEWriteVal)
• last_ie_read_value (IEReadVal)
• ie_read_count (IEReadCount)
• last_ie_write_pc (IEWritePC)

Archivos Afectados

• src/core/cpp/MMU.cpp - Variables estáticas adicionales y instrumentación en write()/read()
• src/core/cpp/MMU.hpp - Getters para instrumentación microscópica de IE
• src/core/cpp/MMU.cpp - Implementación de getters
• src/core/cython/mmu.pxd - Declaraciones Cython para nuevos getters
• src/core/cython/mmu.pyx - Wrappers Python para nuevos getters
• tests/test_ie_write_persists_0471.py - Test clean-room para readback inmediato
• tools/rom_smoke_0442.py - Snapshot con nuevas métricas IE

Tests y Verificación

Validación de módulo compilado C++:

• Tests unitarios: pytest tests/test_ie_write_persists_0471.py - 3 tests pasando
• Test 1: test_ie_write_readback_immediate_dmg - Verifica readback inmediato en modo DMG
• Test 2: test_ie_write_readback_immediate_cgb - Verifica readback inmediato en modo CGB
• Test 3: test_ie_write_readback_multiple_cycles - Verifica persistencia a través de múltiples ciclos

Código del Test:

def test_ie_write_readback_immediate_dmg(self):
    """Test Caso 1 (DMG path): Readback inmediato después de write."""
    # Caso 1a: Escribir 0x1F y verificar readback inmediato
    self.mmu.write(0xFFFF, 0x1F)
    ie_read_1 = self.mmu.read(0xFFFF)
    assert ie_read_1 == 0x1F, \
        f"IE write no persiste (Caso 1a): escribí 0x1F, leí 0x{ie_read_1:02X}"
    
    # Verificar último valor escrito
    last_ie_write_value = self.mmu.get_last_ie_write_value()
    assert last_ie_write_value == 0x1F, \
        f"Último valor escrito a IE incorrecto: esperado 0x1F, obtenido 0x{last_ie_write_value:02X}"
    
    # Caso 1b: Escribir 0x00 y verificar readback inmediato
    self.mmu.write(0xFFFF, 0x00)
    ie_read_2 = self.mmu.read(0xFFFF)
    assert ie_read_2 == 0x00, \
        f"IE write no persiste (Caso 1b): escribí 0x00, leí 0x{ie_read_2:02X}"

Resultado: Todos los tests pasan, confirmando que write/read funciona correctamente en caso simple.

Datos Reales de rom_smoke (Fase D)

Se ejecutaron pruebas con rom_smoke_0442.py en 3 ROMs (240 frames cada una) con VIBOY_DEBUG_PPU=1 para obtener datos reales sobre el comportamiento de IE.

ROMs ejecutadas:

• tetris_dx.gbc (CGB)
• mario.gbc (CGB)
• tetris.gb (DMG - control)

Conclusión Principal

IE persiste correctamente cuando se escribe un valor no-cero (confirmado por tetris.gb con IE=0x09). Los juegos CGB (tetris_dx.gbc, mario.gbc) escriben 0x00 a IE repetidamente, lo cual puede ser comportamiento correcto del juego (deshabilitar interrupciones intencionalmente) o un problema en la lógica de inicialización del modo CGB. El test básico pasa confirmando que el mecanismo write/read funciona correctamente.

IE-DROP Count por ROM

• tetris_dx.gbc: 20 mensajes [IE-DROP]
• mario.gbc: 20 mensajes [IE-DROP]
• tetris.gb: 20 mensajes [IE-DROP] (pero IE persiste correctamente, probablemente falsos positivos debido a que el check es demasiado agresivo)

Decisión Final por ROM

Snapshots Clave - tetris.gb (DMG - Control)

tetris.gb muestra que IE persiste correctamente cuando se escribe un valor no-cero:

• Frame 0: IE=0x01, IEWriteVal=0x01, IEReadVal=0x01
• Frame 60: IE=0x09, IEWriteVal=0x09, IEReadVal=0x09, VBlankServ=59
• Frame 120: IE=0x09, IEWriteVal=0x09, IEReadVal=0x09, VBlankServ=119
• Frame 180: IE=0x09, IEWriteVal=0x09, IEReadVal=0x09, VBlankServ=179

Esto confirma que el mecanismo write/read de IE funciona correctamente cuando los juegos escriben valores no-cero.

Interpretación

Los datos muestran que IE persiste correctamente. Los juegos CGB escriben 0x00 a IE repetidamente (IEWriteVal=0x00 siempre), lo cual puede ser comportamiento correcto del juego (deshabilitar interrupciones intencionalmente durante la inicialización) o un problema en la lógica de inicialización del modo CGB que requiere investigación adicional.

Fuentes Consultadas

• Pan Docs: Interrupts, Interrupt Enable Register (IE)
• Pan Docs: Memory Map

Integridad Educativa

Próximos Pasos

• ✅ Instrumentación microscópica implementada
• ✅ Test clean-room creado y pasando
• ✅ rom_smoke actualizado con nuevas métricas (incluyendo fb_nonzero)
• ✅ Ejecutar rom_smoke con ROMs reales (tetris_dx.gbc, mario.gbc, tetris.gb) - Completado
• ✅ Analizar logs y snapshots - Completado
• ✅ Confirmar que IE persiste correctamente - Completado
• ⏳ Investigar por qué los juegos CGB escriben 0x00 a IE (puede ser comportamiento correcto del juego o problema de inicialización CGB)