Introduction
Here's a book that'll help you program in Rust on the GBA.
It's very "work in progress". At the moment there's only one demo program.
Other Works
If you want to read more about developing on the GBA there are some other good resources as well:
- Tonc, a tutorial series written for C, but it's what I based the ordering of this book's sections on.
- GBATEK, a homebrew tech manual for GBA/NDS/DSi. We will regularly link to parts of it when talking about various bits of the GBA.
Chapter 0: Development Setup
Before you can build a GBA game you'll have to follow some special steps to setup the development environment. Perhaps unfortunately, there's enough detail here to warrant a mini-chapter all on its own.
Per System Setup
Obviously you need your computer to have a working rust installation. However,
you'll also need to ensure that you're using a nightly toolchain. You can run
rustup default nightly
to set nightly as the system wide default toolchain, or
you can use a toolchain
file to use
nightly just on a specific project, but either way we'll be assuming nightly
from now on.
Next you need devkitpro. They've
got a graphical installer for Windows, and pacman
support on Linux. We'll be
using a few of their binutils for the arm-none-eabi
target, and we'll also be
using some of their tools that are specific to GBA development, so even if you
already have the right binutils for whatever reason, you'll still want devkitpro
for the gbafix
utility.
- On Windows you'll want something like
C:\devkitpro\devkitARM\bin
andC:\devkitpro\tools\bin
to be added to your PATH, depending on where you installed it to and such. - On Linux you'll also want it to be added to your path, but if you're using Linux I'll just assume you know how to do all that.
Finally, you'll need cargo-xbuild
. Just run cargo install cargo-xbuild
and
cargo will figure it all out for you.
Per Project Setup
Now you'll need some particular files each time you want to start a new project. You can find them in the root of the rust-console/gba repo.
thumbv4-none-eabi.json
describes the overall GBA to cargo-xbuild so it knows what to do.crt0.s
describes some ASM startup stuff. If you have more ASM to place here later on this is where you can put it. You also need to build it into acrt0.o
file before it can actually be used, but we'll cover that below.linker.ld
tells the linker more critical info about the layout expectations that the GBA has about our program.
Compiling
Once you've got something to build, you perform the following steps:
-
arm-none-eabi-as crt0.s -o crt0.o
- This builds your text format
crt0.s
file into object formatcrt0.o
. You don't need to perform it every time, only whencrt0.s
changes, but you might as well do it every time so that you never forget to because it's a practically instant operation.
- This builds your text format
-
cargo xbuild --target thumbv4-none-eabi.json
- This builds your Rust source. It accepts most of the normal options, such
as
--release
, and options, such as--bin foo
or--examples
, that you'd expectcargo
to accept. - You can not build and run tests this way, because they require
std
, which the GBA doesn't have. You can still run some of your project's tests withcargo test
, but that builds for your local machine, so anything specific to the GBA (such as reading and writing registers) won't be testable that way. If you want to isolate and try out some piece code running on the GBA you'll unfortunately have to make a demo for it in yourexamples/
directory and then run the demo in an emulator and see if it does what you expect. - The file extension is important.
cargo xbuild
takes it as a flag to compile dependencies with the same sysroot, so you can include crates normally. Well, creates that work in the GBA's limited environment, but you get the idea.
- This builds your Rust source. It accepts most of the normal options, such
as
At this point you have an ELF binary that some emulators can execute directly. This is helpful because it'll have debug symbols and all that, assuming a debug build. Specifically, mgba 0.1 beta 1 can do it, and perhaps other emulators can also do it.
However, if you want a "real" ROM that works in all emulators and that you could transfer to a flash cart there's a little more to do.
-
arm-none-eabi-objcopy -O binary target/thumbv4-none-eabi/MODE/BIN_NAME target/ROM_NAME.gba
- This will perform an objcopy on our
program. Here I've named the program
arm-none-eabi-objcopy
, which is what devkitpro calls their version ofobjcopy
that's specific to the GBA in the Windows install. If the program isn't found under that name, have a look in your installation directory to see if it's under a slightly different name or something. - As you can see from reading the man page, the
-O binary
option takes our lovely ELF file with symbols and all that and strips it down to basically a bare memory dump of the program. - The next argument is the input file. You might not be familiar with how
cargo
arranges stuff in thetarget/
directory, and between RLS andcargo doc
and stuff it gets kinda crowded, so it goes like this:- Since our program was built for a non-local target, first we've got a
directory named for that target,
thumbv4-none-eabi/
- Next, the "MODE" is either
debug/
orrelease/
, depending on if we had the--release
flag included. You'll probably only be packing release mode programs all the way into GBA roms, but it works with either mode. - Finally, the name of the program. If your program is something out of the
project's
src/bin/
then it'll be that file's name, or whatever name you configured for the bin in theCargo.toml
file. If your program is something out of the project'sexamples/
directory there will be a similarexamples/
sub-directory first, and then the example's name.
- Since our program was built for a non-local target, first we've got a
directory named for that target,
- The final argument is the output of the
objcopy
, which I suggest putting at just the top level of thetarget/
directory. Really it could go anywhere, but if you're using git then it's likely that your.gitignore
file is already setup to exclude everything intarget/
, so this makes sure that your intermediate game builds don't get checked into your git.
- This will perform an objcopy on our
program. Here I've named the program
-
gbafix target/ROM_NAME.gba
- The
gbafix
tool also comes from devkitpro. The GBA is very picky about a ROM's format, andgbafix
patches the ROM's header and such so that it'll work right. Unlikeobjcopy
, this tool is custom built for GBA development, so it works just perfectly without any arguments beyond the file name. The ROM is patched in place, so we don't even need to specify a new destination.
- The
And you're finally done!
Of course, you probably want to make a script for all that, but it's up to you.
Ch 1: Hello GBA
Traditionally a person writes a "hello, world" program so that they can test that their development environment is setup properly and to just get a feel for using the tools involved. To get an idea of what a small part of a source file will look like. All that stuff.
Normally, you write a program that prints "hello, world" to the terminal. The GBA has no terminal, but it does have a screen, so instead we're going to draw three dots to the screen.
hello1
Ready? Here goes:
hello1.rs
#![feature(start)] #![no_std] #[cfg(not(test))] #[panic_handler] fn panic(_info: &core::panic::PanicInfo) -> ! { loop {} } #[start] fn main(_argc: isize, _argv: *const *const u8) -> isize { unsafe { (0x04000000 as *mut u16).write_volatile(0x0403); (0x06000000 as *mut u16).offset(120 + 80 * 240).write_volatile(0x001F); (0x06000000 as *mut u16).offset(136 + 80 * 240).write_volatile(0x03E0); (0x06000000 as *mut u16).offset(120 + 96 * 240).write_volatile(0x7C00); loop {} } }
Throw that into your project, build the program (as described back in Chapter 0), and give it a run. You should see a red, green, and blue dot close-ish to the middle of the screen. If you don't, something already went wrong. Double check things, phone a friend, write your senators, try asking Ketsuban on the Rust Community Discord, until you're able to get your three dots going.
Explaining hello1
So, what just happened? Even if you're used to Rust that might look pretty strange. We'll go over each part extra carefully.
# #![allow(unused_variables)] #![feature(start)] #fn main() { #}
This enables the start feature, which you would normally be able to read about in the unstable book, except that the book tells you nothing at all except to look at the tracking issue.
Basically, a GBA game is even more low-level than the normal amount of
low-level that you get from Rust, so we have to tell the compiler to account for
that by specifying a #[start]
, and we need this feature on to do that.
# #![allow(unused_variables)] #![no_std] #fn main() { #}
There's no standard library available on the GBA, so we'll have to live a core only life.
# #![allow(unused_variables)] #fn main() { #[cfg(not(test))] #[panic_handler] fn panic(_info: &core::panic::PanicInfo) -> ! { loop {} } #}
This sets our panic handler. Basically, if we somehow trigger a panic, this is where the program goes. However, right now we don't know how to get any sort of message out to the user so... we do nothing at all. We can't even return from here, so we just sit in an infinite loop. The player will have to reset the universe from the outside.
The #[cfg(not(test))]
part makes this item only exist in the program when
we're not in a test build. This is so that cargo test
and such work right as
much as possible.
#[start] fn main(_argc: isize, _argv: *const *const u8) -> isize {
This is our #[start]
. We call it main
, but the signature looks a lot more
like the main from C than it does the main from Rust. Actually, those inputs are
useless, because nothing will be calling our code from the outside. Similarly,
it's totally undefined to return anything, so the fact that we output an isize
is vacuously true at best. We just have to use this function signature because
that's how #[start]
works, not because the inputs and outputs are meaningful.
# #![allow(unused_variables)] #fn main() { unsafe { #}
I hope you're all set for some unsafe
, because there's a lot of it to be had.
# #![allow(unused_variables)] #fn main() { (0x04000000 as *mut u16).write_volatile(0x0403); #}
Sure!
# #![allow(unused_variables)] #fn main() { (0x06000000 as *mut u16).offset(120 + 80 * 240).write_volatile(0x001F); (0x06000000 as *mut u16).offset(136 + 80 * 240).write_volatile(0x03E0); (0x06000000 as *mut u16).offset(120 + 96 * 240).write_volatile(0x7C00); #}
Ah, of course.
# #![allow(unused_variables)] #fn main() { loop {} } } #}
And, as mentioned above, there's no place for a GBA program to "return to", so
we can't ever let main
try to return there. Instead, we go into an infinite
loop
that does nothing. The fact that this doesn't ever return an isize
value doesn't seem to bother Rust, because I guess we're at least not returning
any other type of thing instead.
Fun fact: unlike in C++, an infinite loop with no side effects isn't Undefined Behavior for us rustaceans... semantically. In truth LLVM has a known bug in this area, so we won't actually be relying on empty loops in any future programs.
All Those Magic Numbers
Alright, I cheated quite a bit in the middle there. The program works, but I didn't really tell you why because I didn't really tell you what any of those magic numbers mean or do.
0x04000000
is the address of an IO Register called the Display Control.0x06000000
is the start of Video RAM.
So we write some magic to the display control register once, then we write some other magic to three locations of magic to the Video RAM. We get three dots, each in their own location... so that second part makes sense at least.
We'll get into the magic number details in the other sections of this chapter.
Sidebar: Volatile
We'll get into what all that is in a moment, but first let's ask ourselves: Why are we doing volatile writes? You've probably never used it before at all. What is volatile anyway?
Well, the optimizer is pretty aggressive some of the time, and so it'll skip reads and writes when it thinks can. Like if you write to a pointer once, and then again a moment later, and it didn't see any other reads in between, it'll think that it can just skip doing that first write since it'll get overwritten anyway. Sometimes that's right, but sometimes it's wrong.
Marking a read or write as volatile tells the compiler that it really must do that action, and in the exact order that we wrote it out. It says that there might even be special hardware side effects going on that the compiler isn't aware of. In this case, the Display Control write sets a video mode, and the Video RAM writes set pixels that will show up on the screen.
Similar to "atomic" operations you might have heard about, all volatile operations are enforced to happen in the exact order that you specify them, but only relative to other volatile operations. So something like
# #![allow(unused_variables)] #fn main() { c.volatile_write(5); a += b; d.volatile_write(7); #}
might end up changing a
either before or after the change to c
, but the
write to d
will always happen after the write to c
.
If you ever use volatile stuff on other platforms it's important to note that volatile doesn't make things thread-safe, you still need atomic for that. However, the GBA doesn't have threads, so we don't have to worry about thread safety concerns.
IO Registers
The GBA has a large number of IO Registers (not to be confused with CPU
registers). These are special memory locations from 0x04000000
to
0x040003FE
. GBATEK has a full
list, but we only need to learn
about a few of them at a time as we go, so don't be worried.
The important facts to know about IO Registers are these:
- Each has their own specific size. Most are
u16
, but some areu32
. - All of them must be accessed in a
volatile
style. - Each register is specifically readable or writable or both. Actually, with
some registers there are even individual bits that are read-only or
write-only.
- If you write to a read-only position, those writes are simply ignored. This mostly matters if a writable register contains a read-only bit (such as the Display Control, next section).
- If you read from a write-only position, you get back values that are basically nonsense. There aren't really any registers that mix writable bits with read only bits, so you're basically safe here. The only (mild) concern is that when you write a value into a write-only register you need to keep track of what you wrote somewhere else if you want to know what you wrote (such to adjust an offset value by +1, or whatever).
- You can always check GBATEK to be sure, but if I don't mention it then a bit is probably both read and write.
- Some registers have invalid bit patterns. For example, the lowest three bits of the Display Control register can't legally be set to the values 6 or 7.
When talking about bit positions, the numbers are zero indexed just like an array index is.
The Display Control
The Display Control is our first actual IO Register. GBATEK gives it the shorthand DISPCNT, so you might see it under that name if you read other guides.
Among IO Registers, it's one of the simpler ones, but it's got enough complexity that we can get a hint of what's to come.
Also it's the one that you basically always need to set at least once in every GBA game, so it's a good starting one to go over for that reason too.
The Display Control is a u16
value located at 0x0400_0000
.
Video Modes
The lowest three bits (0-2) let you select from among the GBA's six video modes. You'll notice that 3 bits allows for eight modes, but the values 6 and 7 are prohibited.
Modes 0, 1, and 2 are "Tiled" modes. These are actually the modes that you should eventually learn to use as much as possible. It lets the GBA's limited video hardware do as much of the work as possible, leaving more of your CPU time for gameplay computations. However, they're also complex enough to deserve their own demos and chapters later on, so that's all we'll say about them for now.
Modes 3, 4, and 5 are "Bitmap" modes. These let you write individual pixels to locations on the screen.
- Mode 3 is full resolution (240w x 160h) RBG15 color. You might not be used to RGB15, since modern computers have 24 or 32 bit colors. In RGB15, there's 5 bits for each color channel, and the highest bit is totally ignored.
- Mode 4 is full resolution paletted color. Instead of being a
u16
color, each pixel value is au8
palette index entry, and then the display uses the palette memory (which we'll talk about later) to store the actual color data. Since each pixel is half sized, we can fit twice as many. This lets us have two "pages". At any given moment only one page is active, and you can draw to the other page without the user noticing. You set which page to show with another bit we'll get to in a moment. - Mode 5 is full color, but also with pages. This means that we must have a reduced resolution to compensate (video memory is only so big!). The screen is effectively only 160w x 128h in this mode.
CGB Mode
Bit 3 is read only. It's on if you're running in CGB mode. Since we're making GBA games you'd think that it'll never be on at all, but I guess you can change it with BIOS stuff. Still, basically not an important bit.
Page Flipping
Bit 4 lets you pick which page to use. This is only relevent in video modes 4 or 5, and is just ignored otherwise. It's very easy to remember: when the bit is 0 the 0th page is used, and when the bit is 1 the 1st page is used.
The second page always starts at 0x0600_A000
.
OAM, VRAM, and Blanking
Bit 5 lets you access OAM during HBlank if enabled. This is cool, but it reduces the maximum sprites per scanline, so it's not default.
Bit 6 lets you adjust if the GBA should treat Object Character VRAM as being 2d (off) or 1d (on).
Bit 7 forces the screen to stay in vblank as long as it's set. This allows the fastest use of the VRAM, Palette, and Object Attribute Memory. Obviously if you leave this on for too long the player will notice a blank screen, but it might be okay to use for a moment or two every once in a while.
Screen Layers
Bits 8 through 11 control if Background layers 0 through 3 should be active.
Bit 12 affects the Object layer.
Note that not all background layers are available in all video modes:
- Mode 0: all
- Mode 1: 0/1/2
- Mode 2: 2/3
- Mode 3/4/5: 2
Bit 13 and 14 enable the display of Windows 0 and 1, and Bit 15 enables the object display window. We'll get into how windows work later on, they let you do some nifty graphical effects.
In Conclusion...
So what did we do to the display control in hello1
?
# #![allow(unused_variables)] #fn main() { (0x04000000 as *mut u16).write_volatile(0x0403); #}
First let's convert that to
binary, and we get
0b100_0000_0011
. So, that's setting Mode 3 with background 2 enabled and
nothing else special.
Video Memory Intro
The GBA's Video RAM is 96k stretching from 0x0600_0000
to 0x0601_7FFF
.
The Video RAM can only be accessed totally freely during a Vertical Blank (aka "vblank"). At other times, if the CPU tries to touch the same part of video memory as the display controller is accessing then the CPU gets bumped by a cycle to avoid a clash.
Annoyingly, VRAM can only be properly written to in 16 and 32 bit segments (same
with PALRAM and OAM). If you try to write just an 8 bit segment, then both parts
of the 16 bit segment get the same value written to them. In other words, if you
write the byte 5
to 0x0600_0000
, then both 0x0600_0000
and ALSO
0x0600_0001
will have the byte 5
in them. We have to be extra careful when
trying to set an individual byte, and we also have to be careful if we use
memcopy
or memset
as well, because they're byte oriented by default and
don't know to follow the special rules.
RGB15
TODO
Mode 3
TODO
Mode 4
TODO
Mode 5
TODO
In Conclusion...
TODO