Gameboy Advance coding tutorial

By Hodglim

Version 1.00 - 20th March 2003

Disclaimer
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.
Contents
Introduction

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:

  • The GBA contains a 32-bit ARM7TDMI RISC CPU that runs at 16.78MHz and an 8-bit CISC CPU for backwards compatibility with Gameboy/Gameboy Color software.
  • The CPU can access internal ram 32bits at a time.
  • External RAM (Random Access Memory) and ROM (Read Only Memory) and VRAM (Video RAM) can only be accessed 16 bits at a time.
  • The GBA has 32kb of internal RAM, 256kb of external RAM and 96kb of VRAM.
  • The GBA also contains a graphics processor that accelerates many of the 2D processes, freeing up the CPU for other tasks.
  • The screen is a 2.9inch TFT colour screen and has a maximum screen resolution of 240x160 pixels. The screen can handle up to 511 simultaneous colours in character mode and 32,768 colours in bitmap mode (I will be explaining the different display modes in more detail in the next tutorial).
  • Special effects include rotation/scaling, alpha-blending, screen fading and mosaic. Again these will be explained in future tutorials as we use them.
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.

Text Editor

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.

Compiler

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.

agb-win-binutils-r4.zip

This package contains the binaries required for assembly and linking.

agb-win-gcc-r4.zip

This is the C compiler that will turn your beautifully crafted source code into GBA executables.

agb-win-newlib-r4.zip

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.

agb-win-libstdcpp-r4.zip

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.

agb-win-patch-r4.zip

This package contains some file updates for DevKit Advance so I would highly recommend getting this.

interflip.zip

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 :)

agb-source-r4.zip

You will only need this package if you are planning on developing a new feature to add to DevKit Advance.

Debugging

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.

GBA Emulator

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.

Hardware

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.

agb-win-core-r5.zip
agb-win-binutils-r4.zip
agb-win-gcc-r4.zip
agb-win-newlib-r4.zip
agb-win-patch-r4.zip

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:

set path=%path%;c:\devkitadv\bin

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:

cd c:\gbatuts\tutorial1

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 :)

What's next

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
Links