2018-11-08 15:20:40 +11:00
<!DOCTYPE HTML>
< html lang = "en" class = "sidebar-visible no-js" >
< head >
<!-- Book generated using mdBook -->
< meta charset = "UTF-8" >
2018-11-18 11:14:42 +11:00
< title > Rust GBA Guide< / title >
2018-11-08 15:20:40 +11:00
< meta content = "text/html; charset=utf-8" http-equiv = "Content-Type" >
< meta name = "description" content = "" >
< meta name = "viewport" content = "width=device-width, initial-scale=1" >
< meta name = "theme-color" content = "#ffffff" / >
< link rel = "shortcut icon" href = "favicon.png" >
< link rel = "stylesheet" href = "css/variables.css" >
< link rel = "stylesheet" href = "css/general.css" >
< link rel = "stylesheet" href = "css/chrome.css" >
< link rel = "stylesheet" href = "css/print.css" media = "print" >
<!-- Fonts -->
< link rel = "stylesheet" href = "FontAwesome/css/font-awesome.css" >
< link href = "https://fonts.googleapis.com/css?family=Open+Sans:300italic,400italic,600italic,700italic,800italic,400,300,600,700,800" rel = "stylesheet" type = "text/css" >
< link href = "https://fonts.googleapis.com/css?family=Source+Code+Pro:500" rel = "stylesheet" type = "text/css" >
<!-- Highlight.js Stylesheets -->
< link rel = "stylesheet" href = "highlight.css" >
< link rel = "stylesheet" href = "tomorrow-night.css" >
< link rel = "stylesheet" href = "ayu-highlight.css" >
<!-- Custom theme stylesheets -->
< / head >
< body class = "light" >
<!-- Provide site root to javascript -->
< script type = "text/javascript" > var path _to _root = "" ; < / script >
<!-- Work around some values being stored in localStorage wrapped in quotes -->
< script type = "text/javascript" >
try {
var theme = localStorage.getItem('mdbook-theme');
var sidebar = localStorage.getItem('mdbook-sidebar');
if (theme.startsWith('"') & & theme.endsWith('"')) {
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
}
if (sidebar.startsWith('"') & & sidebar.endsWith('"')) {
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
}
} catch (e) { }
< / script >
<!-- Set the theme before any content is loaded, prevents flash -->
< script type = "text/javascript" >
var theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = 'light'; }
document.body.className = theme;
document.querySelector('html').className = theme + ' js';
< / script >
<!-- Hide / unhide sidebar before it is displayed -->
< script type = "text/javascript" >
var html = document.querySelector('html');
var sidebar = 'hidden';
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
}
html.classList.remove('sidebar-visible');
html.classList.add("sidebar-" + sidebar);
< / script >
< nav id = "sidebar" class = "sidebar" aria-label = "Table of contents" >
2018-12-10 19:48:06 +11:00
< ol class = "chapter" > < li > < a href = "00-introduction/00-index.html" > < strong aria-hidden = "true" > 1.< / strong > Introduction< / a > < / li > < li > < ol class = "section" > < li > < a href = "00-introduction/01-requirements.html" > < strong aria-hidden = "true" > 1.1.< / strong > Reader Requirements< / a > < / li > < li > < a href = "00-introduction/02-goals_and_style.html" > < strong aria-hidden = "true" > 1.2.< / strong > Book Goals and Style< / a > < / li > < li > < a href = "00-introduction/03-development-setup.html" > < strong aria-hidden = "true" > 1.3.< / strong > Development Setup< / a > < / li > < li > < a href = "00-introduction/04-hello-magic.html" > < strong aria-hidden = "true" > 1.4.< / strong > Hello, Magic< / a > < / li > < li > < a href = "00-introduction/05-newtype.html" > < strong aria-hidden = "true" > 1.5.< / strong > Newtype< / a > < / li > < li > < a href = "00-introduction/06-help_and_resources.html" > < strong aria-hidden = "true" > 1.6.< / strong > Help and Resources< / a > < / li > < / ol > < / li > < li > < a href = "01-limitations/00-index.html" > < strong aria-hidden = "true" > 2.< / strong > Limitations< / a > < / li > < li > < ol class = "section" > < li > < a href = "01-limitations/01-no_floats.html" > < strong aria-hidden = "true" > 2.1.< / strong > No Floats< / a > < / li > < li > < a href = "01-limitations/02-core_only.html" > < strong aria-hidden = "true" > 2.2.< / strong > Core Only< / a > < / li > < li > < a href = "01-limitations/03-volatile_destination.html" > < strong aria-hidden = "true" > 2.3.< / strong > Volatile Destination< / a > < / li > < / ol > < / li > < li > < a href = "02-concepts/00-index.html" > < strong aria-hidden = "true" > 3.< / strong > Concepts< / a > < / li > < li > < ol class = "section" > < li > < a href = "02-concepts/01-cpu.html" > < strong aria-hidden = "true" > 3.1.< / strong > CPU< / a > < / li > < li > < a href = "02-concepts/02-bios.html" > < strong aria-hidden = "true" > 3.2.< / strong > BIOS< / a > < / li > < li > < a href = "02-concepts/03-wram.html" > < strong aria-hidden = "true" > 3.3.< / strong > Work RAM< / a > < / li > < li > < a href = "02-concepts/04-io-registers.html" > < strong aria-hidden = "true" > 3.4.< / strong > IO Registers< / a > < / li > < li > < a href = "02-concepts/05-palram.html" > < strong aria-hidden = "true" > 3.5.< / strong > Palette RAM< / a > < / li > < li > < a href = "02-concepts/06-vram.html" > < strong aria-hidden = "true" > 3.6.< / strong > Video RAM< / a > < / li > < li > < a href = "02-concepts/07-oam.html" > < strong aria-hidden = "true" > 3.7.< / strong > Object Attribute Memory< / a > < / li > < li > < a href = "02-concepts/08-rom.html" > < strong aria-hidden = "true" > 3.8.< / strong > Game Pak ROM / Flash ROM< / a > < / li > < li > < a href = "02-concepts/09-sram.html" > < strong aria-hidden = "true" > 3.9.< / strong > Save RAM< / a > < / li > < / ol > < / li > < li > < a href = "03-video/00-index.html" > < strong aria-hidden = "true" > 4.< / strong > Video< / a > < / li > < li > < ol class = "section" > < li > < a href = "03-video/01-rgb15.html" > < strong aria-hidden = "true" > 4.1.< / strong > RBG15 Color< / a > < / li > < li > < a href = "03-video/TODO.html" > < strong aria-hidden = "true" > 4.2.< / strong > TODO< / a > < / li > < / ol > < / li > < li > < a href = "04-non-video/00-index.html" > < strong aria-hidden = "true" > 5.< / strong > Non-Video< / a > < / li > < li > < ol class = "section" > < li > < a href = "04-non-video/01-buttons.html" > < strong aria-hidden = "true" > 5.1.< / strong > Buttons< / a > < / li > < li > < a href = "04-non-video/02-timers.html" > < strong aria-hidden = "true" > 5.2.< / strong > Timers< / a > < / li > < li > < a href = "04-non-video/03-dma.html" > < strong aria-hidden = "true" > 5.3.< / strong > Direct Memory Access< / a > < / li > < li > < a href = "04-non-video/04-sound.html" > < strong aria-hidden = "true" > 5.4.< / strong > Sound< / a > < / li > < li > < a href = "04-non-video/05-interrupts.html" > < strong aria-hidden = "true" > 5.5.< / strong > Interrupts< / a > < / li > < li > < a href = "04-non-video/06-network.html" > < strong aria-hidden = "true" > 5.6.< / strong > Network< / a > < / li > < li > < a href = "04-non-video/07-game_pak.html" > < strong aria-hidden = "true" > 5.7.< / strong > Game Pak< / a > < / li > < / ol > < / li > < li > < a href = "05-examples/00-index.html" > < strong aria-hidden = "true" > 6.< / strong > Examples< / a > < / li > < li > < ol class = "section" > < li > < a href = "05-examples/01-hello_magic.html" > < strong aria-hidden = "true" > 6.1.< / strong > hello_magic< / a > < / li > < li > < a href = "05-examples/02-hello_world.html" > < strong aria-hidden = "true" > 6.2.< / strong > hello_world< / a > < / li > < li > < a href = "05-examples/03-light_cycle.html" > < strong aria-hidden = "true" > 6.3.< / strong > light_cycle< / a > < / li > < li > < a href = "05-examples/04-bg_demo.html" > < strong aria-hidden = "true" > 6.4.< / strong > bg_demo< / a > < / li > < / ol > < / li >
2018-11-08 15:20:40 +11:00
< / nav >
< div id = "page-wrapper" class = "page-wrapper" >
< div class = "page" >
< div id = "menu-bar" class = "menu-bar" >
< div id = "menu-bar-sticky-container" >
< div class = "left-buttons" >
< button id = "sidebar-toggle" class = "icon-button" type = "button" title = "Toggle Table of Contents" aria-label = "Toggle Table of Contents" aria-controls = "sidebar" >
< i class = "fa fa-bars" > < / i >
< / button >
< button id = "theme-toggle" class = "icon-button" type = "button" title = "Change theme" aria-label = "Change theme" aria-haspopup = "true" aria-expanded = "false" aria-controls = "theme-list" >
< i class = "fa fa-paint-brush" > < / i >
< / button >
< ul id = "theme-list" class = "theme-popup" aria-label = "Themes" role = "menu" >
< li role = "none" > < button role = "menuitem" class = "theme" id = "light" > Light < span class = "default" > (default)< / span > < / button > < / li >
< li role = "none" > < button role = "menuitem" class = "theme" id = "rust" > Rust< / button > < / li >
< li role = "none" > < button role = "menuitem" class = "theme" id = "coal" > Coal< / button > < / li >
< li role = "none" > < button role = "menuitem" class = "theme" id = "navy" > Navy< / button > < / li >
< li role = "none" > < button role = "menuitem" class = "theme" id = "ayu" > Ayu< / button > < / li >
< / ul >
< button id = "search-toggle" class = "icon-button" type = "button" title = "Search. (Shortkey: s)" aria-label = "Toggle Searchbar" aria-expanded = "false" aria-keyshortcuts = "S" aria-controls = "searchbar" >
< i class = "fa fa-search" > < / i >
< / button >
< / div >
2018-11-18 11:14:42 +11:00
< h1 class = "menu-title" > Rust GBA Guide< / h1 >
2018-11-08 15:20:40 +11:00
< div class = "right-buttons" >
< a href = "print.html" title = "Print this book" aria-label = "Print this book" >
< i id = "print-button" class = "fa fa-print" > < / i >
< / a >
< / div >
< / div >
< / div >
< div id = "search-wrapper" class = "hidden" >
< form id = "searchbar-outer" class = "searchbar-outer" >
< input type = "search" name = "search" id = "searchbar" name = "searchbar" placeholder = "Search this book ..." aria-controls = "searchresults-outer" aria-describedby = "searchresults-header" >
< / form >
< div id = "searchresults-outer" class = "searchresults-outer hidden" >
< div id = "searchresults-header" class = "searchresults-header" > < / div >
< ul id = "searchresults" >
< / ul >
< / div >
< / div >
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
< script type = "text/javascript" >
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
});
< / script >
< div id = "content" class = "content" >
< main >
2018-11-10 20:03:37 +11:00
< a class = "header" href = "#introduction" id = "introduction" > < h1 > Introduction< / h1 > < / a >
2018-12-10 19:48:06 +11:00
< p > This is the book for learning how to write GBA games in Rust.< / p >
< p > I'm < strong > Lokathor< / strong > , the main author of the book. There's also < strong > Ketsuban< / strong > who
provides the technical advisement, reviews the PRs, and keeps my crazy in check.< / p >
< p > The book is a work in progress, as you can see if you actually try to open many
of the pages listed in the Table Of Contents.< / p >
< a class = "header" href = "#feedback" id = "feedback" > < h2 > Feedback< / h2 > < / a >
< p > It's also often hard to tell when you've explained something properly to someone
who doesn't understand the concept yet. Please, if things don't make sense then
< a href = "https://github.com/rust-console/gba/issues" > file an issue< / a > about it so I know
where things need to improve.< / p >
2018-12-09 04:57:38 +11:00
< a class = "header" href = "#reader-requirements" id = "reader-requirements" > < h1 > Reader Requirements< / h1 > < / a >
2018-12-10 19:48:06 +11:00
< p > This book naturally assumes that you've already read Rust's core book:< / p >
< ul >
< li > < a href = "https://doc.rust-lang.org/book/" > The Rust Programming Language< / a > < / li >
< / ul >
< p > Now, I < em > know< / em > it sounds silly to say " if you wanna program Rust on this old
video game system you should already know how to program Rust" , but the more
people I meet and chat with the more they tell me that they jumped into Rust
without reading any or all of the book. You know who you are.< / p >
< p > Please, read the whole book!< / p >
< p > In addition to the core book, there's also an expansion book that I will declare
to be required reading for this:< / p >
< ul >
< li > < a href = "https://doc.rust-lang.org/nomicon/" > The Rustonomicon< / a > < / li >
< / ul >
< p > The Rustonomicon is all about trying to demystify < code > unsafe< / code > . We'll end up using a
fair bit of unsafe code as a natural consequence of doing direct hardware
manipulations. Using unsafe is like < a href = "https://www.zeldadungeon.net/wp-content/uploads/2013/04/tumblr_mlkpzij6T81qizbpto1_1280.gif" > swinging a
sword< / a > ,
you should start slowly, practice carefully, and always pay attention no matter
how experienced you think you've become.< / p >
< p > That said, it's sometimes a < a href = "https://www.youtube.com/watch?v=rTo2u13lVcQ" > necessary
tool< / a > to get the job done, so you
have to break out of the borderline pathological fear of using it that most rust
programmers tend to have.< / p >
2018-12-09 04:57:38 +11:00
< a class = "header" href = "#book-goals-and-style" id = "book-goals-and-style" > < h1 > Book Goals and Style< / h1 > < / a >
2018-12-10 19:48:06 +11:00
< p > So, what's this book actually gonna teach you?< / p >
< p > I'm < em > not< / em > gonna tell you how to use a crate that already exists.< / p >
< p > Don't get me wrong, there < em > is< / em > a < a href = "https://crates.io/crates/gba" > gba< / a > crate, and
it's on crates.io and all that jazz.< / p >
< p > However, unlike most crates that come with a tutorial book, I don't want to just
teach you how to use the crate. What I want is to teach you what you need to
know so that you could build the crate yourself, from scratch, if it didn't
already exist for you. Let's call it the < a href = "https://handmadehero.org/" > Handmade
Hero< / a > school of design. Much more than you might find
in other Rust crate books, I'll be attempting to show a lot of the < em > why< / em > in
addition to just the < em > how< / em > . Once you know how to do it all on your own, you can
decide for yourself if the < code > gba< / code > crate does it well, or if you think you can
come up with something that suits your needs better.< / p >
< p > Overall the book is sorted for easy review once you're trying to program
something, and the GBA has a few interconnected concepts, so some parts of the
book end up having to refer you to portions that you haven't read yet. The
chapters and sections are sorted so that < em > minimal< / em > future references are
required, but it's unavoidable.< / p >
< p > The actual " tutorial order" of the book is the
< a href = "../05-examples/00-index.html" > Examples< / a > chapter. Each section of that chapter
breaks down one of the provided examples in the < a href = "https://github.com/rust-console/gba/tree/master/examples" > examples
directory< / a > of the
repository. We go over what sections of the book you'll need to have read for
the example code to make sense, and also how we apply the general concepts
described in the book to the specific example cases.< / p >
2018-12-09 04:57:38 +11:00
< a class = "header" href = "#development-setup" id = "development-setup" > < h1 > Development Setup< / h1 > < / a >
2018-12-10 19:48:06 +11:00
< p > Before you can build a GBA game you'll have to follow some special steps to
setup the development environment.< / p >
< p > Once again, extra special thanks to < strong > Ketsuban< / strong > , who first dove into how to
make this all work with rust and then shared it with the world.< / p >
< a class = "header" href = "#per-system-setup" id = "per-system-setup" > < h2 > Per System Setup< / h2 > < / a >
< p > Obviously you need your computer to have a < a href = "https://rustup.rs/" > working rust
installation< / a > . However, you'll also need to ensure that
you're using a nightly toolchain (we will need it for inline assembly, among
other potential useful features). You can run < code > rustup default nightly< / code > to set
nightly as the system wide default toolchain, or you can use a < a href = "https://github.com/rust-lang-nursery/rustup.rs#the-toolchain-file" > toolchain
file< / a > to use
nightly just on a specific project, but either way we'll be assuming the use of
nightly from now on. You'll also need the < code > rust-src< / code > component so that
< code > cargo-xbuild< / code > will be able to compile the core crate for us in a bit, so run
< code > rustup component add rust-src< / code > .< / p >
< p > Next, you need < a href = "https://devkitpro.org/wiki/Getting_Started" > devkitpro< / a > . They've
got a graphical installer for Windows that runs nicely, and I guess < code > pacman< / code >
support on Linux (I'm on Windows so I haven't tried the Linux install myself).
We'll be using a few of their general binutils for the < code > arm-none-eabi< / code > target,
and we'll also be using some of their tools that are specific to GBA
development, so < em > even if< / em > you already have the right binutils for whatever
reason, you'll still want devkitpro for the < code > gbafix< / code > utility.< / p >
< ul >
< li > On Windows you'll want something like < code > C:\devkitpro\devkitARM\bin< / code > and
< code > C:\devkitpro\tools\bin< / code > to be < a href = "https://stackoverflow.com/q/44272416/455232" > added to your
PATH< / a > , depending on where you
installed it to and such.< / li >
< li > On Linux you can use pacman to get it, and the default install puts the stuff
in < code > /opt/devkitpro/devkitARM/bin< / code > and < code > /opt/devkitpro/tools/bin< / code > . If you need
help you can look in our repository's
< a href = "https://github.com/rust-console/gba/blob/master/.travis.yml" > .travis.yml< / a >
file to see exactly what our CI does.< / li >
< / ul >
< p > Finally, you'll need < code > cargo-xbuild< / code > . Just run < code > cargo install cargo-xbuild< / code > and
cargo will figure it all out for you.< / p >
< a class = "header" href = "#per-project-setup" id = "per-project-setup" > < h2 > Per Project Setup< / h2 > < / a >
< p > Once the system wide tools are ready, you'll need some particular files each
time you want to start a new project. You can find them in the root of the
< a href = "https://github.com/rust-console/gba" > rust-console/gba repo< / a > .< / p >
< ul >
< li > < code > thumbv4-none-agb.json< / code > describes the overall GBA to cargo-xbuild (and LLVM)
so it knows what to do. Technically the GBA is < code > thumbv4-none-eabi< / code > , but we
change the < code > eabi< / code > to < code > agb< / code > so that we can distinguish it from other < code > eabi< / code >
devices when using < code > cfg< / code > flags.< / li >
< li > < code > crt0.s< / code > 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 a
< code > crt0.o< / code > file before it can actually be used, but we'll cover that below.< / li >
< li > < code > linker.ld< / code > tells the linker all the critical info about the layout
expectations that the GBA has about our program, and that it should also
include the < code > crt0.o< / code > file with our compiled rust code.< / li >
< / ul >
< a class = "header" href = "#compiling" id = "compiling" > < h2 > Compiling< / h2 > < / a >
< p > Once all the tools are in place, there's particular steps that you need to
compile the project. For these to work you'll need some source code to compile.
Unlike with other things, an empty main file and/or an empty lib file will cause
a total build failure, because we'll need a
< a href = "https://rust-embedded.github.io/book/intro/no-std.html" > no_std< / a > build, and rust
defaults to builds that use the standard library. The next section has a minimal
example file you can use (along with explanation), but we'll describe the build
steps here.< / p >
< ul >
< li >
< p > < code > arm-none-eabi-as crt0.s -o target/crt0.o< / code > < / p >
< ul >
< li > This builds your text format < code > crt0.s< / code > file into object format < code > crt0.o< / code >
that's placed in the < code > target/< / code > directory. Note that if the < code > target/< / code >
directory doesn't exist yet it will fail, so you have to make the directory
if it's not there. You don't need to rebuild < code > crt0.s< / code > every single time,
only when it changes, but you might as well throw a line to do it every time
into your build script so that you never forget because it's a practically
instant operation anyway.< / li >
< / ul >
< / li >
< li >
< p > < code > cargo xbuild --target thumbv4-none-agb.json< / code > < / p >
< ul >
< li > This builds your Rust source. It accepts < em > most of< / em > the normal options, such
as < code > --release< / code > , and options, such as < code > --bin foo< / code > or < code > --examples< / code > , that you'd
expect < code > cargo< / code > to accept.< / li >
< li > You < strong > can not< / strong > build and run tests this way, because they require < code > std< / code > ,
which the GBA doesn't have. If you want you can still run some of your
project's tests with < code > cargo test --lib< / code > or similar, 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 your < code > examples/< / code > directory and then run the demo in an emulator
and see if it does what you expect.< / li >
< li > The file extension is important! It will work if you forget it, but < code > cargo xbuild< / code > takes the inclusion of the extension as a flag to also compile
dependencies with the same sysroot, so you can include other crates in your
build. Well, creates that work in the GBA's limited environment, but you get
the idea.< / li >
< / ul >
< / li >
< / ul >
< p > At this point you have an ELF binary that some emulators can execute directly
(more on that later). However, if you want a " real" ROM that works in all
emulators and that you could transfer to a flash cart to play on real hardware
there's a little more to do.< / p >
< ul >
< li >
< p > < code > arm-none-eabi-objcopy -O binary target/thumbv4-none-agb/MODE/BIN_NAME target/ROM_NAME.gba< / code > < / p >
< ul >
< li > This will perform an < a href = "https://linux.die.net/man/1/objcopy" > objcopy< / a > on our
program. Here I've named the program < code > arm-none-eabi-objcopy< / code > , which is what
devkitpro calls their version of < code > objcopy< / code > 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.< / li >
< li > As you can see from reading the man page, the < code > -O binary< / code > option takes our
lovely ELF file with symbols and all that and strips it down to basically a
bare memory dump of the program.< / li >
< li > The next argument is the input file. You might not be familiar with how
< code > cargo< / code > arranges stuff in the < code > target/< / code > directory, and between RLS and
< code > cargo doc< / code > and stuff it gets kinda crowded, so it goes like this:
< ul >
< li > Since our program was built for a non-local target, first we've got a
directory named for that target, < code > thumbv4-none-agb/< / code > < / li >
< li > Next, the " MODE" is either < code > debug/< / code > or < code > release/< / code > , depending on if we had
the < code > --release< / code > flag included. You'll probably only be packing release
mode programs all the way into GBA roms, but it works with either mode.< / li >
< li > Finally, the name of the program. If your program is something out of the
project's < code > src/bin/< / code > then it'll be that file's name, or whatever name you
configured for the bin in the < code > Cargo.toml< / code > file. If your program is
something out of the project's < code > examples/< / code > directory there will be a
similar < code > examples/< / code > sub-directory first, and then the example's name.< / li >
< / ul >
< / li >
< li > The final argument is the output of the < code > objcopy< / code > , which I suggest putting
at just the top level of the < code > target/< / code > directory. Really it could go
anywhere, but if you're using git then it's likely that your < code > .gitignore< / code >
file is already setup to exclude everything in < code > target/< / code > , so this makes sure
that your intermediate game builds don't get checked into your git.< / li >
< / ul >
< / li >
< li >
< p > < code > gbafix target/ROM_NAME.gba< / code > < / p >
< ul >
< li > The < code > gbafix< / code > tool also comes from devkitpro. The GBA is very picky about a
ROM's format, and < code > gbafix< / code > patches the ROM's header and such so that it'll
work right. Unlike < code > objcopy< / code > , 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.< / li >
< / ul >
< / li >
< / ul >
< p > And you're < em > finally< / em > done!< / p >
< p > Of course, you probably want to make a script for all that, but it's up to you.
On our own project we have it mostly set up within a < code > Makefile.toml< / code > which runs
using the < a href = "https://github.com/sagiegurari/cargo-make" > cargo-make< / a > plugin.< / p >
< a class = "header" href = "#hello-magic" id = "hello-magic" > < h1 > Hello, Magic< / h1 > < / a >
< p > So we know all the steps to build our source, we just need some source.< / p >
< p > We're beginners, so we'll start small. With normal programming there's usually a
console available, so the minimal program prints " Hello, world" to the terminal.
On a GBA we don't have a terminal and standard out and all that, so the minimal
program draws a red, blue, and green dot to the screen.< / p >
< p > At the lowest level of device programming, it's all < a href = "https://en.wikipedia.org/wiki/Magic_number_(programming)" > Magic
Numbers< / a > . You write
special values to special places and then the hardware does something. A clear
API makes every magic number and magic location easy to understand. A clear < em > and
good< / em > API also prevents you from using the wrong magic number in the wrong place
and causing problems for yourself.< / p >
< p > This is the minimal example to just test that our build system is all set, so
just this once we'll go < em > full< / em > magic number crazy town, for fun. Ready? Here
goes:< / p >
< p > < code > hello_magic.rs< / code > :< / p >
< pre > < pre class = "playpen" > < code class = "language-rust" > #![feature(start)]
#![no_std]
#[panic_handler]
fn panic(_info: & core::panic::PanicInfo) -> ! {
loop {}
}
#[start]
fn main(_argc: isize, _argv: *const *const u8) -> isize {
unsafe {
(0x400_0000 as *mut u16).write_volatile(0x0403);
(0x600_0000 as *mut u16).offset(120 + 80 * 240).write_volatile(0x001F);
(0x600_0000 as *mut u16).offset(136 + 80 * 240).write_volatile(0x03E0);
(0x600_0000 as *mut u16).offset(120 + 96 * 240).write_volatile(0x7C00);
loop {}
}
}
< / code > < / pre > < / pre >
< p > Throw that into your project skeleton, build the program, 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 < em > already< / em > went wrong. Double check things, phone a friend,
write your senators, try asking < code > Lokathor< / code > or < code > Ketsuban< / code > on the < a href = "https://discordapp.com/invite/aVESxV8" > Rust Community
Discord< / a > , until you're eventually able to
get your three dots going.< / p >
< p > Of course, I'm sure you want to know why those numbers are the numbers to use.
Well that's what the whole rest of the book is about!< / p >
< a class = "header" href = "#newtype" id = "newtype" > < h1 > Newtype< / h1 > < / a >
< p > There's one thing I want to get out of the way near the start of the book and it
didn't really have a good fit anywhere else in the book so it goes right here.< / p >
< p > We're talking about the " Newtype Pattern" !< / p >
< p > Now, I told you to read the Rust Book before you read this book, and I'm sure
you're all good students who wouldn't sneak into this book without doing the
required reading, so I'm sure you all remember exactly what I'm talking about,
because they touch on the newtype concept in the book twice, in two < em > very< / em > long
named sections:< / p >
< ul >
< li > < a href = "https://doc.rust-lang.org/book/ch19-03-advanced-traits.html#using-the-newtype-pattern-to-implement-external-traits-on-external-types" > Using the Newtype Pattern to Implement External Traits on External
Types< / a > < / li >
< li > < a href = "https://doc.rust-lang.org/book/ch19-04-advanced-types.html#using-the-newtype-pattern-for-type-safety-and-abstraction" > Using the Newtype Pattern for Type Safety and
Abstraction< / a > < / li >
< / ul >
< p > ...Yeah... The Rust Book doesn't know how to make a short sub-section name to
save its life. Shame.< / p >
< a class = "header" href = "#newtype-basics" id = "newtype-basics" > < h2 > Newtype Basics< / h2 > < / a >
< p > So, we have all these pieces of data, and we want to keep them separated, and we
don't wanna pay the cost for it at runtime. Well, we're in luck, we can pay the
cost at compile time.< / p >
< pre > < pre class = "playpen" > < code class = "language-rust" >
# #![allow(unused_variables)]
#fn main() {
pub struct PixelColor(u16);
#}< / code > < / pre > < / pre >
< p > Ah, except that, as I'm sure you remember from < a href = "https://doc.rust-lang.org/nomicon/other-reprs.html#reprtransparent" > The
Rustonomicon< / a >
(and from < a href = "https://github.com/rust-lang/rfcs/blob/master/text/1758-repr-transparent.md" > the
RFC< / a >
too, of course), if we have a single field struct that's sometimes different
from having just the bare value, so we should be using < code > #[repr(transparent)]< / code >
with our newtypes.< / p >
< pre > < pre class = "playpen" > < code class = "language-rust" >
# #![allow(unused_variables)]
#fn main() {
#[repr(transparent)]
pub struct PixelColor(u16);
#}< / code > < / pre > < / pre >
< p > Ah, and of course we'll need to make it so you can unwrap the value:< / p >
< pre > < pre class = "playpen" > < code class = "language-rust" >
# #![allow(unused_variables)]
#fn main() {
#[repr(transparent)]
pub struct PixelColor(u16);
impl From< PixelColor> for u16 {
fn from(color: PixelColor) -> u16 {
color.0
}
}
#}< / code > < / pre > < / pre >
< p > And then we'll need to do that same thing for < em > every other newtype we want< / em > .< / p >
< p > Except there's only two tiny parts that actually differ between newtype
declarations: the new name and the base type. All the rest is just the same rote
code over and over. Generating piles and piles of boilerplate code? Sounds like
a job for a macro to me!< / p >
< a class = "header" href = "#making-it-a-macro" id = "making-it-a-macro" > < h2 > Making It A Macro< / h2 > < / a >
< p > The most basic version of the macro we want goes like this:< / p >
< pre > < pre class = "playpen" > < code class = "language-rust" >
# #![allow(unused_variables)]
#fn main() {
#[macro_export]
macro_rules! newtype {
($new_name:ident, $old_name:ident) => {
#[repr(transparent)]
pub struct $new_name($old_name);
};
}
#}< / code > < / pre > < / pre >
< p > Except we also want to be able to add attributes (which includes doc comments),
so we upgrade our macro a bit:< / p >
< pre > < pre class = "playpen" > < code class = "language-rust" >
# #![allow(unused_variables)]
#fn main() {
#[macro_export]
macro_rules! newtype {
($(#[$attr:meta])* $new_name:ident, $old_name:ident) => {
$(#[$attr])*
#[repr(transparent)]
pub struct $new_name($old_name);
};
}
#}< / code > < / pre > < / pre >
< p > And we want to automatically add the ability to turn the wrapper type back into
the wrapped type.< / p >
< pre > < pre class = "playpen" > < code class = "language-rust" >
# #![allow(unused_variables)]
#fn main() {
#[macro_export]
macro_rules! newtype {
($(#[$attr:meta])* $new_name:ident, $old_name:ident) => {
$(#[$attr])*
#[repr(transparent)]
pub struct $new_name($old_name);
impl From< $new_name> for $old_name {
fn from(x: $new_name) -> $old_name {
x.0
}
}
};
}
#}< / code > < / pre > < / pre >
< p > That seems like enough for all of our examples, so we'll stop there. We could
add more things, such as making the < code > From< / code > impl optional (because what if you
shouldn't unwrap it for some weird reason?), allowing for more precise
visibility controls (on both the newtype overall and the inner field), and maybe
even other things I can't think of right now. We won't really need those in our
example code for this book, so it's probably nicer to just keep the macro
simpler and quit while we're ahead.< / p >
< p > < strong > As a reminder:< / strong > remember that macros have to appear < em > before< / em > they're invoked in
your source, so the < code > newtype< / code > macro will always have to be at the very top of
your file, or in a module that's declared before other modules and code.< / p >
< a class = "header" href = "#help-and-resources" id = "help-and-resources" > < h1 > Help and Resources< / h1 > < / a >
< a class = "header" href = "#help" id = "help" > < h2 > Help< / h2 > < / a >
< p > So you're stuck on a problem and the book doesn't say what to do. Where can you
find out more?< / p >
< p > The first place I would suggest is the < a href = "https://discordapp.com/invite/aVESxV8" > Rust Community
Discord< / a > . If it's a general Rust question
then you can ask anyone in any channel you feel is appropriate. If it's GBA
specific then you can try asking me (< code > Lokathor< / code > ) or < code > Ketsuban< / code > in the < code > #gamedev< / code >
channel.< / p >
< a class = "header" href = "#emulators" id = "emulators" > < h2 > Emulators< / h2 > < / a >
< p > You certainly might want to eventually write a game that you can put on a flash
cart and play on real hardware, but for most of your development you'll probably
want to be using an emulator for testing, because you don't have to fiddle with
cables and all that.< / p >
< p > In terms of emulators, you want to be using
< a href = "https://github.com/mgba-emu/mgba" > mGBA< / a > , and you want to be using the < a href = "https://github.com/mgba-emu/mgba/releases/tag/0.7-b1" > 0.7 Beta
1< / a > or later. This update
lets you run raw ELF files, which means that you can have full debug symbols
available while you're debugging problems.< / p >
< a class = "header" href = "#information-resources" id = "information-resources" > < h2 > Information Resources< / h2 > < / a >
< p > Ketsuban and I didn't magically learn this all from nowhere, we read various
technical manuals and guides ourselves and then distilled the knowledge (usually
oriented towards C and C++) into this book for Rust.< / p >
< p > We have personally used some or all of the following:< / p >
< ul >
< li > < a href = "http://problemkaputt.de/gbatek.htm" > GBATEK< / a > : This is < em > the< / em > resource. It
covers not only the GBA, but also the DS and DSi, and also a run down of ARM
assembly (32-bit and 16-bit opcodes). The link there is to the 2.9b version on
< code > problemkaputt.de< / code > (the official home of the document), but if you just google
for gbatek the top result is for the 2.5 version on < code > akkit.org< / code > , so make sure
you're looking at the newest version. Sometimes < code > problemkaputt.de< / code > is a little
sluggish so I've also < a href = "https://lokathor.com/gbatek.html" > mirrored< / a > the 2.9b
version on my own site as well. GBATEK is rather large, over 2mb of text, so
if you're on a phone or similar you might want to save an offline copy to go
easy on your data usage.< / li >
< li > < a href = "https://www.coranac.com/tonc/text/" > TONC< / a > : While GBATEK is basically just a
huge tech specification, TONC is an actual < em > guide< / em > on how to make sense of the
GBA's abilities and organize it into a game. It's written for C of course, but
it's a large< / li >
< li > < a href = "https://www.cs.rit.edu/%7Etjh8300/CowBite/CowBiteSpec.htm" > CowBite< / a > : This is
more like GBATEK, and it's less complete, but it mixes in a little more
friendly explanation of things in between the hardware spec parts.< / li >
< / ul >
< p > And I haven't had time to look at it myself, < a href = "http://belogic.com/gba/" > The Audio
Advance< / a > seems to be very good. It explains in depth
how you can get audio working on the GBA. Note that the table of contents for
each page goes along the top instead of down the side.< / p >
< a class = "header" href = "#non-rust-gba-community" id = "non-rust-gba-community" > < h2 > Non-Rust GBA Community< / h2 > < / a >
< p > There's also the < a href = "http://www.gbadev.org/" > GBADev.org< / a > site, which has a forum
and everything. They're coding in C and C++, but you can probably overcome that
difference with a little work on your part.< / p >
< p > I also found a place called
< a href = "https://gbatemp.net/categories/nintendo-gba-discussions.32/" > GBATemp< / a > , which
seems to have a more active forum but less of a focus on actual coding.< / p >
2018-12-09 04:57:38 +11:00
< a class = "header" href = "#gba-limitations" id = "gba-limitations" > < h1 > GBA Limitations< / h1 > < / a >
< a class = "header" href = "#no-floats" id = "no-floats" > < h1 > No Floats< / h1 > < / a >
< a class = "header" href = "#core-only" id = "core-only" > < h1 > Core Only< / h1 > < / a >
< a class = "header" href = "#volatile-destination" id = "volatile-destination" > < h1 > Volatile Destination< / h1 > < / a >
< a class = "header" href = "#broad-concepts" id = "broad-concepts" > < h1 > Broad Concepts< / h1 > < / a >
< a class = "header" href = "#cpu" id = "cpu" > < h1 > CPU< / h1 > < / a >
< a class = "header" href = "#bios" id = "bios" > < h1 > BIOS< / h1 > < / a >
2018-12-10 19:48:06 +11:00
< a class = "header" href = "#work-ram" id = "work-ram" > < h1 > Work RAM< / h1 > < / a >
2018-11-10 20:03:37 +11:00
< a class = "header" href = "#io-registers" id = "io-registers" > < h1 > IO Registers< / h1 > < / a >
2018-12-09 04:57:38 +11:00
< a class = "header" href = "#palette-ram" id = "palette-ram" > < h1 > Palette RAM< / h1 > < / a >
< a class = "header" href = "#video-ram" id = "video-ram" > < h1 > Video RAM< / h1 > < / a >
< a class = "header" href = "#object-attribute-memory" id = "object-attribute-memory" > < h1 > Object Attribute Memory< / h1 > < / a >
< a class = "header" href = "#game-pak-rom--flash-rom" id = "game-pak-rom--flash-rom" > < h1 > Game Pak ROM / Flash ROM< / h1 > < / a >
< a class = "header" href = "#save-ram" id = "save-ram" > < h1 > Save RAM< / h1 > < / a >
< a class = "header" href = "#video" id = "video" > < h1 > Video< / h1 > < / a >
< a class = "header" href = "#rbg15-color" id = "rbg15-color" > < h1 > RBG15 Color< / h1 > < / a >
2018-12-10 19:48:06 +11:00
< a class = "header" href = "#todo" id = "todo" > < h1 > TODO< / h1 > < / a >
2018-12-09 04:57:38 +11:00
< a class = "header" href = "#non-video" id = "non-video" > < h1 > Non-Video< / h1 > < / a >
< a class = "header" href = "#buttons" id = "buttons" > < h1 > Buttons< / h1 > < / a >
< a class = "header" href = "#timers" id = "timers" > < h1 > Timers< / h1 > < / a >
< a class = "header" href = "#direct-memory-access" id = "direct-memory-access" > < h1 > Direct Memory Access< / h1 > < / a >
< a class = "header" href = "#sound" id = "sound" > < h1 > Sound< / h1 > < / a >
< a class = "header" href = "#interrupts" id = "interrupts" > < h1 > Interrupts< / h1 > < / a >
< a class = "header" href = "#network" id = "network" > < h1 > Network< / h1 > < / a >
< a class = "header" href = "#game-pak" id = "game-pak" > < h1 > Game Pak< / h1 > < / a >
< a class = "header" href = "#examples" id = "examples" > < h1 > Examples< / h1 > < / a >
< a class = "header" href = "#hello_magic" id = "hello_magic" > < h1 > hello_magic< / h1 > < / a >
< a class = "header" href = "#hello_world" id = "hello_world" > < h1 > hello_world< / h1 > < / a >
2018-11-13 10:29:17 +11:00
< a class = "header" href = "#light_cycle" id = "light_cycle" > < h1 > light_cycle< / h1 > < / a >
2018-12-09 04:57:38 +11:00
< a class = "header" href = "#bg_demo" id = "bg_demo" > < h1 > bg_demo< / h1 > < / a >
2018-11-08 15:20:40 +11:00
< / main >
< nav class = "nav-wrapper" aria-label = "Page navigation" >
<!-- Mobile navigation buttons -->
< div style = "clear: both" > < / div >
< / nav >
< / div >
< / div >
< nav class = "nav-wide-wrapper" aria-label = "Page navigation" >
< / nav >
< / div >
< script src = "elasticlunr.min.js" type = "text/javascript" charset = "utf-8" > < / script >
< script src = "mark.min.js" type = "text/javascript" charset = "utf-8" > < / script >
< script src = "searcher.js" type = "text/javascript" charset = "utf-8" > < / script >
< script src = "clipboard.min.js" type = "text/javascript" charset = "utf-8" > < / script >
< script src = "highlight.js" type = "text/javascript" charset = "utf-8" > < / script >
< script src = "book.js" type = "text/javascript" charset = "utf-8" > < / script >
<!-- Custom JS scripts -->
< script type = "text/javascript" >
window.addEventListener('load', function() {
window.setTimeout(window.print, 100);
});
< / script >
< / body >
< / html >
