This repo is the home of MetroBoy, GateBoy, and LogicBoy (yes, rather too many projects for one repo but they're very tightly interconnected)

Update Dec 2021 - I've merged the "LogicBoy" branch into master. LogicBoy is a translation of GateBoy into more standard C++ idioms, while maintaining bit-identical behavior with the reference GateBoy model. It currently runs at 60+ fps instead of 6 fps in "fast" mode, with a few more optimization passes still left to go.

GateBoy

GateBoy is a gate-level simulation of the original Game Boy hardware that was reverse-engineered from die shots of the original DMG-01 chip. It includes all the standard cells on the chip but not the CPU - it's made of custom logic and is a bit too blurry for me to decipher. GateBoy's CPU is instead my current best guess at how it might be implemented given the constraints implied by the rest of the chip.

Precompiled builds with test ROMS are here - https://github.com/aappleby/MetroBoy/releases/tag/GateBoy_v0.1.1

GateBoy runs at around 6 to 8 frames per second in "fast mode" on a modern 4-ish ghz processor. That's quite horrible compared to an emulator, but pretty impressive for something that's simulating a few billion gates per second on a single core.

I owe a huge amount of thanks to Furrtek for his original die traces and schematics that served as a Rosetta Stone for getting the whole translation started. I've noted in the codebase where I found errors in the schematics - some have been reported back to Furrtek but there are still a lot of discrepancies.

Big thanks are also owed to Gekkio for his Mooneye emulator and tests that helped bootstrap Gateboy, and for the flash cart he designed that I used to build many many additional tests.

GateBoy FAQ

• How is this simulation connected to the Furrtek schematics?

  • Furrtek assigned every gate on the die and in the schematic a 4-character code like "ASUR" or "BALY". Each of those gates has a corresponding line in the GateBoy source code. Lines in the source are tagged like this - /*#p08.ASUR*/ - this means that gate ASUR (which happens to be a 2-mux) is on page 8 of the schematics, and the '#' indicates that I've manually traced the gate to verify that the schematic is correct.
  • Here's a chunk of the unmodified die shot with ASUR in the middle -
  • Here's the same chunk with Furrtek's annotations -
  • And here's a closeup showing the three inputs coming into the top "rungs" of the cell, and the output at the bottom -
  • which corresponds to this ASUR in Furrtek's schematic -
  • which in turn gets translated to this ASUR in GateBoy's code -
  • Repeat that a few thousand times, spend a year-ish debugging, and you get GateBoy. To give you a sense of scale, here's the whole die with a red dot covering ASUR - there are currently 2674 active cells in GateBoy, and another thousand-ish in the audio hardware that aren't being simulated -

• How is this simulation tested?

  • GateBoy has a fairly comprehensive test suite that runs all of the Mooneye tests, as well as a large suite of "micro-tests" that execute in a small number of cycles.
  • GateBoy can also do automated render tests (used for Mealybug's test suite), but those are currently disabled.
  • There are probably a few plain old code bugs remaining as well. Right now one of the early screens in Zelda is doing something funny with the grass tiles...

• Is GateBoy a perfect simulation of a Game Boy?

  • Actually no, for complicated reasons. The Game Boy chip has a handful of logic gates that operate independently of the master clock and whose exact behavior depends on things like gate delay, the physical distance from the gate to its inputs/outputs, the silicon process used to make them, and (in very strange circumstances) the temperature of the silicon and the voltage applied to the chip. These asynchronous gates can create glitches that do strange things which can't be predicted just by looking at a schematic of the chip.
  • For example, there's a glitch in the external address bus logic that causes internal bus addresses like to appear on the external bus even though the logic should prevent that. Due to gate delays, not all of the inputs to gate (a combined AND-OR gate on page 8 in Furrtek's schematics) arrive at the same time. The differences in arrival time cause to produce a glitch pulse that in turn causes latch to make a copy of one bit of the internal bus address. then drives that bit onto the external bus (through a few more gates) where it can be seen with an oscilloscope or logic analyzer.

How do I build and run GateBoy?

All the code is cross-platform and has been tested under Windows 10, Windows 11, Debian, Ubuntu, and WSL-G. Clone the repo and don't forget to do "git submodule init" and "git submodule update" to pull down the support libraries (SDL2, glm, imgui, and json).

• On Windows, open MetroBoy.sln in Visual Studio Community 2019 and build and run as ususal. If you get a "SDL2.dll not found" error, you can either install SDL2 globally, manually copy SDL2.dll into the same folder as the executables, or change "Working Directory" in Project Properties -> Configuration Properties -> Debugging to "$(SolutionDir)".

• On Linux, make sure you have libsdl2-dev installed and run "ninja" from the repo root. You'll get a set of "fast mode" binaries in bin/, which should be launched from the repo root as they make assumptions about directories and such.

• Test roms are symlinked to GBMicrotests.

• To run all tests roms, run bin/GateBoyTests from root. The tests should take a second or two, and there should be 20 (known) failures.

• Running other tests (mooneye, mealybug, etc) requires additional setup that I haven't automated yet. :/

What happened to MetroBoy?

MetroBoy is/was a higher level Game Boy emulator that I wrote from scratch before Furrtek released his schematics. I got it to the point where it passed virtually all the available tests, and then hacked it up in various ways to help get GateBoy working. MetroBoy is currently broken, don't use it. It will be coming back eventually.

So what comes after GateBoy?

The next step after this is LogicBoy, which will be a simulation that's equivalent at the register level to GateBoy but expresses the logic in more conventional C instead of and/or/not/etc. gates.

And after that?

MetroBoy will be rewritten so that its externally visible behavior exactly matches LogicBoy.

That's a lot of stuff. What's the overarching point of all this, anyhow?

GateBoy, LogicBoy, and MetroBoy exist to give me a starting point for working on Metron, which is my long-term project to build a set of programming tools that can bridge between the C/C++ universe used by software and the Verilog/VHDL universe used by hardware. Eventually there will be a single codebase that, using some custom tools, can be translated directly to C++ and run on a PC or that can be translated to SystemVerilog and run on a FPGA.