gbrom-tutorial: recovering a Game Boy ROM from a photograph of the die

Why the Via encoding makes the surface readable

The tutorial's opening explains the choice of target, and it is the most transferable idea in the repository.

The GameBoy is a good target for this because it uses what's called a Via ROM, meaning that metal Vias between layers encode the individual bits and those bits can be read from the surface of the chip. The ROM is also small enough that the author can include it in a Github repository, and the reader will not spend weeks working out minor bit errors.

That second point is a practical constraint with a practical consequence, and it is worth naming clearly. A via ROM stores each bit as the presence or absence of a metal connection through the die, and the connection is visible from the top surface. So the recovery task is not a die analysis, not a layer by layer imaging, and not a voltage probing exercise. It is an image processing problem with a known physical encoding, which is why a single photograph and a desktop program are enough.

The stated goal is to begin with photographs of the mask ROM from Nintendo's GameBoy and end up with a ROM file that can be disassembled or emulated. That framing also sets the boundary of what the tutorial delivers. It gets you to a usable ROM, not to a deeper understanding of the silicon, and the tooling is chosen to be fast rather than exhaustive, which the author is explicit about when he describes MaskRomTool as a CAD program of his for rapid bit extraction.

The other reason the target is friendly is stated plainly. This chip does not require delayering with hydrofluoric acid or bit staining with a Dash Etch solution of HNO3, HF, and acetic acid. Those are the steps that make most die analysis hard and hazardous, and skipping them is what turns a three month project into an afternoon.

The photograph, and why the microscope has to reflect

The photography section is where the practical difficulty of the whole project shows up, and it has two parts, the decapsulation and the imaging.

The source image is dmg01cpurom.bmp, which the author photographed in his home lab after decapsulating a chip in HNO3 and cleaning it in an ultrasonic bath of acetone. The photo was produced in his metallurgical microscope as twenty-two frames under 50x magnification, which were then stitched together in Hugin.

The microscope choice is not a preference, and the tutorial explains why. A biological microscope will not work, because the silicon substrate is opaque to visible light, whereas in a metallurgical microscope the light reflects off of the sample rather than transmitting through it. Since the bits are metal features on an opaque die, a transmitted light microscope sees nothing useful.

The stitching is also more than a convenience. Twenty-two frames at 50x are stitched into one panorama, and the stitching has to work well enough that the software can later find straight lines of bits across the seam. The author notes that if straight lines cannot cross the entire image, you should mark shorter lengths or improve the alignment of the panorama.

There is one more decision that affects the data, and it is about file format rather than optics. The original photo was too large for Github, so the version included is reduced in resolution, and lossy compression is avoided because it can confuse the image recognition. That is a warning worth heeding if you take your own photograph, since the threshold step in MaskRomTool works on pixel values, and a JPEG artefact is a false bit.

The tutorial closes the photography section by saying that if you produce your own photo of the DMG-01-CPU chip, the instructions here will work just as well.

MaskRomTool, and the two executables you need on PATH

The bit extraction is done with MaskRomTool, a CAD program by the same author, for rapid bit extraction. The tutorial tells you to begin by compiling it and installing it, and then to make sure two executables are reachable.

maskromtool
gatorom

If you are comfortable with the unix command-line, you will want the executables maskromtool and gatorom to be in your $PATH. If not, the same features are available from the GUI, which removes the PATH requirement entirely.

That split is a reasonable one for a tool that has to do two different jobs. The GUI is where the interactive work happens, placing rows and columns and adjusting the threshold, and the command line tools are where the deterministic part happens, the extraction of bits once the geometry is known.

The build story differs by platform too. On Windows and macOS you can avoid compiling the code by using a prebuilt release, and the documentation notes that these are compiled every few months when the code feels particularly stable. On a Unix system the expectation is that you compile it yourself, and the two names in the PATH line are the result.

Once it is running, the first action is to open dmg01cpurom.bmp. The screenshot the tutorial shows at that point is the one that explains the interaction model, because a grey crosshair follows the mouse, beginning straight but soon tilting to match the row and column lines that you place on the ROM. The reason is stated: this allows you to predict where repeated rows and columns of the same angle will fall, as most images are tilted but most bits are in perfect lines.

So the crosshair is not a decoration. It is the tool telling you, in advance, where the next bit grid is going to land, which is the entire reason placing rows is tractable by hand.

Placing rows and columns, and why the blue squares matter

The markup work is the bulk of the tutorial, and the key observation is structural. The bits in the ROM come in pairs of regular rows and groups of eight regular columns. That regularity is what makes a human able to lay out a bit grid in a reasonable time, and MaskRomTool is built around exploiting it.

Rows come first, and the advice is to begin with a few short rows and try long ones later. You click a little to the left of the leftmost bit, move your mouse to the right but do not click, and press the R key to place a row, and a thin black line appears between those two points.

The efficiency trick is the spacebar. Keeping the mouse on the right side but moving it down a little, so that the crosshair lines up with the next row, and pressing the spacebar drops another row with the same length and angle. Repeat that across many rows and you have marked them out in short order, which is what the first eight rows screenshot shows.

Once you have the hang of marking repeated rows from only their right hand side, the tutorial suggests marking them across the entire image to save time, and if straight lines cannot cross the entire image then mark shorter lengths or better align the panorama.

Mistakes are recoverable, which matters in a manual process. You drag a box with the left mouse button to select one or more lines, then drag with the right mouse button to move them, the arrow keys also move a selection, and the S key sets the position of a single line to a new end point.

Columns follow the same pattern with the C key, and the reward for doing them is immediate. As each column line is dropped across the row lines, blue squares appear over each bit, and the software now knows where the bits are. The next step is teaching it the difference between a one and a zero.

The tutorial also reminds you to double check the bit positions, and if a bit box is not directly over the bit, to select the offending row or column and drag with the right mouse button. If the angle is wrong, D erases the line so you can draw a fresh one.

Choosing a threshold from the histogram of the first 64 bits

The final documented step is recognising the bits, and it is where the image processing actually happens.

To identify bits, the software needs not just the bit positions you have provided, but also a threshold and color channel to distinguish the bits. The path is Edit and then Choose Bit Threshold, which opens a graph, and the tutorial works through the example on the first 64 bits.

The reasoning is a histogram argument. This histogram of the first 64 bits shows gaps in all three color channels, and the largest gap is in the Green channel, so the threshold is set to 172 in that channel.

That is a clean, general method, and the reason it generalises is that the die is photographed in reflected light under a microscope, so the metal features and the surrounding silicon return different amounts of light. The two populations of pixels separate into clusters, and the valley between the clusters is the threshold that classifies them. Choosing the channel with the largest gap means choosing the one where the two populations are furthest apart, which is the one that will classify most reliably across the whole image rather than only in the region you sampled.

Two things follow. The threshold is derived from the data rather than guessed, so it transfers to a different photograph of a different chip with a different exposure. And the method is auditable, because the graph shows the gap you chose and the 172 is a number you can check against it.

The tutorial stops there, and the natural next steps are the ones the tool exists to make possible: the extracted bits become a ROM file, and a ROM file can be disassembled or emulated, which is the stated end goal of the whole exercise.

What the repository is, and what it is not

It is worth being clear about the shape of this repository, because it is unusual and easy to misjudge from the outside.

The top level contains a.gitignore, the README, dmg01cpurom.bmp and a screenshots/ directory. There is no source code, no build system, no test suite and no package manifest. The primary language is recorded as unknown and no licence is recorded for the repository itself.

So it is a tutorial with its subject matter attached, not a software project. The valuable artefacts are the README, which is a careful, practical description of a procedure, and the bitmap, which is the input data that makes the procedure runnable without a microscope.

The screenshots are the third artefact and they are more than decoration. They show the first opening of the image with the crosshair, the eight short rows marked, the first bits recognised with the blue squares, and the histogram of the first 64 bits. A reader can follow along against the images and see where their own attempt diverges, which is the main practical difficulty in a manual process like this.

The dependency, MaskRomTool, lives in a separate repository, and the tutorial links to it as a CAD program for rapid bit extraction. That split is reasonable for a tool that is independently useful, and it does mean the repository you are reading is not self contained. The tutorial is complete enough to follow on its own, and the tool is the piece you will need to obtain separately.

The other limitation is the one the tutorial itself names, which is worth repeating because it is a safety matter as much as a practical one. Decapsulation means working with concentrated nitric acid and an ultrasonic bath of acetone, and doing it in a home lab is what the author did, with a chemical safety practice that is not discussed in the repository. Anyone following this should read up on handling those substances independently of this write up.

Editorial conclusion

gbrom-tutorial fits a hardware reverse engineer or a self taught tinkerer who wants to recover a ROM from a die they have already decapsulated, and it fits anyone who wants to understand the Via encoding as a physical artefact rather than a schematic. It does not fit a reader who wants a runnable project, because the repository contains a tutorial, a bitmap and screenshots, and the tool it depends on lives in a separate repository. Check three things before you start. Check that you have the hardware, because the tutorial begins after the chip has already been decapsulated in hydrofluoric-free nitric acid and cleaned ultrasonically, and nothing in the repository helps you do that step. Check the microscopy requirement, because a biological microscope will not work since the silicon substrate is opaque to visible light, and you need reflected light rather than transmitted light. And check the tool, because the extraction software is MaskRomTool from another repository, and on Windows and macOS you can avoid compiling by using a prebuilt release, while on a Unix command line you want maskromtool and gatorom on your PATH. The last push was on 2026-08-17, the repository has no GitHub releases, and no licence is recorded for it.

Frequently asked questions

Official sources

1. Issues
2. README
3. travisgoodspeed/gbrom-tutorial on GitHub