ARM® Compiler armlink User Guide

Version 5.04


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.2 Linker command-line syntax
1.3 What the linker can accept as input
1.4 What the linker outputs
1.5 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.2 Input sections, output sections, regions, and program segments
3.3 Load view and execution view of an image
3.4 Methods of specifying an image memory map with the linker
3.5 Types of simple image
3.6 Type 1 image structure, one load region and contiguous execution regions
3.7 Type 2 image structure, one load region and non-contiguous execution regions
3.8 Type 3 image structure, multiple load regions and non-contiguous execution regions
3.9 Image entry points
3.10 The initial entry point for an image
3.11 Section placement with the linker
3.12 Section placement with the FIRST and LAST attributes
3.13 Section alignment with the linker
3.14 Linker support for creating demand-paged files
3.15 Linker reordering of execution regions containing Thumb code
3.16 Overview of veneers
3.17 Veneer sharing
3.18 Veneer types
3.19 Generation of position independent to absolute veneers
3.20 Reuse of veneers when scatter-loading
3.21 Command-line options used to control the generation of C++ exception tables
3.22 Weak references and definitions
3.23 How the linker performs library searching, selection, and scanning
3.24 How the linker searches for the ARM standard libraries
3.25 Specifying user libraries when linking
3.26 How the linker resolves references
3.27 The strict family of linker options
3.28 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.8 How the linker chooses a compressor
4.9 Options available to override the compression algorithm used by the linker
4.10 How compression is applied
4.11 Considerations when working with RW data compression
4.12 Function inlining with the linker
4.13 Factors that influence function inlining
4.14 About branches that optimize to a NOP
4.15 Linker reordering of tail calling sections
4.16 Restrictions on reordering of tail calling sections
4.17 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.4 Image$$ execution region symbols
6.5 Load$$ execution region symbols
6.6 Load$$LR$$ load region symbols
6.7 Region name values when not scatter-loading
6.8 Linker defined symbols and scatter files
6.9 Methods of importing linker-defined symbols in C and C++
6.10 Methods of importing linker-defined symbols in ARM assembly language
6.11 Section-related symbols
6.12 Image symbols
6.13 Input section symbols
6.14 Access symbols in another image
6.15 Creating a symdefs file
6.16 Outputting a subset of the global symbols
6.17 Reading a symdefs file
6.18 Symdefs file format
6.19 What is a steering file?
6.20 Specifying steering files on the linker command-line
6.21 Steering file command summary
6.22 Steering file format
6.23 Hide and rename global symbols with a steering file
6.24 Use of $Super$$ and $Sub$$ to patch symbol definitions
7 Scatter-loading Features
7.1 About scatter-loading
7.2 When to use scatter-loading
7.3 Scatter-loading command-line options
7.4 Scatter-loading images with a simple memory map
7.5 Scatter-loading images with a complex memory map
7.6 Linker-defined symbols that are not defined when scatter-loading
7.7 Specifying stack and heap using the scatter file
7.8 Root execution regions
7.9 Root execution regions and the ABSOLUTE attribute
7.10 Root execution regions and the FIXED attribute
7.11 Methods of placing functions and data at specific addresses
7.12 Example of how to explicitly place a named section with scatter-loading
7.13 Placement of unassigned sections with the .ANY module selector
7.14 Examples of using placement algorithms for .ANY sections
7.15 Example of next_fit algorithm showing behavior of full regions, selectors, and priority
7.16 Examples of using sorting algorithms for .ANY sections
7.17 Placement of veneer input sections in a scatter file
7.18 Placement of code and data with __attribute__((section("name")))
7.19 Placement of __at sections at a specific address
7.20 Restrictions on placing __at sections
7.21 Automatic placement of __at sections
7.22 Manual placement of __at sections
7.23 Placement of a key in flash memory with an __at section
7.24 Mapping a structure over a peripheral register with an __at section
7.25 Placement of sections with overlays
7.26 Placement of ARM C and C++ library code
7.27 Example of placing code in a root region
7.28 Example of placing ARM C library code
7.29 Example of placing ARM C++ library code
7.30 Example of placing ARM library helper functions
7.31 Reserving an empty region
7.32 Creation of regions on page boundaries
7.33 Overalignment of execution regions and input sections
7.34 Preprocessing of a scatter file
7.35 Available operators for expression evaluation
7.36 Example of using expression evaluation in a scatter file to avoid padding
7.37 Equivalent scatter-loading descriptions for simple images
7.38 Type 1 image, one load region and contiguous execution regions
7.39 Type 2 image, one load region and non-contiguous execution regions
7.40 Type 3 image, multiple load regions and non-contiguous execution regions
7.41 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.4 Syntax of a load region description
8.5 Load region attributes
8.6 Execution region descriptions
8.7 Syntax of an execution region description
8.8 Execution region attributes
8.9 Address attributes for load and execution regions
8.10 Considerations when using a relative address +offset for load regions
8.11 Considerations when using a relative address +offset for execution regions
8.12 Inheritance rules for load region address attributes
8.13 Inheritance rules for execution region address attributes
8.14 Inheritance rules for the RELOC address attribute
8.15 Input section descriptions
8.16 Syntax of an input section description
8.17 How the linker resolves multiple matches when processing scatter files
8.18 Behavior when .ANY sections overflow because of linker-generated content
8.19 How the linker resolves path names when processing scatter files
8.20 Expression evaluation in scatter files
8.21 Expression usage in scatter files
8.22 Expression rules in scatter files
8.23 Execution address built-in functions for use in scatter files
8.24 Scatter files containing relative base address load regions and a ZI execution region
8.25 ScatterAssert function and load address related functions
8.26 Symbol related function in a scatter file
8.27 Example of aligning a base address in execution space but still tightly packed in load space
8.28 AlignExpr(expr, align) function
8.29 GetPageSize() function
8.30 SizeOfHeaders() function
9 GNU ld Script Support in armlink
9.1 About GNU ld script support and restrictions
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.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.4 About importing and exporting symbols for BPABI models
10.5 Symbol visibility for BPABI models
10.6 Automatic import and export for BPABI models
10.7 Manual import and export for BPABI models
10.8 Symbol versioning for BPABI models
10.9 RW compression for BPABI models
10.10 Linker options for SysV models
10.11 SysV memory model
10.12 Automatic dynamic symbol table rules in the SysV memory model
10.13 Addressing modes in the SysV memory model
10.14 Thread local storage in the SysV memory model
10.15 Linker command-line options for the SysV memory model
10.16 Changes to command-line defaults with the SysV memory model
10.17 Linker options for bare metal and DLL-like models
10.18 Bare metal and DLL-like standard memory model
10.19 Mandatory symbol versioning in the BPABI DLL-like model
10.20 Automatic dynamic symbol table rules in the BPABI DLL-like model
10.21 Addressing modes in the BPABI DLL-like model
10.22 C++ initialization in the BPABI DLL-like model
10.23 Symbol versioning
10.24 The symbol versioning script file
10.25 Example of creating versioned symbols
10.26 Embedded symbols
10.27 Linker options for enabling implicit symbol versioning
10.28 Linker command-line options for the BPABI DLL-like model
11 Features of the Base Platform Linking Model
11.1 Restrictions on the use of scatter files with the Base Platform model
11.2 Example scatter file 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 --cgfile=type
12.23 --cgsymbol=type
12.24 --cgundefined=type
12.25 --combreloc, --no_combreloc
12.26 --comment_section, --no_comment_section
12.27 --compress_debug, --no_compress_debug
12.28 --cppinit, --no_cppinit
12.29 --cpu=list
12.30 --cpu=name
12.31 --crosser_veneershare, --no_crosser_veneershare
12.32 --datacompressor=opt
12.33 --debug, --no_debug
12.34 --device=list
12.35 --device=name
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 --keep_protected_symbols
12.80 --largeregions, --no_largeregions
12.81 --last=section_id
12.82 --ldpartial
12.83 --legacyalign, --no_legacyalign
12.84 --libpath=pathlist
12.85 --library=name
12.86 --library_type=lib
12.87 --licretry
12.88 --linker_script=ld_script
12.89 --linux_abitag=version_id
12.90 --list=filename
12.91 --list_mapping_symbols, --no_list_mapping_symbols
12.92 --load_addr_map_info, --no_load_addr_map_info
12.93 --locals, --no_locals
12.94 --mangled, --unmangled
12.95 --map, --no_map
12.96 --match=crossmangled
12.97 --max_er_extension=size
12.98 --max_veneer_passes=value
12.99 --max_visibility=type
12.100 --merge, --no_merge
12.101 --muldefweak, --no_muldefweak
12.102 --output=filename
12.103 --override_visibility
12.104 --pad=num
12.105 --paged
12.106 --pagesize=pagesize
12.107 --partial
12.108 --piveneer, --no_piveneer
12.109 --pltgot=type
12.110 --pltgot_opts=mode
12.111 --predefine="string"
12.112 --prelink_support, --no_prelink_support
12.113 --privacy
12.114 --reduce_paths, --no_reduce_paths
12.115 --ref_cpp_init, --no_ref_cpp_init
12.116 --reloc
12.117 --remarks
12.118 --remove, --no_remove
12.119 --ro_base=address
12.120 --ropi
12.121 --rosplit
12.122 --runpath=pathlist
12.123 --rw_base=address
12.124 --rwpi
12.125 --scanlib, --no_scanlib
12.126 --scatter=filename
12.127 --search_dynamic_libraries, --no_search_dynamic_libraries
12.128 --section_index_display=type
12.129 --shared
12.130 --show_cmdline
12.131 --show_full_path
12.132 --show_parent_lib
12.133 --show_sec_idx
12.134 --soname=name
12.135 --sort=algorithm
12.136 --split
12.137 --startup=symbol, --no_startup
12.138 --strict
12.139 --strict_enum_size, --no_strict_enum_size
12.140 --strict_flags, --no_strict_flags
12.141 --strict_ph, --no_strict_ph
12.142 --strict_relocations, --no_strict_relocations
12.143 --strict_symbols, --no_strict_symbols
12.144 --strict_visibility, --no_strict_visibility
12.145 --strict_wchar_size, --no_strict_wchar_size
12.146 --symbolic
12.147 --symbols, --no_symbols
12.148 --symdefs=filename
12.149 --symver_script=filename
12.150 --symver_soname
12.151 --sysroot=path
12.152 --sysv
12.153 --tailreorder, --no_tailreorder
12.154 --thumb2_library, --no_thumb2_library
12.155 --tiebreaker=option
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 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
8-5 .ANY contingency
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 I and issue J
A-2 Differences between issue H and issue I
A-3 Differences between Issue G and Issue H
A-4 Differences between Issue F and Issue G
A-5 Differences between Issue E and Issue F
A-6 Differences between Issue D and Issue E
A-7 Differences between Issue C and Issue D
A-8 Differences between Issue B and Issue C
A-9 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

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.

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 DUI0474J
Copyright © 2010-2013 ARM. All rights reserved.