A repository of gate-level simulators and tools for the original Game Boy.

Overview

This repo is the home of MetroBoy, GateBoy, and Plait.

GateBoy

GateBoy screenshot

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, minus the audio (too slow). It does not currently simulate the CPU at the gate level - 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 and Plait data 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 - drawing
    • Here's the same chunk with Furrtek's annotations - drawing
    • And here's a closeup showing the three inputs coming into the top "rungs" of the cell, and the output at the bottom - drawing
    • which corresponds to this ASUR in Furrtek's schematic - drawing
    • which in turn gets translated to this ASUR in GateBoy's code - drawing
    • 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 - drawing
  • 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. These gates create glitches that depend heavily on the physical placement of the gates, the silicon process used to make them, and other weird things like temperature and voltage.
    • For example, there's a glitch in the external address bus logic that causes internal bus addresses like 0xFF20 to appear on the external bus even though the logic should prevent that. Due to gate delays, not all of the inputs to gate LOXO (page 8 in Furrtek's schematics) arrive at the same time. This causes LOXO to produce a glitch pulse that in turn causes latch ALOR to make a copy of one bit of the internal bus address. ALOR then drives that bit onto the external bus (through a few more gates) where it can be seen with an oscilloscope or logic analyzer.
  • Wait, if glitches don't show up in the schematics then how did you figure that one out?

    • In this case we can deduce what's going on because we can see the side-effect of the glitch on the external bus and there's not that many possible ways that address signal could've gotten there.
    • Other internal glitches are harder to figure out because they don't affect external circuits - they just show up as "something does not match the simulation". There are probably 4-5 glitches that need to be tracked down somehow before the simulation is "perfect", but I'm not going to block the release of GateBoy until I find them.
  • Why is GateBoy so slow?

    • GateBoy simulates every logic gate on the DMG chip, one gate at a time. Adding two 8-bit values isn't simulated as "a = b + c;", it's simulated as eight 1-bit adders and eight 1-bit registers and all the control logic that goes along with it.
    • In debug builds, all gates also includes a bunch of error checking to verify that gates aren't read before they're updated, that buses aren't floating, that the simulation always stabilizes, and other things like that.
    • GateBoy also simulates every clock phase, not just individual clock cycles. While you may have read that the Game Boy runs at 1 megahertz, this is not quite correct. The 4.19 megahertz clock crystal feeds a set of gates AFUR+ALEF+APUK+ADYK that produce four 1 mhz clocks that are out of phase with each other. Those clocks are then combined by additional logic to create sub-clocks of various patterns and frequencies whose edges can lie on either the positive or negative edges of the 4.19 mhz master clock. So, it's more accurate to say that the Game Boy has a 1-megahertz, 8-phase clock. In GateBoy we give each phase a letter (A through H) and all sub-clocks have a suffix like this - BALY_xBCDEFGH - which indicates that the clock generated by gate BALY is high on phases B through H.
    • Even with heroic optimization and all the error checking turned off in "fast mode", we still only hit 6-8 fps on a modern CPU.
  • Why is GateBoy so fast?

    • Aha, now we're asking interesting questions. Simulating hardware in software is usually 1000's of times slower than realtime - GateBoy is "only" 8x slower than realtime. How does it do that?
    • GateBoy is designed so that most of the simulated gates optimize down to a single instruction or less after the compiler's optimization pass - one "and" gate turns into one "and" instruction, chains of "not" gates get optimized out, etcetera.
    • Normally this would require a huge amount of simulation infrastructure to ensure that the simulation doesn't diverge from the "real world" circuit. GateBoy doesn't do this. Instead, GateBoy does all its error checking by adding additional flags to each wire and register and verifying (in debug builds) that every gate is evaluated in the correct order so that the result is the same as if every gate was evaluated in parallel. There are a few workarounds to deal with asynchronous logic, but they are minor.
    • The flags are positioned so that they don't interfere with the usual one-instruction-per-gate operations, and in "fast mode" builds the flags are disabled and everything optimizes down quite tightly.
  • Wouldn't it be even faster to write this in Verilog and then simulate it in Verilator or something?

    • You would think so, and I have translated small portions of GateBoy into Verilog and simulated them in Verilator just to prove that GateBoy's simulation strategy does produce correct results. However, the Verilated code is still around 5-10x slower than GateBoy compiled in "fast mode".

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 in tests/microtests/DMG. If you're using some Linux flavor, you can rebuild them from source by installing wla-dx and then running "ninja" in tests/microtests.

  • Once the test roms are built, 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.

What's Plait?

Plait screenshot

Plait is a tool for visualizing and untangling the mess of gates that makes up GateBoy. It's not at all finished yet, but there's enough functionality to be useful. It's also quite fun to poke around in the graph and see how things like the pixel pipe are actually implemented, gate-wise. The pic above is the "pixel output" circuit that merges the background tile pixels with the sprite pixels, applies the color palettes, and sends the pixels to the LCD.

Plait parses the GateBoy source code, extracts all tagged (/*#p08.ASUR*/) lines, and converts the result to an editable graph. To make the level of complexity more manageable, Plait includes multiple editing features to help modularize and untangle the graph.

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.

Issues
  • Multi core? (theoretical/improvement)

    Multi core? (theoretical/improvement)

    If I understand correctly it is currently running on a single core/thread

    Idk the intricacies of it, but as there are 8 phases they could be paired up to run on 4 threads and maybe an extra 2 for checking that they stay aligned or for how the misaligned phases interact with each other

    Hypothetically of you were able to do this, it would be one heck of a feat as I imagine keeping it aligned on one that it's already difficult enough. But I think it could reap greater performance (not 4x but possibly 2x the speed as there isn't a direct correlation)

    I'm excited to see how far this ultimately goes and how well it'll be able to run in the form of logicboy

    opened by DanHolli123 2
  • dump_slice2n limited to 8 bits

    dump_slice2n limited to 8 bits

    Some addresses in Gateboy like BUS_VRAM_An always show the high byte as 00.

    uint8_t instead of uint16_t: https://github.com/aappleby/MetroBoy/blob/9f55e6683ffbaf638a77d6a7d9f21b25eb0e4a7a/src/CoreLib/Types.h#L236

    opened by paulb-nl 0
  • Goals with the project, testing etc.

    Goals with the project, testing etc.

    Hi @aappleby

    First off, I have been following this project for the last 1 1/2 month now and I must say that I'm really impressed with your progress so far, from a couple of commits up to over 300+ Really nice work!

    This isn't a issue per se but more of a thought.

    What are your main goals with the project? Being a circuit-level Game Boy emulator and all I was wondering if you have future plans to make it like a normal emulator with GUI options and such, like bgb for example?

    We are probably talking about far into the future here but would additional stuff like usage of the Game Boy BIOS, different palettes and such be possible?

    Also regarding testing, I own a dozens of Game Boy games, mostly Japanese versions of the more popular games so if there is something you want me to test I could probably find some time once in a while to test things. I got a fairly strong computer (i7 8700K, NVIDIA GTX 1070, 16GB RAM) so hopefully it's not that bad.

    I'm all in for accuracy so I'm keeping a close watch on this project!

    opened by ghost 0
  • Lags hard if not minimised

    Lags hard if not minimised

    The emulator lags REALLY hard on my machine, but only when it's not minimised. If it's minimised, it runs at full speed, which leads me to believe that a major cause of the slowness is not the simulation itself but the method used to draw the UI. perhaps provide an option to use GPU drawing for the UI? idk

    opened by TorutheRedFox 2
Releases(GateBoy_v0.1.1)
A cycle-accurate Game Boy and Game Boy Color Emulator, with rewind feature.

Azayaka is a free and open-source Game Boy and Game Boy Color emulator written in C++. Features Cycle-Accurate emulation. Console based Debugg

Zach Collins 14 Dec 16, 2021
SameBoy DX is a Qt-based interface of SameBoy, a free, highly accurate Game Boy and Game Boy Color emulator.

SameBoy DX SameBoy DX is a Qt-based interface of SameBoy, a free, highly accurate Game Boy and Game Boy Color emulator. Build requirements: CMake Pyth

Snowy 8 Jul 26, 2022
The Game Boy ROM of the Game Boy bitcoin miner!

game-boy-bitcoin-miner The Game Boy ROM of the Game Boy bitcoin miner! To build this, currently this patch needs to be applied to GBDK: https://gist.g

Ghidra Ninja 79 Jul 17, 2022
A WiFi cartridge for the original Game Boy.

wifi-game-boy-cartridge A WiFi cartridge for the original Game Boy. This open source and open hardware Game Boy cartridge uses an ESP8266 to allow WiF

Sebastian Staacks 116 Jul 25, 2022
GB Studio is a quick and easy to use retro adventure game creator for Game Boy available for Mac, Linux and Windows

GB Studio is a quick and easy to use retro adventure game creator for Game Boy available for Mac, Linux and Windows

Chris Maltby 6.3k Aug 6, 2022
A Game Boy game that rewards you for playing it on several console models!

GB Corp. A Game Boy game for the Game Boy Competition 2021 by Dr. Ludos (2021) This is the source code, you can get a precompiled rom from here: https

Dr. Ludos 9 Oct 21, 2021
civilized Game Boy Advance development from the comfort of your own editor

Rath - civilized Game Boy Advance development from the comfort of your own editor what is it Rath is an interactive development environment for the Ga

Ties Stuij 21 May 23, 2022
Custom Deflemask .vgm based playback engine for the Nintendo Game Boy

-DeflemaskGBVGM- Custom Deflemask .vgm based playback engine for the Nintendo Game Boy. Now the official Deflemask ROM exporter as of v1.0.3. this eng

Daniel Chu 10 Feb 20, 2022
A Game Boy emulator with serial data transfer (link cable) support over tcp.

gbmulator A Game Boy emulator with serial data transfer (link cable) support over tcp. Key bindings Key bindings are not configurable yet. Key Action

null 3 Jul 17, 2022
NeoGB Printer an SD card-based standalone Game Boy Printer emulator.

An open-source and standalone Gameboy Printer emulator 100% compatible with all officially released games (110 in total) that support the accessory. Just print and save the images as BMP

Rafael Zenaro 65 Jul 27, 2022
A Game Boy Printer emulator that supports the Phomemo T02 printer

ESP32 + Phomemo T02 Game Boy Printer This project lets you print Game Boy Printer images via Bluetooth using a Phomemo T02 thermal printer and an ESP3

Jack Gaino 10 May 21, 2022
Slender Man Returns is a game inspired by the original indie game Slender

Slender Man Returns is a game inspired by the original indie game Slender: The Eight Pages, but redesigned to run on the popular Unity game engine. Ported to PSVita. Original project by Rosario Terranova.

null 8 Jul 5, 2022
Remake of the original Space Invaders game.

Space-invaders Remake of the original Space Invaders game.

Kofybrek 20 May 13, 2022
A Tiny 2D OpenGL based C++ Game Engine that is fast, lightweight and comes with a level editor.

A Tiny 2D OpenGL based C++ Game Engine that is fast, lightweight and comes with a level editor.

Samuel Rasquinha 48 Jul 13, 2022
Simple, fast, easy to get started mid-level game engine written in Zig

Alka Game engine written in zig, compatible with master branch. This engine does provide a toolset for you but generally you have to implement how the

Kiakra 21 Jul 27, 2022
Our game generates a random maze every time when the user chooses the difficulty level

Maze Game Random maze generator Hello, We are The Runners ✨ Our game generates a random maze every time when the user chooses the difficulty level. Yo

Kostadin Taligadzhiev 3 Jan 18, 2022
Stealthy way to hijack the existing game process handle within the game launcher (currently supports Steam and Battle.net). Achieve external game process read/write with minimum footprint.

Launcher Abuser Stealthy way to hijack the existing game process handle within the game launcher (currently supports Steam and Battle.net). Achieve ex

Ricardo Nacif 76 Jul 28, 2022
Improved version of the X-Ray Engine, the game engine used in the world-famous S.T.A.L.K.E.R. game series by GSC Game World.

OpenXRay OpenXRay is an improved version of the X-Ray Engine, the game engine used in the world-famous S.T.A.L.K.E.R. game series by GSC Game World. S

null 2k Jul 30, 2022