ARM® Compiler toolchain Using the Linker

Version 5.02


List of Topics

Conventions and feedback
Overview of the linker
About the linker
Linker command-line syntax
Linker command-line options listed in groups
What the linker can accept as input
What the linker outputs
What the linker does when constructing an executable image
Linking models supported by armlink
Overview of linking models
Bare-metal linking model
Partial linking model
Base Platform Application Binary Interface (BPABI) linking model
Base Platform linking model
SysV linking model
Concepts common to both BPABI and SysV linking models
Image structure and generation
The image structure
Input sections, output sections, regions, and Program Segments
Load view and execution view of an image
Methods of specifying an image memory map with the linker
Types of simple image
Type 1 image, one load region and contiguous execution regions
Type 2 image, one load region and non-contiguous execution regions
Type 3 image, two load regions and non-contiguous execution regions
Image entry points
About specifying an initial entry point
Section placement with the linker
Placing sections with FIRST and LAST attributes
Section alignment with the linker
Demand paging
About ordering execution regions containing Thumb code
Overview of veneers
Veneer sharing
Veneer types
Generation of position independent to absolute veneers
Reuse of veneers when scatter-loading
Using command-line options to control the generation of C++ exception tables
About weak references and definitions
How the linker performs library searching, selection, and scanning
Controlling how the linker searches for the ARM standard libraries
Specifying user libraries when linking
How the linker resolves references
Use of the strict family of options in the linker
Using linker optimizations
Elimination of common debug sections
Elimination of common groups or sections
Elimination of unused sections
Elimination of unused virtual functions
About linker feedback
Example of using linker feedback
About link-time code generation
Optimization with RW data compression
How the linker chooses a compressor
Overriding the compression algorithm used by the linker
How compression is applied
Working with RW data compression
Inlining functions with the linker
Factors that influence function inlining
Handling branches that optimize to a NOP
About reordering of tail calling sections
Restrictions on reordering of tail calling sections
About merging comment sections
Getting information about images
Linker options for getting information about images
Identifying the source of some link errors
Example of using the --info linker option
How to find where a symbol is placed when linking
Accessing and managing symbols with armlink
About mapping symbols
Accessing linker-defined symbols
Region-related symbols
Image$$ execution region symbols
Load$$ execution region symbols
Load$$LR$$ load region symbols
Region name values when not scatter-loading
Using scatter files
Importing linker-defined symbols in C and C++
Importing linker-defined symbols in ARM assembler
Section-related symbols
Image symbols
Input section symbols
Accessing symbols in another image
Creating a symdefs file
Outputting a subset of the global symbols
Reading a symdefs file
Symdefs file format
What is a steering file?
Specifying steering files on the linker command-line
Steering file command summary
Steering file format
Hiding and renaming global symbols with a steering file
Using $Super$$ and $Sub$$ to patch symbol definitions
Using scatter files
About scatter-loading
When to use scatter-loading
Scatter-loading command-line option
Images with a simple memory map
Images with a complex memory map
Linker-defined symbols that are not defined when scatter-loading
Specifying stack and heap using the scatter file
What is a root region?
Creating root execution regions
Using the FIXED attribute to create root regions
Placing functions and data at specific addresses
Placing a named section explicitly using scatter-loading
Placing unassigned sections with the .ANY module selector
Examples of using placement algorithms for .ANY sections
Example of next_fit algorithm showing behavior of full regions, selectors, and priority
Examples of using sorting algorithms for .ANY sections
Selecting veneer input sections in scatter-loading descriptions
Using __attribute__((section("name"))) to place code and data
Using __at sections to place sections at a specific address
Restrictions on placing __at sections
Automatic placement of __at sections
Manual placement of __at sections
Placing a key in flash memory using __at
Placing a structure over a peripheral register using __at
Placement of sections with overlays
About placing ARM C and C++ library code
Example of placing code in a root region
Example of placing ARM C library code
Example of placing ARM C++ library code
Example of placing ARM library helper functions
Reserving an empty region
About creating regions on page boundaries
Overalignment of execution regions and input sections
Using preprocessing commands in a scatter file
Expression evaluation in scatter files
Using expression evaluation in a scatter file to avoid padding
Equivalent scatter-loading descriptions for simple images
Type 1 image, one load region and contiguous execution regions
Type 2 image, one load region and non-contiguous execution regions
Type 3 image, two load regions and non-contiguous execution regions
Scatter file to ELF mapping
GNU ld script support in armlink
About GNU ld script support and restrictions
Typical use cases for using ld scripts with armlink
Important ld script commands that are implemented in armlink
Specific restrictions for using ld scripts with armlink
Recommendations for using ld scripts with armlink
Default GNU ld scripts used by armlink
Example GNU ld script for linking an ARM Linux executable
Example GNU ld script for linking an ARM Linux shared object
Example GNU ld script for linking ld --ldpartial object
BPABI and SysV shared libraries and executables
About the Base Platform Application Binary Interface (BPABI)
Platforms supported by the BPABI
Concepts common to all BPABI models
About importing and exporting symbols for BPABI models
Symbol visibility for BPABI models
Automatic import and export for BPABI models
Manual import and export for BPABI models
Symbol versioning for BPABI models
RW compression for BPABI models
Linker options for SysV models
SysV memory model
Automatic dynamic symbol table rules in the SysV memory model
Addressing modes in the SysV memory model
Thread local storage in the SysV memory model
Related linker command-line options for the SysV memory model
Changes to command-line defaults with the SysV memory model
Linker options for bare metal and DLL-like models
Bare metal and DLL-like memory model
Mandatory symbol versioning in the BPABI DLL-like model
Automatic dynamic symbol table rules in the BPABI DLL-like model
Addressing modes in the BPABI DLL-like model
C++ initialization in the BPABI DLL-like model
About symbol versioning
Symbol versioning script file
Example of creating versioned symbols
About embedded symbols
Linker options for enabling implicit symbol versioning
Related linker command-line options for the BPABI DLL-like model
Features of the Base Platform linking model
Restrictions on the use of scatter files with the Base Platform model
Example scatter file for the Base Platform linking model
Placement of PLT sequences with the Base Platform model
Revisions for Using the Linker

Proprietary Notice

Words and logos marked with ® or ™ are registered trademarks or trademarks of ARM in the EU and other countries, except as otherwise stated below in this proprietary notice. Other brands and names mentioned herein may be the trademarks of their respective owners.

Neither the whole nor any part of the information contained in, or the product described in, this document may be adapted or reproduced in any material form except with the prior written permission of the copyright holder.

The product described in this document is subject to continuous developments and improvements. All particulars of the product and its use contained in this document are given by ARM in good faith. However, all warranties implied or expressed, including but not limited to implied warranties of merchantability, or fitness for purpose, are excluded.

This document is intended only to assist the reader in the use of the product. ARM shall not be liable for any loss or damage arising from the use of any information in this document, or any error or omission in such information, or any incorrect use of the product.

Where the term ARM is used it means “ARM or any of its subsidiaries as appropriate”.

Confidentiality Status

This document is Non-Confidential. The right to use, copy and disclose this document may be subject to license restrictions in accordance with the terms of the agreement entered into by ARM and the party that ARM delivered this document to.

Product Status

The information in this document is final, that is for a developed product.

Revision History
Revision A28 May 2010ARM Compiler toolchain v4.1 Release
Revision B30 September 2010Update 1 for ARM Compiler toolchain v4.1
Revision C28 January 2011Update 2 for ARM Compiler toolchain v4.1 Patch 3
Revision D30 April 2011ARM Compiler toolchain v5.0 Release
Revision E29 July 2011Update 1 for ARM Compiler toolchain v5.0
Revision F30 September 2011ARM Compiler toolchain v5.01 Release
Revision G29 February 2012Document update 1 for ARM Compiler toolchain v5.01 Release
Revision H27 July 2012ARM Compiler toolchain v5.02 Release
Copyright © 2010-2012 ARM. All rights reserved.ARM DUI 0474H
Non-ConfidentialID070912