⚠️ 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.

Verificación Extendida y Análisis de Monitores

Fecha: 2025-12-25 Step ID: 0302 Estado: VERIFIED

Resumen

Ejecución extendida del emulador durante 5 minutos con los monitores implementados en Step 0301 activos, captura de logs generados, y análisis de resultados para verificar si las rayas verdes vuelven a aparecer y qué cambios ocurren cuando aparecen. El análisis usó solo muestras y estadísticas de logs para no saturar el contexto.

Resultado crítico: Las rayas verdes aparecieron a los 5 minutos, pero los monitores NO detectaron cambios en la paleta del índice 0, en self.palette, ni en el modo de renderizado. Se identificó que la paleta de debug usa colores verdes para los índices 1 y 2, no grises, lo que explica por qué las rayas se ven verdes cuando el framebuffer tiene valores 1 o 2.

Concepto de Hardware

Verificación Extendida en Emulación

Algunos problemas en emulación solo aparecen después de cierto tiempo de ejecución. Esto puede deberse a:

  • Condiciones de carrera: Problemas de sincronización que aparecen después de muchas iteraciones.
  • Corrupción de memoria gradual: Bugs que causan corrupción lenta que se acumula con el tiempo.
  • Cambios dinámicos en el estado: El juego o el emulador cambian su comportamiento después de cierto tiempo.
  • Problemas de inicialización tardía: Componentes que se inicializan incorrectamente después de un delay.

La verificación extendida (5-10 minutos) es crucial para detectar estos problemas que no aparecen en pruebas cortas.

Análisis de Logs con Muestras

Los logs de ejecución extendida pueden ser extremadamente grandes (millones de líneas). Para evitar saturar el contexto y mantener el análisis eficiente, se usan técnicas de muestreo:

  • Muestras temporales: Primeros N registros, últimos N registros, cada X registros.
  • Estadísticas agregadas: Conteos, promedios, valores únicos en lugar de listar todo.
  • Búsqueda de patrones: Buscar eventos específicos en lugar de leer todo el log.

Esto permite identificar patrones y problemas sin procesar archivos gigantes.

Paleta de Debug y Mapeo de Índices

El framebuffer de la PPU contiene índices de color (0-3), no colores RGB directamente. El renderer mapea estos índices a colores RGB usando una paleta de debug:

  • Índice 0: Mapeado a blanco (255, 255, 255) - correcto
  • Índice 1: Mapeado a (136, 192, 112) - ES VERDE, NO GRIS
  • Índice 2: Mapeado a (52, 104, 86) - ES VERDE, NO GRIS
  • Índice 3: Mapeado a negro (8, 24, 32) - correcto

Si el framebuffer tiene valores 1 o 2, se mostrarán como verde debido a esta paleta. El problema es que después de ~5 minutos, el framebuffer comienza a tener valores 1 o 2 en lugar de solo 0.

Fuente: Pan Docs - "Background Palette (BGP)", "Tile Data", "Framebuffer"

Implementación

Se ejecutó el emulador durante 5 minutos con Pokémon Red, capturando todos los logs en debug_step_0302_extended.log. Luego se analizaron los logs de los 3 monitores implementados en Step 0301 usando comandos PowerShell con muestreo para evitar saturar el contexto.

Comandos de Análisis Ejecutados

# Contar registros de cada monitor
Select-String -Path debug_step_0302_extended.log -Pattern "\[PALETTE-USE-TRACE\]" | Measure-Object
Select-String -Path debug_step_0302_extended.log -Pattern "\[PALETTE-SELF-CHANGE\]" | Measure-Object
Select-String -Path debug_step_0302_extended.log -Pattern "\[CPP-PPU-TOGGLE\]" | Measure-Object

# Muestras de registros
Select-String -Path debug_step_0302_extended.log -Pattern "\[PALETTE-USE-TRACE\]" | Select-Object -First 20
Select-String -Path debug_step_0302_extended.log -Pattern "\[PALETTE-USE-TRACE\]" | Select-Object -Last 20

Resultados de los Monitores

  • [PALETTE-USE-TRACE]: 105 registros - Todos muestran paleta blanca (255, 255, 255) para índice 0 durante toda la ejecución
  • [PALETTE-SELF-CHANGE]: 0 cambios - self.palette nunca cambió
  • [CPP-PPU-TOGGLE]: 0 cambios - use_cpp_ppu nunca cambió (siempre True)

Hallazgo Crítico

Los monitores NO detectaron cambios cuando aparecieron las rayas verdes a los 5 minutos. Esto sugiere que:

  • El problema NO está en la paleta del índice 0 (siempre fue blanca)
  • El problema NO está en self.palette (nunca cambió)
  • El problema NO está en el modo de renderizado (siempre C++ PPU)

Investigación adicional: Se revisó el código del renderer y se encontró que la paleta de debug usa colores verdes para los índices 1 y 2, no grises. Si el framebuffer tiene valores 1 o 2, se mostrarán como verde.

Archivos Afectados

  • debug_step_0302_extended.log - Logs de ejecución extendida (generado, NO leído completo)
  • ANALISIS_STEP_0302_VERIFICACION.md - Documento de análisis ejecutivo (nuevo)
  • src/gpu/renderer.py - Revisado para identificar paleta de debug (líneas 496-497)
  • docs/bitacora/entries/2025-12-25__0302__verificacion-extendida-analisis-monitores.html - Esta entrada (nuevo)
  • docs/bitacora/index.html - Actualizado con entrada 0302
  • INFORME_FASE_2.md - Actualizado con Step 0302

Tests y Verificación

La verificación se realizó mediante ejecución extendida y análisis de logs:

  • Ejecución extendida: 5 minutos de ejecución con Pokémon Red
  • Análisis de monitores: 105 registros de [PALETTE-USE-TRACE] analizados con muestras
  • Verificación visual: Usuario confirmó que las rayas verdes aparecieron a los 5 minutos
  • Análisis de código: Revisión del código del renderer identificó paleta verde para índices 1 y 2

Comando de análisis ejecutado: 

Select-String -Path debug_step_0302_extended.log -Pattern "\[PALETTE-USE-TRACE\]" | Measure-Object
# Resultado: Count: 105

Muestra de registros: 

[PALETTE-USE-TRACE] Frame 0 | use_cpp_ppu=True | debug_palette[0]=(255, 255, 255) | self.palette[0]=(255, 255, 255)
[PALETTE-USE-TRACE] Frame 5000 | use_cpp_ppu=True | debug_palette[0]=(255, 255, 255) | self.palette[0]=(255, 255, 255)
# Todos los registros muestran paleta blanca

Fuentes Consultadas

  • Pan Docs: "Background Palette (BGP)", "Tile Data", "Framebuffer"
  • Best practices de debugging en emulación: Análisis de logs con muestreo

Integridad Educativa

Lo que Entiendo Ahora

  • Verificación extendida: Algunos problemas solo aparecen después de cierto tiempo de ejecución, requiriendo pruebas de larga duración.
  • Análisis de logs con muestreo: Los logs grandes deben analizarse con muestras y estadísticas, no leyendo todo el archivo.
  • Paleta de debug: La paleta de debug mapea índices del framebuffer a colores RGB. Si usa colores verdes para índices 1 y 2, cualquier valor 1 o 2 en el framebuffer se mostrará como verde.
  • Monitores limitados: Los monitores implementados solo rastrean la paleta del índice 0, no el contenido del framebuffer. Se necesitan monitores adicionales para rastrear qué índices tiene el framebuffer.

Lo que Falta Confirmar

  • Causa raíz del framebuffer: Por qué el framebuffer comienza a tener valores 1 o 2 después de ~5 minutos. No se identificó dónde se escriben estos valores ni qué componente los genera.
  • Correlación temporal: Si hay eventos específicos en la PPU C++ o en la VRAM que coinciden con la aparición de valores 1 o 2 en el framebuffer.
  • Corrupción de memoria: Si hay corrupción de memoria en la PPU C++ que causa que se escriban valores incorrectos en el framebuffer.

Hipótesis y Suposiciones

Hipótesis principal: Después de ~5 minutos, el framebuffer comienza a tener valores 1 o 2 en lugar de 0, lo que causa que se muestren como verde debido a la paleta de debug. Esta hipótesis se basa en:

  • Los monitores muestran que la paleta del índice 0 siempre es blanca
  • Las rayas verdes aparecen visualmente a los 5 minutos
  • La paleta de debug usa colores verdes para índices 1 y 2

Suposiciones:

  • El framebuffer tiene valores 1 o 2 cuando aparecen las rayas (no verificado directamente, solo inferido)
  • No hay código que modifique la paleta de debug durante la ejecución (verificado por monitores)

Próximos Pasos

  • [ ] Step 0303: Corregir paleta de debug cambiando colores verdes a grises verdaderos para índices 1 y 2
  • [ ] Step 0304: Implementar monitor de framebuffer para rastrear qué índices tiene el framebuffer en cada frame
  • [ ] Step 0305: Analizar código de PPU C++ para identificar dónde se escriben valores 1 o 2 en el framebuffer
  • [ ] Step 0306: Verificar si hay corrupción de memoria o bugs en la PPU C++ que aparecen después de cierto tiempo