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

El Sensor de VRAM: Monitoreo de Escrituras en Tiempo Real

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

Resumen

El "Test del Checkerboard" del Step 0192 validó que nuestra tubería de renderizado funciona perfectamente. El diagnóstico es definitivo: la pantalla en blanco se debe a que la VRAM está vacía, no a un problema de renderizado.

La hipótesis actual es que la CPU nunca ejecuta el código que copia los datos del logo de Nintendo desde la ROM a la VRAM. Está atrapada en un bucle lógico antes de llegar a ese punto.

Este Step implementa un "sensor de movimiento" en la MMU que detectará y reportará la primera vez que cualquier instrucción intente escribir un byte en la VRAM (0x8000-0x9FFF). Esto nos dará una respuesta binaria y definitiva: ¿la CPU intenta escribir en VRAM, sí o no?

Concepto de Ingeniería: El Punto Único de Verdad (Single Point of Truth)

En nuestra arquitectura, cada escritura en memoria, sin importar qué instrucción de la CPU la origine (LD (HL), A, LDD (HL), A, o una futura transferencia DMA), debe pasar a través de un único método: MMU::write(). Este método es nuestro "punto único de verdad" para todas las operaciones de escritura.

Al colocar un sensor de diagnóstico en este punto, podemos estar 100% seguros de que capturaremos cualquier intento de modificar la VRAM, dándonos una respuesta definitiva: ¿la CPU intenta escribir, sí o no?

Principio del Sensor Binario: Este sensor actúa como un "detector de mentiras" que nos dirá de una vez por todas si la CPU está cumpliendo con su parte del trato. No necesitamos capturar todas las escrituras (eso sería demasiado ruido), solo la primera. Eso es suficiente para responder a nuestra pregunta fundamental.

Rango de VRAM: El rango de memoria de VRAM en Game Boy es de 0x8000 a 0x9FFF (8KB). Este rango contiene tanto los datos de tiles como los tilemaps. Cualquier escritura en este rango es significativa para nuestro diagnóstico.

Implementación

Hemos añadido una comprobación simple dentro del método MMU::write() que detecta la primera escritura en el rango de VRAM y la reporta inmediatamente en la consola.

Componentes modificados

src/core/cpp/MMU.cpp: Añadido include <cstdio> y sensor de VRAM en el método write()

Código del Sensor

El sensor utiliza una variable estática para asegurar que el mensaje se imprima solo una vez:

void MMU::write(uint16_t addr, uint8_t value) {
    // Asegurar que la dirección esté en el rango válido
    addr &= 0xFFFF;
    
    // Enmascarar el valor a 8 bits
    value &= 0xFF;
    
    // --- SENSOR DE VRAM (Step 0194) ---
    // Variable estática para asegurar que el mensaje se imprima solo una vez.
    static bool vram_write_detected = false;
    if (!vram_write_detected && addr >= 0x8000 && addr <= 0x9FFF) {
        printf("\n--- [VRAM WRITE DETECTED!] ---\n");
        printf("Primera escritura en VRAM en Addr: 0x%04X | Valor: 0x%02X\n", addr, value);
        printf("--------------------------------\n\n");
        vram_write_detected = true;
    }
    // --- Fin del Sensor ---
    
    // ... resto de la lógica de write()
}

Decisiones de diseño

Variable estática: Usamos una variable estática local para que el mensaje se imprima solo una vez durante toda la ejecución del emulador. Esto evita inundar la consola con mensajes repetitivos.
Detección de primera escritura: Solo necesitamos saber si la CPU intenta escribir alguna vez en VRAM. La primera escritura es suficiente para responder a nuestra pregunta.
Ubicación del sensor: El sensor está colocado justo después de la validación inicial de dirección y valor, pero antes de cualquier otra lógica especial (registros de hardware, etc.). Esto asegura que capturamos todas las escrituras en VRAM, sin excepción.
Información reportada: Reportamos tanto la dirección como el valor escrito, para poder analizar qué está haciendo la CPU si el sensor se activa.

Archivos Afectados

src/core/cpp/MMU.cpp - Añadido include <cstdio> y sensor de VRAM en método write()
docs/bitacora/entries/2025-12-20__0194__sensor-vram-monitoreo-escrituras-tiempo-real.html - Nueva entrada de bitácora
docs/bitacora/index.html - Actualizado con la nueva entrada
INFORME_FASE_2.md - Actualizado con el Step 0194

Tests y Verificación

La verificación de este Step es principalmente de compilación y ejecución del emulador. El resultado esperado es que el sensor se active (o no) durante la ejecución, dándonos información definitiva sobre el comportamiento de la CPU.

Proceso de Verificación

Recompilar el módulo C++:
```
.\rebuild_cpp.ps1
```
Resultado: ✅ Compilación exitosa (con warnings menores esperados de variables no usadas en otros archivos)
Ejecutar el emulador:
```
python main.py roms/tetris.gb
```
El emulador debe ejecutarse normalmente. El usuario debe presionar una tecla para pasar el bucle del Joypad.
Observar la consola:
El sensor buscará el mensaje [VRAM WRITE DETECTED!] en la salida de la consola.

Validación de módulo compilado C++

El emulador utiliza el módulo C++ compilado (viboy_core), que contiene el sensor de VRAM implementado en MMU::write(). Cualquier escritura en VRAM pasará a través de este método y activará el sensor si corresponde.

Resultados Posibles

Hay dos resultados posibles al ejecutar el emulador:

NO aparece el mensaje [VRAM WRITE DETECTED!]:
- Significado: Nuestra hipótesis es correcta. La CPU NUNCA intenta escribir en la VRAM. Está atrapada en un bucle lógico antes de la rutina de copia de gráficos.
- Diagnóstico: Hemos eliminado todas las causas de hardware. El problema debe ser un bucle de software en la propia ROM que no hemos previsto, quizás esperando otro registro de I/O que no hemos inicializado correctamente.
- Siguiente Paso: Volveríamos a activar la traza de la CPU, pero esta vez con la confianza de que estamos buscando un bucle de software puro, no un deadlock de hardware.
SÍ aparece el mensaje [VRAM WRITE DETECTED!]:
- Significado: ¡Nuestra hipótesis principal era incorrecta! La CPU SÍ está escribiendo en la VRAM.
- Diagnóstico: Si la CPU está escribiendo en la VRAM, pero la pantalla sigue en blanco, solo puede significar una cosa: está escribiendo los datos equivocados (por ejemplo, ceros) o en el lugar equivocado.
- Siguiente Paso: Analizaríamos el valor y la dirección de la primera escritura para entender qué está haciendo la CPU. ¿Está limpiando la VRAM antes de copiar? ¿Está apuntando a una dirección incorrecta?

Fuentes Consultadas

Pan Docs: Memory Map
Pan Docs: VRAM (Video RAM)
Principios de ingeniería de sistemas: Single Point of Truth y instrumentación de diagnóstico

Integridad Educativa

Lo que Entiendo Ahora

El poder del punto único de verdad: En arquitecturas bien diseñadas, todas las operaciones de un tipo específico (en este caso, escrituras en memoria) pasan a través de un único punto. Esto hace que la instrumentación sea trivial y 100% confiable.
Diagnóstico binario: A veces, la mejor herramienta de diagnóstico es la más simple: una pregunta binaria (sí/no) que puede responderse con una sola observación. No necesitamos capturar todo el flujo, solo necesitamos saber si algo está ocurriendo o no.
Sensor de movimiento: Este sensor actúa como un "micrófono" que nos grita en el instante en que algo ocurre. Es simple, directo y definitivo.

Lo que Falta Confirmar

¿La CPU intenta escribir en VRAM? Esta es la pregunta fundamental que el sensor responderá. Dependiendo de la respuesta, sabremos exactamente hacia dónde dirigir nuestros esfuerzos de diagnóstico.
Si la CPU sí escribe, ¿qué está escribiendo? Si el sensor se activa, necesitaremos analizar el valor y la dirección para entender qué está haciendo la CPU.

Hipótesis y Suposiciones

Hipótesis principal: La CPU nunca intenta escribir en VRAM porque está atrapada en un bucle lógico antes de llegar a la rutina de copia de gráficos. Esta hipótesis se basará en la observación previa de que la VRAM está vacía y en la lógica del código de arranque de Game Boy.

Suposición: Si el sensor no se activa, entonces el problema debe ser un bucle de software en la propia ROM, posiblemente esperando un registro de hardware que no hemos inicializado correctamente o un opcode que no hemos implementado.

Próximos Pasos

[ ] Ejecutar el emulador y observar si el sensor se activa
[ ] Si el sensor NO se activa: Analizar el flujo de ejecución de la CPU durante el código de arranque para identificar el bucle de software que impide el progreso
[ ] Si el sensor SÍ se activa: Analizar el valor y dirección de la primera escritura para entender qué está haciendo la CPU
[ ] Identificar la causa raíz del problema (bucle de software, registro mal inicializado, opcode faltante, etc.)