ARM® Compiler armlink User Guide

Version 5.06


Table of Contents

Preface
About this book
Using this book
Glossary
Typographic conventions
Feedback
Other information
1 Overview of the Linker
1.1 About the linker
1.1.1 Summary of the linker features
1.1.2 What the linker can accept as input
1.1.3 What the linker outputs
1.1.4 Linker support for 64-bit host platforms
1.2 Linker command-line syntax
1.3 What the linker does when constructing an executable image
2 Linking Models Supported by armlink
2.1 Overview of linking models
2.2 Bare-metal linking model
2.3 Partial linking model
2.4 Base Platform Application Binary Interface (BPABI) linking model
2.5 Base Platform linking model
2.6 SysV linking model
2.7 Concepts common to both BPABI and SysV linking models
3 Image Structure and Generation
3.1 The structure of an ARM ELF image
3.1.1 Views of the image at each link stage
3.1.2 Input sections, output sections, regions, and program segments
3.1.3 Load view and execution view of an image
3.1.4 Methods of specifying an image memory map with the linker
3.1.5 Image entry points
3.2 Simple images
3.2.1 Types of simple image
3.2.2 Type 1 image structure, one load region and contiguous execution regions
3.2.3 Type 2 image structure, one load region and non-contiguous execution regions
3.2.4 Type 3 image structure, multiple load regions and non-contiguous execution regions
3.3 Section placement with the linker
3.3.1 Default section placement
3.3.2 Section placement with the FIRST and LAST attributes
3.3.3 Section alignment with the linker
3.4 Linker support for creating demand-paged files
3.5 Linker reordering of execution regions containing Thumb code
3.6 Linker-generated veneers
3.6.1 What is a veneer?
3.6.2 Veneer sharing
3.6.3 Veneer types
3.6.4 Generation of position independent to absolute veneers
3.6.5 Reuse of veneers when scatter-loading
3.7 Command-line options used to control the generation of C++ exception tables
3.8 Weak references and definitions
3.9 How the linker performs library searching, selection, and scanning
3.10 How the linker searches for the ARM standard libraries
3.11 Specifying user libraries when linking
3.12 How the linker resolves references
3.13 The strict family of linker options
3.14 Avoiding the BLX (immediate) instruction issue on an ARM1176JZ-S or ARM1176JZF-S processor
4 Linker Optimization Features
4.1 Elimination of common debug sections
4.2 Elimination of common groups or sections
4.3 Elimination of unused sections
4.4 Elimination of unused virtual functions
4.5 About linker feedback
4.6 Example of using linker feedback
4.7 Optimization with RW data compression
4.7.1 How the linker chooses a compressor
4.7.2 Options available to override the compression algorithm used by the linker
4.7.3 How compression is applied
4.7.4 Considerations when working with RW data compression
4.8 Function inlining with the linker
4.9 Factors that influence function inlining
4.10 About branches that optimize to a NOP
4.11 Linker reordering of tail calling sections
4.12 Restrictions on reordering of tail calling sections
4.13 Linker merging of comment sections
5 Getting Image Details
5.1 Options for getting information about linker-generated files
5.2 Identifying the source of some link errors
5.3 Example of using the --info linker option
5.4 How to find where a symbol is placed when linking
5.5 How to find the location of a symbol within the map file
6 Accessing and Managing Symbols with armlink
6.1 About mapping symbols
6.2 Linker-defined symbols
6.3 Region-related symbols
6.3.1 Types of region-related symbols
6.3.2 Image$$ execution region symbols
6.3.3 Load$$ execution region symbols
6.3.4 Load$$LR$$ load region symbols
6.3.5 Region name values when not scatter-loading
6.3.6 Linker defined symbols and scatter files
6.3.7 Methods of importing linker-defined symbols in C and C++
6.3.8 Methods of importing linker-defined symbols in ARM® assembly language
6.4 Section-related symbols
6.4.1 Types of section-related symbols
6.4.2 Image symbols
6.4.3 Input section symbols
6.5 Access symbols in another image
6.5.1 Creating a symdefs file
6.5.2 Outputting a subset of the global symbols
6.5.3 Reading a symdefs file
6.5.4 Symdefs file format
6.6 Edit the symbol tables with a steering file
6.6.1 Specifying steering files on the linker command-line
6.6.2 Steering file command summary
6.6.3 Steering file format
6.6.4 Hide and rename global symbols with a steering file
6.7 Use of $Super$$ and $Sub$$ to patch symbol definitions
7 Scatter-loading Features
7.1 The scatter-loading mechanism
7.1.1 Overview of scatter-loading
7.1.2 When to use scatter-loading
7.1.3 Linker-defined symbols that are not defined when scatter-loading
7.1.4 Specifying stack and heap using the scatter file
7.1.5 Scatter-loading command-line options
7.1.6 Scatter-loading images with a simple memory map
7.1.7 Scatter-loading images with a complex memory map
7.2 Root execution regions
7.2.1 Root execution region and the initial entry point
7.2.2 Root execution regions and the ABSOLUTE attribute
7.2.3 Root execution regions and the FIXED attribute
7.2.4 Methods of placing functions and data at specific addresses
7.2.5 Placement of code and data with __attribute__((section("name")))
7.2.6 Placement of __at sections at a specific address
7.2.7 Restrictions on placing __at sections
7.2.8 Automatic placement of __at sections
7.2.9 Manual placement of __at sections
7.2.10 Placement of a key in flash memory with an __at section
7.2.11 Mapping a structure over a peripheral register with an __at section
7.3 Example of how to explicitly place a named section with scatter-loading
7.4 Placement of unassigned sections with the .ANY module selector
7.4.1 Placement rules when using multiple .ANY selectors
7.4.2 Command-line options for controlling the placement of input sections for multiple .ANY selectors
7.4.3 Prioritization of .ANY sections
7.4.4 Specify the maximum region size permitted for placing unassigned sections
7.4.5 Examples of using placement algorithms for .ANY sections
7.4.6 Example of next_fit algorithm showing behavior of full regions, selectors, and priority
7.4.7 Examples of using sorting algorithms for .ANY sections
7.4.8 Behavior when .ANY sections overflow because of linker-generated content
7.5 Placement of veneer input sections in a scatter file
7.6 Placement of sections with overlays
7.7 Reserving an empty region
7.8 Placement of ARM C and C++ library code
7.8.1 Specifying ARM standard C and C++ libraries in a scatter file
7.8.2 Example of placing code in a root region
7.8.3 Example of placing ARM C library code
7.8.4 Example of placing ARM C++ library code
7.8.5 Example of placing ARM library helper functions
7.9 Creation of regions on page boundaries
7.10 Overalignment of execution regions and input sections
7.11 Preprocessing of a scatter file
7.12 Example of using expression evaluation in a scatter file to avoid padding
7.13 Equivalent scatter-loading descriptions for simple images
7.13.1 Command-line options for creating simple images
7.13.2 Type 1 image, one load region and contiguous execution regions
7.13.3 Type 2 image, one load region and non-contiguous execution regions
7.13.4 Type 3 image, multiple load regions and non-contiguous execution regions
7.14 How the linker resolves multiple matches when processing scatter files
7.15 How the linker resolves path names when processing scatter files
7.16 Scatter file to ELF mapping
8 Scatter File Syntax
8.1 BNF notation used in scatter-loading description syntax
8.2 Syntax of a scatter file
8.3 Load region descriptions
8.3.1 Components of a load region description
8.3.2 Syntax of a load region description
8.3.3 Load region attributes
8.3.4 Inheritance rules for load region address attributes
8.3.5 Inheritance rules for the RELOC address attribute
8.3.6 Considerations when using a relative address +offset for a load region
8.4 Execution region descriptions
8.4.1 Components of an execution region description
8.4.2 Syntax of an execution region description
8.4.3 Execution region attributes
8.4.4 Inheritance rules for execution region address attributes
8.4.5 Considerations when using a relative address +offset for execution regions
8.5 Input section descriptions
8.5.1 Components of an input section description
8.5.2 Syntax of an input section description
8.5.3 Examples of module and input section specifications
8.6 Expression evaluation in scatter files
8.6.1 Expression usage in scatter files
8.6.2 Expression rules in scatter files
8.6.3 Execution address built-in functions for use in scatter files
8.6.4 ScatterAssert function and load address related functions
8.6.5 Symbol related function in a scatter file
8.6.6 AlignExpr(expr, align) function
8.6.7 GetPageSize() function
8.6.8 SizeOfHeaders() function
8.6.9 Example of aligning a base address in execution space but still tightly packed in load space
8.6.10 Scatter files containing relative base address load regions and a ZI execution region
9 GNU ld Script Support in armlink
9.1 About GNU ld script support
9.1.1 Summary of GNU ld script support and restrictions
9.1.2 Considerations when linking images and shared objects with ld scripts
9.1.3 Using ld scripts when linking partial objects
9.2 Typical use cases for using ld scripts with armlink
9.3 Important ld script commands that are implemented in armlink
9.4 Specific restrictions for using ld scripts with armlink
9.5 Recommendations for using ld scripts with armlink
9.6 Default GNU ld scripts used by armlink
9.6.1 Default ld script when building an executable
9.6.2 Default ld script when building a shared object
9.6.3 Default ld script when building a partially linked object
9.7 Example GNU ld script for linking an ARM Linux executable
9.8 Example GNU ld script for linking an ARM Linux shared object
9.9 Example GNU ld script for linking partial objects
10 BPABI and SysV Shared Libraries and Executables
10.1 About the Base Platform Application Binary Interface (BPABI)
10.2 Platforms supported by the BPABI
10.3 Features common to all BPABI models
10.3.1 About importing and exporting symbols for BPABI models
10.3.2 Symbol visibility for BPABI models
10.3.3 Automatic import and export for BPABI models
10.3.4 Manual import and export for BPABI models
10.3.5 Symbol versioning for BPABI models
10.3.6 RW compression for BPABI models
10.4 SysV memory model
10.4.1 Customization of the SysV standard memory model
10.4.2 Automatic dynamic symbol table rules in the SysV memory model
10.4.3 Symbol definitions defined for SysV compatibility with glibc
10.4.4 Addressing modes in the SysV memory model
10.4.5 Thread local storage in the SysV memory model
10.4.6 Linker options for SysV models
10.4.7 Linker command-line options for the SysV memory model
10.5 Bare metal and DLL-like memory models
10.5.1 BPABI standard memory model
10.5.2 Customization of the BPABI standard memory model
10.5.3 Linker command-line options for bare metal and DLL-like models
10.5.4 Mandatory symbol versioning in the BPABI DLL-like model
10.5.5 Automatic dynamic symbol table rules in the BPABI DLL-like model
10.5.6 Addressing modes in the BPABI DLL-like model
10.5.7 C++ initialization in the BPABI DLL-like model
10.6 Symbol versioning
10.6.1 Overview of symbol versioning
10.6.2 Embedded symbols
10.6.3 The symbol versioning script file
10.6.4 Example of creating versioned symbols
10.6.5 Linker options for enabling implicit symbol versioning
11 Features of the Base Platform Linking Model
11.1 Restrictions on the use of scatter files with the Base Platform model
11.2 Scatter files for the Base Platform linking model
11.3 Placement of PLT sequences with the Base Platform model
12 Linker Command-line Options
12.1 --add_needed, --no_add_needed
12.2 --add_shared_references, --no_add_shared_references
12.3 --any_contingency
12.4 --any_placement=algorithm
12.5 --any_sort_order=order
12.6 --api, --no_api
12.7 --arm_linux
12.8 --arm_only
12.9 --as_needed, --no_as_needed
12.10 --autoat, --no_autoat
12.11 --base_platform
12.12 --be8
12.13 --be32
12.14 --bestdebug, --no_bestdebug
12.15 --blx_arm_thumb, --no_blx_arm_thumb
12.16 --blx_thumb_arm, --no_blx_thumb_arm
12.17 --bpabi
12.18 --branchnop, --no_branchnop
12.19 --callgraph, --no_callgraph
12.20 --callgraph_file=filename
12.21 --callgraph_output=fmt
12.22 --callgraph_subset=symbol[,symbol,...]
12.23 --cgfile=type
12.24 --cgsymbol=type
12.25 --cgundefined=type
12.26 --combreloc, --no_combreloc
12.27 --comment_section, --no_comment_section
12.28 --compress_debug, --no_compress_debug
12.29 --cpp_compat linker option
12.30 --cppinit, --no_cppinit
12.31 --cpu=list
12.32 --cpu=name
12.33 --crosser_veneershare, --no_crosser_veneershare
12.34 --datacompressor=opt
12.35 --debug, --no_debug
12.36 --diag_error=tag[,tag,…]
12.37 --diag_remark=tag[,tag,…]
12.38 --diag_style=arm|ide|gnu
12.39 --diag_suppress=tag[,tag,…]
12.40 --diag_warning=tag[,tag,…]
12.41 --dll
12.42 --dynamic_debug
12.43 --dynamic_linker=name
12.44 --eager_load_debug, --no_eager_load_debug
12.45 --edit=file_list
12.46 --emit_debug_overlay_relocs
12.47 --emit_debug_overlay_section
12.48 --emit_non_debug_relocs
12.49 --emit_relocs
12.50 --entry=location
12.51 --errors=filename
12.52 --exceptions, --no_exceptions
12.53 --exceptions_tables=action
12.54 --execstack, --no_execstack
12.55 --export_all, --no_export_all
12.56 --export_dynamic, --no_export_dynamic
12.57 --feedback=filename
12.58 --feedback_image=option
12.59 --feedback_type=type
12.60 --filtercomment, --no_filtercomment
12.61 --fini=symbol
12.62 --first=section_id
12.63 --force_explicit_attr
12.64 --force_so_throw, --no_force_so_throw
12.65 --fpic
12.66 --fpu=list
12.67 --fpu=name
12.68 --gnu_linker_defined_syms
12.69 --help
12.70 --import_unresolved, --no_import_unresolved
12.71 --info=topic[,topic,…]
12.72 --info_lib_prefix=opt
12.73 --init=symbol
12.74 --inline, --no_inline
12.75 --inline_type=type
12.76 --inlineveneer, --no_inlineveneer
12.77 input-file-list
12.78 --keep=section_id
12.79 --largeregions, --no_largeregions
12.80 --last=section_id
12.81 --ldpartial
12.82 --legacyalign, --no_legacyalign
12.83 --libpath=pathlist
12.84 --library=name
12.85 --library_type=lib
12.86 --linker_script=ld_script
12.87 --linux_abitag=version_id
12.88 --list=filename
12.89 --list_mapping_symbols, --no_list_mapping_symbols
12.90 --load_addr_map_info, --no_load_addr_map_info
12.91 --locals, --no_locals
12.92 --mangled, --unmangled
12.93 --map, --no_map
12.94 --match=crossmangled
12.95 --max_er_extension=size
12.96 --max_veneer_passes=value
12.97 --max_visibility=type
12.98 --merge, --no_merge
12.99 --muldefweak, --no_muldefweak
12.100 -o filename, --output=filename
12.101 --output_float_abi=option
12.102 --override_visibility
12.103 --pad=num
12.104 --paged
12.105 --pagesize=pagesize
12.106 --partial
12.107 --piveneer, --no_piveneer
12.108 --pltgot=type
12.109 --pltgot_opts=mode
12.110 --predefine="string"
12.111 --prelink_support, --no_prelink_support
12.112 --privacy
12.113 --reduce_paths, --no_reduce_paths
12.114 --ref_cpp_init, --no_ref_cpp_init
12.115 --reloc
12.116 --remarks
12.117 --remove, --no_remove
12.118 --ro_base=address
12.119 --ropi
12.120 --rosplit
12.121 --runpath=pathlist
12.122 --rw_base=address
12.123 --rwpi
12.124 --scanlib, --no_scanlib
12.125 --scatter=filename
12.126 --search_dynamic_libraries, --no_search_dynamic_libraries
12.127 --section_index_display=type
12.128 --shared
12.129 --show_cmdline
12.130 --show_full_path
12.131 --show_parent_lib
12.132 --show_sec_idx
12.133 --soname=name
12.134 --sort=algorithm
12.135 --split
12.136 --startup=symbol, --no_startup
12.137 --strict
12.138 --strict_enum_size, --no_strict_enum_size
12.139 --strict_flags, --no_strict_flags
12.140 --strict_ph, --no_strict_ph
12.141 --strict_relocations, --no_strict_relocations
12.142 --strict_symbols, --no_strict_symbols
12.143 --strict_visibility, --no_strict_visibility
12.144 --strict_wchar_size, --no_strict_wchar_size
12.145 --symbolic
12.146 --symbols, --no_symbols
12.147 --symdefs=filename
12.148 --symver_script=filename
12.149 --symver_soname
12.150 --sysroot=path
12.151 --sysv
12.152 --tailreorder, --no_tailreorder
12.153 --thumb2_library, --no_thumb2_library
12.154 --tiebreaker=option
12.155 --unaligned_access, --no_unaligned_access
12.156 --undefined=symbol
12.157 --undefined_and_export=symbol
12.158 --unresolved=symbol
12.159 --use_definition_visibility
12.160 --use_sysv_default_script, --no_use_sysv_default_script
12.161 --userlibpath=pathlist
12.162 --veneerinject, --no_veneerinject
12.163 --veneer_inject_type=type
12.164 --veneer_pool_size=size
12.165 --veneershare, --no_veneershare
12.166 --verbose
12.167 --version_number
12.168 --vfemode=mode
12.169 --via=filename
12.170 --vsn
12.171 --xo_base=address
12.172 --xref, --no_xref
12.173 --xrefdbg, --no_xrefdbg
12.174 --xref{from|to}=object(section)
12.175 --zi_base=address
13 Linker Steering File Command Reference
13.1 EXPORT steering file command
13.2 HIDE steering file command
13.3 IMPORT steering file command
13.4 RENAME steering file command
13.5 REQUIRE steering file command
13.6 RESOLVE steering file command
13.7 SHOW steering file command
14 Via File Syntax
14.1 Overview of via files
14.2 Via file syntax rules
A armlink Document Revisions
A.1 Revisions for armlink User Guide

List of Figures

3-1 Relationship between sections, regions, and segments
3-2 Load and execution memory maps for an image without an XO section
3-3 Load and execution memory maps for an image with an XO section
3-4 Simple Type 1 image
3-5 Simple Type 2 image
3-6 Simple Type 3 image
7-1 Simple scatter-loaded memory map
7-2 Complex memory map
7-3 Memory map for fixed execution regions
7-4 .ANY contingency
7-5 Reserving a region for the stack
8-1 Components of a scatter file
8-2 Components of a load region description
8-3 Components of an execution region description
8-4 Components of an input section description
10-1 BPABI tool flow

List of Tables

3-1 Comparing load and execution views
3-2 Comparison of scatter file and equivalent command-line options
4-1 Inlining small functions
6-1 Image$$ execution region symbols
6-2 Load$$ execution region symbols
6-3 Load$$LR$$ load region symbols
6-4 Image symbols
6-5 Section-related symbols
6-6 Steering file command summary
7-1 Input section properties for placement of .ANY sections
7-2 Input section properties for placement of sections with next_fit
7-3 Input section properties for sections_a.o
7-4 Input section properties for sections_b.o
7-5 Sort order for descending_size algorithm
7-6 Sort order for cmdline algorithm
7-7 Using relative offset in overlays
8-1 BNF notation
8-2 Execution address related functions
8-3 Load address related functions
10-1 Symbol visibility
10-2 Turning on SysV support
10-3 Turning on BPABI support
12-1 Supported ARM architectures
12-2 Data compressor algorithms
12-3 GNU equivalent of input sections
A-1 Differences between issue L and issue M
A-2 Differences between issue K and issue L
A-3 Differences between issue J and issue K
A-4 Differences between issue I and issue J
A-5 Differences between issue H and issue I
A-6 Differences between Issue G and Issue H
A-7 Differences between Issue F and Issue G
A-8 Differences between Issue E and Issue F
A-9 Differences between Issue D and Issue E
A-10 Differences between Issue C and Issue D
A-11 Differences between Issue B and Issue C
A-12 Differences between Issue A and Issue B

Release Information

Document History
Issue Date Confidentiality Change
A 28 May 2010 Non-Confidential ARM Compiler v4.1 Release
B 30 September 2010 Non-Confidential Update 1 for ARM Compiler v4.1
C 28 January 2011 Non-Confidential Update 2 for ARM Compiler v4.1 Patch 3
D 30 April 2011 Non-Confidential ARM Compiler v5.0 Release
E 29 July 2011 Non-Confidential Update 1 for ARM Compiler v5.0
F 30 September 2011 Non-Confidential ARM Compiler v5.01 Release
G 29 February 2012 Non-Confidential Document update 1 for ARM Compiler v5.01 Release
H 27 July 2012 Non-Confidential ARM Compiler v5.02 Release
I 31 January 2013 Non-Confidential ARM Compiler v5.03 Release
J 27 November 2013 Non-Confidential ARM Compiler v5.04 Release
K 10 September 2014 Non-Confidential ARM Compiler v5.05 Release
L 29 July 2015 Non-Confidential ARM Compiler v5.06 Release
M 11 November 2016 Non-Confidential Update 3 for ARM Compiler v5.06 Release

Non-Confidential Proprietary Notice

This document is protected by copyright and other related rights and the practice or implementation of the information contained in this document may be protected by one or more patents or pending patent applications. No part of this document may be reproduced in any form by any means without the express prior written permission of ARM. No license, express or implied, by estoppel or otherwise to any intellectual property rights is granted by this document unless specifically stated.

Your access to the information in this document is conditional upon your acceptance that you will not use or permit others to use the information for the purposes of determining whether implementations infringe any third party patents.

THIS DOCUMENT IS PROVIDED “AS IS”. ARM PROVIDES NO REPRESENTATIONS AND NO WARRANTIES, EXPRESS, IMPLIED OR STATUTORY, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTABILITY, SATISFACTORY QUALITY, NON-INFRINGEMENT OR FITNESS FOR A PARTICULAR PURPOSE WITH RESPECT TO THE DOCUMENT. For the avoidance of doubt, ARM makes no representation with respect to, and has undertaken no analysis to identify or understand the scope and content of, third party patents, copyrights, trade secrets, or other rights.

This document may include technical inaccuracies or typographical errors.

TO THE EXTENT NOT PROHIBITED BY LAW, IN NO EVENT WILL ARM BE LIABLE FOR ANY DAMAGES, INCLUDING WITHOUT LIMITATION ANY DIRECT, INDIRECT, SPECIAL, INCIDENTAL, PUNITIVE, OR CONSEQUENTIAL DAMAGES, HOWEVER CAUSED AND REGARDLESS OF THE THEORY OF LIABILITY, ARISING OUT OF ANY USE OF THIS DOCUMENT, EVEN IF ARM HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

This document consists solely of commercial items. You shall be responsible for ensuring that any use, duplication or disclosure of this document complies fully with any relevant export laws and regulations to assure that this document or any portion thereof is not exported, directly or indirectly, in violation of such export laws. Use of the word “partner” in reference to ARM’s customers is not intended to create or refer to any partnership relationship with any other company. ARM may make changes to this document at any time and without notice.

If any of the provisions contained in these terms conflict with any of the provisions of any signed written agreement covering this document with ARM, then the signed written agreement prevails over and supersedes the conflicting provisions of these terms. This document may be translated into other languages for convenience, and you agree that if there is any conflict between the English version of this document and any translation, the terms of the English version of the Agreement shall prevail.

Words and logos marked with ® or ™ are registered trademarks or trademarks of ARM Limited or its affiliates in the EU and/or elsewhere. All rights reserved. Other brands and names mentioned in this document may be the trademarks of their respective owners. Please follow ARM’s trademark usage guidelines at http://www.arm.com/about/trademark-usage-guidelines.php

Copyright © 2010-2016, ARM Limited or its affiliates. All rights reserved.

ARM Limited. Company 02557590 registered in England.

110 Fulbourn Road, Cambridge, England CB1 9NJ.

LES-PRE-20349

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.

Unrestricted Access is an ARM internal classification.

Product Status

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

Web Address

Non-ConfidentialPDF file icon PDF versionARM DUI0474M
Copyright © 2010-2016 ARM Limited or its affiliates. All rights reserved.