Dr. Thomas Tensi Paganinistraße 60
D-81247 München

Revised ASXXX Linker for SDCC
(Version 0.5)

1 Introduction


The revised ASXXX linker program is a completely renovated version of the linker from the 8-bit-assembler suite ASXXX from Alan Baldwin for the compiler SDCC. Parts of this documentation are based on his suite documentation now hosted by gorlik on GitHub [Baldwin09].

The main idea was to modularize the program towards a plugin-architecture. All target platforms supported provide several routines which are called by the linking framework. Platform specific code should only go into those modules; platform-independent code should go into the general framework.

Apart from some syntactical improvements and data structure enhancements the main contribution of this linker is the support for bankswitching at link time. The SDCC compiler has provided bankswitching support for several platforms at compile time, but this proves to be too unflexible in practice. Take a library module for example: it may go to several banks depending on the bank layout of the calling program.

The renovated linker uses a configuration file which tells the bank number for each module. The linker puts the modules in the appropriate banks and also takes care that interbank calls are correctly handled.

2 Usage

The linker is a command line program with the following syntax and options:

        aslink [-i] [-s] [-m] [-u] [-x] [-d] [-q] [-b area = value]
[-g symbol = value] [-k path] [-l file]
file ...

2.1 Platform Independent Options

The following options are supported:

files to be linked

General Options:

-b area = expression specifies an area base address via an expression which may contain constants and/or defined symbols from the linked files (not yet supported)
-g symbol = expression specifies value for the symbol via an expression which may contain constants and/or defined symbols from the linked files

Library File Options:

-k path specifies a library directory prefix path; this will later be combined with a relative library path to find complete library path names
-l file specifies the relative or complete path of a library file; when a relative path is given, the absolute path is found by combination with some library directory prefix path

Note that more than one path and also multiple library files are allowed.

Output Format Options:

-i linker output is in Intel hex format (to file.ihx)
-s linker output is in Motorola S19 format (to file.s19)

Note that output format options are cumulative; it is possible to have the output in more than one format.

Map and List File Options:

-m generate a map file into file.map containing a list of symbols (grouped by area) with relocated addresses, sizes of linked areas, and other linking data
-u update all available listing files file.lst into file.rst by replacing relocatable bytes by their correct absolute values
-x use a hexadecimal number radix for the map file
-d use a decimal number radix for the map file
-q use an octal number radix for the map file

Specific Options for Z80/GBZ80 Platform

-j generate a map file into file.sym in a form suitable for the debugger within the NO\$GMB Gameboy emulator
-yo number set count of ROM banks to number (default is 2)
-ya number set count of RAM banks to number (default is 0)
-yt number set cartridge MBC type to number (default is no MBC)
-yn name set name of program to name (default is the name of output file truncated to eight characters)
-yp addr = byte set byte in the output executable file at address addr to byte
-z produce a Gameboy image as file (with extension .gb)

3 Processing

The linker gathers all command line files and processes them in the order presented in two passes.

In the first pass all modules, areas and symbols definitions and references are collected. For each referenced but undefined symbol all library files are searched and — when they contain such a symbol — are added to the object file list. This process continues until no more references can be satisfied. The library files are found by doing a combination of prefix paths and relative paths of the library files.

Finally area and symbol address definitions from the commandline are added to the internal symbol table.

When banking is used another step has to happen in pass 1: the banking module of the linker checks for interbank calls. Those interbank calls go from code in one bank to code in another parallel bank. Those calls cannot happen directly, because during the call the banks have to be switched and also the bank switch upon return from the callee has to be organized. For those interbank calls the linker introduces trampoline code which does the above steps. Because banking also needs library modules another search of the libraries has to be done.

Note that at the end of the first pass it is clear what object files and libraries are needed for the executable and which symbols are available. It is not yet clear where the areas and symbols are located.

In the second pass all areas are located in the address space. This location is done based on the area type which is one of ABS, CON, REL, OVR or PAG as follows:

When all areas have been located, their addresses and those of the contained symbols have been completely defined.

Several checks are done for sanity of the output executable: The linker e.g. checks whether paged areas (type PAG) are on a 256 byte boundary and have a length less than or equal to 256 bytes. Also referenced but undefined symbols or inconsistent constants’ definitions are reported.

As the main result of linking the output executable is now generated. The executable format is either one of the standard formats HEX or S-records or even a platform-specific format (like the Gameboy load format). The linker can even produce several output formats in parallel.

In addition to the output executables, two more kinds of output can be produced:

Full Documentation as PDF

You can find the full documentation of the Revised SDCC-Linker as a PDF here.


[Baldwin09]  Alan Baldwin.
ASxxxx Cross Assemblers.
Kent State University, Kent, Ohio. (2009).


You can download ZIP-files of the Windows binary plus documentation and the complete installation with TeX and C source files.