Controlling image contents

RealView^® Compilation Tools for µVision Linker and Utilities Guide

Version 3.1

Home > The Linker Command Syntax > armlink command syntax > Controlling image contents

2.2.8. Controlling image contents

These options control miscellaneous factors affecting the image contents:

‑‑[no_]branchnop

The ‑‑branchnop option causes the linker to replace any branch with a relocation that resolves to the next instruction with a NOP. This is the default.

Use ‑‑no_branchnop to disable this behavior.

See Branch inlining for more information on controlling branch inlining.

‑‑[no_]cppinit symbol

The ‑‑cppinit symbol option enables the linker to use alternative C++ libraries with a different initialization symbol. By default, symbol is set to: __cpp_initialize__aeabi_

The ‑‑no_cppinit option does not take a symbol argument.

--device=list

This option lists the supported device names that you can use with the --device=name option.

‑‑device=name

Enables code generation for a specific device and associated processor settings.

The link phase fails if any of the component object files rely on features that are incompatible with the selected processor. The linker also uses this option to optimize the choice of system libraries and any veneers that need to be generated when building the final image. The default is to select a device that is compatible with all of the component object files.

This option follows the same format as that supported by the compiler. See ‑‑device=name in the Compiler Reference Guide for more information.

‑‑datacompressor on|off

RW data compression is enabled by default to minimize ROM size. Use ‑‑datacompressor off to turn off RW data compression.

‑‑datacompressor list|id

Enable you to specify one of the supplied algorithms for RW data compression:

Use ‑‑datacompressor list to get a list of data compressors available to the linker.
If you do not specify a data compression algorithm, the linker chooses the most appropriate one for you automatically. In general, it is not necessary to override this choice. For more information see RW data compression.
If you do want to override the linker, use ‑‑datacompressor id to specify a data compression algorithm. Specifying a compressor adds a decompressor to the code area. If the final image does not have compressed data, the decompressor is not added.

‑‑edit file‑list

Enables you to specify steering files containing commands to edit the symbol tables in the output binary. You can specify commands in a 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.

When you are specifying more than one steering file, the syntax can be either of the following:

armlink ‑‑edit file1 ‑‑edit file2 ‑‑edit file3

armlink ‑‑edit file1,file2,file3

Do not include spaces between the comma and the filenames.

‑‑entry location

Specifies the unique initial entry point of the image. The image can contain multiple entry points, but the initial entry point specified with this option 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. The ARM RealView Debugger uses this entry address to initialize the Program Counter (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

Specifies an image entry point as the address of symbol, for example: ‑‑entry reset_handler

offset+object(section)

Specifies an image entry point as an offset inside a section within a particular object, for example: ‑‑entry 8+startup.o(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. armlink generates an error message if there is more than one input section in object.

Note

If the entry address of your image is in Thumb state, then the least significant bit of the address must be set to 1. The linker does this automatically if you specify a symbol. For example, if the entry code starts at address 0x8000 in Thumb state you must use --entry 0x8001.

‑‑[no_]exceptions

Use ‑‑exceptions to enable the final image to contain exception tables. This is the default.

Use ‑‑no_exceptions to force the linker to generate an error message if any exceptions sections are present in the image after unused sections have been eliminated. Use this option to ensure that your code is exceptions free.

See Using command-line options to handle C++ exceptions for more information.

‑‑exceptions_tables=action

Specifies how exception tables are generated for objects that do not already contain exception unwinding tables. Replace action with one of the following:

nocreate: The linker does not create missing exception tables. This is the default.
unwind: The linker creates an unwinding table for each section in your image that does not already have an exception table.
cantunwind: The linker creates a nounwind table for each section in your image that does not already have an exception table.

See Using command-line options to handle C++ exceptions for more information.

‑‑fini symbol

Specifies the symbol name that is used to define the entry point for finalization code. The dynamic linker executes this code when it unloads the executable file or shared object.

‑‑first section‑id

Places the selected input section first in its execution region. This can, for example, place the section containing the vector table 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 only one section can 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

Note

When using scatter-loading, use +FIRST in the scatter-loading description file instead.

See Ordering input sections by attribute for more information.

‑‑[no_]force_so_throw

Controls whether an image can throw an exception or not. By default, exception tables are discarded if no code throws an exception.

--no_force_so_throw is the default.

--fpu=list

This option lists the supported FPU architecture names that you can use with the --fpu=name option.

‑‑fpu=name

Enables code generation for a specific FPU architecture.

The link phase fails if any of the component object files rely on features that are incompatible with the selected FPU architecture. The linker also uses this option to optimize the choice of system libraries and any veneers that need to be generated when building the final image. The default is to select an FPU that is compatible with all of the component object files.

This option follows the same format as that supported by the compiler. See ‑‑fpu=name in the Compiler Reference Guide for more information.

‑‑init symbol

Specifies the symbol name that is used to define initialization code. The dynamic linker executes this code when it loads the executable file or shared object.

‑‑[no_]inline

‑‑inline enables branch inlining to optimize small function calls in your image.

Note

This branch optimization is off by default because enabling it changes the image such that debug information might be incorrect. If enabled, the linker makes no attempt to correct the debug information.

See Branch inlining for more information on controlling branch inlining.

‑‑keep section‑id

Specifies input sections that must not be removed by unused section elimination (see Specifying an image memory map).

All forms of the section‑id argument can contain the * and ? wildcards. You can specify multiple ‑‑keep options on the command line.

Replace section-id with one of the following:

symbol

Specifies that an input section defining symbol is to be retained during unused section elimination. If multiple definitions of symbol exist, armlink generates an error message.

For example, you might use ‑‑keep int_handler.

To keep all sections that define a symbol ending in _handler, use ‑‑keep *_handler.

object(section)

Specifies that section from object is to be retained during unused section elimination. 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 are vec, use: ‑‑keep vectors.o(vec*)

object

Specifies that the single input section from object is to be retained during unused section elimination. If you use this short form and there is more than one input section in object, armlink generates an error message.

For example, you might use ‑‑keep dspdata.o.

To keep the single input section from each of the objects that has a name starting with dsp, use ‑‑keep dsp*.o.

‑‑last section-id

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 only a single section can 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.

Note

When using scatter-loading, use +LAST in the scatter‑loading description file instead.

See Ordering input sections by attribute for more information.

‑‑[no_]locals

Use ‑‑locals to instruct the linker to add local symbols to the output symbol table when producing an executable image. This is the default.

Use ‑‑no_locals to instruct the linker not to add local symbols to the output symbol table. This is a useful optimization if you want to reduce the size of the output symbol table.

‑‑[no_]merge

Instruct the linker to merge const strings that are placed in shareable sections by the compiler. This option can reduce the size of the image if there are similarities between const strings. The default is ‑‑merge.

--pad num

Enables you to set a value for padding bytes. The linker assigns this value to all padding bytes inserted in load or execution regions.

num is an integer, which can be given in hexadecimal format. For example, setting num to 0xFF might help to speed up ROM programming time. If num is greater than 0xFF, then the padding byte is set to (char)num.

Note

Padding is only inserted:

within load regions. No padding is present between load regions.
between fixed execution regions (in addition to forcing alignment). Padding is not inserted up to the maximum length of a load region unless it has a fixed execution region at the top.
between sections to ensure that they conform to alignment constraints.

‑‑[no_]remove

Enables or disables the removal of unused input sections from the image. An input section is considered used if it contains the image entry point, or if it is referred to from a used section. The default is --remove. See also Unused section elimination for more information.

Use ‑‑no_remove when debugging to retain all input sections in the final image even if they are unused.

Use the ‑‑keep option to retain specific sections in a normal build.

‑‑[no_]startup symbol

‑‑startup symbol enables the linker to use alternative C libraries with a different startup symbol. By default, symbol is set to __main.

The ‑‑no_startup option does not take a symbol argument.

The linker includes the C library startup code if there is a reference to a symbol that is defined by the C library startup code. This symbol reference is called the startup symbol. It is automatically created by the linker when it sees a definition of main(). The ‑‑startup option allows you to change this symbol reference.

If the linker finds a definition of main() and does not find a reference to (or definition of) symbol, then it generates an error.
If the linker finds a definition of main() and a reference to (or definiton of) symbol, and no entry point is specified, then the linker generates a warning. See ‑‑entry location in Controlling image contents for more information.

‑‑[no_]tailreorder

‑‑tailreorder moves tail calling sections immediately before their target, if possible, to optimize the branch instruction at the end of a section. A tail calling section is a section that contains a branch instruction at the end of the section. The branch must have a relocation that targets a function at the start of a section. There are some restrictions to this option. The linker:

can only move one tail calling section for each tail call target
cannot move a tail calling section out of its execution region
does not move tail calling sections before inline veneers.

See Branch inlining for more information on handling tail calling sections.

--no_tailreorder is the default.

‑‑vfemode=mode

Virtual Function Elimination (VFE) is a technique that enables the linker to identify more unused sections.

Use ‑‑vfemode=mode to specify how these, and Runtime Type Information (RTTI) objects, are eliminated.

Where mode is one of the following:

on
off
force
force_no_rtti

See Unused function elimination for more information.

Copyright © 2007 ARM Limited. All rights reserved.	ARM DUI 0377A
PDF version

Home > The Linker Command Syntax > armlink command syntax > Controlling image contents