Compiler, assembler, linker and libs: GBDK

The Compiler

The compiler is based on lcc, a free of charge retargetable compiler for ANSI/ISO C. GBDK includes a code generator for lcc that generates code for the GameBoy custom Z80. For an ehaustive description, read the man page included with the lcc distribution.

The compiler defines the following sizes for basic types:

type size min max
char 1 byte -128 127
unsigned char 1 byte 0 255
int 1 byte -128 127
unsigned int 1 byte 0 255
long 2 byte -32768 32767
unsigned long 2 byte 0 65535
long long 4 byte -2147483648 2147483647
unsigned long long 4 byte 0 4294967296
float 4 byte n/a n/a
double 4 byte n/a n/a
pointer 2 byte n/a n/a

Since the CPU is an 8-bit processor, working with int values is much more efficient than working with long values. But you have to be careful with overflows.

When generating a GameBoy 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 explicitely link the main program with the standard libraries.

Here are some examples of lcc usage:

    lcc -o source.c
    lcc -o source.s
    lcc -c -o object.o source.c
    lcc -c -o object.o source.s
    lcc -o object1.o object2.o
    lcc -o source.s source.c object.o

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


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

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

The Assembler

The assembler is based on ASxxxx Cross Assemblers.

The GameBoy processor is very similar to the Z80, although some of the instructions are missing and some ther have been added. Also, she 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 GameBoy FAQ.

I have modified the name of some of the GB-specific opcodes:

    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. I've called these instructions 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
  a    all user symbols made global
  l    create list   output 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

For an ehaustive description, read the asmlnk.doc file in the doc directory, or this html-ized document.

The Linker

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

The linker accepts the following flags:

ASxxxx Linker V01.75
  --   [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 ...]
  -k    Library path specification, one per -k
  -l    Library file specification, one per -l
  -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   Hexidecimal (default)
  -d   Decimal
  -q   Octal
  -i   Intel Hex as file[IHX]
  -s   Motorola S19 as file[S19]
  -z   Gameboy image as file[GB]
  -u    Update listing file(s) with link data as file(s)[.RST]
  -e   or null line terminates input

For an ehaustive description, read the asmlnk.doc file in the doc directory, or this html-ized document.

The Include Files and Libraries

Several include files are part of 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 GameBoy initialization routines, C support and other essential things. This library is required and automatically linked with every program.

The gb.h include file defines basic GameBoy-related macros and functions. It also includes the hardware.h file that defines GameBoy hardware registers.

Standard C libraries

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

Console Input/Output

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 GameBoy, 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 GameBoy.

Misc Libraries

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

Michael Hope
Last modified: Tue May 18 13:29:04 NZST 1999