This page covers release 3.0 of the english software development kit, but the other versions are very similar to this. It is unclear if this was the last release of the development kit.
In the documentation Nintendo calls this SDK the GameBoy Advance Developers Kit 2000 presumably due to using the millennium/2000 was very trendy at the time.
This was distributed to developers as a windows installer called AGBSetup.exe which would by default install it into a folder called /agb for Advanced Game Boy, so when upgrading the SDK it tells developers to delete the contents of the /agb directory before updating.
As Nintendo is a Japanese company the SDK was originally created in Japanese and localised to English, however there are a few differences between the development kits.
The Japanese version include the Mobile System GB SDK which was a Japanese only accessory to link gameboys together via a mobile phone interface.
This folder contains useful command lines tools for GBA development compiled for Microsoft Windows.
|AGBLOAD||.exe||Tool to load ROM into the IS-AGB-EMULATOR hardware|
|NRDC||.exe||Calculates the CRC checksum for a GBA ROM (for more info see AGB_CRC.txt in /docs)|
|act2agb||.exe||Converts an Adobe Photoshop .ACT (Adobe Color Table) file to a GBA pallete in C source code form|
|agbcomp||.exe||Compresses binary data using either LZ77 or Huffman encoding|
|agbparts||.exe||Converts a bitmap image into 8x8 pixel parts useful for an optimized tileset or even sprites|
|bin2h||.exe||generates a C header file from the Binary result of objcopy|
|bmp2agb||.exe||Converts BMP images to either binary or text with optional compression|
|bmp2bin||.exe||Converts BMP files to binary formats .imb (Image Binary) and .plb (Palette Binary)|
|bmp2map||.exe||Converts BMP files to C-source code based on 8x8 pixel tiles|
|bmpgrid||.exe||Splits up a Bitmap into tiles/partitions based on input width/height (minimum 8x8)|
|bmpred||.exe, .sh||Reduces the colors of a BMP image using a specified palette|
|sgi2bmp||.exe||Converts an SGI format image into a BMP format image|
This folder contains all the documentation provides for the various tools and libraries provided in the Game Boy Advance SDK.
|AGB_CRC||.txt||Describes usage of the tool nrdc.exe for calculating the CRC checksum for a GBA ROM|
|CompilerBugFix||.txt||This text file lists the differences in a patch applied to the cygwin toolchain (for 000512 -> 000513) (2001/2/6)|
|relnotes_rel3||.txt||List of changes in version 3.0 of the SDK|
|relnotes_us||.txt||Notes the differences between the English US SDK and the Japanese version|
|toolsSetup||.txt||Instructions for installing the SDK and connecting to the development kit hardware|
The AGB programming manual is available in both PDF format (AGBProgramming Manual.PDF) and HTML format (/AllManual/program).
It is 163 pages explaining pretty much everything you need to know to start programming for the GBA hardware:
The AGB Backup Library manual is available in both PDF format (AGBBackupLibraryManual.PDF) and HTML format (/AllManual/backup) and covers the Save RAM (SRAM) available built in to certain cartridges.
This documents the use of the libagbbackup.a static library which MUST be used to communicate with the different Save Game Backup chips on the cartridge, as Nintendo forbids not using this library to access the data (presumably for Save Game Safety).
The available SRAM chips on the GBA cartridges were:
They had also planned support for 1Mbit DACS but this was never released.
Each type of backup chip had its own set of functions and their own header files as listed below:
The difference between the two header files comes down to memory vs cpu optimization, the Fast version is more efficient on the CPU but uses 300 extra bytes of Work RAM (WRAM). Apart from the difference in memory usage they are identical.
The AGB System Call Reference manual is available in both PDF format (AGB System Call Reference.PDF) and HTML format (/AllManual/syscall).
This is a 35 page document listing all of the system calls available from the Syscall (libagbsyscall) library to use in your application, such as functions like BgAffineSet or CpuFastSet. it is standard API documentation giving an explanation all the parameters and return type and a little about what the functions achieve.
The AGB Register List is available in both PDF format (AGBRegList.PDF) and HTML format (/AllManual/register). It contains a large table of all the addresses of hardware registers, their names and what each bit does.
This is an extremely helpful document when reverse engineering GBA games as games will often need to read or right to these registers to access the hardware features of the device.
These hardware Registers are used for many things including:
The AGB programming manual is available in both PDF format (AGBDataFormat.PDF) and HTML format (/AllManual/dataformat) and contains the format that data should be in for certain parts of memory, especially related to graphics.
There are a few areas of memory that need to be in a specific format:
If you are creating a GBA game you need to follow these Data Formats otherwise the screen will look corrupt, most emulators will be able to help you out with their VRAM viewer windows.
The ARM7TDMI Reference Manual is a PDF specification (/AllManual/arm/ARM7TDMI_Ref_man.pdf) provided by ARM that has 275 pages of pretty much everything you would ever want to know about the CPU used in the Game Boy Advance.
As this is a reference I wouldn’t recommend reading it and instead just refer to it if you are looking into how a particular feature of the CPU works. You can reverse and create games without ever having opened this manual but when anytime you wonder about the Coprocessor or assembly instruction timings then this is a great reference.
The AGB IR Communication Library manual is available in both PDF format (AGBIRCommLibraryMan1.0.PDF) and HTML format (/AllManual/ir) and covers the very low level technology details of how the IR interface works at the hardware level.
For using the IR communication library in a game see the AGB Infrared Comm Programming Guide instead.
The AGB Infrared Communication Programming guide is available in both PDF format (AGBInfraredCommProgGuide.PDF) and HTML format (/AllManual/ir) and covers programming for use with the Infrared Adapter.
The GBA Infrared Adapter (AGB-006) was an accessory that was released 2 years after the GBA and only ever used in 1 Japanese game called Cyber Drive Zoids.
As the hardware is now quite rare and it was only ever used for one game this documentation will most likely not be useful to anyone reverse engineering or creating a new GBA game.
However Shonumi has written an excellent Edge of Emulation article on implementing an emulated version of the Infrared adaptor and even created a virtual Zoid (Robot):
This folder contains Frequently asked questions in HTML format for Game Boy Advance Development split into the following categories:
This folder contains HTML documentation provided by Cygnus for their GNUPro Toolkit product which was a suite of compilers based on GCC but with official support from Cygnus (later RedHat) for compiling to ARM assembly.
This is the same as any GCC documentation you can find freely on the web and is not customized to the GBA so it will not be covered here.
This folder contains the exact same files as the include directory but with a .TXT extension, this was provided just so the developer could access the files easily in their web browser when the have the documentation pages loaded up.
This is not particularly useful as most IDEs nowadays provide easy ways to check on the source code for the include files without leaving the editor.
This folder contains documentation for the MusicPlayerAGB2000 library, it is split into two different files, one for each of the different types of users:
The Sound developer’s Manual is HTML-based documentation found in the /AllManual/musicplayer/sound_dev folder and is tailored towards the sound engineer.
The documentation for the Sound and Music library is covered in its own post specifically for this functionality, it is recommended you read it here:
This folder contains the following subsections:
This folder contains documentation for the demo Dolphin game included in the /src folder and even includes UML-like Flow diagrams for the main game logic!
This folder contains documentation for the Yoshi Demo project including the basics of how to play and the technology involved in its creation.
This folder contains basic documentation for each of the samples provided in the /src directory that show off certain graphical features of the GBA hardware.
|alphasm||.htm||Alpha Blending demo code|
|bg_rsm||.htm||Background demo code showing rotating, scaling and moving backgrounds|
|bmpmode||.htm||Background Bitmap mode example code|
|coleffsm||.htm||Special Color effects sample code|
|obj_rsm||.htm||Object (Sprite) demo code showing rotating, scaling and moving sprites|
|swinsm||.htm||Example code showing off the different Window modes|
This folder contains both C header include files (.h) and assembly headers (.s) that declare all the functions and macros used in the GBA SDK libraries.
|Agb||.h||Include file for importing all the common header files such as AgbTypes.h|
|AgbDefine||.h, .s||Include file for declaring common macros such as LCD_WIDTH|
|AgbDefineArm||.s||Assembly include file for declaring common macros such as SYSTEM_CLOCK|
|AgbIr||.h||Include file for declaring the functions in the Infrared Communication library|
|AgbMultiBoot||.h||Include file for declaring the types used for the Multi-player download functionality with one cartridge|
|AgbSound||.h||Include file for declaring|
|AgbSystemCall||.h||Include file for declaring|
|AgbTypes||.h||Include file for declaring|
|IsAgbPrint||.h||Include file for declaring the functions in the Debug Print to terminal library|
This folder contains all the C include files for accessing Save Data on the cartridge for all the supported types of Backup chip (Flash/SRAM/EEPROM)
|AgbDacs||.h||Include file for declaring the unused DACS reading/writing functions such as ReadDacs|
|AgbEeprom||.h||Include file for declaring EEPROM reading/writing functions such as ReadEepromDword|
|AgbFlash||.h||Include file for declaring FLASH chip reading/writing functions such as EraseFlashSector|
|AgbSram||.h||Include file for declaring the slower (but uses less WRAM) SRAM reading/writing functions such as ReadSram|
|AgbSramFast||.h||Include file for declaring the faster (but more memory intensive) SRAM reading/writing functions such as ReadSramFast|
This folder contains all the libraries that a developer can link into their GBA game, they contains some useful functions for using system calls, game saves and IR communication. There are two types of library in this folder *.a and *.alf.
The libraries included are as follows:
The source folder contains all the C and assembly source code for:
The GBA SDK comes with source code for 2 demo games:
For more details on the two demos we have a separate post covering the details:
The Assembly source code for the SysCall library is available in the src/lib/syscall folder of the GBA SDK and is available in two different formats:
The source code is not particularly interesting as all it does is act as a wrapper around the 42 GBA Software Interrupts which you can find a full list of here: Tonc: Software Interrupts
They all follow the same format so here is an example:
@******************************************************************** @* AgbSysArcTan.s * @* AGB System Call Functions (for GAS) * @* * @* Copyright (C) 1999-2000 NINTENDO Co.,Ltd. * @******************************************************************** .INCLUDE "AgbDefine.s" .INCLUDE "AgbMemoryMap.s" .TEXT .CODE 16 @-------------------------------------------------------------------- @- Arc Tangent - @-------------------------------------------------------------------- .GLOBAL ArcTan .THUMB_FUNC ArcTan: swi 9 // This calls software interupt number 9 bx lr // return and switch instruction set to THUMB if Least Significant Bit is 1 otherwise switch to ARM .END
The SDK also comes with 13 sample projects, each showing off a different feature of the GBA hardware, this section would be huge if we went into detail on this page, so we have split it out into its own page.
The Tool Source Code folder holds the source code for most of the standard GBA development tools that deal with image conversion, the pre-compiled tools are available in the /bin directory.
If you are interested in going in depth into the source code for how these tools works then we have a separate post covering just that:
The compilers provided for the GBA were a modified version of GNU GCC distributed by Cygnus Solutions (Cygwin) for the ARM architecture. They provided an installed called AGBSetup2.exe on the AGB Developers ToolKit CD which installed the programs to C:\Program files\cygnus.
The version of GCC shipped with the SDK is 2.95.1 which is handy to know when decompiling the games back to C source code, about 90% of games were compiled with this version including the Pokemon series of games.
There is a RAR file called gba_compilers.rar that is an archive that contains the following files inside it:
In the leaked version there is also a armelf-000512 folder which is not the contents of armelf-000512.zip but it looks like it is the GNU source code for the tools provided in that zip.