Boot ROM Legal and Setup Guide

Summary

Complete and reproducible documentation of the use of Boot ROM in Viboy Color, maintaining strict clean-room compliance. It explains how the user can provide their own Boot ROM (legally extracted), how to validate size without exposing content, and how to configure the emulator using CLI or environment variables. Valid sizes (DMG: 256 bytes, CGB: 2304 bytes), configuration methods (flag--bootrom, variableVIBOY_BOOTROM, and stub mode--bootrom-stub), and what to look for in the logs to verify correct operation. This documentation ensures that the project maintains its educational and legal nature, without including proprietary binaries.

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

What is Boot ROM?

TheBoot ROMIt is a small program stored in the internal ROM memory of the Game Boy that is executed when the console is turned on.beforeto transfer control to the cartridge. Its main purpose is:

• Show the Nintendo logo: Characteristic animation of the logo that scrolls down.
• Validate the cartridge: Verify that the cartridge header logo matches the expected one (anti-piracy checksum).
• Initialize hardware: Set PPU, APU, and other component registers to predictable values.
• Transfer control: Jump to address0x0100of the cartridge to run the game.

Boot ROM Sizes

Register 0xFF50: Boot ROM Disable

The record0xFF50controls the visibility of the Boot ROM:

• 0xFF50 = 0x00(initial): Boot ROM is mapped and visible at the corresponding addresses.
• 0xFF50 = 0x01+: Boot ROM is permanently unmapped (not reversible), and the cartridge becomes visible on0x0000-0x00FF.

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

Why some games depend on Boot ROM

The games assume that the Boot ROM configured the hardware correctly. Without it, critical registers may have incorrect values:

• BGP (0xFF47): Background palette. Boot ROM sets it to0xFCeither0xE4. Without Boot ROM, it remains0x00(all white colors, invisible screen).
• LCDC (0xFF40): LCD control. Boot ROM sets it to0x91(LCD ON, BG ON).
• CGB records: CGB Boot ROM configures Color specific registers (VBK, BCPS, BCPD, KEY1, SVBK, etc.).

Legality and Clean Room

⚠️ IMPORTANT: The Boot ROM is the property of Nintendo and is protected by copyright.NOT included in this project. The user must:

• Extract the Boot ROM from your own physical Game Boy (legal for personal use).
• Or use the emulator in modeskip-boot(without Boot ROM, with predefined post-boot values).
• Or use the modestub(minimal simulation of post-boot state without proprietary binary).

Setup: How to Use Boot ROM on Viboy

Method 1: Command Line Flag (--bootrom)

Pass the path to the Boot ROM as an argument:

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

Method 2: Environment variable (VIBOY_BOOTROM)

Set the environment variable once and use it for all executions:

# 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

Method 3: Stub Mode (--bootrom-stub)

If you do not have real Boot ROM, use stub mode (no proprietary binary, just configure minimal post-boot state):

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

Note: Stub mode does NOT execute the complete Boot ROM sequence (does not show logo, does not validate cartridge). Only set I/O registers to basic post-boot values. Some games (especially CGB) may require actual Boot ROM to function properly.

Configuration Priority

If multiple methods are specified, the priority order is:

1. --bootrom PATH(explicit flag)
2. --bootrom-stub(if there is no flag--bootrom)
3. VIBOY_BOOTROM(environment variable, if there are no flags)
4. Skip-boot mode (if none of the above is configured)

Validation: How to Verify the Boot ROM

Check Size Without Exposing Content

To confirm that the file is the correct size without displaying its contents:

#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

Expected sizes:

• DMG: exactly256 bytes
• CGB: exactly2304 bytes(2048 + 256)

What to Look for in the Logs

When running with Boot ROM, look for these lines in the output (limited examples, without cluttering context):

# Safe search (limited to first 50 lines)
grep -E '\[BOOTROM\]|FF50' log.txt | head -n 50

Indicators of success:

• [BOOTROM] Loaded ... bytes: Boot ROM loaded correctly.
• [BOOTROM] Enabled, PC=0x0000: Execution starts from Boot ROM.
• WRITE 0xFF50 = 0x01: Game disabled Boot ROM (completed sequence).
• [BOOTROM] Disabled by FF50: Boot ROM was successfully unmapped.

Verify That It Was NOT Included in the Repository

Confirm that.gitignoreexcludes proprietary binaries:

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

It should contain lines like:

*.bin
boot_rom*
bootrom*

Affected Files

• docs/bitacora/entries/2026-01-01__0403__guia-bootrom-legal-y-configuracion.html- Documentation created (this page).
• docs/bitacora/index.html- Index updated with new entry.
• docs/report_phase_2/index.md- Updated report index.
• docs/report_phase_2/part_00_steps_0370_0402.md- Updated report with entry from Step 0403.

Complete Usage Examples

Example 1: Tetris (DMG) With Boot ROM

#Step 1: Check size
python3 -c 'import os; print(os.path.getsize("boot_dmg.bin"))' # Must be 256

#Step 2: Run
python3 main.py --bootrom boot_dmg.bin roms/Tetris.gb

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

Example 2: Pokémon Gold (CGB) With Environment Variable

#Step 1: Set environment variable
export VIBOY_BOOTROM=/home/user/boot_cgb.bin

#Step 2: Check size
python3 -c 'import os; print(os.path.getsize("/home/user/boot_cgb.bin"))' # Must be 2304

#Step 3: Run
python3 main.py roms/PokemonOro.gbc

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

Example 3: Zelda DX (CGB) With Stub Mode

# Step 1: Run with stub (without real Boot ROM)
python3 main.py --bootrom-stub roms/ZeldaDX.gbc

# Step 2: Verify post-boot configuration
grep -E 'LCDC|BGP|FF50' logs/zeldadx.log | head -n 20

Sources consulted

• Bread Docs: Power Up Sequence- Post-boot registry values.
• Bread Docs: Boot ROM- Boot ROM mapping and sizes.
• Bread Docs: 0xFF50 Register- Boot ROM disable control.
• GBEDG: Boot ROM Behavior- Behavior of the Boot ROM in DMG and CGB.

Educational Integrity

Next Steps

• [x]Step 0403: Boot ROM usage documentation (this document).
• [ ] Step 0404: Implement clear post-boot DMG/CGB separation, diagnostic instrumentation, and CGB rendering adjustments.
• [ ] Empirical testing: Compare behavior with real Boot ROM vs stub vs skip-boot in various ROMs.
• [ ] Document findings from Step 0404 (what records/conditions block Zelda DX/Pokémon).