Guía de Boot ROM Legal y Configuración

Resumen

Documentación completa y reproducible del uso de Boot ROM en Viboy Color, manteniendo estricta conformidad clean-room. Se explica cómo el usuario puede proveer su propia Boot ROM (extraída legalmente), cómo validar tamaño sin exponer contenido, y cómo configurar el emulador mediante CLI o variables de entorno. Se detallan los tamaños válidos (DMG: 256 bytes, CGB: 2304 bytes), los métodos de configuración (flag --bootrom, variable VIBOY_BOOTROM, y modo stub --bootrom-stub), y qué buscar en los logs para verificar funcionamiento correcto. Esta documentación asegura que el proyecto mantiene su naturaleza educativa y legal, sin incluir binarios propietarios.

Concepto de Hardware (Pan Docs - Boot ROM, Power Up Sequence)

¿Qué es la Boot ROM?

La Boot ROM es un pequeño programa almacenado en memoria ROM interna de la Game Boy que se ejecuta al encender la consola, antes de transferir control al cartucho. Su propósito principal es:

• Mostrar el logo de Nintendo: Animación característica del logo que se desplaza hacia abajo.
• Validar el cartucho: Verificar que el logo del header del cartucho coincide con el esperado (checksum anti-piratería).
• Inicializar hardware: Configurar registros de PPU, APU, y otros componentes a valores predecibles.
• Transferir control: Saltar a la dirección 0x0100 del cartucho para ejecutar el juego.

Tamaños de Boot ROM

Registro 0xFF50: Boot ROM Disable

El registro 0xFF50 controla la visibilidad de la Boot ROM:

• 0xFF50 = 0x00 (inicial): Boot ROM está mapeada y visible en las direcciones correspondientes.
• 0xFF50 = 0x01+: Boot ROM se desmapea permanentemente (no reversible), y el cartucho pasa a ser visible en 0x0000-0x00FF.

Fuente: Pan Docs - Boot ROM, 0xFF50 Register.

Por qué algunos juegos dependen de la Boot ROM

Los juegos asumen que la Boot ROM configuró el hardware correctamente. Sin ella, registros críticos pueden tener valores incorrectos:

• BGP (0xFF47): Paleta de Background. Boot ROM lo configura a 0xFC o 0xE4. Sin Boot ROM, queda en 0x00 (todos los colores blancos, pantalla invisible).
• LCDC (0xFF40): Control de LCD. Boot ROM lo configura a 0x91 (LCD ON, BG ON).
• Registros CGB: Boot ROM de CGB configura registros específicos de Color (VBK, BCPS, BCPD, KEY1, SVBK, etc.).

Legalidad y Clean Room

⚠️ IMPORTANTE: La Boot ROM es propiedad de Nintendo y está protegida por copyright. NO se incluye en este proyecto. El usuario debe:

• Extraer la Boot ROM de su propia Game Boy física (legal para uso personal).
• O usar el emulador en modo skip-boot (sin Boot ROM, con valores post-boot predefinidos).
• O usar el modo stub (simulación mínima de estado post-boot sin binario propietario).

Configuración: Cómo Usar Boot ROM en Viboy

Método 1: Flag de línea de comandos (--bootrom)

Pasar el path a la Boot ROM como argumento:

python3 main.py --bootrom /path/to/boot_dmg.bin roms/Tetris.gb
python3 main.py --bootrom /path/to/boot_cgb.bin roms/PokemonOro.gbc

Método 2: Variable de entorno (VIBOY_BOOTROM)

Configurar la variable de entorno una vez y usarla para todas las ejecuciones:

# Bash/Linux
export VIBOY_BOOTROM=/path/to/boot_cgb.bin
python3 main.py roms/PokemonOro.gbc

# Windows PowerShell
$env:VIBOY_BOOTROM="C:\path\to\boot_cgb.bin"
python main.py roms\PokemonOro.gbc

Método 3: Modo Stub (--bootrom-stub)

Si no se tiene Boot ROM real, usar modo stub (sin binario propietario, solo configura estado post-boot mínimo):

python3 main.py --bootrom-stub roms/PokemonOro.gbc

Nota: El modo stub NO ejecuta la secuencia completa de la Boot ROM (no muestra logo, no valida cartucho). Solo configura registros I/O a valores post-boot básicos. Algunos juegos (especialmente CGB) pueden requerir Boot ROM real para funcionar correctamente.

Prioridad de Configuración

Si se especifican múltiples métodos, el orden de prioridad es:

1. --bootrom PATH (flag explícito)
2. --bootrom-stub (si no hay flag --bootrom)
3. VIBOY_BOOTROM (variable de entorno, si no hay flags)
4. Modo skip-boot (si ninguno de los anteriores está configurado)

Validación: Cómo Verificar la Boot ROM

Verificar Tamaño Sin Exponer Contenido

Para confirmar que el archivo tiene el tamaño correcto sin mostrar su contenido:

# Linux/Bash
ls -lh /path/to/boot.bin

# Python (cross-platform)
python3 -c 'import os,sys; p=sys.argv[1]; print(f"{p}: {os.path.getsize(p)} bytes")' /path/to/boot.bin

Tamaños esperados:

• DMG: exactamente 256 bytes
• CGB: exactamente 2304 bytes (2048 + 256)

Qué Buscar en los Logs

Al ejecutar con Boot ROM, buscar estas líneas en la salida (ejemplos acotados, sin saturar contexto):

# Búsqueda segura (limitada a primeras 50 líneas)
grep -E '\[BOOTROM\]|FF50' log.txt | head -n 50

Indicadores de éxito:

• [BOOTROM] Loaded ... bytes: Boot ROM cargada correctamente.
• [BOOTROM] Enabled, PC=0x0000: Ejecución comienza desde Boot ROM.
• WRITE 0xFF50 = 0x01: Juego deshabilitó Boot ROM (completó secuencia).
• [BOOTROM] Disabled by FF50: Boot ROM se desmapeó correctamente.

Verificar Que NO Se Incluyó en el Repositorio

Confirmar que .gitignore excluye binarios propietarios:

grep -E "\.bin|boot_rom" .gitignore

Debe contener líneas como:

*.bin
boot_rom*
bootrom*

Archivos Afectados

• docs/bitacora/entries/2026-01-01__0403__guia-bootrom-legal-y-configuracion.html - Documentación creada (esta página).
• docs/bitacora/index.html - Índice actualizado con nueva entrada.
• docs/informe_fase_2/index.md - Índice del informe actualizado.
• docs/informe_fase_2/parte_00_steps_0370_0402.md - Informe actualizado con entrada del Step 0403.

Ejemplos de Uso Completos

Ejemplo 1: Tetris (DMG) Con Boot ROM

# Paso 1: Verificar tamaño
python3 -c 'import os; print(os.path.getsize("boot_dmg.bin"))'  # Debe ser 256

# Paso 2: Ejecutar
python3 main.py --bootrom boot_dmg.bin roms/Tetris.gb

# Paso 3: Verificar logs
grep -E '\[BOOTROM\]|FF50' logs/tetris.log | head -n 20

Ejemplo 2: Pokémon Oro (CGB) Con Variable de Entorno

# Paso 1: Configurar variable de entorno
export VIBOY_BOOTROM=/home/user/boot_cgb.bin

# Paso 2: Verificar tamaño
python3 -c 'import os; print(os.path.getsize("/home/user/boot_cgb.bin"))'  # Debe ser 2304

# Paso 3: Ejecutar
python3 main.py roms/PokemonOro.gbc

# Paso 4: Verificar logs
grep '\[BOOTROM\]' logs/pokemonoro.log | head -n 30

Ejemplo 3: Zelda DX (CGB) Con Modo Stub

# Paso 1: Ejecutar con stub (sin Boot ROM real)
python3 main.py --bootrom-stub roms/ZeldaDX.gbc

# Paso 2: Verificar configuración post-boot
grep -E 'LCDC|BGP|FF50' logs/zeldadx.log | head -n 20

Fuentes Consultadas

• Pan Docs: Power Up Sequence - Valores de registros post-boot.
• Pan Docs: Boot ROM - Mapeo y tamaños de Boot ROM.
• Pan Docs: 0xFF50 Register - Control de deshabilitación de Boot ROM.
• GBEDG: Boot ROM Behavior - Comportamiento de la Boot ROM en DMG y CGB.

Integridad Educativa

Próximos Pasos

• [x] Step 0403: Documentación de uso de Boot ROM (este documento).
• [ ] Step 0404: Implementar separación clara DMG/CGB post-boot, instrumentación de diagnóstico, y ajustes de renderizado CGB.
• [ ] Testing empírico: Comparar comportamiento con Boot ROM real vs stub vs skip-boot en ROMs variadas.
• [ ] Documentar hallazgos de Step 0404 (qué registros/condiciones bloquean Zelda DX/Pokémon).