The ARM Linker
armlink
SYNOPSIS
armlink [options] file ...
DESCRIPTION
The purpose of the ARM Linker is to combine the contents
of one or more object files (the output of a compiler or
assembler) with selected parts of one or more object
libraries, to produce an executable program. The ARM
linker, armlink, accepts as input:
o one or more separately compiled or assembled object
files written in ARM Object Format (see section"ARM
Object Format" of the Reference Manual for a synopsis,
and chapter "ARM Object Format" starting on page18 of
the Technical Specifications for full details);
o optionally, one or more object libraries in ARM Object
Library Format (see chapter "ARM Object Library For-
mat" of the Technical Specifications for details).
The ARM linker performs the following functions:
o it resolves symbolic references between object files;
o it extracts from object libraries the object modules
needed to satisfy otherwise unsatisfied symbolic ref-
erences;
o it sorts object fragments (AOF areas) according to
their attributes and names, and consolidates similarly
attributed and named fragments into contiguous chunks.
(See section "Area Placement and Sorting Rules" of the
Reference Manual for details);
o it relocates (possibly partially) relocatable values;
o it generates an output image possibly comprising sev-
eral files (or a partially linked object file
instead).
The ARM linker can produce output in any of the following
formats:
o ARM Object Format (see section "ARM Object Format" of
the Reference Manual for a synopsis, and chapter "ARM
Object Format" of the Technical Specifications for
full details);
o Plain binary format, relocated to a fixed address,
(see section "Plain Binary Format" of the Reference
the Reference Manual for a synopsis, and chapter of
the Technical Specifications for full details);
o Extended Intellec Hex Format, suitable for driving the
Compass integrated circuit design tools, (see section
"Extended Intellec Hex Format (IHF)" of the Reference
Manual for details);
o ARM Shared Library Format: a read-only position-
independent reentrant sharable code segment (or shared
library), written as a plain binary file, together
with a stub containing read-write data, entry veneers,
etc., written in ARM Object Format. (See section "ARM
Shared Library Format" of the Reference Manual for
details);
o ARM Overlay Format: a root segment written in ARM
Image Format, together with a collection of overlay
segments, each written as a plain binary file. (See
section "Overlays" of the Reference Manual for
details). A system of overlays may be static (each
segment bound to a fixed address at link time), or
dynamic (each segment may be relocated when it is
loaded).
OPTIONS
Linker Command Line
If present, input-file-list is a list of one or more
object files and libraries; this is described under "Input
File List". Input files, libraries and linker options may
also be given in a file used as an argument to a -VIA
option (see "General Options" for details of the -VIA
option). This is especially convenient when the input file
list is long.
If an option keyword takes an argument, a space must sepa-
rate the argument from the keyword. Option keywords are
case insensitive. In the remainder of this sectionthe
abbreviations recognised by armlink are shown capitalised.
General Options
-Help Print a screen of help text summarising the
linker's options and exit with a good return code.
-Output name
Name the linker's final output; often, this is the
name of the image file.
-Debug Include ARM Symbolic Debugger tables in the output
image for use by armsd. Debug causes armlink to
include in the output image all high-level debug-
the whole image.
If the output image type is AIF and any input
object file contains high-level debugging data then
-Debug is implied.
-LIST file
Re-direct the standard output stream to file. This
is especially useful in conjunction with -MAP,
-Xref and -Symbols -.
-ERRORS file
Re-direct the standard error stream to file (diag-
nostics will be filed there). This is especially
useful under DOS.
-VIA file
Read a further list of input file names and linker
options from file. There may be no more than 64
words on each line of a VIA file, and an option may
not be split across more than one line. Convention-
ally, each file name and option is given on a sepa-
rate line. There may be multiple -VIA options, and
-VIA options may be nested.
-Verbose
Print messages indicating progress of the link
operation. Giving the option twice makes it even
more verbose (this may be abbreviated to -VV).
-MAP Create a map of the base and size of each area in
the output image. This option is most useful in
conjunction with the -SHL and -OVerlay options. The
map output is produced on the standard output
stream (from where it can be re-directed to a file
using the host's stream re-direction facilities or
the -LIST option).
-Xref List references between input areas (most useful
with the -OVerlay option). The cross-reference list
is produced on the standard output stream (from
where it can be re-directed to a file using the
host's stream re-direction facilities or the -LIST
option).
-Symbols file
List each symbol used in the link step (including
linker-generated symbols) and its value, to file. A
file name of - (minus) names the standard output
stream.
Output Format Options
-AIF Generate an output image in executable ARM Image
Format (the default if no output format option is
given). The default load address for an AIF image
is 0x8000 (32KB). Any other address (greater than
0x80) can be specified by using the -Base option
(see "Special Options"). AIF is described in sec-
tion "ARM Image Format" of the Reference Manual,
and in chapter "ARM Image Format" of the Technical
Specifications.
-AIF -Relocatable
Generate a relocatable AIF image which when entered
self-relocates to its load address.
-AIF -Relocatable -Workspace n
Generate a relocatable AIF image which when entered
copies itself to within n bytes of the top of mem-
ory and self-relocates to that address. For a
description of -Workspace see section "Special
Options").
Some fields of the AIF header and the self-
relocation code generated by armlink can be cus-
tomised by giving your versions in areas called
AIF_HDR and AIF_RELOC, respectively, in the first
object file in the input list. AIF_HDR must be
exactly 128 bytes long (for further details see
"ARM Image Format" starting on page15 of the Refer-
ence Manual).
-AIF -BIN
Generate a plain binary image preceded by an AIF
header which describes it (see the following
descriptions of "-BIN" and "-BIN -AIF" starting on
page22 for further details). The default base
address for images of type -AIF -BIN is 0, but any
other address can be specified by using the -Base
option (see "Special Options").
-AOF Generate partially linked output, in ARM Object
Format (AOF), suitable for inclusion in a subse-
quent link step. AOF is described in section "ARM
Object Format" of the Reference Manual, and in
chapter "ARM Object Format" of the Technical Speci-
fications.
-BIN Generate a plain binary image. The default load
address for a binary image is 0. Any other address
can be specified using the -Base option (see "Spe-
cial Options"). Plain binary images are described
in section " Plain Binary Format" of the Reference
Generate a plain binary image preceded by an AIF
header which describes it. This format is intended
to be consumed by simple program loaders and is the
format of choice for them.
Such an image cannot be executed by loading it at
its load address and entering it at its first word:
the AIF header must be discarded first and the
image must be entered at its entry point. As with a
plain AIF image, the base address, which defaults
to 0, can be set using the -Base option (see sec-
tion "Special Options"). Note that with -BIN -AIF,
the base address is the address of the binary
image, not the address of the AIF header (which is
discarded). A separate base address can be given
for the image's data segment using the -DATA option
(see "Special Options"); otherwise, by default,
data are linked immediately following code. This
option directly supports images with code in ROM
and data in RAM.
-IHF Generate a plain binary image encoded in extended
Intellec Hex Format. The output is ASCII-coded.
-SHL file
Generate a position-independent reentrant read-only
sharable library, suitable for placement in ROM,
together with a non-reentrant stub in ARM Object
Format (in the file named by the -Output keyword)
which can be used in a subsequent client link step.
A description of what is to be exported from the
library is given in file, which also contains the
name of the file to hold the sharable library
image. See section "Describing a Shared Library to
the Linker" of the Refernce Manual for further
details.
-SHL file -REENTrant
As for -SHL, except that a reentrant stub is gener-
ated rather than a non-reentrant stub. A reentrant
stub is required if some other shared library is to
refer to this one (by including the code of the
reentrant stub in it). Dually, a reentrant stub
demands a reentrant client. Usually, a client
application is not reentrant (multi-threadable) so
the default non-reentrant stub is more often use-
ful.
-SPLIT This option tells the linker to output the read-
only and read-write image sections to separate out-
put files. It may be used only in conjunction with
-BIN and -IHF image types, and is meaningful only
-Base base-address" and "-RW-base data-base-address
-DATA data-base-address"). The separate output
files are named as in the following table: center
tab (/); c c s c c c l l l . linker command-line
options/output file names /read-only/read-write -o
file -SPLIT -RO robase -RW rwbase/file.ro/file.rw
-o file -SPLIT -B robase -DATA rwbase/file/file.dat
-OVerlay file
Generate a statically overlaid image, as described
in file. The output is a root AIF image together
with a collection of plain binary overlay segments.
Although the static overlay scheme is independent
of the target system, parts of the overlay manager
are not, and must be re-implemented for each target
environment. See the section "Overlays" of the Ref-
erence Manual for details.
-OVerlay file -Relocatable
Generate a dynamically relocatable overlaid image,
as described in file. The output is a relocatable
AIF root image together with a collection of relo-
catable plain binary overlay segments. Although the
dynamic overlay scheme is independent of the target
system, parts of the overlay manager are not, and
must be re-implemented for each target environment.
See section "Overlays" starting on page25 of the
Reference Manual for details.
The following output options are specific to Acorn
computers running the RISC OS operating system:
-RMF or -Module
Generate a RISC OS module as output. The module
self-relocation code generated by armlink can be
customised by giving your version of it in an area
called AMF_RELOC in the first object file in the
input list.
Special Options
The options -Base, -Entry, -DATA and -Workspace are each
followed by a numerical argument. You can use a 0x or &
prefix to indicate a hexadecimal value, and the suffixes K
and M to indicate multiplication by 1024 and 1024 x 1024,
respectively. The default base address for an AIF image
is &8000 (=32K, =0x20K). The default base address for a
binary image (-BIN, -BIN -AIF, and -IHF) is 0.
-RO-base base-address -Base base-address
Set the base address for the output to base-
address. This is the address at which an image may
be loaded and executed without further relocation.
section.
-RW-base
data-base-address -DATA data-base-address Set the
base for the data (read-write) segment of the out-
put to data-base-address rather than to base-
address + code-size. Currently, this option is only
meaningful if the output type is -BIN -AIF, -BIN
-SPLIT or -IHF -SPLIT.
-Entry entry-address or -Entry offset>+object(area)
The objects included in an image must have a unique
designated entry point. Usually, this is given by
one of the input areas having been assembled from a
source containing an ENTRY directive. Otherwise,
the entry point must be given on the linker's com-
mand line. The entry point is the target of the
entry branch from the image's AIF header.
The entry point may be given as an absolute address
or as an offset within an area within a particular
object. For example:
-Entry 8+startup(C$$code)
(Note that there must be no spaces within the argu-
ment to -Entry and that letter case is ignored when
matching both object and area names).
This latter form is often more convenient and is
mandatory when specifying an entry point for unused
area elimination (see "-NOUNUSEDareas" starting on
page25).
-Case Make the matching of symbol names case insensitive.
-MATCH flags
Set the last-gasp symbol matching options and the
pc-relative implies code relocation default. Each
option is controlled by a single bit in flags, as
follows:
0x01: match an undefined symbol of the form _sym
to a symbol definition of the form sym;
0x02: match an undefined symbol of the form sym to
a symbol definition of the form_sym;
0x04: match an undefined symbol of the form Mod-
ule_Symbol to a definition of the form Mod-
ule.Symbol;
symbol;
0x10: treat all pc-relative relocation directives
as relocating instructions.
These options are usually set by configuring the armlink
image when it is installed. The default value is 0x10
(treat pc-relative relocations as relocating code but do
no default symbol matching). Care must be taken when using
-MATCH from the command line not to override options acci-
dentally.
-FIRST object(area) or -LAST object(area)
Place the area named area from the object named
object first or last, respectively, in the output.
These options are useful for forcing an area map-
ping low addresses (typically the reset and inter-
rupt vector addresses) to be placed first, or an
area containing a checksum to be placed last.
-NOUNUSEDareas
Do not remove unused areas from the output (output
of type AIF only). An area is used if:
o it is the area containing the entry point;
o it is referred to from a used area.
(An area X refers to an area Y if any value in X is
relocated relative to the base of Y or relative to
any symbol defined in Y. That is, if there is any
symbolic reference from X to Y).
-Unresolved symbol
Match each reference to an undefined symbol to the
global definition of symbol . Note that symbol must
be both defined and global, otherwise it too will
appear in the list of undefined symbols, and the
link step will fail. This option is particularly
useful during top-down development, when it may be
possible to test a partially implemented system
from which the lower levels of code are missing, by
connecting each reference to a missing function to
a dummy function which does nothing.
Input File List
On the command line, the input file list is one or more
file names separated by spaces, together with the files
listed in arguments to -VIA options; (for details see
"General Options"). The input list is strictly ordered as
given. For example:
file1 file2 -VIA vf1 file3 -VIA vf2 file4
file1 file2 vf1/1 vf1/2 ... file3 vf2/1 vf2/2 ...
file4
where vf1/1, vf1/2, ... are the first, second, ... files
listed in -VIA file vf1, etc. Each of the files in the
input list must be in ARM Object Format (compiled or
assembled files) or ARM Object Library Format (libraries).
SEE ALSO
armlib(1)
Reference Manual, Technical Specifications