How to write a Game Boy emulator - Part 1: Loading the bios
Writing an emulator may sound impossible to many people, but I can assure you it’s very possible but also very fun and rewarding. The difficult part is not writing the emulator, it’s understanding how the emulated machine works. As always, code is cheap; documentation is priceless.
I could not have written my Game Boy emulator if people before me had not documented how the Game Boy works:
- http://bgb.bircd.org/pandocs.htm
- http://gbdev.gg8.se/wiki/articles/Main_Page
- http://goldencrystal.free.fr/GBZ80Opcodes.pdf
- http://imrannazar.com/GameBoy-Emulation-in-JavaScript
- http://marc.rawer.de/Gameboy/Docs/GBCPUman.pdf
- http://zilog.com/docs/z80/um0080.pdf
- http://www.codeslinger.co.uk/pages/projects/gameboy.html
- http://www.pastraiser.com/cpu/gameboy/gameboy_opcodes.html
- https://github.com/AntonioND/giibiiadvance/blob/master/docs/TCAGBD.pdf
- https://realboyemulator.wordpress.com/
- https://www.reddit.com/r/EmuDev/
I hope to return the favor by writing this blog series. My goal is to document step-by-step how to write a Game Boy emulator, and hopefully make emulator development more accessible. Each post in this blog series will describe a commit in the gammaboy repository.
Many consoles have been released in the Game Boy line throughout the years:
- Game Boy family
- Game Boy (DMG) (1989)
- Game Boy Pocket (1996)
- Game Boy Light (1998)
- Game Boy Color (1998)
- Game Boy Advance family
- Game Boy Advance (2001)
- Game Boy Advance SP (2003)
- Game Boy Micro (2005)
Our emulator will only support the original 1989 Game Boy. This model is called the Dot Matrix Game Boy or DMG. From this point on, when I say “Game Boy”, what I really mean is the DMG.
The bios, also called the bootstrap rom or boot rom, is a program stored in the Game Boy that is executed on startup before any game code.
The bios behaves differently whether you start the Game Boy with a cartridge or not. If no cartridge is inserted, it scrolls a black bar® and plays a sound:
If a cartridge is inserted, it scrolls the Nintendo logo and plays a sound:
Behind the scenes, it does various checks to determine the legitimacy of the cartridge.
The DMG bios is a 256-byte file with this SHA-256 hash:
cf053eccb4ccafff9e67339d4e78e98dce7d1ed59be819d2a1ba2232c6fce1c7
You don’t need the bios to write a Game Boy emulator. Game Boy emulators out there don’t ask you for the bios because they just skip it. For pedagogical purposes though, I think it’s best to start by emulating the bios because it’s the fastest way to get things displayed on the screen.
Once you have the bios, your emulator needs to:
- Read the bios file.
- Store it in a byte array.
- Verify its SHA-256 hash.
When I say to store the bios in an array, I mean at runtime. Whatever you do, don’t hardcode the bios in the source code of your emulator (for legal reasons).