Crate gba

source ·
Expand description

A crate for GBA development.

§How To Make Your Own GBA Project Using This Crate

This will require the use of Nightly Rust. Any recent-ish version of Nightly should be fine.

  • Get The ARM Binutils: You’ll need the ARM version of the GNU binutils in your path, specifically the linker (arm-none-eabi-ld). Linux folks can use the package manager. Mac and Windows folks can use the ARM Website.
  • Run rustup component add rust-src: This makes rustup keep the standard library source code on hand, which is necessary for build-std to work.
  • Create A .cargo/config.toml: You’ll want to set up a file to provide all the right default settings so that a basic cargo build and cargo run will “just work”. Something like the following is what you probably want.
target = "thumbv4t-none-eabi"

build-std = ["core"]

runner = "mgba-qt"
rustflags = ["-Clink-arg=-Tlinker_scripts/mono_boot.ld"]
  • Make Your Executables: At this point you can make a bin or an example file. Every executable will need to be #![no_std] and #![no_main]. They will also need a #[panic_handler] defined, as well as a #[no_mangle] extern "C" fn main() -> ! {} function, which is what the assembly runtime will call to start your Rust program after it fully initializes the system. The C ABI must be used because Rust’s own ABI is not stable.

fn panic_handler(_: &core::panic::PanicInfo) -> ! {
  loop {}

extern "C" fn main() -> ! {
  loop {}
  • Optional: Use objcopy and gbafix: The cargo build will produce ELF files, which mGBA can run directly. If you want to run your program on real hardware you’ll need to first objcopy the raw binary out of the ELF into its own file, then Use gbafix to give an appropriate header to the file. objcopy is part of the ARM binutils you already installed, it should be named arm-none-eabi-objcopy. You can get gbafix through cargo: cargo install gbafix.

This crate provides an API to interact with the GBA that is safe, but with minimal restrictions on what components can be changed when. If you’d like an API where the borrow checker provides stronger control over component access then the agb crate might be what you want.


All safety considerations for the crate assume that you’re building for the thumbv4t-none-eabi or armv4t-none-eabi targets, using the provided linker script, and then running the code on a GBA. While it’s possible to break any of these assumptions, if you do that some or all of the code provided by this crate may become unsound.


  • This module holds the assembly runtime that supports your Rust program.
  • The GBA’s BIOS provides limited built-in utility functions.
  • This module provides some basic art assets.
  • Module for interfacing with the GBA’s Direct Memory Access units.
  • A GBA-specific “cell” type that allows safe global mutable data.
  • Module for interfacing with the device’s button inputs.
  • Module for direct memory operations.
  • Lets you interact with the mGBA debug output buffer.
  • Contains all the MMIO address definitions for the GBA’s components.
  • A module that just re-exports all the other modules of the crate.
  • Module to interface with the GBA’s four timer units.
  • Module to control the GBA’s screen.



  • Wraps a value to be aligned to a minimum of 4.