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.
[build]
target = "thumbv4t-none-eabi"

[unstable]
build-std = ["core"]

[target.thumbv4t-none-eabi]
runner = "mgba-qt" # sets the emulator to run bins/examples with
rustflags = [
  "-Clinker=arm-none-eabi-ld", # uses the ARM linker
  "-Clink-arg=-Tlinker_scripts/mono_boot.ld", # sets the link script
]
  • 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.
#![no_std]
#![no_main]

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

#[no_mangle]
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.

§Safety

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.

Modules§

bios
The GBA’s BIOS provides limited built-in utility functions.
builtin_art
This module provides some basic art assets.
dma
Module for interfacing with the GBA’s Direct Memory Access units.
fixed
gba_cell
A GBA-specific “cell” type that allows safe global mutable data.
interrupts
keys
Module for interfacing with the device’s button inputs.
mem
mgba
Lets you interact with the mGBA debug output buffer.
mmio
Contains all the MMIO address definitions for the GBA’s components.
prelude
A module that just re-exports all the other modules of the crate.
random
sound
timers
Module to interface with the GBA’s four timer units.
video
Module to control the GBA’s screen.

Macros§

include_aligned_bytes
Works like include_bytes!, but the value is wrapped in Align4.

Structs§

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

Statics§

RUST_IRQ_HANDLER
The function pointer that the assembly runtime calls when an interrupt occurs.