sm83-cpu-core

Game Boy SM83 CPU core

Game Boy consoles use a custom Sharp CPU core that resembles Z80 and 8080 but is not exactly either. Some people use the name LR35902, but that is actually the name of the original Game Boy (DMG) SoC, which includes a huge amount of other things than just the CPU despite being labeled "DMG-CPU". This is why I call the chip a System-on-a-Chip (SoC), and the CPU core needs a separate name.

A couple of old Sharp databooks describe a "SM83" CPU core, which happens to have an instruction set that is a perfect match with the Game Boy CPU. This exact instruction set is unique and has not been seen in any other CPU cores, so SM83 is the most probable name based on currently available information. Personally I actually think that the CPU core might have an even older name, since some very old Sharp SM-812/SM-813/SM-814 chips seem to have an unnamed CPU core that seems at least like a relative. Since public information about these chips is scarce, SM83 is the most accurate name. You can read further information about this topic at the NESdev forums

The reverse engineering work is based on an SGB-CPU 01 chip used in the Super Game Boy. The chip is a DMG-CPU B chip with a different boot ROM, so the are no relevant differences to DMG-CPU B, and all researched information applies to the original Game Boy as well.

The HDL model passes the following tests:

• The whole Blargg's cpu_instrs test suite, except "02 - interrupts" which requires SoC peripherals and won't work with just the CPU core
• DAA test from mooneye-test-suite

What has been done

• a stitched top photo of the entire SM83 CPU core using a 40x objective
• an SVG file that contains hand-drawn traces of almost all interesting signals. Some repetitive areas and signals have not been traced because they follow a pattern that is already understood. Note: the background photo is not in the repo and needs to be downloaded separately from here
• a non-synthesizable HDL model (written in VHDL) using a "medium abstraction level". It's meant for simulation and won't work directly on an FPGA. The abstraction level focuses on logical blocks and their connections, and does not include every single transistor, or even every single signal
• real-world ROM testing by plugging the CPU core into a "mock SoC" (not included in the repo at the moment). The CPU core passes all Blargg's cpu_instrs that don't require SoC peripherals. In practice this means everything except "02 - interrupts" which only passes partially. Simulating cpu_instrs took around 3 hours 20 minutes on my Ryzen 9 5950X machine using a single core at 100% the whole time (GHDL does not support multi-core simulation)

What has not been done

• implementation of propagation delays. Estimating realistic propagation delays is complicated, especially due to dynamic logic. So far there has been no need, but this may change in the future when more testing is done and possible edge-cases are discovered
• perfect names for everything. A lot of effort has been spent on naming things, but for example the control unit signals currently have poor names

What is planned

• KiCad schematics of at least the control unit. They already exist but are not ready for release. The hand-written HDL will be replaced with HDL generated from the schematics once this is done

Repository contents

• SGB-CPU_01_sm83_core_40x.svg: Inkscape SVG with most of the CPU core traced and identified. Download the background image here separately and put it in the same folder to use it
• hdl/: a non-synthesizable HDL model of the SM83 CPU core
• io-cell/: a separate description of the "I/O cell" that connects the SoC data bus to the SM83 CPU core internal data buses

Running the HDL test suite

1. Install Poetry
2. Install GHDL
3. Run poetry install in the hdl directory
4. Run poetry run test in the hdl directory

Running a test ROM

1. Install Poetry
2. Install GHDL
3. Run poetry install in the hdl directory
4. Place a test ROM file to the hdl directory and name the file test.gb
5. Run poetry run rom in the hdl directory

The poetry run rom command runs VUnit and accepts various extra arguments, for example:

• --help: display help
• -v: enable verbose mode which displays some logging information
• -g: open simulator GUI with test / waveform

The test ROM execution is terminated when any of these conditions is true:

• 100 000 000 instructions have been executed
• 60 seconds of "emulated time" has been reached
• a self-pointing JR opcode is fetched (= infinite loop)
• a self-pointing JP opcode is fetched (= infinite loop)

Further reading

• Game Boy: Complete Technical Reference: contains a high-level description of the CPU core and its instruction set