Latest revision as of 02:44, 7 December 2022

The Game Boy Development Kit (often referred to as GBDK) is a suite of tools that allows users to program for the Nintendo Game Boy platform in C and GB-Z80 Assembly.

GBDK-2020 (3.x and later): In 2020 a forked version with many improvements called GBDK-2020 was released. It fixed long standing bugs and used a modernized SDCC release which generates more efficient code. Since then new versions have continued to be released.

Original GBDK (through 2.x): The original GBDK was created by Pascal Felber, Lars Malmborg, John Fuge, David Galloway, Michael Hope, Sandeep Dutta, and Daniel Rammelt. It ceased to be updated in 2002 after GBDK-v2.96a was released. The website for the original version is: GBDK Homepage

Distribution

GBDK-2020 (3.x and later): GBDK-2020 releases are available at the project's Github page in source and binary formats.

• Source and binary releases are available for:
  • Linux
  • Windows
  • macOS

Original GBDK (through 2.x): Versions of the old GBDK remain available on it's SourceForge download page in both source code and binary formats for the x86 platform.

• Linux (Binaries and source compiling)
• Windows (Binaries)
• macOS - a semi-working private alpha has been created by davisr. Direct link [1]

GBDK-2020

For documentation and support with GBDK-2020, the following links are recommended:

• Main docs page
• Getting Started
• Toolchain
• Frequently Asked Questions
• Using GBDK-2020
• Migrating to new versions (including from the original GBDK 2.x releases)

Historical Information about the original GBDK (through 2.x)

Compiler, assembler, linker and libs: GBDK

The information in this section is taken from the GBDK SourceForge page.

The Compiler

The GBDK's lcc compiler is based on lcc, a retargetable compiler for ANSI C. The compiler turns C source code into code for the GB-Z80. The compiler defines the following sizes for basic types:

Since the CPU is an 8-bit processor, working with int values is much more efficient than working with long values. However, overflows still need to be handled carefully.

When generating a Game Boy image, the linker will look for undefined symbols in each of the object files listed in the lib/gb.lib text file. If one of these object files contains the symbol, it will be linked with the main program. If none of these object files contain the symbol, the linker will generate an error. Therefore, there is no need to explicitly link the main program with the standard libraries.

Examples of lcc usage

• Compile a C source file (source.c) and generate a Game Boy image (image.gb):

 lcc -o image.gb source.c

• Assemble an assembly source file (source.s) and generate a Game Boy image (image.gb):

 lcc -o image.gb source.s

• Compile a C source file (source.c) and generate an object file (object.o):

 lcc -c -o object.o source.c

• Assemble an assembly source file (source.s) and generate an object file (object.o):

 lcc -c -o object.o source.s

• Link two object files (object1.o and object2.o) and generate a Game Boy image (image.gb):

 lcc -o image.gb object1.o object2.o

• Generate a Game Boy image (image.gb) from an assembly source file (source.s), a C source file (source.c), and an object file (object.o):

 lcc -o image.gb source.s source.c object.o

The following flags allow to pass options to the preprocessor, the compiler, the assembler, and the linker:

 -Wp
 -Wf
 -Wa
 -Wl

A typical usage of these flags is for generating listing and map files:

• A listing file is produced by the assembler if you use the -Wa-l flag. The name of this file is the same as the object file, with the .lst extension. It contains the assembly code and source. If the assembler generates error messages, listing files are necessary for locating these errors.
• A map file is produced by the linker if you use the -Wl-m flag. The name of this file is the same as the image file, with the .map extension. It contains informations about where functions and variables are located in ROM. If the linker generates error messages, map files are useful for locating these errors.
• A symbol file for the no$gmb emulator is produced by the linker if you use the -Wl-j flag. The name of this file is the same as the image file, with the .sym extension. It contains informations that can be used by the no$gmb built-in debugger.

It is generally a good habit to generate listing and map files.

The Assembler

The assembler is based on ASxxxx Cross Assemblers.

The Game Boy processor is very similar to the Z80, although some of the instructions are missing, more were added by Nintendo. Also, the second set of registers (BC', DE', HL', AF') and the index registers (IX, IY) are missing and, consequently, there are no DD and FD opcode tables. Finally, I/O ports are gone and so are all IN/OUT opcodes. for a descriptions of the changed instructions, read the Game Boy FAQ(link).

The names of some Game Boy specific opcodes have been modified, as seen below.

 LD (HLI),A        >    LD (HL+),A
 LD (HLD),A        >    LD (HL-),A
 LD A,(HLI)        >    LD A,(HL+)
 LD A,(HLD)        >    LD A,(HL-)
 ADD SP,OFFSET     >    LDA SP,OFFSET(SP)
 LDHL SP,OFFSET    >    LDA HL,OFFSET(SP)

The LDA opcode means "load address", like in 68x00 assembly. These instructions are called like this because both are orthogonal (they do the same thing on two different registers).

The assembler accepts the following flags:

 ASxxxx Assembler V01.75 (GameBoy Z80-like CPU)
 
 Usage: [-dqxgalopsf] outfile file1 [file2 file3 ...]
   d   decimal listing
   q   octal listing
   x   hex listing (default)
   g   undefined symbols made global
   l   create list outut outfile[LST]
   o   create object output outfile[o]
   s   create symbol output outfile[SYM]
   p   disable listing pagination
   f   flag relocatable references by ' in listing file
   ff  flag relocatable references by mode in listing file

The Linker

The linker is based on ASxxxx Cross Assemblers. It has been extended in particular to support generation of Game Boy images.

The linker accepts the following flags:

 ASxxxx Linker V01.75
 
 Startup:
   --   [Commands]              Non-interactive command line input
   -c                           Command line input
   -f   file[LNK]               File input
   -p   Prompt and echo of file[LNK] to stdout (default)
   -n   No echo of file[LNK] to stdout
 Usage: [-Options] outfile file [file ...]
 Libraries:
   -k    Library path specification, one per -k
   -l    Library file specification, one per -l
 Relocation:
   -b   area base address = expression
   -g   global symbol = expression
   -yo  Number of rom banks (default: 2)
   -ya  Number of ram banks (default: 0)
   -yt  MBC type (default: no MBC)
   -yn  Name of program (default: name of output file)
   -yp# Patch one byte in the output GB file (# is: addr=byte)
 Map format:
   -m   Map output generated as file[MAP]
   -j   no$gmb symbol file generated as file[SYM]
   -x   Hexadecimal (default)
   -d   Decimal
   -q   Octal
 Output:
   -i   Intel Hex as file[IHX]
   -s   Motorola S19 as file[S19]
   -z   Game Boy image as file[GB]
 List:
   -u    Update listing file(s) with link data as file(s)[.RST]
 End:
   -e   or null line terminates input

The include files and libraries

Several include files are part of the GBDK. Some of them only define useful macros (with no code associated), while others define functions implemented in separate object modules. The libraries are split in several small object files in order to reduce the size of the final image file (only the required modules are linked with the main program). The include files and libraries are divided in the following groups.

Runtime support

The crt0.o object module contains the basic C runtime library, with Game Boy initialization routines, C support, and other essential things. This library is required and automatically linked with every program.

The gb/gb.h include file defines basic Game Boy related macros and functions. It also includes the hardware.h file that defines Game Boy hardware registers.

Standard C libraries

The ctype.h, stdarg.h, stdlib.h, and types.h include files define some functions found in the standard C libraries.

Console I/O

Basic console I/O is provided through a set of functions defined in the console.h and stdio.h include files. note that console I/O uses most of the tiles and sprites of the Game Boy, and thus is not easily mixable with graphics programs.

Simple graphic library

Simple graphic functions for drawing points and images on the screen are defined in the drawing.h include file. Note that the graphic library uses most of the tiles and sprites of the Game Boy.

Misc libraries

The rand.h include file defines functions for using the GBDK random generator.

See also

• SDCC output samples