UM20005 Linker
UM20005 Linker
UM20005 Linker
Document: UM20005
Software Version: 4.4.0
Revision: 0
Date: December 8, 2020
www.segger.com
2
Disclaimer
Specifications written in this document are believed to be accurate, but are not guaranteed to
be entirely free of error. The information in this manual is subject to change for functional or
performance improvements without notice. Please make sure your manual is the latest edition.
While the information herein is assumed to be accurate, SEGGER Microcontroller GmbH (SEGGER)
assumes no responsibility for any errors or omissions. SEGGER makes and you receive no
warranties or conditions, express, implied, statutory or in any communication with you. SEGGER
specifically disclaims any implied warranty of merchantability or fitness for a particular purpose.
Copyright notice
You may not extract portions of this manual or modify the PDF file in any way without the prior
written permission of SEGGER. The software described in this document is furnished under a
license and may only be used or copied in accordance with the terms of such a license.
© 2017-2020 SEGGER Microcontroller GmbH, Monheim am Rhein / Germany
Trademarks
Names mentioned in this manual may be trademarks of their respective companies.
Brand and product names are trademarks or registered trademarks of their respective holders.
Contact address
SEGGER Microcontroller GmbH
Ecolab-Allee 5
D-40789 Monheim am Rhein
Germany
*By sending us an email your (personal) data will automatically be processed. For further information please refer to our
privacy policy which is available at https://www.segger.com/legal/privacy-policy/.
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
3
Manual versions
This manual describes the current software version. If you find an error in the manual or a
problem in the software, please report it to us and we will try to assist you as soon as possible.
Contact us for further information on topics or functions that are not yet documented.
Print date: December 8, 2020
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
4
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
5
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
6
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
7
Assumptions
This document assumes that you already have a solid knowledge of the following:
• The software tools used for building your application (assembler, linker, C compiler).
• The C programming language.
• The target processor.
• DOS command line.
If you feel that your knowledge of C is not sufficient, we recommend The C Programming
Language by Kernighan and Richie (ISBN 0--13--1103628), which describes the standard in C
programming and, in newer editions, also covers the ANSI C standard.
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
8
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
9
Table of contents
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
10
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
11
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
12
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
13
5 Indexes ......................................................................................................................243
5.1 Subject index .............................................................................................244
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
Chapter 1
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
15 CHAPTER 1 Introduction
1.1 Introduction
This section presents an overview of the SEGGER Linker and its capabilities.
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
Chapter 2
This section describes how to use the linker to link your Cortex application.
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
17 CHAPTER 2 Memories
2.1 Memories
The SEGGER linker is capable of linking an application for any Cortex device. However, it
has no internal knowledge of the way that memory is laid out for any device and must
be told, using a linker script or command line options, the specific memory layout of the
target device.
The define memory statement defines the single memory space used by Cortex devices and
its size.
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
18 CHAPTER 2 Regions
2.2 Regions
The define region statement defines a region in the available memory into which sections
of code and data can be placed. The define region statement is much the same as a C
preprocessor #define directive, it merely names a region of memory.
A memory region consists of one or more memory ranges, where a memory range is
a contiguous sequence of bytes. Memory regions are central to the way that the linker
allocates sections, and groups of sections, into the available memory.
Note that it is possible for the size to be zero, in which case the memory range is considered
“null” and will not have anything allocated into it.
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
19 CHAPTER 2 Regions
The resulting region is the combination of the two ranges, and as such there is a hole of
32k in the region, at 0x1fff8000 of size 32k.
It is possible to combine two contiguous ranges into a single region:
In this case the resulting region defines a contiguous range of addresses from 0x1fff000
of size 256k, but the region remains divided into two ranges.
Note
The fact that these two remain divided is very important for some devices where two
memories are contiguous and, from a programmer perspective, would appear to be
a single linear address space to allocate data into, but from a hardware perspective
are discrete. It is common for a microcontroller to fault when reading misaligned data
that spans the boundary between the two memories or when reading double-word
data that spans the same boundary.
The Kinetis devices, which have such a boundary, are affected by this. Because the linker
knows that there are two distinct ranges, it ensures that objects are allocated completely
within each range and not over the seemingly contiguous memory area thus avoiding any
latent bugs with memory accesses.
When two ranges overlap, they are combined into a single range. Therefore:
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
20 CHAPTER 2 Regions
This operator is particularly effective when you need to reserve places in flash or RAM for
configuration or personalisation data or for bootloaders and other items.
Example
if FAST_RAM then [from 0x1fff8000 size 32k] else [from 0x20000000 size 96k]
if FAST_RAM is zero.
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
21 CHAPTER 2 Regions
and override those regions on the command line for a specific device with different region
sizes or placements.
For instance:
The default region is only used when there is no other definition of the region either on the
command line or previously within the linker script using define region.
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
22 CHAPTER 2 A simple linker script
Define memory
The define memory statement covers the entire Cortex-M address space.
Place vectors
This place at statement instructs the linker to place the .vectors section at the start of
flash memory. The vectors section typically contains the reset program counter and initial
stack pointer along with interrupt and exception vectors for the target device and must, by
convention, be placed at the start of memory.
Keep vectors
This keep statement instructs the linker to keep the vectors section. The linker eliminates all
code and data that is not specifically referenced by the linked application, so dead code and
data are removed from the linked application and do not form part of the image. As there
is usually no reference to the vectors section by the application, it would be eliminated by
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
23 CHAPTER 2 A simple linker script
the linker in normal operation. The keep statement instructs the linker to keep the vectors
section, and anything it references, in the application.
You can use the keep statement to keep otherwise-unreferenced data in your application,
such as configuration data or personalization data.
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
24 CHAPTER 2 Selecting sections
This selects all sections named .bss, and there may well be more than one input section
names .bss, and this selects all of them.
Selection can also be by wildcard in the section name, for instance:
This selects all sections that are named .bss and all sections that match the wildcard .bss.*
where * stands for a sequence of zero or more characters. These two selectors will never
select a section .bss2 because .bss2 does not match the section name and does not match
the wildcard.
The wildcard character ? matches exactly one character, so the wildcard .bss.?* will match
all sections that start .bss. and have a non-empty suffix. In this case, .bss.Data will be
selected but .bss. will not be selected because there is nothing following the final period.
It is very common to select sections that are related, for instance:
This particular construction can be written using the ^ matcher, e.g. .text^.*. The ^ matches
the end of string or continues with matching the suffix. Hence, .text^a will match only the
two sections with names .text or .texta.
This construction is particularly valuable when using the empty selector warning (see --
warn-empty-selects on page 231). In this case, if the input contains no .text sections,
the section selector will cause a warning to be issued even if .text.* sections are present.
This can be rewritten to use a wildcard selector that will select any .text section and any
.text.* section using a single wildcard covering both:
This construction will not cause the linker to issue an empty selector warning (if that warning
is enabled).
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
25 CHAPTER 2 Grouping code and data
Blocks can also be used to reserve memory or fix the order of sections when allocating
them to memory.
place in RAM {
block rwdata { readwrite },
block zidata { zeroinit }
};
place in RAM {
block { readwrite },
block { zeroinit }
};
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
26 CHAPTER 2 Fixed placement of objects
This places the .config section at address 0x400. In GNU C syntax you can define the object
allocated to the section like this:
then you can use the symbol name directly bypassing the requirement to use a named
section:
This locates the function MyFunc to start at address 0x8000. The same scheme extends to
variables:
Interpretation of section names is turned on by default. You control this capability using
the --autoat and --no-autoat command line switches: see --autoat on page 142 and --
no-autoat on page 143.
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
27 CHAPTER 2 Placing code in RAM
And then placing all such sections in RAM in the linker script:
The initialize by copy is required as the linker assumes that all sections containing read-
execute code are implicitly present at system startup, even if they have been placed into
RAM. The initialize by copy overrides the default handling of this particular section and
instructs the linker to make an image of the section and copy it to its final destination on
system startup.
Note
At high optimization levels the compiler may make an inline copy of a function even
though it is declared to be in a nondefault section. To ensure that the function is indeed
run from RAM the compiler must be told not to inline the function:
void __attribute((section(“.ramfunc”), noinline)) MyFunc(void) …
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
28 CHAPTER 2 Placement with preferences
The linker will allocate code and data, however it fits, into the RAM with no priority given
to placing code in the lower fast-execute region.
A simple remedy for this is to use two separate ranges and manually distribute the code
and data:
This will allocate the code that should run quickly into the low memory, with read-write and
zero-initialized data allocated to the remainder. The linker will typically allocate from low
memory to high memory in a memory region, so it’s highly likely that some data will be
allocated to the low memory which may impact performance.
What we need to do is instruct the linker to apply a preference order for the data, to try to
allocate objects first into high memory and, if any do not fit, to place the overflow into the
low memory with the code. We specify a preference using then:
With this script, we accomplish the best layout possible without sacrificing flexibility: the
code is placed into fast-executing low memory, the data is separated into high memory that
doesn’t affect performance, and if data is so big it will not fit into high memory, it overflows
into low memory which might affect performance but will not cause a link error.
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
29 CHAPTER 2 Placement with preferences
The following is an example of how to construct a linker script for this device, placing
data used for Ethernet and USB in separate memories so they can be used in parallel, and
assigning data in a way that maximizes performance whilst, at the same time, relieving the
developer from arduous section placement.
place in DTCM_SRAM
then AXI_SRAM
then AHB_SRAM2 + AHB_SRAM3
then AHB_SRAM1 + AHB_SRAM4
then BACKUP_SRAM { readwrite, zeroinit };
Define regions
Configuring regions is straightforward, one definition per memory:
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
30 CHAPTER 2 Thread-local data
The specific arrangement for thread-local data will be documented in the real-time operating
system manual. You will need to refer to this manual when using the SEGGER linker with
your RTOS.
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
31 CHAPTER 2 Firmware integrity checks
The default is to use a standard CRC-32 algorithm and assume that any usused gaps in the
region FLASH are filled with the value 0xFF.
The integrity check section must be placed using a place at or place in selector. Usually
the integrity check is at a fixed location in flash or in the load image, or immediately follows
the firmware image. Therefore, something like the following can be used:
place in APPLICATION {
section .text, section .text.*,
section .rodata.*, section .rodata.*
};
place in CRC {
integrity check of APPLICATION with algorithm="CRC-32" fill=0xFF
};
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
32 CHAPTER 2 Firmware integrity checks
place in CRC {
integrity check of INTERNAL_FLASH + EXTERNAL_FLASH - CRC;
}
This will calculate a single CRC over the two regions. Please note that the linker calculates
the integrity check over regions in address order. This means that the CRC in the example
above is calculated over the external flash first, as it has the lowest address, followed by
the internal flash, and excludes the region where the CRC is itself held.
When verifying such an integrity check, calculate the integrity check over the regions in
the same order that the linker calculates them. This is supported by SEGGER’s emLib-CRC
and emCrypt.
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
33 CHAPTER 2 Firmware integrity checks
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
34 CHAPTER 2 Firmware integrity checks
Algorithm ID Description
Adler-32 algorithm. The 4-byte checksum is stored in network
Adler-32 (big-endian) byte order. See RFC 1950 for a description and
example implementation of the Adler-32 algorithm.
xxH32 algorithm. The 4-byte checksum, initialized with a seed of
zero, is stored in PC (little-endian) byte order. See xxHash fast
XXH32
digest algorithm for a description and example implementation of
the XXH32 algorithm.
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
35 CHAPTER 2 Firmware integrity checks
//
// Combined regions per memory type
//
define region FLASH = FLASH1;
define region RAM = RAM1;
//
// Block definitions
//
define block vectors { section .vectors };
define block vectors_ram { section .vectors_ram };
define block ctors { section .ctors, section .ctors.*,
block with alphabetical order { init_array } };
define block dtors { section .dtors, section .dtors.*,
block with reverse alphabetical order { fini_array } };
define block exidx { section .ARM.exidx, section .ARM.exidx.* };
define block tbss { section .tbss, section .tbss.* };
define block tdata { section .tdata, section .tdata.* };
define block tls { block tbss, block tdata };
define block tdata_load { copy of block tdata };
//
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
36 CHAPTER 2 Firmware integrity checks
// Stack reservation
//
define block heap with size = __HEAPSIZE__, alignment = 8, readwrite access { };
define block stack with size = __STACKSIZE__, alignment = 8, readwrite access { };
//
// Explicit initialization settings for sections
//
do not initialize { section .non_init, section .non_init.*,
section .*.non_init, section .*.non_init.* };
initialize by copy { section .data, section .data.*,
section .*.data, section .*.data.* };
initialize by copy { section .fast, section .fast.* };
//
// Explicit placement in FLASHn
//
place in FLASH1 { section .FLASH1, section .FLASH1.* };
//
// Define a section with known contents.
//
define root section .rodata.TestData {
udata8 0x31, udata8 0x32, udata8 0x33,
udata8 0x34, udata8 0x35, udata8 0x36,
udata8 0x37, udata8 0x38, udata8 0x39,
};
//
// Wrap that section in a block so that we can access the test
// data using linker-generated symbols.
//
define block TestData {
section .rodata.TestData
};
//
// Define a region where the test data sits.
//
define region TEST = [start(FLASH)+64k size 9];
//
// Place the test data.
//
place in TEST { block TestData };
//
// Follow the test data with a set of CRCs and hashes which
// can be verified.
//
place after TEST {
block with fixed order {
//
// CRCs
//
integrity check of TEST with algorithm="CRC-7/MMC",
integrity check of TEST with algorithm="CRC-8",
integrity check of TEST with algorithm="CRC-8/CDMA2000",
integrity check of TEST with algorithm="CRC-8/DARC",
integrity check of TEST with algorithm="CRC-8/MAXIM",
integrity check of TEST with algorithm="CRC-8/AUTOSAR",
integrity check of TEST with algorithm="CRC-8/BLUETOOTH",
integrity check of TEST with algorithm="CRC-16/CCITT:AUG",
integrity check of TEST with algorithm="CRC-16/CCITT:NOAUG",
integrity check of TEST with algorithm="CRC-16/KERMIT",
integrity check of TEST with algorithm="CRC-16/X.25",
integrity check of TEST with algorithm="CRC-16/XMODEM",
integrity check of TEST with algorithm="CRC-16/MODBUS",
integrity check of TEST with algorithm="CRC-16/USB",
integrity check of TEST with algorithm="CRC-16/ARC",
integrity check of TEST with algorithm="CRC-16/UMTS",
integrity check of TEST with algorithm="CRC-16/CDMA2000",
integrity check of TEST with algorithm="CRC-32",
integrity check of TEST with algorithm="CRC-32/BZIP2",
integrity check of TEST with algorithm="CRC-32/MPEG2",
integrity check of TEST with algorithm="CRC-32/POSIX",
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
37 CHAPTER 2 Firmware integrity checks
//
// FLASH Placement
//
place at start of FLASH { block vectors };
place in FLASH with minimum size order { section .init, section .init.*,
section .init_rodata, section .init_rodata.*,
section .text, section .text.*,
section .rodata, section .rodata.*,
section .segger.*,
block exidx,
block ctors,
block dtors };
place in FLASH { block tdata_load };
//
// Explicit placement in RAMn
//
place in RAM1 { section .RAM1, section .RAM1.* };
//
// RAM Placement
//
place at start of RAM { block vectors_ram };
place in RAM { section .non_init, section .non_init.*,
block tls };
place in RAM with auto order { section .fast, section .fast.*,
section .data, section .data.*,
section .bss, section .bss.*
};
place in RAM { block heap };
place at end of RAM { block stack };
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
38 CHAPTER 2 Firmware integrity checks
* *
* - Redistributions of source code must retain the above copyright *
* notice, this list of conditions and the following disclaimer. *
* *
* - Neither the name of SEGGER Microcontroller GmbH *
* nor the names of its contributors may be used to endorse or *
* promote products derived from this software without specific *
* prior written permission. *
* *
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND *
* CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, *
* INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF *
* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE *
* DISCLAIMED. *
* IN NO EVENT SHALL SEGGER Microcontroller GmbH BE LIABLE FOR *
* ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR *
* CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT *
* OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; *
* OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF *
* LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT *
* (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE *
* USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH *
* DAMAGE. *
* *
**********************************************************************
File : main.c
Purpose : Demonstrate verification of each SEGGER Linker integrity
check algorithm.
*/
/*********************************************************************
*
* #include Section
*
**********************************************************************
*/
#include "SEGGER_CRC.h"
#include "CRYPTO.h"
#include <stdio.h>
/*********************************************************************
*
* External data
*
**********************************************************************
*/
/*********************************************************************
*
* Static code
*
**********************************************************************
*/
/*********************************************************************
*
* _Assert()
*
* Function description
* Break when an assertion fails.
*/
static void _Assert(int x) {
if (x == 0) {
printf("Integrity check failed!\n");
asm("bkpt");
}
}
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
39 CHAPTER 2 Firmware integrity checks
/*********************************************************************
*
* _LoadU16()
*
* Function description
* Load 16-bit value from memory, PC byte order.
*/
static unsigned _LoadU16(const U8 *pData) {
return pData[0] + pData[1]*0x100u;
}
/*********************************************************************
*
* _LoadU32()
*
* Function description
* Load 32-bit value from memory, PC byte order.
*/
static unsigned _LoadU32(const U8 *pData) {
return pData[0] + pData[1]*0x100u + pData[2]*0x10000u + pData[3]*0x1000000u;
}
/*********************************************************************
*
* Public code
*
**********************************************************************
*/
/*********************************************************************
*
* CRYPTO_X_Panic()
*
* Function description
* Called when the library detectes an unrecoverable error.
*/
void CRYPTO_X_Panic(void) {
printf("CRYPTO panic!\n");
asm("bkpt");
}
/*********************************************************************
*
* main()
*
* Function description
* Application entry point for integrity verification.
*/
int main(void) {
unsigned char *pTestData = __TestData_start__;
unsigned char *pCheckData = __TestData_end__;
unsigned TestDataLen = __TestData_end__ - __TestData_start__;
U32 CalcCRC;
static U8 aHash[512/8];
//
// Initialize CRYPTO.
//
CRYPTO_MD5_Install (&CRYPTO_HASH_MD5_SW, NULL);
CRYPTO_RIPEMD160_Install(&CRYPTO_HASH_RIPEMD160_SW, NULL);
CRYPTO_SM3_Install (&CRYPTO_HASH_SM3_SW, NULL);
CRYPTO_SHA1_Install (&CRYPTO_HASH_SHA1_SW, NULL);
CRYPTO_SHA224_Install (&CRYPTO_HASH_SHA224_SW, NULL);
CRYPTO_SHA256_Install (&CRYPTO_HASH_SHA256_SW, NULL);
CRYPTO_SHA512_Install (&CRYPTO_HASH_SHA512_SW, NULL);
CRYPTO_SHA3_224_Install (&CRYPTO_HASH_SHA3_224_SW, NULL);
CRYPTO_SHA3_256_Install (&CRYPTO_HASH_SHA3_256_SW, NULL);
CRYPTO_SHA3_384_Install (&CRYPTO_HASH_SHA3_384_SW, NULL);
CRYPTO_SHA3_512_Install (&CRYPTO_HASH_SHA3_512_SW, NULL);
//
// Get address and length of data to check.
//
pTestData = __TestData_start__;
TestDataLen = __TestData_end__ - __TestData_start__;
//
// Get address of the list of corresponding integrity check
// values.
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
40 CHAPTER 2 Firmware integrity checks
//
pCheckData = __TestData_end__;
//
// CRC-7/MMC.
//
CalcCRC = SEGGER_CRC_Calc_MSB(pTestData, TestDataLen, 0x00, 0x09, 7);
_Assert(CalcCRC == *pCheckData);
pCheckData += 1;
//
// CRC-8
//
CalcCRC = SEGGER_CRC_Calc_MSB(pTestData, TestDataLen, 0x00, 0x07, 8);
_Assert(CalcCRC == *pCheckData);
pCheckData += 1;
//
// CRC-8/CDMA2000
//
CalcCRC = SEGGER_CRC_Calc_MSB(pTestData, TestDataLen, 0xFF, 0x9B, 8);
_Assert(CalcCRC == *pCheckData);
pCheckData += 1;
//
// CRC-8/DARC
//
CalcCRC = SEGGER_CRC_Calc(pTestData, TestDataLen, 0x00, 0x9C);
_Assert(CalcCRC == *pCheckData);
pCheckData += 1;
//
// CRC-8/MAXIM.
//
CalcCRC = SEGGER_CRC_Calc(pTestData, TestDataLen, 0x00, 0x8C);
_Assert(CalcCRC == *pCheckData);
pCheckData += 1;
//
// CRC-8/AUTOSAR
//
CalcCRC = SEGGER_CRC_Calc_MSB(pTestData, TestDataLen, 0xFF, 0x1D, 8) ^ 0xFF;
_Assert(CalcCRC == *pCheckData);
pCheckData += 1;
//
// CRC-8/BLUETOOTH
//
CalcCRC = SEGGER_CRC_Calc(pTestData, TestDataLen, 0x00, 0xE5);
_Assert(CalcCRC == *pCheckData);
pCheckData += 1;
//
// CRC-16/CCITT:AUG
//
CalcCRC = SEGGER_CRC_Calc_MSB(pTestData, TestDataLen, 0x1D0F, 0x1021, 16);
_Assert(CalcCRC == _LoadU16(pCheckData));
pCheckData += 2;
//
// CRC-16/CCITT:NOAUG
//
CalcCRC = SEGGER_CRC_Calc_MSB(pTestData, TestDataLen, 0xFFFF, 0x1021, 16);
_Assert(CalcCRC == _LoadU16(pCheckData));
pCheckData += 2;
//
// CRC-16/KERMIT
//
CalcCRC = SEGGER_CRC_Calc(pTestData, TestDataLen, 0x0000, 0x8408);
_Assert(CalcCRC == _LoadU16(pCheckData));
pCheckData += 2;
//
// CRC-16/X.25
//
CalcCRC = SEGGER_CRC_Calc(pTestData, TestDataLen, 0xFFFF, 0x8408) ^ 0xFFFF;
_Assert(CalcCRC == _LoadU16(pCheckData));
pCheckData += 2;
//
// CRC-16/XMODEM
//
CalcCRC = SEGGER_CRC_Calc_MSB(pTestData, TestDataLen, 0x0000, 0x1021, 16);
_Assert(CalcCRC == _LoadU16(pCheckData));
pCheckData += 2;
//
// CRC-16/MODBUS
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
41 CHAPTER 2 Firmware integrity checks
//
CalcCRC = SEGGER_CRC_Calc(pTestData, TestDataLen, 0xFFFF, 0xA001);
_Assert(CalcCRC == _LoadU16(pCheckData));
pCheckData += 2;
//
// CRC-16/USB
//
CalcCRC = SEGGER_CRC_Calc(pTestData, TestDataLen, 0xFFFF, 0xA001) ^ 0xFFFF;
_Assert(CalcCRC == _LoadU16(pCheckData));
pCheckData += 2;
//
// CRC-16/ARC
//
CalcCRC = SEGGER_CRC_Calc(pTestData, TestDataLen, 0x0000, 0xA001);
_Assert(CalcCRC == _LoadU16(pCheckData));
pCheckData += 2;
//
// CRC-16/UMTS
//
CalcCRC = SEGGER_CRC_Calc_MSB(pTestData, TestDataLen, 0x0000, 0x8005, 16);
_Assert(CalcCRC == _LoadU16(pCheckData));
pCheckData += 2;
//
// CRC-16/CDMA2000
//
CalcCRC = SEGGER_CRC_Calc_MSB(pTestData, TestDataLen, 0xFFFF, 0xC867, 16);
_Assert(CalcCRC == _LoadU16(pCheckData));
pCheckData += 2;
//
// CRC-32
//
CalcCRC = SEGGER_CRC_Calc(pTestData, TestDataLen, 0xFFFFFFFF, 0xEDB88320) ^ 0xFFFFFFFF;
_Assert(CalcCRC == _LoadU32(pCheckData));
pCheckData += 4;
//
// CRC-32/BZIP2
//
CalcCRC = SEGGER_CRC_Calc_MSB(pTestData, TestDataLen, 0xFFFFFFFF, 0x04C11DB7, 32) ^ 0xFFFFFFFF;
_Assert(CalcCRC == _LoadU32(pCheckData));
pCheckData += 4;
//
// CRC-32/MPEG2
//
CalcCRC = SEGGER_CRC_Calc_MSB(pTestData, TestDataLen, 0xFFFFFFFF, 0x04C11DB7, 32);
_Assert(CalcCRC == _LoadU32(pCheckData));
pCheckData += 4;
//
// CRC-32/POSIX
//
CalcCRC = SEGGER_CRC_Calc_MSB(pTestData, TestDataLen, 0x00000000, 0x04C11DB7, 32) ^ 0xFFFFFFFF;
_Assert(CalcCRC == _LoadU32(pCheckData));
pCheckData += 4;
//
// CRC-32/XFER
//
CalcCRC = SEGGER_CRC_Calc_MSB(pTestData, TestDataLen, 0x00000000, 0x000000AF, 32);
_Assert(CalcCRC == _LoadU32(pCheckData));
pCheckData += 4;
//
// CRC-32C
//
CalcCRC = SEGGER_CRC_Calc(pTestData, TestDataLen, 0xFFFFFFFF, 0x82F63B78) ^ 0xFFFFFFFF;
_Assert(CalcCRC == _LoadU32(pCheckData));
pCheckData += 4;
//
// CRC-32D
//
CalcCRC = SEGGER_CRC_Calc(pTestData, TestDataLen, 0xFFFFFFFF, 0xD419CC15) ^ 0xFFFFFFFF;
_Assert(CalcCRC == _LoadU32(pCheckData));
pCheckData += 4;
//
// CRC-32Q
//
CalcCRC = SEGGER_CRC_Calc_MSB(pTestData, TestDataLen, 0x00000000, 0x814141AB, 32);
_Assert(CalcCRC == _LoadU32(pCheckData));
pCheckData += 4;
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
42 CHAPTER 2 Firmware integrity checks
//
// MD5.
//
CRYPTO_MD5_Calc(aHash, CRYPTO_MD5_DIGEST_BYTE_COUNT, pTestData, TestDataLen);
_Assert(memcmp(aHash, pCheckData, CRYPTO_MD5_DIGEST_BYTE_COUNT) == 0);
pCheckData += CRYPTO_MD5_DIGEST_BYTE_COUNT;
//
// RIPEMD-160
//
CRYPTO_RIPEMD160_Calc(aHash, CRYPTO_RIPEMD160_DIGEST_BYTE_COUNT, pTestData, TestDataLen);
_Assert(memcmp(aHash, pCheckData, CRYPTO_RIPEMD160_DIGEST_BYTE_COUNT) == 0);
pCheckData += CRYPTO_RIPEMD160_DIGEST_BYTE_COUNT;
//
// SHA-1
//
CRYPTO_SHA1_Calc(aHash, CRYPTO_SHA1_DIGEST_BYTE_COUNT, pTestData, TestDataLen);
_Assert(memcmp(aHash, pCheckData, CRYPTO_SHA1_DIGEST_BYTE_COUNT) == 0);
pCheckData += CRYPTO_SHA1_DIGEST_BYTE_COUNT;
//
// SHA-224
//
CRYPTO_SHA224_Calc(aHash, CRYPTO_SHA224_DIGEST_BYTE_COUNT, pTestData, TestDataLen);
_Assert(memcmp(aHash, pCheckData, CRYPTO_SHA224_DIGEST_BYTE_COUNT) == 0);
pCheckData += CRYPTO_SHA224_DIGEST_BYTE_COUNT;
//
// SHA-256
//
CRYPTO_SHA256_Calc(aHash, CRYPTO_SHA256_DIGEST_BYTE_COUNT, pTestData, TestDataLen);
_Assert(memcmp(aHash, pCheckData, CRYPTO_SHA256_DIGEST_BYTE_COUNT) == 0);
pCheckData += CRYPTO_SHA256_DIGEST_BYTE_COUNT;
//
// SHA-384
//
CRYPTO_SHA384_Calc(aHash, CRYPTO_SHA384_DIGEST_BYTE_COUNT, pTestData, TestDataLen);
_Assert(memcmp(aHash, pCheckData, CRYPTO_SHA384_DIGEST_BYTE_COUNT) == 0);
pCheckData += CRYPTO_SHA384_DIGEST_BYTE_COUNT;
//
// SHA-512
//
CRYPTO_SHA512_Calc(aHash, CRYPTO_SHA512_DIGEST_BYTE_COUNT, pTestData, TestDataLen);
_Assert(memcmp(aHash, pCheckData, CRYPTO_SHA512_DIGEST_BYTE_COUNT) == 0);
pCheckData += CRYPTO_SHA512_DIGEST_BYTE_COUNT;
//
// SHA-512/224
//
CRYPTO_SHA512_224_Calc(aHash, CRYPTO_SHA512_224_DIGEST_BYTE_COUNT, pTestData, TestDataLen);
_Assert(memcmp(aHash, pCheckData, CRYPTO_SHA512_224_DIGEST_BYTE_COUNT) == 0);
pCheckData += CRYPTO_SHA512_224_DIGEST_BYTE_COUNT;
//
// SHA-512/256
//
CRYPTO_SHA512_256_Calc(aHash, CRYPTO_SHA512_256_DIGEST_BYTE_COUNT, pTestData, TestDataLen);
_Assert(memcmp(aHash, pCheckData, CRYPTO_SHA512_256_DIGEST_BYTE_COUNT) == 0);
pCheckData += CRYPTO_SHA512_256_DIGEST_BYTE_COUNT;
//
// SHA3-224
//
CRYPTO_SHA3_224_Calc(aHash, CRYPTO_SHA3_224_DIGEST_BYTE_COUNT, pTestData, TestDataLen);
_Assert(memcmp(aHash, pCheckData, CRYPTO_SHA3_224_DIGEST_BYTE_COUNT) == 0);
pCheckData += CRYPTO_SHA3_224_DIGEST_BYTE_COUNT;
//
// SHA3-256
//
CRYPTO_SHA3_256_Calc(aHash, CRYPTO_SHA3_256_DIGEST_BYTE_COUNT, pTestData, TestDataLen);
_Assert(memcmp(aHash, pCheckData, CRYPTO_SHA3_256_DIGEST_BYTE_COUNT) == 0);
pCheckData += CRYPTO_SHA3_256_DIGEST_BYTE_COUNT;
//
// SHA3-384
//
CRYPTO_SHA3_384_Calc(aHash, CRYPTO_SHA3_384_DIGEST_BYTE_COUNT, pTestData, TestDataLen);
_Assert(memcmp(aHash, pCheckData, CRYPTO_SHA3_384_DIGEST_BYTE_COUNT) == 0);
pCheckData += CRYPTO_SHA3_384_DIGEST_BYTE_COUNT;
//
// SHA3-512
//
CRYPTO_SHA3_512_Calc(aHash, CRYPTO_SHA3_512_DIGEST_BYTE_COUNT, pTestData, TestDataLen);
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
43 CHAPTER 2 Firmware integrity checks
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
Chapter 3
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
45 CHAPTER 3 Preliminaries
3.1 Preliminaries
3.1.1 Primary symbol expressions
A primary symbol expression has the following syntax:
symbol-primary =
start of symbol name |
end of symbol name |
size of symbol name |
after symbol name |
alignment of symbol name
Untyped symbols
Untyped symbols have no size, they are simply numbers.
Evaluation
start of symbol name evaluates to the address of the symbol name for function and object
symbols, and to the value of the symbol for untyped symbols.
size of symbol name evaluates to the size of the symbol name, if the associated symbol
has a size, else zero.
end of symbol name evaluates to:
start of symbol name + size of symbol name - 1
after symbol name evaluates to:
start of symbol name + size of symbol name
alignment of symbol name evaluates to the alignment of the section that the symbol name
is associated with, or 1 if the symbol is not associated with a section.
Evaluation
start of block name evaluates to the origin address of the block name.
size of block name evaluates to the size of the block name.
end of block name evaluates to:
start of block name + size of block name - 1
after block name evaluates to:
start of block name + size of block name
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
46 CHAPTER 3 Preliminaries
alignment of block name evaluates to the minimum alignment of the block name calculated
from the block specification and over the locatables contained within the block.
Evaluation
start of region name evaluates to the origin address of the region name.
size of region name evaluates to the size of the region name, spanning the lowest address
to the highest address in the region irrespective of whether there are discontinuities.
end of region name evaluates to:
start of region name + size of region name - 1
after region name evaluates to:
start of region name + size of region name
Evaluation
The section name name must be unique. If there are multiple sections with the same name,
evaluation of any section expression with that name results in a special, undefined value.
start of section name evaluates to the origin address of the unique section name.
size of section name evaluates to the size of the unique section name.
end of section name evaluates to:
start of section name + size of section name - 1
after section name evaluates to:
start of section name + size of section name
alignment of section name evaluates to the alignment of the section according to the
section’s alignment and any additional per-section-class alignment set on the command
line.
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
47 CHAPTER 3 Preliminaries
logical-and-expr =
relational-expr [ && relational-expr ]…
relational-expr =
term [ relop term ]…
term =
factor [ addop factor ]…
factor =
primary [ mulop primary ]…
primary =
number |
name |
~ primary |
! primary |
symbol-primary |
block-primary |
region-primary |
section-primary |
( expr )
where:
relop =
<|≤|>|≥|=|≠
addop =
+|-
mulop =
*|/|%
Evaluation
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
48 CHAPTER 3 Memory ranges and regions
Description
Defines the memory name with size expr; if name is omitted, it defaults to “mem” and if the
size attribute is omitted, the memory size is set to “4G”.
There must be at exactly one memory defined by the script before any memory regions
are declared.
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
49 CHAPTER 3 Memory ranges and regions
Description
Defines the named region name to the region expression region-expr.
See also
Regions on page 18
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
50 CHAPTER 3 Memory ranges and regions
Description
Defines the named region name to the region expression region-expr only if no other region
definition of name exists. A region definition will exist if it is set using the --add-region
command line option or by a previous define region statement.
See also
Regions on page 18, --add-region on page 141
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
51 CHAPTER 3 Sections and symbols
3.3.1.1 Size
The size of the block can be set using the size attribute. If the block size is set with this
attribute, the block size is fixed and does not expand. If the block size is not set with a size
attribute, the block size is as large as required to contain its inputs.
3.3.1.2 Alignment
The minimum alignment of the block can be set using the alignment attribute. The final
alignment of the block is the maximum of the alignment set by the alignment attribute (if
any) and the maximum alignment of any input section.
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
52 CHAPTER 3 Sections and symbols
alphabetical order
All inputs in the block are ordered by section name in alphabetical order.
size then alignment order
All inputs in the block are ordered by size, largest to smallest, and equal-size blocks
are ordered by alignment, largest to smallest.
alignment then size order
All inputs in the block are ordered by alignment largest to smallest and for blocks of
equal alignments, then ordered by size, largest to smallest.
alignment then alphabetical order
All inputs in the block are ordered by alignment largest to smallest and for blocks of
equal alignments, then ordered by name.
reverse size order
All inputs in the block are ordered by reverse size, smallest to largest.
reverse alphabetical order
All inputs in the block are ordered by section name in reverse alphabetical order.
access then size order
All inputs in the block are ordered by access type (rx, ro, rw, zi) and then by size,
largest to smallest.
maximum packing [order]
All inputs in the block are ordered to reduce inter-section gaps caused by alignment
and to reduce the size of the associated unwind tables (if any).
minimum size order
Identical to maximum packing.
Please refer to the ARMv7-M Architecture Reference Manual for further information on the
Cortex-M MPU.
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
53 CHAPTER 3 Sections and symbols
Description
Defines the symbol name to be the value number or the value of the symbol symbol. Once
defined, symbols cannot be redefined by a subsequent define symbol statement.
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
54 CHAPTER 3 Sections and symbols
3.3.3.1 Packing
The linker is capable of compressing initialized data or code copied to RAM using different
packing algorithms. The algorithm can be one of:
none
packbits
zpak
lzss | lz77
auto | smallest
Each algorithm has different compression characteristics. The packing algorithms are:
none
The initialization image is stored verbatim without any compression.
packbits
The initialization image is compressed using the PackBits algorithm.
zpak
The initialization image is compressed using the SEGGER ZPak algorithm which is good
for images that have many zeros in them but are otherwise not suitable for other forms
of packing (PackBits and LZSS).
lzss or lz77
The initialization image is compressed using a Lempel-Ziv-Storer-Szymanski scheme.
auto or smallest
The linker chooses the packing algorithm that minimizes the initialization image size
from the active set of algorithms.
3.3.3.2 Ranges
The simple ranges and complex ranges attributes are accepted but are otherwise ignored.
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
55 CHAPTER 3 Sections and symbols
This sequence of statements reserves space for the heap and gathers together the
constructors and any pre-init arrays.
If the heap has a nonzero size (i.e. if __HEAPSIZE__ is not zero) then the linker will add a
call to the function __SEGGER_init_heap() to the end of the initialization list.
Similarly, after gathering all static constructors that must be called before entering main(),
if the size of the ctors block is nonzero then constructors exist and initialization must take
place. In this case the linker will add a call to the function __SEGGER_init_ctors() to the
end of the initialization list.
Both __SEGGER_init_heap() and __SEGGER_init_ctors() are already written and provided
in the startup code.
Order of initialization
The order of initialization calls follows the order of intialize by calling statements in the
linker script. As static constructors may well call the memory-allocation functions malloc(),
calloc(), and realloc(), the intialize by calling statements are ordered to ensure the
heap is initialized before calling any static constructor.
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
56 CHAPTER 3 Sections and symbols
Description
The sections selected by section-selectors are not added to the initialization table and will
not be initialized on program entry.
This capability enables battery-backed data to be preserved across a reset or power cycle.
Example
do not initialize {
section .backup,
section .backup.*
};
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
57 CHAPTER 3 Sections and symbols
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
58 CHAPTER 3 Sections and symbols
…which cannot be resolved by the linker using section selection precedence, resulting in
an error.
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
59 CHAPTER 3 Sections and symbols
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
60 CHAPTER 3 Sections and symbols
Example
Example
Example
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
61 CHAPTER 3 Sections and symbols
Description
The keep statement requests that the linker keep sections in the generated output that
would otherwise be discarded.
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
62 CHAPTER 3 Sections and symbols
Description
Instruct the linker to place expt in any unused bytes in the region defined by region-expr.
This is useful when preparing program images that must be subjected to checks (such as
a CRC, hash, or digital signature).
A fill statement can appear anywhere in the linker script; fills are executed after all
sections are placed, adding linker-created sections that ensure any gaps (before, between,
or after user sections) are filled.
The linker will report an error if there are conflicting fill statements, when the filled ranges
overlap.
Example
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
63 CHAPTER 3 Control options
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
64 CHAPTER 3 Control options
Description
The assert statement ensures that one or more conditions are satisfied by the link process.
All assert statements run after all sections are placed and memory layout is known,
immediately before writing the output files.
The implication operator => is the standard implication operation of Boolean logic. This
statement reads “if the symbol free() is linked into the application than either malloc() or
realloc() must also be linked into the application.”
assert with warning "when using a heap, malloc() and free() require a heap > 8 bytes" {
( linked symbol malloc
|| linked symbol free
|| linked symbol realloc) ==> size of block heap > 8
};
The implication operator is used again and this reads “if any of the symbols malloc(),
free(), or realloc() are linked into the application then the size of the heap must be greater
than eight bytes.” The expression does not require parentheses, it is a matter of taste, but
this makes the left-hand expression clear.
//
// Create blocks that combine constructors, destructors, and exception index
//
define block ctors { section .ctors, section .ctors.*, init_array };
define block dtors { section .dtors, section .dtors.*, fini_array };
define block exidx { section .ARM.exidx, section .ARM.exidx.* };
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
65 CHAPTER 3 Control options
//
// Check blocks are well-formed.
//
assert with "constructors, destructors, or exception index is malformed" {
size of block dtors % 4 == 0,
size of block ctors % 4 == 0,
size of block exidx % 8 == 0
};
The constructor block is simply an array of addresses, so its size must be a multiple of
four. The same is true for the destructor block. The exception index is an array of two-
word entries that are pointers or literal data, and therefore the size of the exception index
must be a multiple of eight.
With such checking its possible to ensure that functions will execute in the intended
instruction set and that execution speed is maintained and code size does not suffer inflation
from unintended veneers.
Similarly, assert that a function is coded in the Thumb instruction set:
//
// Thread-local data blocks
//
define block tbss { section .tbss, section .tbss.* };
define block tdata { section .tdata, section .tdata.* };
define block tls { block tbss, block tdata };
//
// Check size of thread-local data, warning if too big.
//
assert size of block tls <= 32 with error "thread-local storage is too big";
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
66 CHAPTER 3 Control options
the quantity of data stored in these configuration areas increases. In this situation you might
want to indicate to developers that the configuration area is becoming full and something
should be done to limit its expansion.
Assuming that data are added to the area linearly, or by using a single variable to structure
the block, the block’s utilized size can be monitored:
//
// Define an empty section that acts as a high-water marker.
//
define section ConfigHighWater { };
//
// Place data in the block but make sure the sentinel is placed
// after all other sections.
//
define block Config with size=256 {
symbol ConfigData, // This is, e.g., a C-level variable.
last section ConfigHighWater
};
//
// Warning if the is not at least 5% empty.
//
assert with warning "Configuration area is filling!" {
100 * (end of block Config - start of section ConfigHighWater)
/ size of block Config >= 5;
}
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
Chapter 4
Command-line options
Command line option naming is generally compatible with the following toolsets:
• GNU linker ld
• Arm linker armlink
• IAR linker ilink
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
68 CHAPTER 4 Input file options
Syntax
--script filename
--script=filename
-Tfilename
Description
This option sets the linker script file name to filename. This option can be used more than
once to supply multiple linker script files to the linker. The linker concatenates individual
linker scripts into one combined script for processing.
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
69 CHAPTER 4 Input file options
4.1.2 --via
Synopsis
Read additional options and input files from file.
Syntax
--via filename
--via=filename
-f filename
@filename
Description
This option reads the file filename for additional options and input files. Options are
separated by spaces or newlines, and file names which contain special characters, such as
spaces, must be enclosed in double quotation marks.
Notes
This option can only be provided on the command line and cannot appear in an indirect file.
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
70 CHAPTER 4 Output file options
Syntax
--bare
--no-sections
Description
This option eliminates all debug information, the symbol table, and the string table from
the ELF file, and also removes the section table.
Note
This option is equivalent to specifying --no-debug and --no-symbols.
See also
--no-debug on page 73, --no-symbols on page 85
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
71 CHAPTER 4 Output file options
4.2.2 --block-section-headers
Summary
Produce minimal section table with block information.
Syntax
--block-section-headers
Description
This option produces an ELF file containing minimal section information (section header
string table and string table) together with sections covering any blocks created by the
linker script.
See also
--bare on page 70, --full-section-headers on page 79, --minimal-section-headers on
page 81
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
72 CHAPTER 4 Output file options
4.2.3 --debug
Summary
Include debugging information.
Syntax
--debug
Description
This option instructs the linker to include any relevant debug input sections from the input
object files and libraries and also includes both the symbol table and string table in the
ELF file.
See also
--no-debug on page 73
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
73 CHAPTER 4 Output file options
4.2.4 --no-debug
Summary
Discard debugging information.
Syntax
--no-debug
Description
This option excludes debug information from the output file: all input debug sections are
excluded and both the symbol table and string table are removed. With debug information
removed, the resulting Arm ELF file is smaller, but debugging at source level is impossible.
Note
Discarding debug information only affects the image size as loaded into the debugger—it
has no effect on the size of the executable image that is loaded into the target.
See also
--debug on page 72
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
74 CHAPTER 4 Output file options
4.2.5 --entry
Summary
Set target core or architecture.
Syntax
--entry name
--entry=name
-ename
Description
Sets the entry point to the symbol name and name is automatically kept.
The default is --entry=Reset_Handler.
See also
--no-entry on page 75
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
75 CHAPTER 4 Output file options
4.2.6 --no-entry
Summary
Set the entry point to zero.
Syntax
--no-entry
Description
The entry point in the ELF file is set to zero. To link code into the final application, there
must be at least one root symbol--see --keep on page 161.
Note
The entry point may be used by debuggers to configure applications ready for execution
once downloaded. Removing the entry point may, therefore, require manual setup or
scripting specific to the debugger to correctly configure the application for execution.
See also
--entry on page 74
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
76 CHAPTER 4 Output file options
4.2.7 --force-output
Summary
Write ELF file regardless of link errors.
Syntax
--force-output
Description
This option instructs the linker to write an ELF file even if there are link errors.
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
77 CHAPTER 4 Output file options
4.2.8 --no-force-output
Summary
Do not write ELF file when link errors.
Syntax
--no-force-output
Description
This option instructs the linker not to write an ELF file in the presence of errors.
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
78 CHAPTER 4 Output file options
4.2.9 --full-program-headers
Summary
Produce program headers for all load regions.
Syntax
--full-program-headers
Description
This option produces an ELF file containing program headers for all sections including
regions that are initialized by the runtime startup using the initialization table.
Note
See also
--load-program-headers on page 80
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
79 CHAPTER 4 Output file options
4.2.10 --full-section-headers
Summary
Produce a section table with per-object sections.
Syntax
--full-section-headers
Description
This option produces an ELF file containing a detailed per-object section table.
See also
--bare on page 70, --block-section-headers on page 71, --minimal-section-headers on
page 81
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
80 CHAPTER 4 Output file options
4.2.11 --load-program-headers
Summary
Produce program headers for implicit load regions.
Syntax
--load-program-headers
Description
This option produces an ELF file containing program headers only for load regions that are
implicitly loaded. Any region that is initialized by an initialize statement or is precluded
from initialization by a do not initialize statement will be excluded from the ELF program
headers.
Note
See also
--full-program-headers on page 78
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
81 CHAPTER 4 Output file options
4.2.12 --minimal-section-headers
Summary
Produce minimal section header table.
Syntax
--minimal-section-headers
Description
This option produces an ELF file containing minimal section information (section header
string table and string table if symbols are required).
This is the default option for section headers.
See also
--bare on page 70, --block-section-headers on page 71, --full-section-headers on page 79
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
82 CHAPTER 4 Output file options
4.2.13 --output
Summary
Set output file name.
Syntax
--output filename
-o filename
--output=filename
-o=filename
Description
This option sets the ELF output filename, typically with extension “elf”.
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
83 CHAPTER 4 Output file options
4.2.14 --strip
Summary
Remove debug information and symbols.
Syntax
--strip
Description
This option eliminates all debug information, the symbol table, and the string table from
the ELF file, but does no remove the section table.
This option is equivalent to specifying --no-debug and --no-symbols.
See also
--no-debug on page 73, --no-symbols on page 85
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
84 CHAPTER 4 Output file options
4.2.15 --symbols
Summary
Include symbol table.
Syntax
--symbols
Description
This option includes the symbol table in the ELF file.
See also
--no-symbols on page 85
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
85 CHAPTER 4 Output file options
4.2.16 --no-symbols
Summary
Discard symbol table.
Syntax
--no-symbols
Description
This option removes the symbol table from the ELF file.
See also
--symbols on page 84
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
86 CHAPTER 4 Map file options
Rather than select each option individually, increasing level of detail can be selected by:
--map-none
--map-compact
--map-standard
--map-detailed
--map-full
The following table shows which sections are enabled for each detail level.
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
87 CHAPTER 4 Map file options
4.3.1 --map-file
Summary
Generate a linker map file.
Syntax
--map-file filename
--Map filename
--map-file=filename
--Map=filename
Description
Generates a linker map file to the given filename.
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
88 CHAPTER 4 Map file options
4.3.2 --map-none
Summary
Exclude all map file sections in the generated map file.
Syntax
--map-none
Description
This can be used to easily select a small subset of map sections, for example to include
only symbols and a summary use:
--map-none --map-symbols --map-summary
See also
--map-detailed on page 91, --map-full on page 92, --map-standard on page 90
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
89 CHAPTER 4 Map file options
4.3.3 --map-compact
Summary
Set compact map file options.
Syntax
--map-compact
Description
This option enables the following map section options:
--map-modules
--map-symbols
--map-summary
See also
--map-none on page 88, --map-standard on page 90, --map-detailed on page 91, --
map-full on page 92
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
90 CHAPTER 4 Map file options
4.3.4 --map-standard
Summary
Set standard map file options.
Syntax
--map-standard
--map-defaults
-M
Description
This option enables the following map section options:
--map-modules
--map-section-detail
--map-symbols
--map-summary
See also
--map-none on page 88, --map-compact on page 89, --map-detailed on page 91, --map-
full on page 92
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
91 CHAPTER 4 Map file options
4.3.5 --map-detailed
Summary
Set detailed map file options.
Syntax
--map-compact
Description
This option enables the following map section options:
--map-placement
--map-modules
--map-module-detail
--map-section-detail
--map-init-table
--map-exceptions
--map-symbols
--map-summary
See also
--map-none on page 88, --map-standard on page 90, --map-detailed on page 91, --
map-full on page 92
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
92 CHAPTER 4 Map file options
4.3.6 --map-full
Summary
Include all map file sections in the generated map file.
Syntax
--map-full
--map-all
Description
This option enables the following map section options:
--map-placement
--map-modules
--map-module-detail
--map-section-detail
--map-summary
--map-script
--map-init-table
--map-exceptions
--map-veneers
--map-symbols
--map-listing
See also
--map-none on page 88, --map-compact on page 89, --map-standard on page 90, --map-
detailed on page 91
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
93 CHAPTER 4 Map file options
4.3.7 --map-html
Summary
Generate linker map file in HTML format.
Syntax
--map-html
Description
This option formats the map file as an HTML document.
See also
--map-text on page 94
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
94 CHAPTER 4 Map file options
4.3.8 --map-text
Summary
Generate linker map file in plain text format.
Syntax
--map-html
Description
This option formats the map file as a plain text document.
See also
--map-html on page 93
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
95 CHAPTER 4 Map file options
4.3.9 --map-narrow
Summary
Enable narrow name fields in map file.
Syntax
--map-narrow
See also
--map-wide on page 96
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
96 CHAPTER 4 Map file options
4.3.10 --map-wide
Summary
Enable wide name fields in map file.
Syntax
--map-wide
See also
--map-narrow on page 95
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
97 CHAPTER 4 Map file options
4.3.11 --map-wrap
Summary
Wrap when text exceeds column with.
Syntax
--map-wrap
Description
When text within a column exceeds the column width, the linker wraps following columns
to a new line and maintains column alignment.
See also
--no-map-wrap on page 98
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
98 CHAPTER 4 Map file options
4.3.12 --no-map-wrap
Summary
Wrap when text exceeds column with.
Syntax
--no-map-wrap
Description
When text within a column exceeds the column width, the text is truncated to fix and “…”
replaces the truncated part.
See also
--map-wrap on page 97
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
99 CHAPTER 4 Map file options
4.3.13 --map-addr-format
Summary
Set the format for addresses.
Syntax
--map-addr-format=value
Description
This option defines how addresses are formatted in the map file and log file.
The following table shows the presentation for all formats and a selection of addresses.
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
100 CHAPTER 4 Map file options
4.3.14 --map-size-format
Summary
Set the format for sizes.
Syntax
--map-size-format=value
Description
This option defines how sizes are formatted in the map file and log file.
The following table shows the presentation for all formats and a selection of sizes.
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
101 CHAPTER 4 Map file options
4.3.15 --map-exception-table
Summary
Include an exception table summary in the generated map file.
Syntax
--map-exception-table
Description
The linker will gather exception tables and exception indexes together for C++ programs.
It will ensure the correct ordering of sections along with the index is maintained and will
synthesize no-unwind exception table entires for C functions without exception support.
Example
***************************************************************************************
*** ***
*** EXCEPTION TABLE ***
*** ***
***************************************************************************************
Summary:
See also
--no-map-exception-table on page 102, --optimize-exception-index on page 188, --no-
optimize-exception-index on page 189
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
102 CHAPTER 4 Map file options
4.3.16 --no-map-exception-table
Summary
Include the exception table summary from the generated map file.
Syntax
--no-map-exception-table
See also
--map-exception-table on page 101
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
103 CHAPTER 4 Map file options
4.3.17 --map-init-table
Summary
Include an initializaton table map section in the generated map file.
Syntax
--map-init-table
Example
*******************************************************************************
*** ***
*** INITIALIZATION TABLE ***
*** ***
*******************************************************************************
Zero (__SEGGER_init_zero)
1 destination range, total size 0xa5
[0x1fff0444 to 0x1fff04e8]
Totals
Table size: 0x30 bytes
Image size: 0x54 bytes
See also
--no-map-init-table on page 104
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
104 CHAPTER 4 Map file options
4.3.18 --no-map-init-table
Summary
Exclude an initializaton table map section from the generated map file.
Syntax
--no-map-init-table
See also
--map-init-table on page 103
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
105 CHAPTER 4 Map file options
4.3.19 --map-listing
Summary
Include an absolute program listing in the generated map file.
Syntax
--map-listing
Example
*******************************************************************************
*** ***
*** ABSOLUTE LISTING ***
*** ***
*******************************************************************************
;==============================================================================
; Section .init from thumb_crt0.o, alignment 4
;
_start:
0x0000051C 4924 LDR R1, [PC, #0x90]
0x0000051E 4825 LDR R0, [PC, #0x94]
0x00000520 1A0A SUBS R2, R1, R0
0x00000522 D002 BEQ 0x0000052A
0x00000524 2207 MOVS R2, #7
0x00000526 4391 BICS R1, R2
0x00000528 468D MOV SP, R1
0x0000052A 4923 LDR R1, [PC, #0x8C]
0x0000052C 4823 LDR R0, [PC, #0x8C]
0x0000052E 1A0A SUBS R2, R1, R0
0x00000530 D006 BEQ 0x00000540
0x00000532 2207 MOVS R2, #7
0x00000534 4391 BICS R1, R2
See also
--no-map-listing on page 106
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
106 CHAPTER 4 Map file options
4.3.20 --no-map-listing
Summary
Exclude an absolute program listing from the generated map file.
Syntax
--no-map-listing
See also
--map-listing on page 105
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
107 CHAPTER 4 Map file options
4.3.21 --map-listing-with-comments
Summary
Include information comments in absolute listing.
Syntax
--map-listing-with-comments
Description
When this option is selected, a comment field is appended to the instruction that describes,
for instance, the target address of a branch, the effective address of an instruction, and
any data loaded by the instruction if known.
This is the default.
See also
--no-map-listing-with-comments on page 108
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
108 CHAPTER 4 Map file options
4.3.22 --no-map-listing-with-comments
Summary
Exclude informational comments from absolute listing.
Syntax
--no-map-listing-with-comments
Description
When this option is selected, no informational comments are appended to the instruction.
See also
--map-listing-with-comments on page 107
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
109 CHAPTER 4 Map file options
4.3.23 --map-listing-with-data
Summary
Include data sections in the absolute listing.
Syntax
--map-listing-with-data
Description
The default absolute program listing selected by --map-listing will only include executable
code. The --map-listing-with-data option will include data sections (as data) in the
absolute listing.
Example
*******************************************************************************
*** ***
*** ABSOLUTE LISTING ***
*** ***
*******************************************************************************
;======================================================================================
; Section .rodata.MainTask.str1.4 from Start_Zynq7007s_emPower.o, size=16, align=4
;
.LC1:
0xFC019BF0 4C DC8 0x4C
0xFC019BF1 50 DC8 0x50
0xFC019BF2 20 DC8 0x20
0xFC019BF3 54 DC8 0x54
0xFC019BF4 61 DC8 0x61
0xFC019BF5 73 DC8 0x73
0xFC019BF6 6B DC8 0x6B
0xFC019BF7 00 DC8 0x00
;======================================================================================
; Section .rodata.OS_L2CACHE_XilinxZynq7000 from Start_Zynq7007s_emPower.o, size=24, align=4
;
OS_L2CACHE_XilinxZynq7000:
0xFC019BF8 6D8601FC DC32 0xFC01866D
0xFC019BFC A18701FC DC32 0xFC0187A1
0xFC019C00 2D8601FC DC32 0xFC01862D
0xFC019C04 4D8601FC DC32 0xFC01864D
0xFC019C08 598701FC DC32 0xFC018759
0xFC019C0C 058701FC DC32 0xFC018705
See also
--no-map-listing-with-data on page 110
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
110 CHAPTER 4 Map file options
4.3.24 --no-map-listing-with-data
Summary
Exclude data section from the absolute listing.
Syntax
--no-map-listing-with-data
Description
This option excludes any read-write, read-only, or zero-initialized data sections from the
absolute listing selected by --map-listing. Only sections marked to contain executable code
will be included in the absolute listing.
See also
--map-listing-with-data on page 109
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
111 CHAPTER 4 Map file options
Syntax
--map-listing-use-abi-names
Description
When this option is selected, instructions are disassembled using ABI register names (e.g.
a1) in preference to hard register names (e.g. x11).
This is the default.
See also
--no-map-listing-use-abi-names (RISC-V) on page 112
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
112 CHAPTER 4 Map file options
Syntax
--no-map-listing-use-abi-names
Description
When this option is selected, instructions are disassembled using hard register names (e.g.
x11) in preference to ABI register names (e.g. a1).
See also
--map-listing-use-abi-names (RISC-V) on page 111
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
113 CHAPTER 4 Map file options
Syntax
--map-listing-use-adr
Description
When this option is selected, the instruction ADD Rd, PC, #imm is shown using the standard
Arm assembler pseudo-instruction ADR Rd, addr.
This is the default.
See also
--no-map-listing-use-adr-pseudo (Arm) on page 114
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
114 CHAPTER 4 Map file options
Syntax
--no-map-listing-use-adr-pseudo
Description
When this option is selected, the instruction ADD Rd, PC, #imm is shown exactly as it appears
in the Arm Architecture Reference Manual.
See also
--map-listing-use-adr-pseudo (Arm) on page 113
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
115 CHAPTER 4 Map file options
Syntax
--map-listing-use-c-prefix
Description
When this option is selected, compact instructions are disassembled using the compact
prefix C..
See also
--no-map-listing-use-c-prefix (RISC-V) on page 116
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
116 CHAPTER 4 Map file options
Syntax
--no-map-listing-use-c-prefix
Description
When this option is selected, compact instructions are disassembled without the C. compact
prefix which is a more natural way of presenting RISC-V instructions.
This is the default.
See also
--map-listing-use-c-prefix (RISC-V) on page 115
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
117 CHAPTER 4 Map file options
Syntax
--map-listing-use-ldr-pseudo
Description
When this option is selected, the instruction LDR Rd, [PC, #offs] is shown using the
standard Arm assembler pseudo-instruction LDR Rd, =data whenever possible. The value
of data is the value that will be loaded into Rd by the instruction.
This is the default.
See also
--no-map-listing-use-ldr-pseudo (Arm) on page 118
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
118 CHAPTER 4 Map file options
Syntax
--no-map-listing-use-ldr-pseudo
Description
When this option is selected, the instruction LDR Rd, [PC, #offs] is is shown exactly as it
appears in the Arm Architecture Reference Manual.
See also
--map-listing-use-ldr-pseudo (Arm) on page 117
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
119 CHAPTER 4 Map file options
4.3.33 --map-listing-xref
Summary
Include a section cross-refernce in the absolute listing.
Syntax
--map-listing-xref
Description
The default absolute program listing selected by --map-listing will only include executable
code. The --map-listing-with-data option will include data sections (as data) in the
absolute listing.
Example
***********************************************************************************************
*** ***
*** ABSOLUTE LISTING ***
*** ***
***********************************************************************************************
;==============================================================================================
; .text.log
;==============================================================================================
; Module: floatops.o (x-libc_v7m_t_le_eabi_small_swc_ienum.a)
; Attributes: read-only, executable (SHF_EXECINSTR), allocatable (SHF_ALLOC), %progbits
; Size: 400 (0x190) bytes
; Align: 4 bytes
;
; Uses:
; 0x00002818 __aeabi_dadd
; 0x00002C6C __aeabi_dmul
; 0x00002A56 __aeabi_ddiv
; 0x000031FC __aeabi_i2d
; 0x000026F4 ldexp
; 0x00003222 frexp
; 0x0000311E __SEGGER_RTL_float64_PolyEvalP
; 0x0000307C __SEGGER_RTL_float64_PolyEvalQ
; 0x00000C00 __SEGGER_RTL_float64_Log
;
; Used by:
; 0x00002618 log1p
; 0x00001CA4 asinh
; 0x00001E68 acosh
;
log:
0x00000DE4 E92D 4FFE PUSH.W {R1-R11, LR}
0x00000DE8 F04F 32FF MOV.W R2, #0xFFFFFFFF
0x00000DEC F240 73FE MOVW R3, #0x07FE
0x00000DF0 EB02 5211 ADD.W R2, R2, R1, LSR #20
...
See also
--no-map-listing-xref on page 120
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
120 CHAPTER 4 Map file options
4.3.34 --no-map-listing-xref
Summary
Exclude section cross-reference from the absolute listing.
Syntax
--no-map-listing-xref
Description
This option excludes the section cross-reference from the listing.
See also
--map-listing-xref on page 119
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
121 CHAPTER 4 Map file options
4.3.35 --map-modules
Summary
Include a module breakdown in the generated map file.
Syntax
--map-modules
Example
***********************************************************************************************
*** ***
*** MODULE SUMMARY ***
*** ***
***********************************************************************************************
See also
--no-map-modules on page 122
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
122 CHAPTER 4 Map file options
4.3.36 --no-map-modules
Summary
Exclude a module breakdown from the generated map file.
Syntax
--no-map-modules
See also
--map-modules on page 121
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
123 CHAPTER 4 Map file options
4.3.37 --map-module-detail
Summary
Include a detailed section breakdown by module in the generated map file.
Syntax
--map-module-detail
Example
***************************************************************************************
*** ***
*** MODULE DETAIL ***
*** ***
***************************************************************************************
Module BSP.o:
Module BSP_FPGA.o:
...more modules...
All modules:
See also
--no-map-module-detail on page 124
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
124 CHAPTER 4 Map file options
4.3.38 --no-map-module-detail
Summary
Exclude a detailed section breakdown by module from the generated map file.
Syntax
--no-map-module-detail
See also
--map-module-detail on page 123
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
125 CHAPTER 4 Map file options
4.3.39 --map-placement
Summary
Include a section placement section in the generated map file.
Syntax
--map-placement
Example
*******************************************************************************
*** ***
*** PLACEMENT SUMMARY ***
*** ***
*******************************************************************************
place at 0x00000000
...more sections...
...more sections...
See also
--no-map-placement on page 126
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
126 CHAPTER 4 Map file options
4.3.40 --no-map-placement
Summary
Exclude a section placement section from the generated map file.
Syntax
--no-map-placement
See also
--map-placement on page 125
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
127 CHAPTER 4 Map file options
4.3.41 --map-script
Summary
Include a listing of all input scripts in the generated map file and include the invocation
command line.
Syntax
--map-script
See also
--no-map-script on page 128
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
128 CHAPTER 4 Map file options
4.3.42 --no-map-script
Summary
Exclude a listing of all input scripts in the generated map file and exclude the invocation
command line.
Syntax
--no-map-script
See also
--map-script on page 127
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
129 CHAPTER 4 Map file options
4.3.43 --map-section-detail
Summary
Include a detailed section breakdown in the generated map file.
Syntax
--map-section-detail
Example
***************************************************************************************
*** ***
*** SECTION DETAIL ***
*** ***
***************************************************************************************
Sections by address:
See also
--no-map-section-detail on page 130
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
130 CHAPTER 4 Map file options
4.3.44 --no-map-section-detail
Summary
Exclude a detailed section breakdown from the generated map file.
Syntax
--no-map-section-detail
See also
--map-section-detail on page 129
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
131 CHAPTER 4 Map file options
4.3.45 --map-summary
Summary
Include a link summary in the generated map file.
Syntax
--map-summary
Example
***************************************************************************************
*** ***
*** LINK SUMMARY ***
*** ***
***************************************************************************************
Load summary:
See also
--no-map-summary on page 132
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
132 CHAPTER 4 Map file options
4.3.46 --no-map-summary
Summary
Exclude a link summary from the generated map file.
Syntax
--no-map-summary
See also
--map-summary on page 131
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
133 CHAPTER 4 Map file options
4.3.47 --map-symbols
Summary
Include a symbol map section in the generated map file.
Syntax
--map-symbols
Example
*******************************************************************************
*** ***
*** SYMBOL LIST ***
*** ***
*******************************************************************************
Symbols by value
...more symbols...
Symbols by name
...more symbols...
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
134 CHAPTER 4 Map file options
4.3.48 --no-map-symbols
Summary
Exclude a symbol map section from the generated map file.
Syntax
--no-map-symbols
See also
--map-symbols on page 133
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
135 CHAPTER 4 Map file options
4.3.49 --map-unused
Summary
Include a summary of unused memory in the generated map file.
Syntax
--map-unused
Description
The linker will automatically generate a listing of all unused memory regions and the reason
they are unused.
Example
***************************************************************************************
*** ***
*** UNUSED MEMORY SUMMARY ***
*** ***
***************************************************************************************
Detail:
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
136 CHAPTER 4 Map file options
4.3.50 --no-map-unused
Summary
Exclude summary of unused memory from the generated map file.
Syntax
--no-map-unused
See also
--map-unused on page 135
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
137 CHAPTER 4 Map file options
4.3.51 --map-veneers
Summary
Include a summary of linker-created veneers in the generated map file.
Syntax
--map-veneers
Description
The linker will automatically generate veneers when required. The linker constructs two
types of veneer:
• a range extension veneer when a branch or call cannot reach the target address.
• a mode switch veneer when a branch or call requires a mode switch from one instruction
set to another.
A range extension veneer is required when execution flows over two distant memory
regions, such as flash and RAM, and these regions are far apart. Time-critical functions
are usually placed in RAM to eliminate the stalls inherent with flash memory and flash
accelerators and, therefore, execute code with known timing. If the call from flash to RAM
is too far, the linker inserts a small amount of code between functions, close to the call,
that will trampoline the call to the target with a small code and execution penalty.
A mode switch veneer is required when the calling function is written in a different
instruction set to the called function. For instance, it could be that compute-intensive code
is written in the Arm instruction set but the remainder of the application is written in the
Thumb instruction set to reduce code size. When the Arm code calls the Thumb code, a
mode switch veneer may be required if there is no instruction set support for the mode
switch.
The --map-veneers option enables a listing of all the constructed veneers for inspection.
With this information, the user is able to check that functions are coded in the correct
instruction set and that they reside in the correct memory range in order to avoid undue
veneer construction by the linker.
Example
***************************************************************************************
*** ***
*** LINKER-CREATED VENEERS ***
*** ***
***************************************************************************************
Target Source
Veneer Size Address Symbol Address Section
----------- -------- -------------------- -------- --------------------
0 Total
----------- ------------------------------
Target Source
Veneer Size Address Symbol Address Section
----------- -------- -------------------- -------- --------------------
8 00000475 _EraseSector fc2010c8 .text.FLASH_WriteEx+148
8 00000475 _EraseSector fc201114 .text.FLASH_EraseSector+64
8 000004e1 _Program fc2010c0 .text.FLASH_WriteEx+140
8 0000055d _GetUID fc201148 .text.FLASH_GetUID+48
----------- ------------------------------
32 Total
----------- ------------------------------
Target Source
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
138 CHAPTER 4 Map file options
Target Source
Veneer Size Address Symbol Address Section
----------- -------- -------------------- -------- --------------------
12 fc200800 HW_Delay_us fc201284 .text.HW_ActivateTargetPower+52
12 fc200800 HW_Delay_us fc203110 .text.HW_S8_Stop+48
12 fc200a54 OS_EnableInt fc202130 .text.OS_InitHW+320
12 fc200a54 OS_EnableInt fc2228c0 .text.USB_OS_DecRI+56
12 fc200a54 OS_EnableInt fc228b70 .text.IP_OS_EnableInterrupt+56
12 fc200a54 OS_EnableInt fc2305d8 .text.OS_EVENT_GetBlocked+236
12 fc200a54 OS_EnableInt fc230a68 .text.OS_EnableProfiling+128
12 fc200a54 OS_EnableInt fc230af8 .text.OS_TASK_LeaveRegion+120
12 fc200a54 OS_EnableInt fc230b30 .text.OS_INT_EnableConditional+52
12 fc200a54 OS_EnableInt fc230f24 .text.OS_MakeTaskReady+172
12 fc200a54 OS_EnableInt fc230f74 .text.OS_ClearWaitObj+76
12 fc200a54 OS_EnableInt fc231488 .text.OS_Deactivated+88
12 fc200a54 OS_EnableInt fc231628 .text._PutMail+112
12 fc200a54 OS_EnableInt fc2316c0 .text._GetMail+148
12 fc200a54 OS_EnableInt fc232c18 .text._CleanRange+96
12 fc200a54 OS_EnableInt fc232c74 .text._Clean+88
12 fc200a54 OS_EnableInt fc232cd0 .text._Sync+88
12 fc200a54 OS_EnableInt fc2374b8 .text._AddToConnectCnt+100
----------- ------------------------------
216 Total
=========== ==============================
260 Grand Total
----------- ------------------------------
Target Source
Veneer Size Address Symbol Address Section
----------- -------- -------------------- -------- --------------------
8 00014690 LowArmLeaf fc017f54 .text.HighArmAux+88
8 00014690 LowArmLeaf fc0180c4 .text.HighArm+340
(reused) 00014690 LowArmLeaf fc017f98 .text.HighArm+40
(reused) 00014690 LowArmLeaf fc018070 .text.HighArm+256
(reused) 00014690 LowArmLeaf fc0180b0 .text.HighArm+320
8 fc0008c0 HighArmLeaf 00014624 .fast.LowArmAux+88
8 fc0008c0 HighArmLeaf 000144d4 .fast.LowArm+332
(reused) fc0008c0 HighArmLeaf 000143a4 .fast.LowArm+28
(reused) fc0008c0 HighArmLeaf 00014458 .fast.LowArm+208
(reused) fc0008c0 HighArmLeaf 00014498 .fast.LowArm+272
----------- ------------------------------
32 Total
----------- ------------------------------
See also
--no-map-veneers on page 139
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
139 CHAPTER 4 Map file options
4.3.52 --no-map-veneers
Summary
Exclude a summary of linker-created veneers.
Syntax
--no-map-veneers
See also
--map-veneers on page 137
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
140 CHAPTER 4 Log file options
Syntax
--log-file filename
--log-file=filename
Description
Generates a linker log file to the given filename.
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
141 CHAPTER 4 Symbol and section options
Syntax
--add-region region-name=size@addr
--add-region:region-name=size@addr
--add-region=region-name=size@addr
Description
Add a region in addition to those defined in the linker script. This option allows you to write
a generic linker script file for your selected toolset and to parameterize the target’s memory
regions (typically RAM and flash) from the command line.
It is possible to define a non-continguous memory region from the command line using two
--add-region options, for example:
--add-region:RAM=64k@0x1fff0000 --add-region:RAM=192k@0x20000000
is equivalent to the linker script fragment:
define region RAM = [0x1fff0000 size 64k] | [0x20000000 size 192k];
See also
define region statement on page 49
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
142 CHAPTER 4 Symbol and section options
4.5.2 --autoat
Summary
Enable automatic placement of sections.
Syntax
--autoat
Description
When enabled, the linker places sections that conform to the “auto-at” naming convention
at the designated position in the linked image.
See also
--no-autoat on page 143
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
143 CHAPTER 4 Symbol and section options
4.5.3 --no-autoat
Summary
Disable automatic placement of sections.
Syntax
--no-autoat
Description
Turns off automatic placement of sections which use the “auto-at” naming convention.
See also
--autoat on page 142
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
144 CHAPTER 4 Symbol and section options
4.5.4 --autokeep
Summary
Enable automatic retention of sections.
Syntax
--autokeep
Description
When enabled, the linker retains all initializer and finalizer sections in all input files so they
can be selected and placed as appropriate for the runtime system. The linker defaults to
autokeep enabled.
Enabling autokeep is identical to placing the following in the linker script:
See also
--no-autokeep on page 145
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
145 CHAPTER 4 Symbol and section options
4.5.5 --no-autokeep
Summary
Disable automatic retention of sections.
Syntax
--no-autokeep
Description
The linker does not automatically keep initialization and finalization sections and it is the
user’s responsibility to keep and select them in the linker script.
See also
--autokeep on page 144
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
146 CHAPTER 4 Symbol and section options
4.5.6 --auto-arm-symbols
Summary
Enable automatic generation of Armlink symbols.
Syntax
--auto-arm-symbols
Description
Turns on automatic generation of Armlink symbols. The symbols defined in this mode are:
B$$Start
B$$Limit
B$$Length
where B is the name of a block declared using define block.
See also
--no-auto-arm-symbols on page 147
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
147 CHAPTER 4 Symbol and section options
4.5.7 --no-auto-arm-symbols
Summary
Disable automatic generation of Armlink symbols.
Syntax
--no-auto-arm-symbols
Description
Turns off automatic generation of Armlink symbols.
See also
--auto-arm-symbols on page 146
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
148 CHAPTER 4 Symbol and section options
4.5.8 --auto-es-symbols
Summary
Enable automatic generation of Embedded Studio symbols.
Syntax
--auto-es-symbols
Description
Turns on automatic generation of Embedded Studio symbols. This option is equivalent to
specifying --auto-es-block-symbols and --auto-es-region-symbols.
The symbols defined in this mode are:
__B_start__
__B_end__
__B_size__
__B_start
__B_end
__B_size
where B is the name of a block declared using define block, and:
__R_segment_start__
__R_segment_end__
__R_segment_size__
__R_segment_used_start__
__R_segment_used_end__
__R_segment_used_size__
where R is the name of a memory region created by a define region script command or
by the --add-region command line option.
See also
--auto-es-block-symbols on page 150, --auto-es-region-symbols on page 152, --no-
auto-es-symbols on page 149
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
149 CHAPTER 4 Symbol and section options
4.5.9 --no-auto-es-symbols
Summary
Disable automatic generation of Embedded Studio symbols.
Syntax
--no-auto-es-symbols
Description
Turns off automatic generation of Embedded Studio symbols.
See also
--auto-es-symbols on page 148
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
150 CHAPTER 4 Symbol and section options
4.5.10 --auto-es-block-symbols
Summary
Enable automatic generation of Embedded Studio block symbols.
Syntax
--auto-es-block-symbols
Description
The symbols defined in this mode are:
__B_start__
__B_end__
__B_size__
__B_start
__B_end
__B_size
where B is the name of a block declared using define block.
See also
--no-auto-es-block-symbols on page 151
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
151 CHAPTER 4 Symbol and section options
4.5.11 --no-auto-es-block-symbols
Summary
Disable automatic generation of Embedded Studio block symbols.
Syntax
--no-auto-es-block-symbols
Description
Turns off automatic generation of Embedded Studio block symbols.
See also
--auto-es-block-symbols on page 150
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
152 CHAPTER 4 Symbol and section options
4.5.12 --auto-es-region-symbols
Summary
Enable automatic generation of Embedded Studio region symbols.
Syntax
--auto-es-region-symbols
Description
Turns on automatic generation of Embedded Studio region symbols. The symbols defined
in this mode are:
__R_segment_start__
__R_segment_end__
__R_segment_size__
__R_segment_used_start__
__R_segment_used_end__
__R_segment_used_size__
where R is the name of a memory region created by a define region script command or
by the --add-region command line option.
See also
--no-auto-es-region-symbols on page 153
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
153 CHAPTER 4 Symbol and section options
4.5.13 --no-auto-es-region-symbols
Summary
Disable automatic generation of Embedded Studio region symbols.
Syntax
--no-auto-es-region-symbols
Description
Turns off automatic generation of Embedded Studio region symbols.
See also
--auto-es-region-symbols on page 152
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
154 CHAPTER 4 Symbol and section options
4.5.14 --define-symbol
Summary
Define linker symbol.
Syntax
--define-symbol name=number | name
--defsym:name=number | name
--defsym=name=number | name
-defsym:name=number | name
-defsym=name=number | name
-Dname=number | name
-Dname=number | name
Description
Define the symbol name as either a number or the value of an existing symbol.
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
155 CHAPTER 4 Symbol and section options
4.5.15 --enable-lzss
Summary
Enable LZSS algorithm in auto packing selection.
Syntax
--enable-lzss
Description
When this option is specified, the LZSS compression algorithm is a a candidate algorithm
when selecting a packing algorithm using packing=auto. This is the default.
See also
--disable-lzss on page 156
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
156 CHAPTER 4 Symbol and section options
4.5.16 --disable-lzss
Summary
Disable LZSS algorithm in auto packing selection.
Syntax
--disable-lzss
Description
When this option is specified, the LZSS compression algorithm is not a candidate algorithm
when selecting a packing algorithm using packing=auto.
Note that disabling LZSS compression in this manner does not prevent it from being selected
as a packing algorithm using with packing=lzss in an initialize by copy statement.
See also
--enable-lzss on page 155
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
157 CHAPTER 4 Symbol and section options
4.5.17 --enable-packbits
Summary
Enable PackBits algorithm in auto packing selection.
Syntax
--enable-packbits
Description
When this option is specified, the PackBits compression algorithm is a a candidate algorithm
when selecting a packing algorithm using packing=auto. This is the default.
See also
--disable-packbits on page 158
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
158 CHAPTER 4 Symbol and section options
4.5.18 --disable-packbits
Summary
Disable PackBits algorithm in auto packing selection.
Syntax
--enable-packbits
Description
When this option is specified, the PackBits compression algorithm is not a candidate
algorithm when selecting a packing algorithm using packing=auto.
Note that disabling PackBits compression in this manner does not prevent it from being
selected as a packing algorithm using with packing=packbits in an initialize by copy
statement.
See also
--enable-packbits on page 157
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
159 CHAPTER 4 Symbol and section options
4.5.19 --enable-zpak
Summary
Enable ZPak algorithm in auto packing selection.
Syntax
--enable-zpak
Description
When this option is specified, the SEGGER ZPak compression algorithm is a a candidate
algorithm when selecting a packing algorithm using packing=auto. This is the default.
See also
--disable-zpak on page 160
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
160 CHAPTER 4 Symbol and section options
4.5.20 --disable-zpak
Summary
Disable ZPak algorithm in auto packing selection.
Syntax
--disable-zpak
Description
When this option is specified, the SEGGER ZPak compression algorithm is not a candidate
algorithm when selecting a packing algorithm using packing=auto.
Note that disabling ZPak compression in this manner does not prevent it from being selected
as a packing algorithm using with packing=zpak in an initialize by copy statement.
See also
--enable-zpak on page 159
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
161 CHAPTER 4 Symbol and section options
4.5.21 --keep
Summary
Keep symbol.
Syntax
--keep name
--keep=name
Description
The linker keeps code and data reachable from root symbols, such as the entry point symbol,
and discards all other sections. If an application image must contain some code or data
(such as configuration or personalization data) that is not directly reachable from the root
symbols, use this option to instruct the linker to treat additional symbols as roots.
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
162 CHAPTER 4 Symbol and section options
4.5.22 --min-align-code
Summary
Set minimum code section alignment.
Description
Please see --min-align-rx on page 168.
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
163 CHAPTER 4 Symbol and section options
4.5.23 --min-align-data
Summary
Set minimum data section alignment.
Syntax
--min-align-data=value
Description
This option overrides the alignment of all data section (read-only, read-write, zero-
initialized) from input object files and libraries such that each section has a minimum
alignment requirement of value bytes (which is limited to 1024).
This options can be useful to force data that would be aligned on an odd byte address to an
even or word-aligned address. Some example applications from silicon vendors have made
assumptions regarding alignment of data and will fail to work correctly, usually failing with
a misaligned load or store resulting in a hard fault. This is not a fault of the linker, which
honors all alignment requirements, but increasing the alignment of all data to at least four
bytes can quickly identify if a hard fault is caused by alignment assumptions.
See also
--min-align-ro on page 165, --min-align-rw on page 167, --min-align-rx on page 168
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
164 CHAPTER 4 Symbol and section options
4.5.24 --min-align-ram
Summary
Set minimum read-write and zero-initialized section alignment.
Syntax
--min-align-ram=value
Description
This option overrides the alignment of read-write and zero-initialized sections from input
object files and libraries such that each section has a minimum alignment requirement of
value bytes (which is limited to 1024).
See also
--min-align-rw on page 167, --min-align-zi on page 169
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
165 CHAPTER 4 Symbol and section options
4.5.25 --min-align-ro
Summary
Set minimum read-only data section alignment.
Syntax
--min-align-ro=value
Description
This option overrides the alignment of all read-only data sections from input object files
and libraries such that each section has a minimum alignment requirement of value bytes
(which is limited to 1024).
This options can be useful to force data that would be aligned on an odd byte address to an
even or word-aligned address. Some example applications from silicon vendors have made
assumptions regarding alignment of data and will fail to work correctly, usually failing with
a misaligned load or store resulting in a hard fault. This is not a fault of the linker, which
honors all alignment requirements, but increasing the alignment of all data to at least four
bytes can quickly identify if a hard fault is caused by alignment assumptions.
See also
--min-align-data on page 163, --min-align-rw on page 167, --min-align-zi on page 169
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
166 CHAPTER 4 Symbol and section options
4.5.26 --min-align-rom
Summary
Set minimum read-execute and read-only section alignment.
Syntax
--min-align-rom=value
Description
This option overrides the alignment of read-execute and read-only sections from input
object files and libraries such that each section has a minimum alignment requirement of
value bytes (which is limited to 1024). Read-execute and read-only sections are typically
allocated to flash memory on an embedded system.
See also
--min-align-rw on page 167, --min-align-zi on page 169
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
167 CHAPTER 4 Symbol and section options
4.5.27 --min-align-rw
Summary
Set minimum read-write data section alignment.
Syntax
--min-align-rw=value
Description
This option overrides the alignment of all read-write data sections from input object files
and libraries such that each section has a minimum alignment requirement of value bytes
(which is limited to 1024).
This options can be useful to force data that would be aligned on an odd byte address to an
even or word-aligned address. Some example applications from silicon vendors have made
assumptions regarding alignment of data and will fail to work correctly, usually failing with
a misaligned load or store resulting in a hard fault. This is not a fault of the linker, which
honors all alignment requirements, but increasing the alignment of all data to at least four
bytes can quickly identify if a hard fault is caused by alignment assumptions.
See also
--min-align-data on page 163, --min-align-ro on page 165, --min-align-zi on page 169
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
168 CHAPTER 4 Symbol and section options
4.5.28 --min-align-rx
Summary
Set minimum code section alignment.
Syntax
--min-align-rx=value
--min-align-code=value
Description
This option overrides the alignment of read-execute sections from input object files and
libraries such that each section has a minimum alignment requirement of value bytes (which
is limited to 1024).
This options can be useful to force functions that would have two-byte alignment to be
aligned on four-byte boundaries which may increase the effectiveness of flash accelerators
and thereby increase execution speed (but at the expense of some wasted flash storage
for the alignment).
It can also be used to increase the alignment of all functions to 16-byte boundaries that
some flash accelerators benefit from.
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
169 CHAPTER 4 Symbol and section options
4.5.29 --min-align-zi
Summary
Set minimum zero-initialized data section alignment.
Syntax
--min-align-zi=value
Description
This option overrides the alignment of all zero-initialized data sections from input object
files and libraries such that each section has a minimum alignment requirement of value
bytes (which is limited to 1024).
This options can be useful to force data that would be aligned on an odd byte address to an
even or word-aligned address. Some example applications from silicon vendors have made
assumptions regarding alignment of data and will fail to work correctly, usually failing with
a misaligned load or store resulting in a hard fault. This is not a fault of the linker, which
honors all alignment requirements, but increasing the alignment of all data to at least four
bytes can quickly identify if a hard fault is caused by alignment assumptions.
See also
--min-align-data on page 163, --min-align-ro on page 165, --min-align-rw on page 167
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
170 CHAPTER 4 Symbol and section options
4.5.30 --pad-all
Summary
Pad all sections.
Syntax
--pad-all
Description
Pad all sections to a multiple of their alignment. The linker adds 0xFF bytes to the end of
any code or read-only data section and 0x00 bytes to the end of any read-write or zero-
initialized section when padding. A maximum alignment of 16 is enforced for padding such
that a maximum of 15 bytes are added to the end of the section in order to limit the
maximum expansion of a section.
Note
This option is equivalent to specifying specifying --pad-ro, --pad-rw, --pad-rx, --pad-zi.
See also
--pad-ro on page 175, --pad-rw on page 177, --pad-rx on page 178, --pad-zi on
page 179
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
171 CHAPTER 4 Symbol and section options
4.5.31 --pad-code
Summary
Pad code sections.
Syntax
--pad-code
Description
Pad all code sections to a multiple of their alignment. The linker adds 0xFF bytes to the end
of any code section when padding. A maximum alignment of 16 is enforced for padding
such that a maximum of 15 bytes are added to the end of the section in order to limit the
maximum expansion of a section.
Note
This option is equivalent to specifying --pad-rx.
See also
--pad-rx on page 178
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
172 CHAPTER 4 Symbol and section options
4.5.32 --pad-data
Summary
Pad data sections.
Syntax
--pad-data
Description
Pad all data sections to a multiple of their alignment. The linker adds 0xFF bytes to the end
of any read-only data section and 0x00 bytes to the end of any read-write or zero-initialized
section when padding. A maximum alignment of 16 is enforced for padding such that a
maximum of 15 bytes are added to the end of the section in order to limit the maximum
expansion of a section.
Note
This option is equivalent to specifying --pad-ro, --pad-rw, --pad-zi.
See also
--pad-ro on page 175, --pad-rw on page 177, --pad-zi on page 179
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
173 CHAPTER 4 Symbol and section options
4.5.33 --pad-none
Summary
Do not pad sections.
Syntax
--pad-none
Description
Turn of padding for all sections, i.e. no section is padded.
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
174 CHAPTER 4 Symbol and section options
4.5.34 --pad-ram
Summary
Pad RAM-based sections.
Syntax
--pad-ram
Description
Pad all RAM-based sections to a multiple of their alignment. The linker adds 0x00 bytes to
the end of any read-write or zero-initialized when padding. A maximum alignment of 16 is
enforced for padding such that a maximum of 15 bytes are added to the end of the section
in order to limit the maximum expansion of a section.
Note
This option is equivalent to specifying --pad-rw, --pad-zi.
See also
--pad-rw on page 177, --pad-zi on page 179
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
175 CHAPTER 4 Symbol and section options
4.5.35 --pad-ro
Summary
Pad read-only data sections.
Syntax
--pad-ro
Description
Pad all read-only data sections to a multiple of their alignment. The linker adds 0xFF bytes
to the end of any read-only data section when padding. A maximum alignment of 16 is
enforced for padding such that a maximum of 15 bytes are added to the end of the section
in order to limit the maximum expansion of a section.
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
176 CHAPTER 4 Symbol and section options
4.5.36 --pad-rom
Summary
Pad ROM-based sections.
Syntax
--pad-rom
Description
Pad all ROM-based sections to a multiple of their alignment. The linker adds 0xFF bytes
to the end of any code or read-only data section when padding. A maximum alignment of
16 is enforced for padding such that a maximum of 15 bytes are added to the end of the
section in order to limit the maximum expansion of a section.
Note
This option is equivalent to specifying --pad-ro, --pad-rx.
See also
--pad-ro on page 175, --pad-rx on page 178
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
177 CHAPTER 4 Symbol and section options
4.5.37 --pad-rw
Summary
Pad read-write sections.
Syntax
--pad-rw
Description
Pad all read-write sections to a multiple of their alignment. The linker adds 0x00 bytes to
the end of any read-write section when padding. A maximum alignment of 16 is enforced
for padding such that a maximum of 15 bytes are added to the end of the section in order
to limit the maximum expansion of a section.
See also
--pad-data on page 172, --pad-zi on page 179
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
178 CHAPTER 4 Symbol and section options
4.5.38 --pad-rx
Summary
Pad code sections.
Syntax
--pad-rx
Description
Pad all code sections to a multiple of their alignment. The linker adds 0xFF bytes to the end
of any code section when padding. A maximum alignment of 16 is enforced for padding
such that a maximum of 15 bytes are added to the end of the section in order to limit the
maximum expansion of a section.
Note
This option is equivalent to specifying --pad-code.
See also
--pad-code on page 171
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
179 CHAPTER 4 Symbol and section options
4.5.39 --pad-zi
Summary
Pad read-write sections.
Syntax
--pad-zi
Description
Pad all zero-initialized sections to a multiple of their alignment. The linker adds 0x00 bytes
to the end of any zero-initialized section when padding. A maximum alignment of 16 is
enforced for padding such that a maximum of 15 bytes are added to the end of the section
in order to limit the maximum expansion of a section.
See also
--pad-data on page 172, --pad-rw on page 177
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
180 CHAPTER 4 Symbol and section options
4.5.40 --pretty-section-names
Summary
Demangle Elf section names to human-readable C++ section names
Syntax
--pretty-section-names
Description
The names of Elf sections containing C++ functions and objects are encoded by the compiler
to produce an acceptable ELF section name in a process generally known as “mangling”.
Unfortunately this name is incomprehensible by the average user as it doesn’t directly relate
to the C++ souce code.
With this option, the linker recognizes these encoded ELF section names and “demangles”
them to a human-readable section names referring to the C++ object or function name.
This is the default.
See also
--no-pretty-section-names on page 181
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
181 CHAPTER 4 Symbol and section options
4.5.41 --no-pretty-section-names
Summary
Do not demangle Elf section names to human-readable C++ section names
Syntax
--no-pretty-section-names
Description
The names of C++ functions and objects are encoded by the compiler to produce an
acceptable ELF section name in a process generally known as “mangling”. Unfortunately
this name is incomprehensible by the average user as it doesn’t directly relate to the C+
+ souce code.
With this option, the linker leaves section names in their native state, useful for tool
developers and integrators.
See also
--pretty-section-names on page 180
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
182 CHAPTER 4 Symbol and section options
4.5.42 --pretty-symbol-names
Summary
Demangle Elf symbols to human-readable C++ symbols
Syntax
--pretty-symbol-names
Description
The names of C++ functions and objects are encoded by the compiler to produce an
acceptable ELF symbol name in a process generally known as “mangling”. Unfortunately
this name is incomprehensible by the average user as it doesn’t directly relate to the C+
+ souce code.
With this option, the linker recognizes these encoded ELF symbols and “demangles” them
to a human-readable C++ object or function name.
This is the default.
See also
--no-pretty-symbol-names on page 183
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
183 CHAPTER 4 Symbol and section options
4.5.43 --no-pretty-symbol-names
Summary
Do not demangle Elf symbols to human-readable C++ symbols
Syntax
--no-pretty-symbol-names
Description
The names of C++ functions and objects are encoded by the compiler to produce an
acceptable ELF symbol name in a process generally known as “mangling”. Unfortunately
this name is incomprehensible by the average user as it doesn’t directly relate to the C+
+ souce code.
With this option, the linker leaves symbol names in their native state, useful for tool
developers and integrators.
See also
--pretty-symbol-names on page 182
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
184 CHAPTER 4 Symbol and section options
4.5.44 --undefined-weak-is-zero
Summary
Undefined weak references are replaced with zero.
Syntax
--undefined-weak-is-zero
Description
All references to an undefined weak symbol are resolved as if the weak symbol had the
value zero.
Note
The Arm EABI requires that direct calls to undefined weak symbols are replaced with no-
operation instructions rather than a call to location zero. This behavior is implemented
irrespective of the --no-undefined-weak-is-zero and --undefined-weak-is-zero setting.
See also
--undefined-weak-is-zero on page 184
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
185 CHAPTER 4 Symbol and section options
4.5.45 --no-undefined-weak-is-zero
Summary
Report undefined weak references as errors.
Syntax
--no-undefined-weak-is-zero
Description
A reference to an undefined weak symbol is reported as an error. This is the default setting.
Note
The Arm EABI requires that direct calls to undefined weak symbols are replaced with no-
operation instructions. This behavior is implemented irrespective of the --no-undefined-
weak-is-zero and --undefined-weak-is-zero setting.
See also
--undefined-weak-is-zero on page 184
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
186 CHAPTER 4 Symbol and section options
4.5.46 --unwind-tables
Summary
Include and generate exception unwinding tables.
Syntax
--unwind-tables
Description
Include all references exception unwinding entries and create an unwinding table for stack
unwinding according to the Arm EAEBI. This is the default.
Notes
If there are no sections that have associated unwinding information, the table is empty and
takes no space in the application even with this option selected.
See also
--no-unwind-tables on page 187
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
187 CHAPTER 4 Symbol and section options
4.5.47 --no-unwind-tables
Summary
Remove exception unwinding tables.
Syntax
--no-unwind-tables
Description
Remove all references to exception unwinding entries and do not create an unwiding table
for stack unwinding. In this case it is not possible for C or C++ code to throw exceptions
or unwind the stack.
See also
--unwind-tables on page 186
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
188 CHAPTER 4 Symbol and section options
4.5.48 --optimize-exception-index
Summary
Optimize exception index table.
Syntax
--optimize-exception-index
Description
Directs the linker to optimize the exception index by collapsing adjacent entries with
identical unwind sequences.
Collapsing one or more adjacent entries with the same unwind sequence reduces the size
of the exception index and also reduces the time required to search for an entry at runtime
when an exception is thrown.
This is the default.
See also
--no-optimize-exception-index on page 189
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
189 CHAPTER 4 Symbol and section options
4.5.49 --no-optimize-exception-index
Summary
Do not optimize exception index table.
Syntax
--no-optimize-exception-index
Description
Directs the linker to retain individual exception index entries and not collapse them.
See also
--optimize-exception-index on page 188
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
190 CHAPTER 4 Symbol and section options
4.5.50 --wrap
Summary
Wrap symbol.
Syntax
--wrap name
Description
Use a wrapper function for the symbol name. Any undefined reference to the symbol name
will be resolved to __wrap_name. The existing definition of the symbol name will be renamed
to __real_name. This can be used to provide a wrapper for library functions, e.g. to provide
a trace or monitoring capability.
Example
In this example the symbol sin is wrapped so that its inputs and output can be monitoed.
As the function is typically provided in a object library, it cannot easily be changen, but
symbol wrapping provides a way to modify its behavior.
#include <stdio.h>
#include <math.h>
double __real_sin(double);
void main(void) {
double x;
//
x = sin(2.7);
}
Note
Wrapping is performed by the linker where references to the wrapped function are replaced.
The linker will not be able to wrap references that are resolved internally by the assembler
(which do not lead to a name resolution), or when link-time optimization is selected.
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
191 CHAPTER 4 Program transformation options
Syntax
--dedupe-code
--dedupe-rx
Description
This option instructs the linker to try to find readonly code sections that are identical and
discard duplicates, retaining a single “leader” instance.
This optimization potentially reduces readonly code size with no detrimental effect on
runtime performance (and may even enhance performance for cached systems).
See also
--no-dedupe-code on page 192
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
192 CHAPTER 4 Program transformation options
4.6.2 --no-dedupe-code
Summary
Do not deduplicate code sections.
Syntax
--no-dedupe-code
--no-dedupe-rx
Description
This option instructs the linker not to deduplicate readonly code sections.
See also
--dedupe-code on page 191
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
193 CHAPTER 4 Program transformation options
4.6.3 --dedupe-data
Summary
Deduplicate data sections.
Syntax
--dedupe-data
--dedupe-ro
Description
This option instructs the linker to try to find readonly data sections that are identical and
discard duplicates, retaining a single “leader” instance.
This optimization potentially reduces readonly data size with no detrimental effect on
runtime performance.
See also
--no-dedupe-data on page 194
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
194 CHAPTER 4 Program transformation options
4.6.4 --no-dedupe-data
Summary
Do not deduplicate data sections.
Syntax
--no-dedupe-data
--no-dedupe-ro
Description
This option instructs the linker not to deduplicate readonly data sections.
See also
--dedupe-data on page 193
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
195 CHAPTER 4 Program transformation options
4.6.5 --inline
Summary
Inline small functions.
Syntax
--inline
Description
This option instructs the linker to inline small functions at the call site rather than calling
the function. Functions that take one or two halfwords, excluding function return, can be
inlined in many cases.
If all instances of calls to the function are inlined, it becomes possible for the called function
to be eliminated entirely as long as it is not used as a function pointer.
This optimization always increases runtime performance and may reduce overall code size.
See also
--no-inline on page 196
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
196 CHAPTER 4 Program transformation options
4.6.6 --no-inline
Summary
Do not inline small functions.
Syntax
--no-inline
Description
This option instructs the linker not to inline small functions.
See also
--inline on page 195
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
197 CHAPTER 4 Program transformation options
4.6.7 --merge-sections
Summary
Merge compatible sections.
Syntax
--merge-sections
Description
This option instructs the linker to merge duplicate entries in compatible sections (sections
with the SHF_MERGE section flag set). This optimization reduces data size with no detrimental
effect on runtime performance.
This is the default.
Note that section merging is related to section deduplication, but works with finer-grained
section content.
See also
--no-merge-sections on page 198
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
198 CHAPTER 4 Program transformation options
4.6.8 --no-merge-sections
Summary
Do not merge compatible sections.
Syntax
--no-merge-strings
Description
This option instructs the linker not to perform section merging. Note that section merging
is related to section deduplication, but works with finer-grained section content.
See also
--merge-strings on page 199
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
199 CHAPTER 4 Program transformation options
4.6.9 --merge-strings
Summary
Merge string constants.
Syntax
--merge-strings
Description
This option instructs the linker to merge duplicate string constants so that the duplicates
are reduced to one shared constant thus reducing memory footprint. In addition, a string
constant matches the end of another, a single string constant suffices.
This optimization reduces data size with no detrimental effect on runtime performance.
See also
--no-merge-strings on page 200
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
200 CHAPTER 4 Program transformation options
4.6.10 --no-merge-strings
Summary
Do not merge string constants.
Syntax
--no-merge-strings
Description
This option instructs the linker to keep all duplicate string constants separate and not merge
them to a single, shared string.
See also
--merge-strings on page 199
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
201 CHAPTER 4 Program transformation options
Syntax
--outline
Description
This option instructs the linker to try to reduce code size by extracting small strands
of common code into subroutines. This reduces code size at the expense of adding one
additional subroutine call per outline fragment at runtime.
Outlining is not enabled by default.
See also
--no-outline (RISC-V) on page 202
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
202 CHAPTER 4 Program transformation options
Syntax
--no-outline
Description
This option instructs the linker not to run the outlining pass.
Outlining is not enabled by default.
See also
--outline (RISC-V) on page 201
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
203 CHAPTER 4 Program transformation options
Syntax
--relax
-mrelax
Description
This option instructs the linker to try to reduce code size by replacing data access sequences
and function calling sequences with smaller, faster sequences.
For relaxation to be effective, ELF files and archives should be compiled with relaxation
enabled before they are provided to the linker.
Instriction relaxation is enabled by default.
See also
--no-relax (RISC-V) on page 204
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
204 CHAPTER 4 Program transformation options
Syntax
--no-relax
-mno-relax
Description
This option instructs the linker not to run the relaxation pass and to leave data access
sequences and function calling sequences as they appear after compilation.
This option can reduce linking time at the expense of larger application code size.
See also
--relax (RISC-V) on page 203
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
205 CHAPTER 4 Program transformation options
Syntax
--springboard
Description
This option instructs the linker to reduce code size further than standard relaxation by
springboarding calls. Only function call sites that are marked as relaxable are eligible for
springboarding.
Springboarding adds a set of “springboards” to the end of the function. For each call in a
function, the linker determines whether it would be advantageous to replace that call with
a call through a springboard appened to the function instead. As such, a set of long calls
can be replaced by compact calls to a springboard, saving code space.
Whilst reducing code size, it also adds an execution penalty of one branch instruction for
each call that is springboarded.
Springboarding is enabled by default.
See also
--no-springboard (RISC-V) on page 206
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
206 CHAPTER 4 Program transformation options
Syntax
--no-springboard
Description
This option instructs the linker not to run the springboarding optimization.
See also
--springboard (RISC-V) on page 205
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
207 CHAPTER 4 Program transformation options
Syntax
--tail-merge
Description
This option instructs the linker to try to reduce code size by extracting small strands of
common code immediately before a function return. This reduces code size at the expense
of adding one additional jump per merged fragment at runtime.
Tail merging is not enabled by default.
See also
--no-tail-merge (RISC-V) on page 208
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
208 CHAPTER 4 Program transformation options
Syntax
--no-tail-merge
Description
This option instructs the linker not to run the tail merging pass.
Tail merging is not enabled by default.
See also
--tail-merge (RISC-V) on page 207
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
209 CHAPTER 4 Program transformation options
Syntax
--tp=model=model
Description
This option controls how the thread pointer register (tp) is used in the linked application:
none
The linker considers the thread pointer register untouchable—it is an error if thread-
local data is linked into in the application.
tls
The application uses the thread pointer register as the the base of the executing thread’s
thread-local data.
base
The linker is allowed to use the thread pointer register as a secondary base pointer,
in addition to the global pointer (gp), in order to reduce program size and increase
execution speed.
auto
The linker chooses between tls and base depending upon whether the application
requires thread-local data.
The default for this option is auto.
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
210 CHAPTER 4 Control options
Syntax
--cpu=name
-cpu=name
-mcpu=name
Description
This option selects the target processor for the application and controls the construction of
appropriate veneers when required.
The core names accepted are:
• cortex-m0
• cortex-m0plus
• cortex-m1
• cortex-m3
• cortex-m4
• cortex-m7
• cortex-m23
• cortex-m33
• cortex-a8
• cortex-a9
The architecture names accepted are:
• 6-M
• 7-M
• 7E-M
• 7-A
• 8-M.base
• 8-M.main
The default is --cpu=cortex-m0.
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
211 CHAPTER 4 Control options
Syntax
--cpu=name
-cpu=name
-mcpu=name
Description
This option selects the target processor for the application and controls the construction of
appropriate veneers when required.
The architecture names accepted are:
• rv32e
• rv32ema
• rv32emac
• rv32i
• rv32ima
• rv32imac
• rv32imaf
• rv32imafc
• rv32g
• rv32gc
The default is --cpu=rv32imac.
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
212 CHAPTER 4 Control options
4.7.3 --big-endian
Synopsis
Big-endian byte ordering.
Syntax
--big-endian
-EB
Description
Specify that all input ELF files must be in big-endian byte order and the linked output must
be in big-endian byte order.
See also
--little-endian on page 213
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
213 CHAPTER 4 Control options
4.7.4 --little-endian
Synopsis
Little-endian byte ordering.
Syntax
--little-endian
-EL
Description
Specify that all input ELF files must be in little-endian byte order and the linked output
must be in little-endian byte order.
This is the default.
See also
--big-endian on page 212
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
214 CHAPTER 4 Control options
4.7.5 --lazy-load-archives
Summary
Defer loading object modules from archives until required.
Syntax
--lazy-load-archives
Description
Delays reading the content of a required ELF object module until one of its symbols is
required. This option can improve link performance if there are archives which contain many
object files that are not ignored when linking.
For small applications and small archives, the performance gain is negligible.
For this option to work correctly, archives must contain an index to the contents, usually
created by the archiver or by ranlib. If there is no table of contents, the archive may still
be linked but lazy loading must be disabled using --no-lazy-load-archives.
See also
--no-lazy-load-archives on page 215
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
215 CHAPTER 4 Control options
4.7.6 --no-lazy-load-archives
Summary
Defer loading object modules from archives until required.
Syntax
--no-lazy-load-archives
Description
Loads all object modules from an archive before linking, irrespective of whether its content
is required or not. This option can improve link performance for archives that most always
provide required object modules. For small applications and small archives, the performance
of lazy loading and non-lazy loading is negligible.
This is the default.
See also
--lazy-load-archives on page 214
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
216 CHAPTER 4 Control options
4.7.7 --list-all-undefineds
Summary
Issue one error for each undefined symbol.
Syntax
--list-all-undefineds
Description
This option instructs the linker to issue one error per undefined symbol which is the
preferred option when running the linker inside an integrated development environment.
See also
--no-list-all-undefineds on page 217
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
217 CHAPTER 4 Control options
4.7.8 --no-list-all-undefineds
Summary
Issue one error covering all undefined symbols.
Syntax
--no-list-all-undefineds
Description
This option instructs the linker to issue a list of undefined symbols and a single error
message indicating that there are undefined symbols. This is the default option for
undefined symbols and is intended to produce clear output when the linker is run
interactively from the command line.
See also
--list-all-undefineds on page 216
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
218 CHAPTER 4 Control options
4.7.9 --remarks
Summary
Issue remarks.
Syntax
--remarks
Description
This option instructs the linker to issue remarks for potential issues during linking. This
is the default.
See also
--no-remarks on page 221, --remarks-are-warnings on page 220, --remarks-are-errors
on page 219
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
219 CHAPTER 4 Control options
4.7.10 --remarks-are-errors
Summary
Elevate remarks to errors.
Syntax
--remarks-are-errors
Description
This option elevates all remark diagnostics issued by the linker to errors.
See also
--no-remarks on page 221, --remarks on page 218, , --remarks-are-warnings on
page 220
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
220 CHAPTER 4 Control options
4.7.11 --remarks-are-warnings
Summary
Elevate remarks to warnings.
Syntax
--remarks-are-warnings
Description
This option elevates all remark diagnostics issued by the linker to warnings.
See also
--no-remarks on page 221, --remarks on page 218, , --remarks-are-errors on page 219
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
221 CHAPTER 4 Control options
4.7.12 --no-remarks
Summary
Suppress remarks.
Syntax
--no-remarks
Description
This option disables all remark diagnostics issued by the linker. Although remarks are
suppressed, the total number of remarks that are suppressed by the linker is shown at
the end of linking:
C:> _
See also
--remarks-are-warnings on page 220, --remarks-are-errors on page 219
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
222 CHAPTER 4 Control options
4.7.13 --silent
Summary
Do not show output.
Syntax
--silent
-q
Description
This option inhibits all linker status messages; only diagnostic messages are shown.
See also
--verbose on page 223
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
223 CHAPTER 4 Control options
4.7.14 --verbose
Summary
Increase verbosity.
Syntax
--verbose
-b
Description
This option increase the verbosity of the linker by one level.
See also
--silent on page 222
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
224 CHAPTER 4 Control options
4.7.15 --warn-any-double
Summary
Warn when application requires any double support.
Syntax
--warn-any-double
Description
This option instructs the linker to issue warnings when the application requires any runtime
support for the double datatype. This is useful when your application uses the float
datatype but it unintentionally promotes float to double.
For instance, the following piece of code seems to do exactly what is intended, see if a
floating value is less than 1.1:
Unfortunately the comparison is performed using double as 1.1 is a double, not float
constant.
With this option enabled, such use is diagnosed at link time:
Notes
This warning can be promoted to an error using --warnings-are-errors.
See also
--warn-unintended-double on page 225, --no-warn-double on page 226, --warnings-are-
errors on page 234
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
225 CHAPTER 4 Control options
4.7.16 --warn-unintended-double
Summary
Warn when application requires unintended double support.
Syntax
--warn-unintended-double
Description
This option instructs the linker to issue warnings when the application requires any runtime
support for the double datatype except for conversion from float to double. This is useful
when your application uses the float datatype but must also convert it to double for use in
variadic argument lists, for instance when using the SEGGER Semihosting library for output.
With this option enabled, the following code will not illicit a warning becuase promotion from
float to double is intended: in this case as all float arguments are promoted to double
when passing through a variable argument list:
…is rejected because the multiplication is performed using double arithmetic as the constant
1000.0 is a double:
Notes
With this option, conversion of float to double is permitted so that a floating argument can
be passed through a variadic argument list. Conversion from double to float is permitted
so that the incoming double argument can be converted back to float and maniplulated
using float-only arithmetic.
This warning can be promoted to an error using --warnings-are-errors.
See also
--warn-any-double on page 224, --no-warn-double on page 226, --warnings-are-errors
on page 234
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
226 CHAPTER 4 Control options
4.7.17 --no-warn-double
Summary
Do not warn when application requires double support.
Syntax
--no-warn-double
Description
This option instructs the linker inhibit warnings for applications thay require double runtime
support.
This is the default.
See also
--warn-any-double on page 224, --warn-unintended-double on page 225
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
227 CHAPTER 4 Control options
Syntax
--warn-arch-mismatch
Description
This option instructs the linker to issue a warning when it detects linkage of ELF files with
mismatching architecture flags in the ELF header.
This is the default.
See also
--no-warn-arch-mismatch (RISC-V) on page 228
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
228 CHAPTER 4 Control options
Syntax
--no-warn-arch-mismatch
Description
This option instructs the linker not to issue a warning when it detects linkage of ELF files
with mismatching architecture flags in the ELF header. Although matching architecture flags
for all inputs is ideal, it may be that linking object files with incorrect flags is unavoidable,
in which case specifying this option will silence the warning.
See also
--warn-arch-mismatch (RISC-V) on page 227
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
229 CHAPTER 4 Control options
4.7.20 --warn-deprecated
Summary
Issue warnings for deprecated features.
Syntax
--warn-deprecated
Description
This option instructs the linker to issue a diagnostic remark for features that are deprecated
and due to be removed. This can be elevated to a warning by using --remarks-are-warnings.
See also
--no-warn-deprecated on page 230, --remarks-are-warnings on page 220
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
230 CHAPTER 4 Control options
4.7.21 --no-warn-deprecated
Summary
Do not issue warnings for deprecated features.
Syntax
--no-warn-deprecated
Description
This option instructs the linker not to issue diagnostic remarks for features that are
deprecated and due to be removed.
This is the default.
See also
--warn-deprecated on page 229
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
231 CHAPTER 4 Control options
4.7.22 --warn-empty-selects
Summary
Issue warnings for potential section selection errors.
Syntax
--warn-empty-selects
Description
This option instructs the linker to issue warnings for section selections that do not select
any sections.
Consider a section “.IDLABEL” that is intended to be selected into a region IDREGION using
the section selection statement:
Because the section name in the ELF file (.IDLABEL) does not exactly match the section
name in the section selector (IDLABEL, no period), the section is not selected and therefore
not placed into IDREGION.
This option instructs the linker to issue a warning when an exact section selector, in this
case section IDLABEL, does not select any section and as such could be considered an error.
See also
--no-warn-empty-selects on page 232
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
232 CHAPTER 4 Control options
4.7.23 --no-warn-empty-selects
Summary
Do not issue warnings for potential section selection errors.
Syntax
--no-warn-empty-selects
Description
This option instructs the linker inhibit warnings for section selections that do not select
any sections.
See also
--warn-empty-selects on page 231
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
233 CHAPTER 4 Control options
4.7.24 --warnings
Summary
Issue warnings.
Syntax
--warnings
Description
This option instructs the linker to issue warnings for dubious use or inputs. This is the
default.
See also
--no-warnings on page 235, --warnings-are-errors on page 234
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
234 CHAPTER 4 Control options
4.7.25 --warnings-are-errors
Summary
Elevate warnings to errors.
Syntax
--warnings-are-errors
--fatal-warnings
Description
This option elevates all warning diagnostics issued by the linker to errors.
See also
--no-warnings on page 235, --warnings on page 233
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
235 CHAPTER 4 Control options
4.7.26 --no-warnings
Summary
Suppress warnings.
Syntax
--no-warnings
Description
This option disables all warning diagnostics issued by the linker. Although warnings are
suppressed, the total number of warnings that are suppressed by the linker is shown at
the end of linking:
C:> _
See also
--warnings on page 233, --warnings-are-errors on page 234
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
236 CHAPTER 4 Compatibility options
Syntax
--begin-group
-(
Description
This option is accepted for GNU ld compatibility and is otherwise ignored. The SEGGER
Linker will automatically resolve references from object files and libraries and does not
require library grouping to do so.
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
237 CHAPTER 4 Compatibility options
4.8.2 --end-group
Synopsis
End input file group.
Syntax
--end-group
-)
Description
This option is accepted for GNU ld compatibility and is otherwise ignored.
The SEGGER Linker will automatically resolve references from object files and libraries and
does not require library grouping to do so.
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
238 CHAPTER 4 Compatibility options
4.8.3 --emit-relocs
Synopsis
Emit relocations.
Syntax
--emit-relocs
Description
This option is accepted for GNU ld compatibility and is otherwise ignored.
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
239 CHAPTER 4 Compatibility options
4.8.4 --allow-multiple-definition
Synopsis
Allow multiple definitions of the same symbol.
Syntax
--allow-multiple-definition
Description
This option is accepted for GNU ld compatibility and is otherwise ignored.
The SEGGER Linker does not support multiple definitions of identical symbols: a symbol is
required to have exactly one strong definition.
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
240 CHAPTER 4 Compatibility options
4.8.5 --gc-sections
Synopsis
Garbage collect sections.
Syntax
--gc-sections
Description
This option is accepted for GNU ld compatibility and is otherwise ignored.
The SEGGER Linker only includes sections that are reachable from root symbols and,
therefore, this option is redundant.
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
241 CHAPTER 4 Compatibility options
4.8.6 --omagic
Synopsis
Set NMAGIC flag.
Syntax
--omagic
Description
This option is accepted for GNU ld compatibility and is otherwise ignored.
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
242 CHAPTER 4 Compatibility options
4.8.7 --discard-locals
Synopsis
Discard local symbols.
Syntax
--discard-locals
-X
Description
This option is accepted for GNU ld compatibility and is otherwise ignored.
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
Chapter 5
Indexes
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
244 INDEXES Subject index
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
245 INDEXES Subject index
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH
246 INDEXES Subject index
region, 18
conditional, 20
SEGGER Linker User Guide & Reference Manual © 2017-2020 SEGGER Microcontroller GmbH