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:
source.c) and generate a GameBoy image (image.gb):
lcc -o image.gb source.c
source.s) and generate a GameBoy image (image.gb):
lcc -o image.gb source.s
source.c) and generate an object file (object.o):
lcc -c -o object.o source.c
source.s) and generate an object file (object.o):
lcc -c -o object.o source.s
object1.o and object2.o) and generate a GameBoy image (image.gb):
lcc -o image.gb object1.o object2.o
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 useage of these flags is for generating listing and map files:
-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.
-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.
-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 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 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 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 Hexidecimal (default) -d Decimal -q Octal Output: -i Intel Hex as file[IHX] -s Motorola S19 as file[S19] -z Gameboy image as file[GB] List: -u Update listing file(s) with link data as file(s)[.RST] End: -e or null line terminates input
For an ehaustive description, read the asmlnk.doc file in the doc
directory, or this html-ized document.
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:
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.
The ctype.h, stdarg.h, stdlib.h, string.h, and types.h include files define some functions found in the standard C libraries.
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 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.
The rand.h include file defines functions for using the GBDK random generator.