Gameboy Advance coding tutorial
Version 1.00 - 20th March 2003
|Although a lot of time has gone into writing this document, Hodglim (Darren Hodges) holds no responsibility for the accuracy or effects of using this document. Any person using the information contained within this file do so at their own risk.|
Welcome to the first in a series of tutorials on programming the Gameboy Advance (GBA). The GBA is a fantastic console and you are going to find that it's also great fun to develop for. When developing software for the GBA you have the option of either using Assembly or C/C++. In this series of tutorials I am going to be focusing on C and hope to build up a library of reusable code that you can go on to use in any future GBA project.
This first tutorial will get you acquainted with the GBA hardware itself and tell you what you will need to get your development environment set up. At the end of the tutorial we will test that you have your development environment successfully set up by trying to compile some code.
If you have any questions or comments regarding this tutorial I would love to hear from you.
|About the GBA hardware|
Before you get your hands dirty with some code it is vital that you understand the platform that you will be developing for. Don't worry if some of these details make no sense to you at the moment, it should all become a lot clearer when you start coding.
I have provided a link to a fantastic GBA hardware specification in the Links section of this tutorial but here is a quick overview to get you up to speed quickly:
|Tools of the trade|
Okay, now that you have a better understanding of what's inside the console you need to get the tools together that will be needed to create your GBA demos and games.
The first thing you will need is a text editor for editing your source code. There is not much to say about text editors really, some people prefer to use Notepad that comes with Windows but I prefer to use an editor called UltraEdit as it has many useful features including syntax highlighting. Feel free to use whichever editor takes your fancy.
Obviously the next thing that you are going to need is a compiler that will turn your source code into something that will run on the GBA. Personally I use the freely available DevKit Advance so that is what we will be using in these tutorials :) DevKit Advance is an open source development kit based on GCC (GNU Compiler Collection).
DevKit Advance is made up of several packages that you will need to download from the DevKit Advance web site. Here is a brief description of each of the packages available:agb-win-core-r5.zip
This is the core of the compiler. R5 refers to the release number of this package, release 5 was the current release at the time of this tutorial.
This package contains the binaries required for assembly and linking.
This is the C compiler that will turn your beautifully crafted source code into GBA executables.
The standard libraries are contained in this package. The standard libraries contain many useful functions including those for memory allocation, string handling and maths. Definitely a recommended download.
You will only need this package if you are planning on programming in C++. These tutorials will be sticking to C so it wont be needed.
This package contains some file updates for DevKit Advance so I would highly recommend getting this.
This tool flips the interwork bit in ARM ELF object files. It will hush interwork mismatch warnings by setting the interwork bit on binary files objcopied to object files ... err just grab it :)
You will only need this package if you are planning on developing a new feature to add to DevKit Advance.
Insight is an excellent free graphical user interface for GDB (the debugger that comes with GCC). I will not be covering the use of the debugger in these tutorials but I just wanted to point out the availability of this tool as you will find it invaluable during your debugging sessions when you start putting together more complex code.
So that you can test your creations you will find that a GBA emulator is an invaluable addition to your development environment. An emulator allows you to run GBA software on your PC.
There are quite a few GBA emulators available but I find that the fastest and most accurate is VisualBoy Advance. Another good emulator is BoycottAdvance that also has a Java version available so you can embed your GBA creations right into a web page!, very impressive.
If you want to be able to test your work on a real Gameboy Advance you will need a piece of hardware that will allow you to write your own GBA carts, for example a Flash Linker. Basically you connect the Flash Linker to your PC, insert a Flash Cart into the Linker and then write your masterpiece to the cart ready to be inserted into your GBA. A good supplier for this kind of kit for those in the UK is CDWorld.co.uk.
Obviously this hardware is not mandatory for GBA development as you can always test your stuff on an emulator, but it really is quite a buzz when you get to see your hard work running on the real thing. It is also extremely useful to test your gfx out on the real hardware because what might appear bright and clear on your PC monitor might be barely visible on the GBA screen. If you are serious about developing GBA software and you can afford it, I would highly recommend getting yourself a Linker.
|Setting up your environment|
Assuming that you have your favourite text editor set up and ready to go, the next thing that you will need to do is download the DevKit Advance files (see above). Each file has been packaged in a zip file so you will also need some software to extract them, for example WinZip.
I would recommend extracting the files in the following way:
1) Extract the following files directly onto your route drive (eg. c:\ ) , a folder called devkitadv will be created automatically for you and the development kit files will be placed within it.
2) Finally extract the interflip.zip file into c:\devkitadv\bin
Now that you have your editor and compiler set up you should get your emulator installed if you have not already done so. How you install this depends on the emulator you have chosen to use. VisualBoy Advance is provided in a zip file so you just need to extract the installation file to the location of your choice.
The next thing that you should do is create a folder to contain your GBA projects, for these tutorials I am going to create a folder on the C drive called gbatuts (c:\gbatuts) , you don't have to use the same folder name and location but if you do decide to put the files somewhere else you will need to make a small path update in the make files we will be using in future tutorials.
The final step that you will need to perform in setting up your development environment is to add the path to the DevKit Advance executables (c:\devkitadv\bin) to your system's path environment variable. Basically this lets your system know where the files are located that it needs to use when compiling your projects. If you are unsure how to set up the environment variables on your system you can simply type:
into a command prompt window before you try compiling anything. This path setting will temporarily remain in effect for that session, until you close that command prompt window. You could also add the above line into a batch file that you could run at the beginning of each GBA coding session.
|Testing your environment|
Phew, after that lot you should now have your GBA development environment installed and configured. I am sure that you are probably now itching to get onto some coding but I am afraid that we are not going to get started on coding our GBA library until the next part of this tutorial where we start looking at the GBA display. All that is left for us to do in this first tutorial in the series is to test that our development environment is properly set up. I have put together a very simple piece of code that does absolutely nothing, but what it will do if you can get it to compile correctly is prove that you have done everything above correctly :)
Download the tutorial1.zip file and extract it into your GBA projects folder (c:\gbatuts). It will create a new folder in this projects folder called tutorial1 that contains a source file and a batch file that will attempt to compile the source file when run.
Once you have extracted the tutorial1.zip file you will need to bring up a command prompt window and change to the tutorial1 directory, for example type:
Now run the make.bat file by typing make. If you find that when you run the make.bat file you get some error messages like 'gcc' is not recognized as an internal or external command, it means that your system doesn't know where the DevKit Advance files it needs to compile the source code are to be found. You need to check that you have set up your path environment variable correctly, see the section above for configuring this correctly.
If all goes well you should get no error messages and you will be left with 2 new files in your project folder, tutorial1.elf and tutorial1.gba.
tutorial1.gba is your compiled code ready to be loaded up in your emulator or written to a cart for testing on your GBA. Of course as I mentioned earlier it does a whole lot of nothing and so don't expect exciting results, in fact you will probably just be presented with an exciting white screen but, we are now ready to get onto the fun stuff :)
I hope that you found this first tutorial useful!, you should now be set up with a fully functional GBA development environment and ready to start putting together our GBA code library. In the next part things will get a bit more exciting as we cover the different display modes available on the GBA and put some code together to get something up on the screen.
|Files to download|