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 [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
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
[Baldwin09] |
Alan Baldwin. ASxxxx Cross Assemblers. Kent State University, Kent, Ohio. (2009). https://shop-pdp.kent.edu/ashtml/asxxxx.htm |
Download
You can download ZIP-files of the Windows binary plus documentation and the complete installation with TeX and C source files.