MagenBoy

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.

Building

Install cargo-make

cargo install cargo-make

verify you have docker or podman installed

Desktop

cargo make sdl

or with more configuration options:

cargo build --release --package magenboy_sdl --features [optional_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

Key bindings:

Joypad	Keyboard
A	X
B	Z
Start	S
Select	A
Dpad Up	Up arrow
Dpad Down	Down arrow
Dpad Left	Left arrow
Dpad Right	Right arrow

(WIP) Raspberry Pi Baremetal (with ili9341 display and gpio buttons)

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

Libretro

See - LibretroDocs

Running

Desktop

magenboy [path_to_rom] [other_optional_flags]

Raspberry Pi Desktop with peripherals

See - RealMagenBoy

Optional flags

• --file-audio - Saves the audio to a file
• --full-screen - Full screen mode
• --no-vsync - Disable vsync
• --bootrom [path to bootrom file] - Specify the path for a bootrom (If not specified the emualtor will look for dmg_boot.bin at the cwd)
• --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)
• --mode [mahcine mode] - Override the auto machine detection for the game (mode can be: CGB - Gameboy color | DMG - Original Gameboy | ANY - default)
• --shutdown-rpi - Requires rpi feature, shutdown the RPi upon shutdown of the program

Raspberry Pi Baremetal

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

• Format a sd card and make a single FAT32 partition called boot
• Copy the file config.txt to the root dir of the sd card
• Copy the following files from the Raspberry Pi firmware repo onto the SD card:
  • fixup4.dat
  • start4.elf
  • bcm2711-rpi-4-b.dtb
• Copy kernel7.img onto 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.

QEMU

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

Development Status

Implemented Cartridges Types

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

Testing

• 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

Resources

Gameboy

• 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

RaspberryPi

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

BareMetal RaspberryPi

• 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