The ARM Linker (armlink)
------------------------


About the ARM Linker 
.....................

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:

 *  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);

 *  optionally, one or more object libraries in ARM Object Library Format (see 
    chapter "<ARM Object Library Format>" of the Technical 
    Specifications for details).

The ARM linker performs the following functions:

 *  it resolves symbolic references between object files;

 *  it extracts from object libraries the object modules needed to satisfy 
    otherwise unsatisfied symbolic references;

 *  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);

 *  it relocates (possibly partially) relocatable values;

 *  it generates an output <image> possibly comprising several files (or a 
    partially linked object file instead).

The ARM linker can produce output in any of the following formats:

 *  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);

 *  Plain binary format, relocated to a fixed address, (see section "<Plain 
    Binary Format>" of the Reference Manual for details);

 *  ARM Image Format, (see section "<ARM Image Format>" of 
    the Reference Manual for a synopsis, and chapter   of the Technical 
    Specifications for full details);

 *  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);

 *  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);

 *  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).


Using the Linker
................


Linker Command Line

The format of the link command is:

    armlink <options input-file-list>

If present, <input-file-list >is a list of one or more object files and 
libraries; this is described under "<Input File List>".  Inp
ut 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 separate 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 debugging 
areas present in the input object files, and to generate low-level symbolic 
debugging data for 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> (diagnostics 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. Conventionally, each file name and option 
is given on a separate 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

The following options each select a different output format (and, hence, are 
mutually exclusive):


-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 section "<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 memory 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 customised 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 Reference 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 subsequent link step. AOF is described in section "<ARM Object 
Format>" of the Reference Manual, and in chapter "<ARM 
Object Format>" of the Technical Specifications.


-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 "<Special 
Options>"). Plain binary images are described in section "
<Plain Binary Format>" of the Reference Manual.


-BIN -AIF

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 section "<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 generated 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 useful.


-SPLIT

This option tells the linker to output the read-only and read-write image 
sections to separate output files.  It may be used only in conjunction with 
-BIN and -IHF image types, and is meaningful only if separate read-only and 
read-write base addresses have been specified (see "<-RO-base base-address 
-Base base-address>" and "<-RW-base data-base-address -DATA 
data-base-address>").  The separate output files are named 
as in the following table:

    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 Reference 
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 
relocatable 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
-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. If there 
are separate read-only and read-write sections then this is the base of the 
read-only section.


-RW-base  <data-base-address>
 -DATA <data-base-address>

Set the base for the data (read-write) segment of the output 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>
-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 command 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 argument 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 <Module_Symbol> to a 
definition of the form 
            <Module.Symbol>;
      0x08: match an undefined symbol of the form <symbol__type> to a 
definition of the form
             <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 accidentally.


-FIRST <object>(<area>)
-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 
mapping low addresses (typically the reset and interrupt 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:

 *  it is the area containing the entry point;

 *  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>

yields the input file list:

    <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).

 

 

