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

Sensor de VRAM para Diagnóstico

Fecha: 2025-12-18 Step ID: 0064 Estado: Draft

Resumen

Se implementó un "Sensor de VRAM" que calcula la suma (checksum) de todos los bytes en la VRAM (0x8000-0x9FFF) y lo muestra en el heartbeat del emulador. Este diagnóstico permite determinar si el problema de la pantalla blanca se debe a VRAM vacía (todo ceros) o a datos gráficos que no se están renderizando correctamente.

Concepto de Hardware

La VRAM (Video RAM) es la memoria dedicada a almacenar los datos gráficos del Game Boy. Ocupa el rango de direcciones 0x8000-0x9FFF (8KB). En esta memoria se almacenan:

  • Tiles (baldosas): Datos de píxeles que forman los gráficos (fondos, sprites).
  • Tile Maps (mapas de tiles): Índices que indican qué tile dibujar en cada posición.
  • Attribute Maps (CGB): Atributos de color y prioridad (solo en Game Boy Color).

Si la VRAM está completamente vacía (todo ceros), la pantalla será blanca independientemente de cómo funcione el renderer. Si la VRAM contiene datos pero la pantalla sigue blanca, el problema está en el renderer (decodificación de tiles, paletas, offsets, capas).

Fuente: Pan Docs - Memory Map, VRAM Access Restrictions

Implementación

Se añadió un método público get_vram_checksum() en la clase MMU que calcula la suma de todos los bytes en el rango 0x8000-0x9FFF. Este valor se muestra en el heartbeat del emulador cada 60 frames (≈1 segundo).

Componentes creados/modificados

  • MMU.get_vram_checksum(): Método que suma todos los bytes de VRAM (0x8000-0x9FFF).
  • Viboy.run(): Modificado para incluir VRAM_SUM en el heartbeat usando print() para garantizar visibilidad.
  • main.py: Añadida opción --verbose para activar nivel de logging INFO.

Decisiones de diseño

Se eligió una suma simple (checksum) en lugar de un hash más complejo porque:

  • Es rápido de calcular (no afecta el rendimiento).
  • Es suficiente para distinguir entre VRAM vacía (suma=0) y VRAM con datos (suma>0).
  • No requiere dependencias adicionales.

CRÍTICO - Visibilidad del Heartbeat: Inicialmente el heartbeat usaba solo logger.info(), pero el nivel de logging por defecto está en WARNING, por lo que los mensajes no se mostraban. Se añadió print() además de logger.info() para garantizar que el heartbeat siempre sea visible en consola, independientemente del nivel de logging configurado. Esto es esencial para diagnóstico.

El checksum se muestra en el heartbeat junto con otros indicadores de diagnóstico (FPS, número de escrituras en VRAM) para facilitar el análisis.

Archivos Afectados

  • src/memory/mmu.py - Añadido método get_vram_checksum()
  • src/viboy.py - Modificado heartbeat para mostrar VRAM_SUM usando print() para garantizar visibilidad
  • main.py - Añadida opción --verbose para activar nivel de logging INFO

Tests y Verificación

Este es un cambio de diagnóstico, no una funcionalidad nueva. No se requieren tests unitarios, pero se debe ejecutar el emulador con una ROM para verificar que el sensor funciona correctamente.

Ejecución manual requerida:

  • Comando: python main.py pkmn.gb (o python main.py pkmn.gb --verbose para más detalle)
  • Entorno: Windows 10, Python 3.10+
  • Criterio de éxito: El heartbeat debe mostrarse en la consola cada segundo con VRAM_SUM=X donde X es un número entero.
  • Interpretación:
    • Si VRAM_SUM=0: La VRAM está vacía. El problema está en la CPU (bucle de copia fallido) o en el MBC (lee ceros del cartucho).
    • Si VRAM_SUM > 0 (ej: 45032): Hay datos gráficos. El problema está en el Renderer (paletas, offsets, capas).

Nota: El resultado del sensor se mostrará en la consola cuando el emulador ejecute el heartbeat (cada 60 frames ≈ 1 segundo). El heartbeat usa print() para garantizar visibilidad incluso si el nivel de logging está en WARNING. El usuario debe ejecutar el emulador y observar el valor de VRAM_SUM en la consola.

Fuentes Consultadas

Integridad Educativa

Lo que Entiendo Ahora

  • Diagnóstico binario: El problema de pantalla blanca puede tener dos causas fundamentales: VRAM vacía o renderer defectuoso. El checksum de VRAM permite distinguir entre ambas.
  • VRAM como almacén de gráficos: La VRAM contiene los datos de píxeles (tiles) y los mapas que indican dónde dibujarlos. Si está vacía, no hay nada que renderizar.
  • Heartbeat como herramienta de diagnóstico: El heartbeat periódico es ideal para mostrar métricas de diagnóstico sin saturar los logs.

Lo que Falta Confirmar

  • Valor esperado de VRAM_SUM: No sé qué valor debería tener el checksum cuando un juego ha cargado correctamente sus gráficos. Esto se determinará ejecutando el emulador y observando el valor.
  • Timing de carga de gráficos: No sé cuándo exactamente el juego debería haber cargado los gráficos en VRAM. Puede que necesite ejecutarse durante varios segundos antes de que la VRAM se llene.

Hipótesis y Suposiciones

Hipótesis principal: Si el emulador corre fluido (sin errores en consola) pero la pantalla es blanca, el problema es binario: o la VRAM está vacía (CPU/MBC no cargan datos) o el renderer no dibuja correctamente los datos que sí están en VRAM.

El sensor de VRAM permitirá confirmar o refutar esta hipótesis de forma inmediata.

Próximos Pasos

  • [ ] Ejecutar el emulador con pkmn.gb y observar el valor de VRAM_SUM en el heartbeat.
  • [ ] Si VRAM_SUM=0: Investigar por qué la CPU no está cargando datos en VRAM (bucle de copia, MBC, etc.).
  • [ ] Si VRAM_SUM > 0: Investigar el renderer (decodificación de tiles, paletas, offsets, capas).
  • [ ] Documentar el valor esperado de VRAM_SUM cuando un juego ha cargado correctamente sus gráficos.