Technical Support
On-Line Manuals
Compiler Reference Guide
Preface
Arm Compiler Tools Overview
armclang Reference
armlink Reference
armlink Command-line Options
--any_contingency
--any_placement=algorithm
--any_sort_order=order
--api, --no_api
--autoat, --no_autoat
--bare_metal_pie
--base_platform
--be8
--be32
--bestdebug, --no_bestdebug
--blx_arm_thumb, --no_blx_arm_thumb
--blx_thumb_arm, --no_blx_thumb_arm
--bpabi
--branchnop, --no_branchnop
--callgraph, --no_callgraph
--callgraph_file=filename
--callgraph_output=fmt
--callgraph_subset=symbol[,symbol,...]
--cgfile=type
--cgsymbol=type
--cgundefined=type
--comment_section, --no_comment_section
--cppinit, --no_cppinit
--cpu=list (armlink)
--cpu=name (armlink)
--crosser_veneershare, --no_crosser_veneershare
--dangling-debug-address=address
--datacompressor=opt
--debug, --no_debug
--diag_error=tag[,tag,…] (armlink)
--diag_remark=tag[,tag,…] (armlink)
--diag_style={arm|ide|gnu} (armlink)
--diag_suppress=tag[,tag,…] (armlink)
--diag_warning=tag[,tag,…] (armlink)
--dll
--dynamic_linker=name
--eager_load_debug, --no_eager_load_debug
--eh_frame_hdr
--edit=file_list
--emit_debug_overlay_relocs
--emit_debug_overlay_section
--emit_non_debug_relocs
--emit_relocs
--entry=location
--errors=filename
--exceptions, --no_exceptions
--export_all, --no_export_all
--export_dynamic, --no_export_dynamic
--filtercomment, --no_filtercomment
--fini=symbol
--first=section_id
--force_explicit_attr
--force_so_throw, --no_force_so_throw
--fpic
--fpu=list (armlink)
--fpu=name (armlink)
--got=type
--gnu_linker_defined_syms
--help (armlink)
--import_cmse_lib_in=filename
--import_cmse_lib_out=filename
--import_unresolved, --no_import_unresolved
--info=topic[,topic,…] (armlink)
--info_lib_prefix=opt
--init=symbol
--inline, --no_inline
--inline_type=type
--inlineveneer, --no_inlineveneer
input-file-list (armlink)
--keep=section_id (armlink)
--keep_intermediate
--largeregions, --no_largeregions
--last=section_id
--legacyalign, --no_legacyalign
--libpath=pathlist
--library=name
--library_security=protection
--library_type=lib
--list=filename
--list_mapping_symbols, --no_list_mapping_symbols
--load_addr_map_info, --no_load_addr_map_info
--locals, --no_locals
--lto, --no_lto
--lto_keep_all_symbols, --no_lto_keep_all_symbols
--lto_intermediate_filename
--lto_level
--lto_relocation_model
--mangled, --unmangled
--map, --no_map
--max_er_extension=size
--max_veneer_passes=value
--max_visibility=type
--merge, --no_merge
--merge_litpools, --no_merge_litpools
--muldefweak, --no_muldefweak
-o filename, --output=filename (armlink)
--output_float_abi=option
--overlay_veneers
--override_visibility
-Omax (armlink)
-Omin (armlink)
--pad=num
--paged
--pagesize=pagesize
--partial
--pie
--piveneer, --no_piveneer
--pixolib
--pltgot=type
--pltgot_opts=mode
--predefine="string"
--preinit, --no_preinit
--privacy (armlink)
--ref_cpp_init, --no_ref_cpp_init
--ref_pre_init, --no_ref_pre_init
--reloc
--remarks
--remove, --no_remove
--ro_base=address
--ropi
--rosplit
--rw_base=address
--rwpi
--scanlib, --no_scanlib
--scatter=filename
--section_index_display=type
--shared
--show_cmdline (armlink)
--show_full_path
--show_parent_lib
--show_sec_idx
--soname=name
--sort=algorithm
--split
--startup=symbol, --no_startup
--stdlib
--strict
--strict_flags, --no_strict_flags
--strict_ph, --no_strict_ph
--strict_preserve8_require8
--strict_relocations, --no_strict_relocations
--strict_symbols, --no_strict_symbols
--strict_visibility, --no_strict_visibility
--symbols, --no_symbols
--symdefs=filename
--symver_script=filename
--symver_soname
--sysv
--tailreorder, --no_tailreorder
--tiebreaker=option
--unaligned_access, --no_unaligned_access
--undefined=symbol
--undefined_and_export=symbol
--unresolved=symbol
--use_definition_visibility
--userlibpath=pathlist
--veneerinject, --no_veneerinject
--veneer_inject_type=type
--veneer_pool_size=size
--veneershare, --no_veneershare
--verbose
--version_number (armlink)
--via=filename (armlink)
--vsn (armlink)
--xo_base=address
--xref, --no_xref
--xrefdbg, --no_xrefdbg
--xref{from|to}=object(section)
--zi_base=address
Linking Models Supported by armlink
Overview of linking models
Bare-metal linking model overview
Partial linking model overview
Base Platform Application Binary Interface (BPABI)
Base Platform linking model overview
SysV linking model overview
Concepts common to both BPABI and SysV linking mod
Image Structure and Generation
The structure of an Arm ELF image
Views of the image at each link stage
Input sections, output sections, regions, and prog
Load view and execution view of an image
Methods of specifying an image memory map with the
Image entry points
Restrictions on image structure
Simple images
Types of simple image
Type 1 image structure, one load region and contig
Type 2 image structure, one load region and non-co
Type 3 image structure, multiple load regions and
Section placement with the linker
Default section placement
Section placement with the FIRST and LAST attribut
Section alignment with the linker
Linker support for creating demand-paged files
Linker reordering of execution regions containing
Linker-generated veneers
What is a veneer?
Veneer sharing
Veneer types
Generation of position independent to absolute ven
Reuse of veneers when scatter-loading
Generation of secure gateway veneers
Command-line options used to control the generatio
Weak references and definitions
How the linker performs library searching, selecti
How the linker searches for the Arm standard libra
Specifying user libraries when linking
How the linker resolves references
The strict family of linker options
Linker Optimization Features
Elimination of common section groups
Elimination of unused sections
Optimization with RW data compression
How the linker chooses a compressor
Options available to override the compression algo
How compression is applied
Considerations when working with RW data compressi
Function inlining with the linker
Factors that influence function inlining
About branches that optimize to a NOP
Linker reordering of tail calling sections
Restrictions on reordering of tail calling section
Linker merging of comment sections
Merging identical constants
Accessing and Managing Symbols with armlink
About mapping symbols
Linker-defined symbols
Region-related symbols
Types of region-related symbols
Image$$ execution region symbols
Load$$ execution region symbols
Load$$LR$$ load region symbols
Region name values when not scatter-loading
Linker defined symbols and scatter files
Methods of importing linker-defined symbols in C a
Methods of importing linker-defined symbols in Arm
Section-related symbols
Types of section-related symbols
Image symbols
Input section symbols
Access symbols in another image
Creating a symdefs file
Outputting a subset of the global symbols
Reading a symdefs file
Symdefs file format
Edit the symbol tables with a steering file
Specifying steering files on the linker command-li
Steering file command summary
Steering file format
Hide and rename global symbols with a steering fil
Use of $Super$$ and $Sub$$ to patch symbol definit
Scatter-loading Features
The scatter-loading mechanism
Overview of scatter-loading
When to use scatter-loading
Linker-defined symbols that are not defined when s
Placing the stack and heap with a scatter file
Scatter-loading command-line options
Scatter-loading images with a simple memory map
Scatter-loading images with a complex memory map
Root region and the initial entry point
Effect of the ABSOLUTE attribute on a root region
Effect of the FIXED attribute on a root region
Methods of placing functions and data at specific
Placing functions and data in a named section
Placing __at sections at a specific address
Restrictions on placing __at sections
Automatically placing __at sections
Manually placing __at sections
Placing a key in flash memory with an __at section
Example of how to explicitly place a named section
Placement of unassigned sections
Default rules for placing unassigned sections
Command-line options for controlling the placement
Prioritizing the placement of unassigned sections
Specify the maximum region size permitted for plac
Examples of using placement algorithms for .ANY se
Example of next_fit algorithm showing behavior of
Examples of using sorting algorithms for .ANY sect
Behavior when .ANY sections overflow because of li
Placing veneers with a scatter file
Placement of CMSE veneer sections for a Secure ima
Reserving an empty block of memory
Characteristics of a reserved empty block of memor
Example of reserving an empty block of memory
Placement of Arm C and C++ library code
Placing code in a root region
Placing Arm C library code
Placing Arm C++ library code
Aligning regions to page boundaries
Aligning execution regions and input sections
Preprocessing a scatter file
Default behavior for armclang -E in a scatter file
Using other preprocessors in a scatter file
Example of using expression evaluation in a scatte
Equivalent scatter-loading descriptions for simple
Command-line options for creating simple images
Type 1 image, one load region and contiguous execu
Type 2 image, one load region and non-contiguous e
Type 3 image, multiple load regions and non-contig
How the linker resolves multiple matches when proc
How the linker resolves path names when processing
Scatter file to ELF mapping
Scatter File Syntax
BNF notation used in scatter-loading description s
Syntax of a scatter file
Load region descriptions
Components of a load region description
Syntax of a load region description
Load region attributes
Inheritance rules for load region address attribut
Inheritance rules for the RELOC address attribute
Considerations when using a relative address +offs
Execution region descriptions
Components of an execution region description
Syntax of an execution region description
Execution region attributes
Inheritance rules for execution region address att
Considerations when using a relative address +offs
Input section descriptions
Components of an input section description
Syntax of an input section description
Examples of module and input section specification
Expression evaluation in scatter files
Expression usage in scatter files
Expression rules in scatter files
Execution address built-in functions for use in sc
ScatterAssert function and load address related fu
Symbol related function in a scatter file
AlignExpr(expr, align) function
GetPageSize() function
SizeOfHeaders() function
Example of aligning a base address in execution sp
Scatter files containing relative base address loa
BPABI and SysV Shared Libraries and Executables
About the Base Platform Application Binary Interfa
Platforms supported by the BPABI
Features common to all BPABI models
About importing and exporting symbols for BPABI mo
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
SysV linking model
SysV standard memory model
Using the C and C++ libraries
Using a dynamic Linker
Automatic dynamic symbol table rules in the SysV l
Symbol definitions defined for SysV compatibility
Addressing modes in the SysV linking model
Thread local storage in the SysV linking model
Linker command-line options for the SysV linking m
Bare metal and DLL-like memory models
BPABI standard memory model
Customization of the BPABI standard memory model
Linker command-line options for bare metal and DLL
Mandatory symbol versioning in the BPABI DLL-like
Automatic dynamic symbol table rules in the BPABI
Addressing modes in the BPABI DLL-like model
C++ initialization in the BPABI DLL-like model
Symbol versioning
Overview of symbol versioning
Embedded symbols
The symbol versioning script file
Example of creating versioned symbols
Linker options for enabling implicit symbol versio
Features of the Base Platform Linking Model
Restrictions on the use of scatter files with the
Scatter files for the Base Platform linking model
Placement of PLT sequences with the Base Platform
Linker Steering File Command Reference
EXPORT steering file command
HIDE steering file command
IMPORT steering file command
RENAME steering file command
REQUIRE steering file command
RESOLVE steering file command
SHOW steering file command
fromelf Reference
armar Reference
armasm Legacy Assembler Reference
Appendixes
|
Home / Compiler Reference Guide Version 6.15
How the linker resolves multiple matches when processing scatter files
C6.14 How the linker resolves multiple matches when processing scatter files
An input section must be unique. In the case of multiple matches, the linker attempts to assign the input section to a region based on the attributes of the input section description.
The linker assignment of the input section is based on a module_select_pattern
and input_section_selector pair that is the most specific.
However, if a unique match cannot be found, the linker faults the scatter-loading
description.
The following variables describe how the linker matches multiple input sections:
m1 and m2 represent module selector
patterns.
s1 and s2 represent input section
selectors.
For example, if input section A matches m1,s1 for execution region
R1, and A matches m2,s2 for execution region R2, the linker:
- Assigns A to R1 if
m1,s1 is more specific than
m2,s2 .
- Assigns A to R2 if
m2,s2 is more specific than
m1,s1 .
- Diagnoses the scatter-loading description as faulty if
m1,s1 is not more specific than
m2,s2 and m2,s2 is not more specific than
m1,s1 .
armlink uses the following strategy
to determine the most specific module_select_pattern , input_section_selector pair:
- Resolving the priority of two module_selector, section_selector pairs m1, s1
and m2, s2
-
The strategy starts with two module_select_pattern,
input_section_selector pairs. m1,s1 is more specific than m2,s2 only if any of the following are
true:
s1 is either a literal input section
name, that is it contains no pattern characters, or a section type
and s2 matches input section
attributes.
m1 is more specific than m2 .
s1 is more specific than s2 .
The conditions are tested in order so
condition 1 takes precedence over condition 2 and 3, and condition 2
takes precedence over condition 3.
- Resolving the priority of two module selectors m1 and m2 in isolation
- For the module selector patterns,
m1 is more specific than m2 if the text string m1
matches pattern m2 and the text string
m2 does not match pattern m1 .
- Resolving the priority of two section selectors s1 and s2 in isolation
-
For the input section selectors:
- If one of
s1 or
s2 matches the input section
name or type and the other matches the input section attributes,
s1 and s2 are unordered and the description
is diagnosed as faulty.
- If both
s1 and
s2 match the input section
name or type, the following relationships determine whether s1 is
more specific than s2:
- Section type is more specific than section
name.
- If both
s1 and s2
match input section type, s1 and s2
are unordered and the description is diagnosed as
faulty.
- If
s1
and s2 are both patterns
matching section names, the same definition as for module
selector patterns is used.
- If both
s1 and
s2 match input section
attributes, the following relationships determine whether s1 is more specific than s2 s:
ENTRY is
more specific than RO-CODE , RO-DATA , RW-CODE , or RW-DATA .
RO-CODE
is more specific than RO .
RO-DATA
is more specific than RO .
RW-CODE
is more specific than RW .
RW-DATA
is more specific than RW .
- There are no other members of the (
s1 more specific than
s2 ) relationship
between section attributes.
This matching strategy has the following consequences:
- Descriptions do not depend on the order they are written in the
file.
- Generally, the more specific the description of an object, the
more specific the description of the input sections it contains.
- The
input_section_selector s are not examined unless:
- Object selection is inconclusive.
- One selector specifies a literal
input section name or a section type and the other selects by attribute.
In this case, the explicit input section name or type is more specific
than any attribute. This is true even if the object selector associated
with the input section name is less specific than that of the
attribute.
The .ANY module selector is available to assign any sections that
cannot be resolved from the scatter-loading description.
Example
The following example shows multiple execution regions and pattern matching:
LR_1 0x040000
{
ER_ROM 0x040000 ; The startup exec region address is the same
{ ; as the load address.
application.o (+ENTRY) ; The section containing the entry point from
} ; the object is placed here.
ER_RAM1 0x048000
{
application.o (+RO-CODE) ; Other RO code from the object goes here
}
ER_RAM2 0x050000
{
application.o (+RO-DATA) ; The RO data goes here
}
ER_RAM3 0x060000
{
application.o (+RW) ; RW code and data go here
}
ER_RAM4 +0 ; Follows on from end of ER_R3
{
*.o (+RO, +RW, +ZI) ; Everything except for application.o goes here
}
}
|