A GameBoy emulator developed by me.

The main goal of this project is to be able to play Pokemon on my own emulator on various platforms.

Install cargo-make

cargo install cargo-make

Verify you have cmake and docker or podman installed

cargo make sdl

or with more configuration options:

cargo build --release --package magenboy_sdl --features [optional_features]

• dbg - Enable debugger
• static-sdl - will link statically to sdl2, On by default

Note to turn off on by default features pass --no-default-features when building

Edit the relevant settings in configuration.rs install arm-none-eabi-gcc and then run:

cargo make -e [rpi_revision] rpibm 

This command will do the folowing:

1. Install the rust source to compile for toolchain armv7a-none-eabihf:

rustup +nightly component add rust-src

Unfurtuantly armv7a-none-eabihf is a tier3 target for the Rust compiler so building for it requires the nightly toolchain - source

Notice We install the armv7a-none-eabihf target and not the armv7a-none-eabi target, as the later doesn't have support for hardware floats.

2. Install Cargo Binutils:

cargo install cargo-binutils rustup component add llvm-tools-preview

3. Builds the image

See - LibretroDocs

See - NxDocs

magenboy [path_to_rom] [other_optional_flags]

See - RealMagenBoy

• --bootrom [path to bootrom file] - Specify the path for a bootrom, also used to detect the system type to emulate
• --mode [mahcine type] - Sets the machine type to emualte in case of a missing bootrom (mode can be: CGB - Gameboy color | DMG - Original Gameboy) in case both flags are missing the system to auto detect the machine type
• --file-audio - Saves the audio to a file
• --full-screen - Full screen mode
• --no-vsync - Disable vsync
• --rom-menu [path to roms folder] - Opens an interactive dialog uopn start to choose the rom from the folder Choose a game with the Joypad bindings (Dpad and A to confirm)
• --shutdown-rpi - Requires rpi feature, shutdown the RPi upon shutdown of the program

Currently only Raspberry Pi 4 is supported using the following instructions:

• Format a sd card to MBR (not GPT) and create a single FAT32 partition (On windows you can use Rufus)

• Copy the following files from the Raspberry Pi firmware repo onto the SD card:

  • fixup4.dat
  • start4.elf
  • bcm2711-rpi-4-b.dtb

  Notice: This is a specific revision, for some reason it broke on the latest version of those files

• Copy kernel7.img and config.txt to the SD card

• Connect all the peripherals (ili9341 display and gpio buttons)

• Insert the SD card to the RPI4 and boot it

Note: Should it not work on your RPi4, try renaming start4.elf to start.elf (without the 4) on the SD card.

Currently Qemu doesn't support RPI4 in 32 bit mode, so in order to test it I added support for RPI2 mapping. To change to RPI2 mode build with the rpi2 feature and not the default rpi4 feature.

running with qemu:

qemu-system-arm.exe -M raspi2b -serial null -serial mon:stdio -kernel path_to_elf

Note Qemu takes the path to the elf generated by cargo not the image generated by binutils the UART output will be written to the console.

I think that not all the peripherals I use are implemented in QEMU so I used this mainly to debug boot and CPU initialization problems

• Rom (No MBC controller)
• MBC1
• MBC3
• MBC5

• CPU - Cycle accurate CPU
• PPU - Cycle accurate fifo PPU
• Timer - Mostly accurate timer
• APU - mostly accurate APU
• Tests
  • Blargg's cpu_instrs
  • dmg-acid2
  • TurtleTests
  • CPU cycle accurate
  • mooneye-test-suite
    • acceptance/ppu/intr_2_0_timing
    • acceptance/ppu/intr_2_mode0_timing
    • acceptance/ppu/intr_2_mode3_timing
    • acceptance/ppu/intr_2_oam_ok_timing
  • APU passes some of blargs dmg_sound tests
  • Timer passes most of mooneye-test-suite
  • cgb-acid2
  • MagenTests

• The Pandocs
• gbops
• The GameBoy Programming Manual
• gbdev gameboy sound hardware
• Hactix's awsome blog post
• Nightshade's awsome blog post
• The Ultimate GameBoy Talk
• Nitty gritty Gameboy timing
• mgba gbdoc

• Raspberry Pi docs
• juj/fbcp-ili9341 as a reference
• Raspberry Pi DMA programming in C
• Ili9341 docs

• Bare-metal Boot Code for ARMv8-A
• Low performance Baremetal code Blog post
• Raspberry-Pi-Multicode examples by LdB-ECM
• RaspberryPi official Linux fork
• ARM official Docs
  • ARM Cortex-A72 manual
  • ARMv7-A Architecture Reference Manual
  • ARMv8-A Architecture Reference Manual
  • ARMv8-A Registers
  • ARMv7-A programmer Guide
• LLD BareMetal tutorial
• Circle baremetal framework as a reference
• FAT32 specs
• Baremetal SD card on the RPI4 blog post