ARM® Compiler armlink User Guide

Version 6.4


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.2 Linker command-line syntax
1.3 Linker command-line options listed by group
1.4 What the linker does when constructing an executable image
1.5 Support level definitions
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
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.1.6 Restrictions on image structure
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 T32 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.6.6 Generation of secure gateway veneers
3.7 Weak references and definitions
3.8 How the linker performs library searching, selection, and scanning
3.9 How the linker searches for the ARM standard libraries
3.10 Specifying user libraries when linking
3.11 How the linker resolves references
3.12 The strict family of linker options
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 Optimization with RW data compression
4.4.1 How the linker chooses a compressor
4.4.2 Options available to override the compression algorithm used by the linker
4.4.3 How compression is applied
4.4.4 Considerations when working with RW data compression
4.5 Function inlining with the linker
4.6 Factors that influence function inlining
4.7 About branches that optimize to a NOP
4.8 Linker reordering of tail calling sections
4.9 Restrictions on reordering of tail calling sections
4.10 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
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.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 CMSE veneer sections for a Secure image
7.7 Placement of sections with overlays
7.8 Reserving an empty region
7.9 Placement of ARM C and C++ library code
7.9.1 Specifying ARM standard C and C++ libraries in a scatter file
7.9.2 Example of placing code in a root region
7.9.3 Example of placing ARM C library code
7.9.4 Example of placing ARM C++ library code
7.10 Creation of regions on page boundaries
7.11 Overalignment of execution regions and input sections
7.12 Preprocessing of a scatter file
7.13 Example of using expression evaluation in a scatter file to avoid padding
7.14 Equivalent scatter-loading descriptions for simple images
7.14.1 Command-line options for creating simple images
7.14.2 Type 1 image, one load region and contiguous execution regions
7.14.3 Type 2 image, one load region and non-contiguous execution regions
7.14.4 Type 3 image, multiple load regions and non-contiguous execution regions
7.15 How the linker resolves multiple matches when processing scatter files
7.16 How the linker resolves path names when processing scatter files
7.17 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 select patterns
8.6 Expression evaluation in scatter files
8.6.1 Methods of specifying numeric constants for expression evaluation
8.6.2 Available operators for expression evaluation
8.6.3 Expression usage in scatter files
8.6.4 Expression rules in scatter files
8.6.5 Execution address built-in functions for use in scatter files
8.6.6 ScatterAssert function and load address related functions
8.6.7 Symbol related function in a scatter file
8.6.8 AlignExpr(expr, align) function
8.6.9 GetPageSize() function
8.6.10 SizeOfHeaders() function
8.6.11 Example of aligning a base address in execution space but still tightly packed in load space
8.7 Scatter files containing relative base address load regions and a ZI execution region
9 BPABI Shared Libraries and Executables
9.1 About the Base Platform Application Binary Interface (BPABI)
9.2 Platforms supported by the BPABI
9.3 Features common to all BPABI models
9.3.1 About importing and exporting symbols for BPABI models
9.3.2 Symbol visibility for BPABI models
9.3.3 Automatic import and export for BPABI models
9.3.4 Manual import and export for BPABI models
9.3.5 Symbol versioning for BPABI models
9.3.6 RW compression for BPABI models
9.4 Bare metal and DLL-like memory models
9.4.1 BPABI standard memory model
9.4.2 Customization of the BPABI standard memory model
9.4.3 Linker command-line options for bare metal and DLL-like models
9.4.4 Mandatory symbol versioning in the BPABI DLL-like model
9.4.5 Automatic dynamic symbol table rules in the BPABI DLL-like model
9.4.6 Addressing modes in the BPABI DLL-like model
9.4.7 C++ initialization in the BPABI DLL-like model
9.5 Symbol versioning
9.5.1 Overview of symbol versioning
9.5.2 Embedded symbols
9.5.3 The symbol versioning script file
9.5.4 Example of creating versioned symbols
9.5.5 Linker options for enabling implicit symbol versioning
10 Features of the Base Platform Linking Model
10.1 Restrictions on the use of scatter files with the Base Platform model
10.2 Scatter files for the Base Platform linking model
10.3 Placement of PLT sequences with the Base Platform model
11 Linker Command-line Options
11.1 --any_contingency
11.2 --any_placement=algorithm
11.3 --any_sort_order=order
11.4 --api, --no_api
11.5 --autoat, --no_autoat
11.6 --bare_metal_pie
11.7 --base_platform
11.8 --bestdebug, --no_bestdebug
11.9 --blx_arm_thumb, --no_blx_arm_thumb
11.10 --blx_thumb_arm, --no_blx_thumb_arm
11.11 --bpabi
11.12 --branchnop, --no_branchnop
11.13 --callgraph, --no_callgraph
11.14 --callgraph_file=filename
11.15 --callgraph_output=fmt
11.16 --callgraph_subset=symbol[,symbol,...]
11.17 --cgfile=type
11.18 --cgsymbol=type
11.19 --cgundefined=type
11.20 --comment_section, --no_comment_section
11.21 --compress_debug, --no_compress_debug
11.22 --cppinit, --no_cppinit
11.23 --cpu=list
11.24 --cpu=name
11.25 --crosser_veneershare, --no_crosser_veneershare
11.26 --datacompressor=opt
11.27 --debug, --no_debug
11.28 --diag_error=tag[,tag,…]
11.29 --diag_remark=tag[,tag,…]
11.30 --diag_style=arm|ide|gnu
11.31 --diag_suppress=tag[,tag,…]
11.32 --diag_warning=tag[,tag,…]
11.33 --dll
11.34 --eager_load_debug, --no_eager_load_debug
11.35 --eh-frame-hdr
11.36 --edit=file_list
11.37 --emit_debug_overlay_relocs
11.38 --emit_debug_overlay_section
11.39 --emit_non_debug_relocs
11.40 --emit_relocs
11.41 --entry=location
11.42 --errors=filename
11.43 --exceptions
11.44 --exceptions_tables=action
11.45 --export_all, --no_export_all
11.46 --export_dynamic, --no_export_dynamic
11.47 --filtercomment, --no_filtercomment
11.48 --fini=symbol
11.49 --first=section_id
11.50 --force_explicit_attr
11.51 --force_so_throw, --no_force_so_throw
11.52 --fpic
11.53 --fpu=list
11.54 --fpu=name
11.55 --gnu_linker_defined_syms
11.56 --help
11.57 --import_cmse_lib_in=filename
11.58 --import_cmse_lib_out=filename
11.59 --info=topic[,topic,…]
11.60 --info_lib_prefix=opt
11.61 --init=symbol
11.62 --inline, --no_inline
11.63 --inlineveneer, --no_inlineveneer
11.64 input-file-list
11.65 --keep=section_id
11.66 --keep_intermediate
11.67 --largeregions, --no_largeregions
11.68 --last=section_id
11.69 --legacyalign, --no_legacyalign
11.70 --libpath=pathlist
11.71 --library=name
11.72 --library_type=lib
11.73 --list=filename
11.74 --list_mapping_symbols, --no_list_mapping_symbols
11.75 --load_addr_map_info, --no_load_addr_map_info
11.76 --locals, --no_locals
11.77 --lto, --no_lto [ALPHA]
11.78 --lto_keep_all_symbols, --no_lto_keep_all_symbols [ALPHA]
11.79 --lto_set_intermediate_filename [ALPHA]
11.80 --lto_set_relocation_model [ALPHA]
11.81 --mangled, --unmangled
11.82 --map, --no_map
11.83 --match=crossmangled
11.84 --max_veneer_passes=value
11.85 --max_visibility=type
11.86 --merge, --no_merge
11.87 --muldefweak, --no_muldefweak
11.88 -o filename, --output=filename
11.89 --output_float_abi=option
11.90 --override_visibility
11.91 --pad=num
11.92 --paged
11.93 --pagesize=pagesize
11.94 --partial
11.95 --pie
11.96 --piveneer, --no_piveneer
11.97 --pltgot=type
11.98 --pltgot_opts=mode
11.99 --predefine="string"
11.100 --preinit, --no_preinit
11.101 --privacy
11.102 --ref_cpp_init, --no_ref_cpp_init
11.103 --ref_pre_init, --no_ref_pre_init
11.104 --reloc
11.105 --remarks
11.106 --remove, --no_remove
11.107 --ro_base=address
11.108 --ropi [BETA]
11.109 --rosplit
11.110 --rw_base=address
11.111 --rwpi [BETA]
11.112 --scanlib, --no_scanlib
11.113 --scatter=filename
11.114 --section_index_display=type
11.115 --show_cmdline
11.116 --show_full_path
11.117 --show_parent_lib
11.118 --show_sec_idx
11.119 --sort=algorithm
11.120 --split
11.121 --startup=symbol, --no_startup
11.122 --stdlib
11.123 --strict
11.124 --strict_enum_size, --no_strict_enum_size
11.125 --strict_flags, --no_strict_flags
11.126 --strict_ph, --no_strict_ph
11.127 --strict_relocations, --no_strict_relocations
11.128 --strict_symbols, --no_strict_symbols
11.129 --strict_visibility, --no_strict_visibility
11.130 --strict_wchar_size, --no_strict_wchar_size
11.131 --symbols, --no_symbols
11.132 --symdefs=filename
11.133 --symver_script=filename
11.134 --symver_soname
11.135 --tailreorder, --no_tailreorder
11.136 --tiebreaker=option
11.137 --unaligned_access, --no_unaligned_access
11.138 --undefined=symbol
11.139 --undefined_and_export=symbol
11.140 --unresolved=symbol
11.141 --use_definition_visibility
11.142 --userlibpath=pathlist
11.143 --veneerinject,--no_veneerinject
11.144 --veneer_inject_type=type
11.145 --veneer_pool_size=size
11.146 --veneershare, --no_veneershare
11.147 --verbose
11.148 --version_number
11.149 --via=filename
11.150 --vsn
11.151 --xo_base=address
11.152 --xref, --no_xref
11.153 --xrefdbg, --no_xrefdbg
11.154 --xref{from|to}=object(section)
11.155 --zi_base=address
12 Linker Steering File Command Reference
12.1 EXPORT steering file command
12.2 HIDE steering file command
12.3 IMPORT steering file command
12.4 RENAME steering file command
12.5 REQUIRE steering file command
12.6 RESOLVE steering file command
12.7 SHOW steering file command
13 Via File Syntax
13.1 Overview of via files
13.2 Via file syntax rules

List of Figures

1-1 Integration boundaries in ARM Compiler 6.
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
9-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
9-1 Symbol visibility
9-2 Turning on BPABI support
11-1 Supported ARM architectures
11-2 Data compressor algorithms
11-3 GNU equivalent of input sections
11-4 Link time optimization dependencies

Release Information

Document History
Issue Date Confidentiality Change
A 14 March 2014 Non-Confidential ARM Compiler v6.00 Release
B 15 December 2014 Non-Confidential ARM Compiler v6.01 Release
C 30 June 2015 Non-Confidential ARM Compiler v6.02 Release
D 18 November 2015 Non-Confidential ARM Compiler v6.3 Release
E 24 February 2016 Non-Confidential ARM Compiler v6.4 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.
Copyright © [2014-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 DUI0803E
Copyright © 2014-2016 ARM. All rights reserved.