Keil Logo

ARM Compiler v5.06 for µVision armlink User Guide

ARM® Compiler v5.06 for µVision® armlink User Guide

Version 5


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 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
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 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.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
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.1.8 Scatter file with link to bit-band objects
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 Linker Command-line Options
9.1 --any_contingency
9.2 --any_placement=algorithm
9.3 --any_sort_order=order
9.4 --api, --no_api
9.5 --arm_only
9.6 --autoat, --no_autoat
9.7 --be8
9.8 --be32
9.9 --bestdebug, --no_bestdebug
9.10 --blx_arm_thumb, --no_blx_arm_thumb
9.11 --blx_thumb_arm, --no_blx_thumb_arm
9.12 --branchnop, --no_branchnop
9.13 --callgraph, --no_callgraph
9.14 --callgraph_file=filename
9.15 --callgraph_output=fmt
9.16 --callgraph_subset=symbol[,symbol,...]
9.17 --cgfile=type
9.18 --cgsymbol=type
9.19 --cgundefined=type
9.20 --comment_section, --no_comment_section
9.21 --compress_debug, --no_compress_debug
9.22 --cpp_compat linker option
9.23 --cppinit, --no_cppinit
9.24 --cpu=list
9.25 --cpu=name
9.26 --crosser_veneershare, --no_crosser_veneershare
9.27 --datacompressor=opt
9.28 --debug, --no_debug
9.29 --diag_error=tag[,tag,…]
9.30 --diag_remark=tag[,tag,…]
9.31 --diag_style=arm|ide|gnu
9.32 --diag_suppress=tag[,tag,…]
9.33 --diag_warning=tag[,tag,…]
9.34 --eager_load_debug, --no_eager_load_debug
9.35 --edit=file_list
9.36 --emit_debug_overlay_relocs
9.37 --emit_debug_overlay_section
9.38 --emit_non_debug_relocs
9.39 --emit_relocs
9.40 --entry=location
9.41 --errors=filename
9.42 --exceptions, --no_exceptions
9.43 --feedback=filename
9.44 --feedback_image=option
9.45 --feedback_type=type
9.46 --filtercomment, --no_filtercomment
9.47 --fini=symbol
9.48 --first=section_id
9.49 --force_explicit_attr
9.50 --fpu=list
9.51 --fpu=name
9.52 --help
9.53 --info=topic[,topic,…]
9.54 --info_lib_prefix=opt
9.55 --init=symbol
9.56 --inline, --no_inline
9.57 --inline_type=type
9.58 --inlineveneer, --no_inlineveneer
9.59 input-file-list
9.60 --keep=section_id
9.61 --largeregions, --no_largeregions
9.62 --last=section_id
9.63 --ldpartial
9.64 --legacyalign, --no_legacyalign
9.65 --libpath=pathlist
9.66 --library_type=lib
9.67 --liclinger=seconds
9.68 --list=filename
9.69 --list_mapping_symbols, --no_list_mapping_symbols
9.70 --load_addr_map_info, --no_load_addr_map_info
9.71 --locals, --no_locals
9.72 --mangled, --unmangled
9.73 --map, --no_map
9.74 --match=crossmangled
9.75 --max_er_extension=size
9.76 --max_veneer_passes=value
9.77 --max_visibility=type
9.78 --merge, --no_merge
9.79 --muldefweak, --no_muldefweak
9.80 -o filename, --output=filename
9.81 --output_float_abi=option
9.82 --override_visibility
9.83 --pad=num
9.84 --paged
9.85 --pagesize=pagesize
9.86 --partial
9.87 --piveneer, --no_piveneer
9.88 --predefine="string"
9.89 --reduce_paths, --no_reduce_paths
9.90 --ref_cpp_init, --no_ref_cpp_init
9.91 --reloc
9.92 --remarks
9.93 --remove, --no_remove
9.94 --ro_base=address
9.95 --ropi
9.96 --rosplit
9.97 --rw_base=address
9.98 --rwpi
9.99 --scanlib, --no_scanlib
9.100 --scatter=filename
9.101 --section_index_display=type
9.102 --show_cmdline
9.103 --show_full_path
9.104 --show_parent_lib
9.105 --show_sec_idx
9.106 --sort=algorithm
9.107 --split
9.108 --startup=symbol, --no_startup
9.109 --strict
9.110 --strict_enum_size, --no_strict_enum_size
9.111 --strict_flags, --no_strict_flags
9.112 --strict_ph, --no_strict_ph
9.113 --strict_relocations, --no_strict_relocations
9.114 --strict_symbols, --no_strict_symbols
9.115 --strict_visibility, --no_strict_visibility
9.116 --strict_wchar_size, --no_strict_wchar_size
9.117 --symbols, --no_symbols
9.118 --symdefs=filename
9.119 --tailreorder, --no_tailreorder
9.120 --thumb2_library, --no_thumb2_library
9.121 --tiebreaker=option
9.122 --unaligned_access, --no_unaligned_access
9.123 --undefined=symbol
9.124 --undefined_and_export=symbol
9.125 --unresolved=symbol
9.126 --use_definition_visibility
9.127 --userlibpath=pathlist
9.128 --veneerinject, --no_veneerinject
9.129 --veneer_inject_type=type
9.130 --veneer_pool_size=size
9.131 --veneershare, --no_veneershare
9.132 --verbose
9.133 --version_number
9.134 --vfemode=mode
9.135 --via=filename
9.136 --vsn
9.137 --xo_base=address
9.138 --xref, --no_xref
9.139 --xrefdbg, --no_xrefdbg
9.140 --xref{from|to}=object(section)
9.141 --zi_base=address
10 Linker Steering File Command Reference
10.1 EXPORT steering file command
10.2 HIDE steering file command
10.3 IMPORT steering file command
10.4 RENAME steering file command
10.5 REQUIRE steering file command
10.6 RESOLVE steering file command
10.7 SHOW steering file command
11 Via File Syntax
11.1 Overview of via files
11.2 Via file syntax rules

Release Information

Document History
Issue Date Confidentiality Change
A May 2007 Non-Confidential Release for RVCT v3.1 for µVision
B December 2008 Non-Confidential Release for RVCT v4.0 for µVision
C June 2011 Non-Confidential Release for ARM Compiler v4.1 for µVision
D July 2012 Non-Confidential Release for ARM Compiler v5.02 for µVision
E 30 May 2014 Non-Confidential Release for ARM Compiler v5.04 for µVision
F 12 December 2014 Non-Confidential Release for ARM Compiler v5.05 for µVision
G 15 August 2015 Non-Confidential Release for ARM Compiler v5.06 for µVision
H 17 June 2016 Non-Confidential Release for ARM Compiler v5.06 update 3 for µVision

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 © 2007, 2008, 2011, 2012, 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 DUI0377H
Copyright © 2007, 2008, 2011, 2012, 2014-2016 ARM. All rights reserved. 
  Arm logo
Important information

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies.

Change Settings

Privacy Policy Update

Arm’s Privacy Policy has been updated. By continuing to use our site, you consent to Arm’s Privacy Policy. Please review our Privacy Policy to learn more about our collection, use and transfers
of your data.