RealView™ Compilation Tools for BREW Linker and Utilities Guide 2.2. armlink command syntax

2.2. armlink command syntax

The complete linker command syntax is:

armlink [-help] [-vsn] [-partial] [-output file] [-elf] [-reloc] [[-ro-base address]] [-ropi] [-rw-base address] [-rwpi] [-split] [[-debug] | [-nodebug]] [[-remove (RO/RW/ZI/DBG)] | [-noremove]] [-entry location ] [-keep section-id] [-first section-id] [-last section-id] [-libpath pathlist] [[-scanlib] | [-noscanlib]] [[-locals] | [-nolocals]] [-callgraph] [[-info topics]] [-map] [-symbols] [[-symdefs file]] [[-edit file]] [-xref] [[-xreffrom object(section)]] [[-xrefto object(section)]] [[-errors file]] [[-list file]] [-verbose] [[-unmangled ] | [-mangled]] [-match crossmangled] [[-via file]] [-strict] [[-unresolved symbol]] [ -MI | -LI | -BI] [input-file-list]

where:

-help

This option prints a summary of some commonly used command-line options.

-vsn

This option displays the armlink version information.

-partial

This option creates a partially-linked object instead of an executable image.

-output file

This option specifies the name of the output file. The file can be either a partially-linked object or executable image. If the output file name is not specified, armlink uses the following defaults:

__image.axf: if the output is an executable image
__object.o: if the output is a partially-linked object.

If file is specified without path information, it is created in the current working directory. If path information is specified, then that directory becomes the default output directory.

-elf

This option generates the image in ELF format. This is the only output format supported by armlink. This is the default.

-reloc

This option makes relocatable images.

A relocatable image has a dynamic segment that contains relocations that can be used to relocate the image post link-time. Examples of post link-time relocation include advanced ROM construction and dynamic loading at run time.

If the image is loaded at its link-time address, the relocatable image produced by armlink does not require the relocations to be processed and debug data for the image is valid. Loading the image at a different address to the link-time address and processing the relocations, however, invalidates any debug data present in the image.

Used on its own, -reloc makes an image similar to Simple type 1, but the single load region has the RELOC attribute. See Type 1: one load region and contiguous output regions for more information on type 1 images.

The combination -reloc -split makes an image similar to Simple type 3, but the two load regions now have the RELOC attribute. See Type 3: two load regions and noncontiguous output regions for more information on type 3 images.

Using -reloc -rw-base without also using -split causes an error.

-ro-base address

This option sets both the load and execution addresses of the region containing the RO output section at address. address must be word-aligned. If this option is not specified, the default RO base address is 0x8000.

-ropi

This option makes the load and execution region containing the RO output section position-independent. If this option is not used the region is marked as absolute. Usually each read-only input section must be read-only position-independent. If this option is selected, armlink:

checks that relocations between sections are valid
ensures that any code generated by armlink itself, such as interworking veneers, is read-only position-independent.

Note

The ARM tools cannot determine if the final output image will be read-only position-independent until armlink finishes processing input sections. This means that armlink might emit ROPI error messages, even though you have selected the ROPI option for the compiler and assembler.

-rw-base address

This option sets the execution addresses of the region containing the RW output section at address. address must be word-aligned.

If this option is used with -split, it sets both the load and the execution address of the region containing the RW output sections at address.

-rwpi

This option makes the load and execution region containing the RW and ZI output section position-independent. If this option is not used the region is marked as absolute. This option requires a value for -rw-base. If -rw-base is not specified, -rw-base 0 is assumed. Usually each writable input section must be read-write position-independent.

If this option is selected, armlink:

checks that the PI attribute is set on input sections to any read-write execution regions
checks that relocations between sections are valid
generates static base-relative entries in the tables that are used when RO and RW regions are copied or initialized.

Note

The compiler does not force your writable data to be position-independent. This means that armlink might diagnose that data is not RWPI, even though you have selected the RWPI option for the compiler and assembler.

-split

This option splits the default load region, that contains the RO and RW output sections, into the following load regions:

One containing the RO output section. The default load address is 0x8000, but a different address can be specified with the -ro-base option.
One containing the RW output section. The load address is specified with the -rw-base option. This option requires a value for -rw-base. If -rw-base is not specified, -rw-base 0 is assumed.

-debug

This option includes debug information in the output file. The debug information includes debug input sections and the symbol and string table. This is the default.

-nodebug

This option turns off the inclusion of debug information in the output file. The image is smaller, but you cannot debug it at the source level. armlink discards any debug input section it finds in the input objects and library members, and does not include the symbol and string table in the image as loaded into the debugger. This only affects the image size as loaded into the debugger and has no effect on the size of any resulting binary image that is downloaded to the target.

If you are creating a partially-linked object rather than an image, armlink discards the debug input sections it finds in the input objects, but does produce the symbol and string table in the partially-linked object.

Note

Do not use -nodebug if a fromELF step is required. If your image is produced without debug information:

fromELF cannot translate the image into other file formats
fromELF cannot produce a meaningful disassembly listing.

-remove (RO/RW/ZI/DBG)

This option performs unused section elimination on the input sections to remove unused sections from the image. An input section is considered to be used if it contains the image entry point, or if it is referred to from a used section. See also Unused section elimination.

Note

You must take care not to remove exception handlers when using -remove. Use the -keep option to identify exception handlers or use the ENTRY directive to label them as entry points.

You can use section attribute qualifiers for more precise control of the unused section elimination process. If a qualifier is used, it can be one or more of the following:

RO: Remove all unused sections of type RO.
RW: Remove all unused sections of type RW.
ZI: Remove all unused sections of type ZI.
DBG: Remove all unused sections of type DEBUG.

The qualifiers can appear in any case and order, but must be enclosed in parentheses (), and must be separated by a slash /.

The default is -remove (RO/RW/ZI/DBG).

If no section attribute qualifiers are specified, all unused sections are eliminated. -remove is equivalent to -remove (RO/RW/ZI/DBG).

-noremove

This option does not perform unused section elimination on the input sections. This retains all input sections in the final image even if they are unused.

-entry location

This option specifies the unique initial entry point of the image. The image can contain multiple entry points, but the initial entry point specified using this command is stored in the executable file header for use by the loader. There can be only one occurrence of this option on the command line. ARM debuggers use this entry address to initialize the PC when an image is loaded. The initial entry point must meet the following conditions:

the image entry point must lie within an execution region
the execution region must be non-overlay, and must be a root execution region (load address == execution address).

Replace location with one of the following:

entry_address

A numerical value, for example:

-entry 0x0

symbol

This option specifies an image entry point as the address of symbol. For example:

-entry int_handler

If multiple definitions of symbol exist, armlink generates an error message.

offset+object(section)

This option specifies an image entry point as an offset inside a section within a particular object. For example:

-entry 8+startup(startupseg)

There must be no spaces within the argument to -entry. The input section and object names are matched without case-sensitivity. You can use the following simplified notation:

object(section) if offset is zero
object if there is only one input section. If this form is used and there is more than one non-debug input section in object, armlink generates an error message.

-keep section-id

Specifies input sections that are not to be removed by unused section elimination. See Specifying an image memory map. All forms of section-id argument to -keep can contain the * and ? wildcards. Replace section-id with one of the following:

symbol

This option specifies that the input section defining symbol is to be retained during unused section elimination. If multiple definitions of symbol exist, then all input sections that define symbol are treated similarly. For example:

-keep int_handler

To keep all sections that define a symbol ending in _handler, use:

-keep *_handler

There can be multiple occurrences of this command on the command line.

object(section)

This option specifies that section from object is to be retained during unused section elimination. The input section and object names are matched without case-sensitivity. For example, to keep the vect section from the vectors.o object use:

-keep vectors.o(vect)

To keep all sections from the vectors.o object where the first three characters of the name of the section is vec, use:

-keep vectors.o(vec*)

There can be multiple occurrences of this command on the command line.

object

This option specifies that the single input section from object is to be retained during unused section elimination. The object name is matched without case-sensitivity. If you use this short form and there is more than one input section in object, armlink generates an error message. For example:

-keep dspdata.o

To keep the single input section from each of the objects that have a name starting with dsp, use:

-keep dsp*.o

There can be multiple occurrences of this option on the command line.

-first section-id

This option places the selected input section first in its execution region. This can, for example, place the section containing the reset and interrupt vector addresses first in the image. Replace section-id with one of the following:

symbol

Selects the section that defines symbol. You must not specify a symbol that has more than one definition, because more than one section cannot be placed first. For example:

-first reset

object(section)

Selects section from object. There must be no space between object and the following open parenthesis. For example:

-first init.o(init)

object

Selects the single input section in object. If you use this short form and there is more than one input section, armlink generates an error message. For example:

-first init.o

Using -first cannot override the basic attribute sorting order for output sections in regions that places RO first, RW second, and ZI last. If the region has an RO section, an RW or a ZI section cannot be placed first. If the region has an RO or RW section, a ZI section cannot be placed first.

Two different sections cannot both be placed first in the same execution region, so only one instance of this option is permitted.

-last section-id

This option places the selected input section last in its execution region. For example, this can force an input section that contains a checksum to be placed last in the RW section. Replace section-id with one of the following:

symbol

Selects the section that defines symbol. You must not specify a symbol that has more than one definition, because more than one section cannot be placed last. For example:

-last checksum

object(section)

Selects the section from object. There must be no space between object and the following open parenthesis. For example:

-last checksum.o(check)

object

Selects the single input section from object. If there is more than one input section in object, armlink generates an error message.

Using -last cannot override the basic attribute sorting order for output sections in regions that places RO first, RW second, and ZI last. If the region has a ZI section, an RW section cannot be placed last. If the region has an RW or ZI section, an RO section cannot be placed last.

Two different sections cannot both be placed last in the same execution region, so only one instance of this option is permitted.

-libpath pathlist

This option specifies a list of paths that are used to search for the ARM standard C and C++ libraries.

Note

This option does not affect searches for user libraries.

These paths override the path specified by the ARMLIB environment variable. pathlist is a comma-separated list of pathspath1, path2,... pathn that are only used to search for required ARM libraries. The default path for the directory containing the ARM libraries is specified by the ARMLIB environment variable. See Library searching, selection, and scanning for more information on including libraries.

-scanlib

This option enables scanning of default libraries (the standard ARM C and C++ libraries) to resolve references. This is the default.

-noscanlib

This option prevents the scanning of default libraries in a link step.

-locals

This option instructs the linker to add local symbols to the output symbol table when producing an executable image. This is the default.

-nolocals

This option instructs the linker not to add local symbols to the output symbol table when producing an executable image. This is a useful optimization if you want to reduce the size of the output symbol table.

-callgraph

This option creates a static callgraph of functions in HTML format. The callgraph gives definition and reference information for all functions in the image.

Note

Any assembler files must contain appropriate FRAME directives, so that the linker can use the debug information subsequently generated to work out stack usage.

Also, the stack usage cannot take into account, for example, recursive functions and function pointers.

For each function func it lists:

the processor state for which the function is compiled (ARM or Thumb)
the set of functions that call func
the set of functions that are called by func
the number of times the address of func is used in the image.

In addition, the callgraph identifies functions that are:

called through interworking veneers
defined outside the image
allowed to remain undefined (weak references).

The static callgraph also provides stack usage information. It lists:

the size of the stack frame used by each function
the maximum size of the stack used by the function over any call sequence, that is, over any acyclic chain of function calls in the callgraph.

-info topics

This option prints information about specified topics, where topics is a comma-separated list of topic keywords. A topic keyword can be one of the following:

sizes: Gives a list of the Code and Data (RO Data, RW Data, ZI Data, and Debug Data) sizes for each input object and library member in the image. Using this option implies -info sizes,totals.
totals: Gives totals of the Code and Data (RO Data, RW Data, ZI Data, and Debug Data) sizes for input objects and libraries.
veneers: Gives details of armlink-generated veneers. For more information on veneers see Veneer generation.
unused: Lists all unused sections that were eliminated from the image as a result of using -remove.

Note

Spaces are not permitted between keywords in a list. For example, you can enter:

-info sizes,totals

but not:

-info sizes, totals

-map

This option creates an image map. The image map contains the address and the size of each load region, execution region, and input section in the image, including debugging and linker-generated input sections.

-symbols

This option lists each local and global symbol used in the link step, and its value. This includes linker-generated symbols.

-symdefs file

This option creates a symbol definition file containing the global symbol definitions from the output image.

By default, all global symbols are written to the symdefs file. If file already exists, the linker restricts its output to the symbols listed in the existing symdefs file.

If file is specified without path information, the linker searches for it in the directory where the output image is being written. If it is not found, it is created in that directory.

You can use the symbol definition file as input when linking another image. See Accessing symbols in another image for more information.

-edit file

This option enables you to specify a steering file containing commands to edit the symbol tables in the output binary. You can specify commands in the steering file to:

Hide global symbols. Use this option to hide specific global symbols in object files. The hidden symbols are not publicly visible.
Rename global symbols. Use this option to resolve symbol naming conflicts.

See Hiding and renaming global symbols for more information on steering file syntax.

-xref

This option lists all cross-references between input sections.

-xreffrom object(section)

This option lists cross-references from input section in object to other input sections. This is a useful subset of the listing produced by using -xref if you are interested in references from a specific input section. You can have multiple occurrences of this option to list references from more than one input section.

-xrefto object(section)

This option lists cross-references to input section in object from other input sections. This is a useful subset of the listing produced by using -xref if you are interested in references to a specific input section. You can have multiple occurrences of this option in order to list references to more than one input section.

-errors file

Redirects the diagnostics from the standard error stream to file.

-list file

This option redirects the diagnostics from output of the -info, -map, -symbols, -xref, -xreffrom, and -xrefto commands to file.

If file is specified without path information, it is created in the output directory, that is the directory the output image is being written to.

-verbose

This option prints detailed information about the link operation, including the objects that are included and the libraries from which they are taken.

-unmangled

This option instructs the linker to display unmangled C++ symbol names in diagnostic messages, and in listings produced by the -xref, -xreffrom, -xrefto, and -symbols options.

If this option is selected, the linker unmangles C++ symbol names so that they are displayed as they appear in your source code. This is the default.

-mangled

This option instructs the linker to display mangled C++ symbol names in diagnostic messages, and in listings produced by the -xref, -xreffrom, -xrefto, and -symbols options. If this option is selected, the linker does not unmangle C++ symbol names. The symbol names are displayed as they appear in the object symbol tables.

-match crossmangled

This tells the linker to match the following combinations together:

a reference to an unmangled symbol with the mangled definition
a reference to a mangled symbol with the unmangled definition.

Libraries and matching operate as follows:

if the library members define a mangled definition, and there is an unresolved unmangled reference, the member is loaded to satisfy it
if the library members define an unmangled definition, and there is an unresolved mangled reference, the member is loaded to satisfy it.

Note

This option has no effect if used with partial linking. The partial object contains all the unresolved references to unmangled symbols, even if the mangled definition exists. Matching is done only in the final link step.

-via file

This option reads a further list of input filenames and linker options from file.

You can enter multiple -via options on the armlink command line. The -via options can also be included within a via file. See RealView Compilation Tools for BREW Compilers and Libraries Guide for more information on writing via files.

-strict

This option instructs the linker to report conditions that might result in failure as errors, rather than warnings.

-unresolved symbol

This option matches each reference to an undefined symbol to the global definition of symbol. symbol must be both defined and global, otherwise it appears in the list of undefined symbols and the link step fails. This option is particularly useful during top-down development, because it enables you to test a partially-implemented system by matching each reference to a missing function to a dummy function.

This option does not display warnings.

input-file-list

This is a space-separated list of objects or libraries.

A special type of object file, the symdef file, can be included in the list to provide global symbol values for a previously generated image file. See Accessing symbols in another image for more information.

You can use libraries in the input file list in the following ways:

Specify particular members to be extracted from a library and added to the image as individual objects. For example, specify mystring.lib(strcmp.o) in the input file list.
Specify a library to be added to the list of libraries that is used to extract members if they resolve any non-weak unresolved references. For example, specify mystring.lib in the input file list. Other libraries are added to this list implicitly by armlink when it scans the default library directories and selects the closest matching library variants available. Members from the libraries in this list are added to the image only when they resolve an unresolved non-weak reference. For more information see Library searching, selection, and scanning.

armlink processes the input file list in the following order:

Objects are added to the image unconditionally.
Members selected from libraries using patterns are added to the image unconditionally, as if they were objects. For example:
```
armlink main.o mylib(stdio.o) mylib(a*.o). 
```
unconditionally adds all a*.o objects, and stdio.o.
Libraries are added to the list of libraries that are later used to resolve any remaining non-weak unresolved references.

Copyright © 2002 ARM Limited. All rights reserved.	ARM DUI 0212A
Non-Confidential
PDF version