Overview

This app has three distinct functions:

• Address line scan - Use with a ROM dump file to search for stuck address bits or memory mirroring. This section is not Game Boy specific, but can be used with any kind of ROM dump. I originally came up with the idea when troubleshooting a BIOS file dumped from a laptop.
• Game Boy boot logo glitcher - Force address and data bits low or high to see what the resulting glitched logo would look like. Most useful for cases where parts of the Nintendo logo are repeated.
• Game Boy boot logo search - Provide a clean ROM dump and recreate the glitched logo by drawing it. The app searches the provided ROM for bit patterns matching the pixels you've drawn.

The goal in all cases is to aid in hardware troubleshooting by pointing to one or more address or data lines to check for loose connections or other faults.

Made by nitro2k01/GameboyGenius with the help of Claude AI. (The documentation in the how-to sections is 100% human written.)

Address line scan

Principle of operation

When a device with a parallel address/data bus wants to read from memory, it first presents the address it wants to read from, then sends a read signal. The memory chip detects the read signal, reads the address and finally outputs the data from the requested read address. Let's look at an example read sequence from address 0-7 with the binary equivalent and finally what the memory chip sees.

Now what happens if one of the data lines is faulty, for example disconnected or grounded, and always reads 0? Let's try this with address bit 0, the lowest address bit.

The pattern is that every odd address would incorrectly read the value of its corresponding even address. We can check for this going through the file and comparing every odd and even pair. If all of them match, it's likely address bit 0 is stuck. Let's now try the same thing with bit 1.

The pattern this time is more complex: 2 became 0 and 3 became 1. We now expect addresses that are two steps apart to be identical if this fault exists. So we can scan through the file and check if addresses that are 1 apart, 2 apart, 4 apart, 8 apart etc, are identical to detect a fault in a certain address bit. For every address bit, we check whether addresses that are 2ⁿ bytes apart are identical. If 100% of addresses are mirrored, we likely have a fault. If close to 100% of addresses are mirrored, we may have a fault, but this is not a given as we'll see in the following examples.

How to analyze the data, and examples of real life data

Here's an example of a real-life file, a ROM dump of the BIOS chip, which inspired this project.

Looking first at the clean dump. Something you can note is that the graph goes up and down. What are the red areas in the graph? Those area areas where the ROM is empty, which is to say filled with just the same value. We're looking for error by checking if pairs of data are equal. But if all bytes in a memory area equal anyway, they match this test. In essence, the areas where the graph is high are low entropy areas, where the data is very similar. Areas where the graph is low are high entropy areas where the data is more random. However, the telltale sign that this is likely a clean dump, is that the graphs for all of the tested bits are more or less identical. Every graph shows kind of the same thing and none of them diverge.

The A14 stuck example shows what to look for: when one of the data lines shows something different. Every tested pair off addresses where A14 is forced low and forced high, is identical. This is because A14 had a bad connection so every read from two addresses that differ only in the value of A14 ended up reading the same address in ROM.

The A7/A14 soft failure example shows something more subtle. A7 and A14 are stuck either low or high, but intermittently. Still, this is highly indicative of an issue with those address lines.

A couple more examples:

The mirrored example shows a request to read 32 kiB from an 8 kiB chip. This means that the contents of the 8 kiB chip is mirrored (repeated) 4 times. This shows up as A13 and A14 being "stuck", which in a sense they are: A13 and A14 don't influence the data being read. If looking blindly at a dump where one or more of the highest address bits show as stuck, it's theoretically possible that those address lines are indeed actually stuck, but your first instinct might be that you the read size is mismatched with the memory chip's size so you're getting an overdump.

In particular, the mirrored example is a dump of a Game Boy cartridge's save RAM after the battery has run out, which means that it contains "random" data. One somewhat interesting observation is that A3 and A8 are showing a flatline 0%, unlike the other lines which hover somewhere in the middle. Let's look at some of the data:

The file consists of repeated runs of 8 bytes with mostly all bits set, and then 8 bytes with mostly all bytes cleared. This gives a very low chance that two bytes that are 8 bytes apart match (addresses that only differ in bit 3) are ever equal. This happens due to physical construction of the SRAM chip. The bit cells for the first 8 bytes may for example be closer to the chip's internal V_CC rail so they're pulled toward a logic 1. Whereas the next 8 bytes are closer to the chip's ground rail, and are biased toward a logic 0. This is a quirk of the chip that's visible in the statistics gathered by this test.

The mostly empty example shows a ROM dump which is mostly empty apart (fileld with the same value) from the bottom 512 bytes or so bytes. This file would be reported as suspect on all data lines by the tool because over 90% of the byte pair are identical. However, this is a false positive that comes from the overwhelming majority of repeated bytes in the file. However, as explained before, an error would show up as one (or more) address lines looking different than the others.

Boot logo glitcher

Principle of operation

When a Game Boy is booting, it reads and displays the Nintendo logo from the cartridge's ROM header. If the cartridge (or Game Boy) has a fault in one of the address lines, the Game Boy will display data from an incorrect memory location, which will show up as a glitched Nintendo logo. The idea of the boot logo glitcher is that it allows you, by trial and error, to try to reproduce the pattern you see on the screen. If you successfully reproduce something that looks like the glitched logo, you will know which address lines to check for damage or corrosion.

Likewise, if a data line is faulty, every byte read from the cartridge will miss that bit of information. Because of so-called pullup resistors in the CPU chip, missing data bits will typically always read as a logic 1, which shows up as a dark pixel on the screen. This is why this type of fault will always show up as a repeating pattern of dark pixels, but never as a pattern of light pixels. This is also why the app only has the option to set data lines to 1, not 0

Once you know which address or data lines are faulty, you can use a tool like remysharp's PCB tracer and a board file for your cartridge to find where the trace goes on the cartridge.

Data line corruption

When you see a pattern of dots in the logo, it means a data line has a fault. Experiment with the setting one or more data lines high until you have a matching image.

Repeating corruption (Address line A0-A5)

When you see parts of the Nintendo logo repeated, it means a fault with one of the lower address lines, A0-A5. The tighter the repetition is, the lower the address line number. The more spread out the repetition is, the higher the address line number is. These tests assume one or more address lines are permanently high or low, but sometimes a fault can make an address line jump between 0 and 1 during the drawing of the logo. This tool can't reproduce such an error exactly, but it can still be useful in finding a glitched logo that has similarities, which can help in identifying the faulty address lines.

Glitch pattern corruption (Address line A6-A14)

When you see a seemingly random glitchy pattern, it means the cartridge returned code/data from the game itself instead of the logo. This indicates a fault with one or more of the upper address lines (A6-A14). This data depends on the game. Unlike the Nintendo logo which is identical in all games, this type of pattern will look different for each game because the ROM contents are different. You need to provide a clean ROM dump for the specific game. To troubleshoot this type of pattern, it's recommended to use the boot logo search function instead.

If you're able to make a dump using a flasher, and the dump has the issue, you can instead use the address line scan function to look for stuck address bits.

Boot logo search

Principle of operation

When a Game Boy is booting, it reads and displays the Nintendo logo from the cartridge's ROM header. If the cartridge (or Game Boy) has a fault in one of the address lines, the Game Boy will display data from an incorrect memory location, which will show up as a glitched Nintendo logo. The idea of the boot logo search is that it allows you to draw (part of) the logo you see, and the tool will search for this pattern in a clean dump of the game, which you have to provide. The boot logo search function is intended to be used if you see a logo that is completely garbled. (If you have a cartridge dumper, you may also want to try analyzing the ROM with the address line scan function.)

Once you know which address lines are faulty, you can use a tool like remysharp's PCB tracer and a board file for your cartridge to find where the trace goes on the cartridge.

How to use

Load a clean dump of the game you got the incorrect logo from. It wouldn't be a bad idea to take a sharp picture of the screen so you can zoom in and see the individual pixels easier if you need to. Set the display style to match the console. The point of this is that the ® mark serves as visual guide, so you don't accidentally draw pixels from the ® mark into the logo, which would search for an incorrect pattern.

The tool will search through the ROM file to find the pattern you have drawn and show candidates below the canvas. The search function will prioritze matches that only differ by 1-2 address bits, but will also do an exhaustive search through the ROM. Usually you don't have to draw many pixels before the one you're looking for is visible in the search result. The search result card will report the address in GB address space and ROM file offset, as well which address bits are implicated.

Instead of showing the address bits, the result card may see "full sweep" which means that this result was found during the exhaustive search. This means many address lines are different from the CPU's read address, which makes the result unlikely to be correct, but it's still included for completeness.