Revised ASXXX Linker for SDCC
(Version 0.5)

1 Introduction

Overview

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:

Library File Options:

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

Output Format Options:

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

Map and List File Options:

Specific Options for Z80/GBZ80 Platform

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:

• Absolute areas (ABS) have a specific address either assembled in or given by the -b option on the linker command line. They are always put to the address given and are not relocated.

• Relative areas (REL) have a base address of 0x0000 assembled in. The real start address is either given by a -b option on the linker command line or is defined for the platform.

  All subsequent relative areas are concatenated to proceeding relative areas in an order defined by the first linker input file.

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:

• A linking map file provides detailed information about symbol addresses, areas, modules, libraries and errors during linking.
• The updated listing files are generated from original assembler listings (.lst-files). For each of those files a companion file is produced which has all addresses and data relocated to their final values.

Full Documentation as PDF

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

References

Download

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