https://github.com/alpyen/zynq-gbcartreader
Embedded Software Development project to read & write GameBoy cartridges.
https://github.com/alpyen/zynq-gbcartreader
cpp embedded fpga gameboy gameboy-color vhdl vitis vivado
Last synced: 4 months ago
JSON representation
Embedded Software Development project to read & write GameBoy cartridges.
- Host: GitHub
- URL: https://github.com/alpyen/zynq-gbcartreader
- Owner: alpyen
- Created: 2025-07-22T23:35:07.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2025-12-07T14:23:16.000Z (6 months ago)
- Last Synced: 2025-12-09T11:14:13.315Z (6 months ago)
- Topics: cpp, embedded, fpga, gameboy, gameboy-color, vhdl, vitis, vivado
- Language: C++
- Homepage:
- Size: 1.67 MB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
### Note: This project is a work in progress and is being actively developed. See the Todo-List at the bottom.
___
# ZYNQ GBCartReader - Read & Write GameBoy cartridges
This project is aimed to dive into FPGA SoCs and embedded software development
by designing a system that's able to read and write to gameboy cartridges with
a custom designed PCB which interfaces between the FPGA and the game cartridge.
Starting from a very basic bitbanging implementation solely running on the ARM core,
the following design iterations will make use of a more sophisticated architecture
by offloading the board communication to an IP core and moving commands and responses
around with AXI interfaces.
A (badly) handsoldered demonstration of this project with a Pokémon Red cartridge.
Left is Top, Right is Bottom.
## Supported Cartridge Types
There are a couple of different cartridge types that mostly distinguish between the type of
mapper chip and additional periphery such as RAM, Real-Time-Clock, Battery and more. Here's
a list of the ones that are available.
| Type | Status | Verified On |
| :----: | :-----: | :------------------------------------------------------------------------------------------- |
| No MBC | ✅ | Motocross Maniacs (DMG-MX-NOE)
Othello (DMG-OT-NOE) |
| MBC1 | ✅* | Super Mario Land (DMG-ML-NOE) |
| MBC2 | ✅ | F-1 RACE (DMG-F1-NOE) |
| MBC3 | WIP ✅* | Pokémon Crystal (CGB-BYTD-NOE)
Pokémon Silver (DMG-AAXD-NOE) |
| MBC5 | ✅ | Pokémon Red (DMG-APAD-NOE)
Pokémon Blue (DMG-APED-NOE)
Pokémon Yellow (DMG-APSD-NOE) |
- ✅ compatible and verified
- ✅* compatible but only partially verified
- 🚫 not implemented yet
Some exotic cartridges exist which are not supported. For an exhaustive list check the Pan Docs
and GameBoy hardware database. Most games simply use No MBC, MBC1, 3 or 5.
If I own any of the uncommon ones I'll implement them, otherwise I'll skip them as I cannot verify them.
## Quick Start
This project was developed with Vivado/Vitis 2025.1 and uses scripts for these versions.
It should be possible to recreate the projects with minimal hassle on older versions.
### Vivado
You can regenerate the project by starting Vivado and opening the tcl console.
Navigate with `cd` into the vivado subfolder and run: `source regenerate.tcl`
Vivado will rebuild the project from the source files. Once that's done you can
generate the wrappers for the different block design implementations, synthesize
and export the XSA files for use in Vitis.
> Note: The automatic wrapper generation is not implemented for now.
### Vitis
Vitis offers a python interface to dispatch commands from scripts to the application.
In order to use this, you need to source the settings64.sh from the Vitis installation.
If you've installed the Xilinx tools in the default location then open up a new terminal
and load the settings by running these commands based on your operating system:
- Windows: `call C:/Xilinx/2025.1/Vitis/settings64.bat`
- Linux: `source /opt/Xilinx/2025.1/Vitis/settings64.sh`
In the same terminal navigate with `cd` into the vitis subfolder of this repository
and run: `vitis -s regenerate.py`
> Note: This script has to be run from Vitis, it will not work with your local python installation.
The script takes care of several things:
1. Performs sanity checks to see if the execution environment is correct and if the
XSA files have been exported, otherwise the platform generation will fail.
2. Delete **everything** except the regenerate.py inside the vitis subfolder to remove
a potentionally old workspace.
3. Regenerate the different platforms and applications used to run it on the board.
4. Link sources located outside the vitis workspace to into the projects.
Once the regeneration is complete you can open the Vitis GUI and set the workspace
to the vitis subfolder. Now you're ready to build the applications and deploy them.
___
### Acknowledgements
This project heavily relies on the work of others who have reverse engineered and documented
the inner workings of the Game Boy and its cartridges and/or compiled existing information:
- Pan Docs - https://github.com/gbdev/pandocs
- Game Boy: Complete Technical Reference - https://github.com/Gekkio/gb-ctr
___
### Todo-List
- Port bare-metal app to MicroBlaze on a Basys3
- Port bare-betal app to be used on Arduino