ARM Assembly Language Tools v15.12.0.LTS User's Guide
SPNU118O - REVISED JANUARY 2016

The ARM linker creates executable modules by combining object modules. This chapter describes the linker options, directives, and statements used to create executable modules. Object libraries, command files, and other key concepts are discussed as well.

The concept of sections is basic to linker operation; Section 2 includes a detailed discussion of sections.

The ARM linker allows you to allocate output sections efficiently in the memory map. As the linker combines object files, it performs the following tasks:

• Allocates sections into the target system's configured memory
• Relocates symbols and sections to assign them to final addresses
• Resolves undefined external references between input files

The linker command language controls memory configuration, output section definition, and address binding. The language supports expression assignment and evaluation. You configure system memory by defining and creating a memory model that you design. Two powerful directives, MEMORY and SECTIONS, allow you to:

• Allocate sections into specific areas of memory
• Combine object file sections
• Define or redefine global symbols at link time

8.2 The Linker's Role in the Software Development Flow

illustrates the linker's role in the software development process. The linker accepts several types of files as input, including object files, command files, libraries, and partially linked files. The linker creates an executable object module that can be downloaded to one of several development tools or executed by a ARM device.

The general syntax for invoking the linker is:

 armcl --run_linker [options] filename1 .... filenamen
 armcl --run_linker is the command that invokes the linker. The --run_linker option's short form is -z. options can appear anywhere on the command line or in a linker command file. (Options are discussed in Section 8.4.) filename1, filenamen can be object files, linker command files, or archive libraries. The default extension for all input files is .obj; any other extension must be explicitly specified. The linker can determine whether the input file is an object or ASCII file that contains linker commands. The default output filename is a.out, unless you use the --output_file option to name the output file.

There are two methods for invoking the linker:

• Specify options and filenames on the command line. This example links two files, file1.obj and file2.obj, and creates an output module named link.out.
•  armcl --run_linker file1.obj file2.obj --output_file=link.out 
• Put filenames and options in a linker command file. Filenames that are specified inside a linker command file must begin with a letter. For example, assume the file linker.cmd contains the following lines:
•  --output_file=link.out file1.obj file2.obj

Now you can invoke the linker from the command line; specify the command filename as an input file:

 armcl --run_linker linker.cmd 

When you use a command file, you can also specify other options and files on the command line. For example, you could enter:

 armcl --run_linker --map_file=link.map linker.cmd file3.obj 

The linker reads and processes a command file as soon as it encounters the filename on the command line, so it links the files in this order: file1.obj, file2.obj, and file3.obj. This example creates an output file called link.out and a map file called link.map.

For information on invoking the linker for C/C++ files, see Section 8.11.

Linker options control linking operations. They can be placed on the command line or in a command file. Linker options must be preceded by a hyphen (-). Options can be separated from arguments (if they have them) by an optional space.

Table 8-1 Basic Options Summary

Option Alias Description Section
--output_file -o Names the executable output module. The default filename is a.out. Section 8.4.25
--map_file -m Produces a map or listing of the input and output sections, including holes, and places the listing in filename Section 8.4.20
--stack_size -stack Sets C system stack size to sizebytes and defines a global symbol that specifies the stack size. Default = 2K bytes Section 8.4.31
--heap_size -heap Sets heap size (for the dynamic memory allocation in C) to sizebytes and defines a global symbol that specifies the heap size. Default = 2K bytes Section 8.4.16

Table 8-2 File Search Path Options Summary

Option Alias Description Section
--library -l Names an archive library or link command filename as linker input Section 8.4.18
--search_path -i Alters library-search algorithms to look in a directory named with pathname before looking in the default location. This option must appear before the --library option. Section 8.4.18.1
--priority -priority Satisfies unresolved references by the first library that contains a definition for that symbol Section 8.4.18.3
--reread_libs -x Forces rereading of libraries, which resolves back references Section 8.4.18.3
--disable_auto_rts Disables the automatic selection of a run-time-support library Section 8.4.9

Table 8-3 Command File Preprocessing Options Summary

Option Alias Description Section
--define Predefines name as a preprocessor macro. Section 8.4.11
--undefine Removes the preprocessor macro name. Section 8.4.11
--disable_pp Disables preprocessing for command files Section 8.4.11

Table 8-4 Diagnostic Options Summary

Option Alias Description Section
--diag_error Categorizes the diagnostic identified by num as an error Section 8.4.8
--diag_remark Categorizes the diagnostic identified by num as a remark Section 8.4.8
--diag_suppress Suppresses the diagnostic identified by num Section 8.4.8
--diag_warning Categorizes the diagnostic identified by num as a warning Section 8.4.8
--display_error_number Displays a diagnostic's identifiers along with its text Section 8.4.8
--emit_warnings_as_errors -pdew Treats warnings as errors
--issue_remarks Issues remarks (nonserious warnings) Section 8.4.8
--no_demangle Disables demangling of symbol names in diagnostics Section 8.4.22
--no_warnings Suppresses warning diagnostics (errors are still issued) Section 8.4.8
--set_error_limit Sets the error limit to num. The linker abandons linking after this number of errors. (The default is 100.) Section 8.4.8
--verbose_diagnostics Provides verbose diagnostics that display the original source with line-wrap Section 8.4.8
--warn_sections -w Displays a message when an undefined output section is created Section 8.4.36

Table 8-5 Linker Output Options Summary

Option Alias Description Section
--absolute_exe -a Produces an absolute, executable module. This is the default; if neither --absolute_exe nor --relocatable is specified, the linker acts as if --absolute_exe were specified. Section 8.4.3.1
--ecc:data_error Inject the specified errors into the output file for testing
--ecc:ecc_error Inject the specified errors into the Error Correcting Code (ECC) for testing
--mapfile_contents Controls the information that appears in the map file. Section 8.4.21
--relocatable -r Produces a nonexecutable, relocatable output module
--generate_dead_funcs_list Writes a list of the dead functions that were removed by the linker to file fname.
--rom -r Create a ROM object
--run_abs -abs Produces an absolute listing file Section 8.4.29
--xml_link_info Generates a well-formed XML file containing detailed information about the result of a link Section 8.4.37

Table 8-6 Symbol Management Options Summary

Option Alias Description Section
--entry_point -e Defines a global symbol that specifies the primary entry point for the output module Section 8.4.13
--globalize Changes the symbol linkage to global for symbols that match pattern Section 8.4.19
--hide Hides global symbols that match pattern Section 8.4.17
--localize Changes the symbol linkage to local for symbols that match pattern Section 8.4.19
--make_global -g Makes symbol global (overrides -h)
--make_static -h Makes all global symbols static Section 8.4.19.1
--no_symtable -s Strips symbol table information and line number entries from the output module Section 8.4.24
--retain Retains a list of sections that otherwise would be discarded
--scan_libraries -scanlibs Scans all libraries for duplicate symbol definitions Section 8.4.30
--symbol_map Maps symbol references to a symbol definition of a different name Section 8.4.33
--undef_sym -u Places an unresolved external symbol into the output module's symbol table Section 8.4.35
--unhide Reveals (un-hides) global symbols that match pattern Section 8.4.17

Table 8-7 Run-Time Environment Options Summary

Option Alias Description Section
--arg_size --args Allocates memory to be used by the loader to pass arguments Section 8.4.4
-be32 Forces the linker to generate BE-32 object code. Section 8.4.5
-be8 Forces the linker to generate BE-8 object code. Section 8.4.5
--cinit_hold_wdt={on|off} Hold (on) or do not hold (off) watchdog timer during cinit auto-initialization.
--fill_value -f Sets default fill values for holes within output sections; fill_value is a 32-bit constant Section 8.4.14
--ram_model -cr Initializes variables at load time Section 8.4.27
--rom_model -c Autoinitializes variables at run time
--trampolines Generates far call trampolines; on by default

Table 8-8 Link-Time Optimization Options Summary

Option Alias Description Section
--cinit_compression Specifies the type of compression to apply to the c auto initialization data (default is rle)
--compress_dwarf Aggressively reduces the size of DWARF information from input object files
--copy_compression Compresses data copied by linker copy tables
--unused_section_elimination Eliminates sections that are not needed in the executable module; on by default

Table 8-9 Miscellaneous Options Summary

Option Alias Description Section
--minimize_trampolines Places sections to minimize number of far trampolines required
--preferred_order Prioritizes placement of functions
--strict_compatibility Performs more conservative and rigorous compatibility checking of input object files Section 8.4.32
--trampoline_min_spacing When trampoline reservations are spaced more closely than the specified limit, tries to make them adjacent
--zero_init Controls preinitialization of uninitialized variables. Default is on.

8.4.1 Wildcards in File, Section, and Symbol Patterns

The linker allows file, section, and symbol names to be specified using the asterisk (*) and question mark (?) wildcards. Using * matches any number of characters and using ? matches a single character. Using wildcards can make it easier to handle related objects, provided they follow a suitable naming convention.

For example:

mp3*.obj /* matches anything .obj that begins with mp3 */ task?.o* /* matches task1.obj, task2.obj, taskX.o55, etc. */ SECTIONS { .fast_code: { *.obj(*fast*) } > FAST_MEM .vectors : { vectors.obj(.vector:part1:*) > 0xFFFFFF00 .str_code : { rts*.lib<str*.obj>(.text) } > S1ROM }

8.4.2 Specifying C/C++ Symbols with Linker Options

The link-time symbol is the same as the high-level language name.

See Section 8.6.1 for information about referring to linker symbols in C/C++ code.

8.4.3 Relocation Capabilities (--absolute_exe and --relocatable Options)

The linker performs relocation, which is the process of adjusting all references to a symbol when the symbol's address changes (Section 2.7).

The linker supports two options (--absolute_exe and --relocatable) that allow you to produce an absolute or a relocatable output module. The linker also supports a third option (-ar) that allows you to produce an executable, relocatable output module.

When the linker encounters a file that contains no relocation or symbol table information, it issues a warning message (but continues executing). Relinking an absolute file can be successful only if each input file contains no information that needs to be relocated (that is, each file has no unresolved references and is bound to the same virtual address that it was bound to when the linker created it).

8.4.3.1 Producing an Absolute Output Module (--absolute_exe option)

When you use the --absolute_exe option without the --relocatable option, the linker produces an absolute, executable output module. Absolute files contain no relocation information. Executable files contain the following:

• Special symbols defined by the linker (see Section 8.5.10.4)
• An header that describes information such as the program entry point
• No unresolved references

The following example links file1.obj and file2.obj and creates an absolute output module called a.out:

armcl --run_linker --absolute_exe file1.obj file2.obj

NOTE

The --absolute_exe and --relocatable Options

If you do not use the --absolute_exe or the --relocatable option, the linker acts as if you specified --absolute_exe.

8.4.3.2 Producing a Relocatable Output Module (--relocatable option)

When you use the --relocatable option, the linker retains relocation entries in the output module. If the output module is relocated (at load time) or relinked (by another linker execution), use --relocatable to retain the relocation entries.

The linker produces a file that is not executable when you use the --relocatable option without the --absolute_exe option. A file that is not executable does not contain special linker symbols or an optional header. The file can contain unresolved references, but these references do not prevent creation of an output module.

This example links file1.obj and file2.obj and creates a relocatable output module called a.out:

armcl --run_linker --relocatable file1.obj file2.obj

8.4.3.3 Producing an Executable, Relocatable Output Module (-ar Option)

If you invoke the linker with both the --absolute_exe and --relocatable options, the linker produces an executable, relocatable object module. The output file contains the special linker symbols, an optional header, and all resolved symbol references; however, the relocation information is retained.

This example links file1.obj and file2.obj to create an executable, relocatable output module called xr.out:

armcl --run_linker -ar file1.obj file2.obj --output_file=xr.out

8.4.4 Allocate Memory for Use by the Loader to Pass Arguments (--arg_size Option)

The --arg_size option instructs the linker to allocate memory to be used by the loader to pass arguments from the command line of the loader to the program. The syntax of the --arg_size option is:

--arg_size= size

The size is the number of bytes to be allocated in target memory for command-line arguments.

By default, the linker creates the __c_args__ symbol and sets it to -1. When you specify --arg_size=size, the following occur:

• The linker creates an uninitialized section named .args of size bytes.
• The __c_args__ symbol contains the address of the .args section.

The loader and the target boot code use the .args section and the __c_args__ symbol to determine whether and how to pass arguments from the host to the target program. See the ARM Optimizing C/C++ Compiler User's Guide for information about the loader.

8.4.5 Changing Encoding of Big-Endian Instructions

When you are creating big-endian executable files, you can determine whether instruction encoding is in little or big endian. The -be8 option produces big-endian executable modules with little-endian encoded instructions. This is the default behavior for architecture version 6 and higher.

The -be32 option produces big-endian executable modules with big-endian encoded instructions. This is the default behavior for architecture version 5 and lower.

8.4.6 Compression (--cinit_compression and --copy_compression Option)

By default, the linker does not compress data. These two options specify compression through the linker.

The --cinit_compression option specifies the compression type the linker applies to the C autoinitialization data. The default is rle.

Overlays can be managed by using linker-generated copy tables. To save ROM space the linker can compress the data copied by the copy tables. The compressed data is decompressed during copy. The --copy_compression option controls the compression of the copy data tables.

The syntax for the options are:

--cinit_compression[=compression_kind]

--copy_compression[=compression_kind]

The compression_kind can be one of the following types:

• off. Don't compress the data.
• rle. Compress data using Run Length Encoding.
• lzss. Compress data using Lempel-Ziv Storer and Symanski compression.

8.4.7 Compress DWARF Information (--compress_dwarf Option)

The --compress_dwarf option aggressively reduces the size of DWARF information by eliminating duplicate information from input object files. The --compress_dwarf option eliminates duplicate information that could not be removed through the use of ELF COMDAT groups. (See the ELF specification for information on COMDAT groups.)

The linker uses certain C/C++ compiler options to control linker-generated diagnostics. The diagnostic options must be specified before the --run_linker option.

 --diag_error=num Categorize the diagnostic identified by num as an error. To find the numeric identifier of a diagnostic message, use the --display_error_number option first in a separate link. Then use --diag_error=num to recategorize the diagnostic as an error. You can only alter the severity of discretionary diagnostics. --diag_remark=num Categorize the diagnostic identified by num as a remark. To find the numeric identifier of a diagnostic message, use the --display_error_number option first in a separate link. Then use --diag_remark=num to recategorize the diagnostic as a remark. You can only alter the severity of discretionary diagnostics. --diag_suppress=num Suppress the diagnostic identified by num. To find the numeric identifier of a diagnostic message, use the --display_error_number option first in a separate link. Then use --diag_suppress=num to suppress the diagnostic. You can only suppress discretionary diagnostics. --diag_warning=num Categorize the diagnostic identified by num as a warning. To find the numeric identifier of a diagnostic message, use the --display_error_number option first in a separate link. Then use --diag_warning=num to recategorize the diagnostic as a warning. You can only alter the severity of discretionary diagnostics. --display_error_number Display a diagnostic's numeric identifier along with its text. Use this option in determining which arguments you need to supply to the diagnostic suppression options (--diag_suppress, --diag_error, --diag_remark, and --diag_warning). This option also indicates whether a diagnostic is discretionary. A discretionary diagnostic is one whose severity can be overridden. A discretionary diagnostic includes the suffix -D; otherwise, no suffix is present. See the ARM Optimizing C/C++ Compiler User's Guide for more information on understanding diagnostic messages. --emit_warnings_as_      errors Treat all warnings as errors. This option cannot be used with the --no_warnings option. The --diag_remark option takes precedence over this option. This option takes precedence over the --diag_warning option. --issue_remarks Issue remarks (nonserious warnings), which are suppressed by default. --no_warnings Suppress warning diagnostics (errors are still issued). --set_error_limit=num Set the error limit to num, which can be any decimal value. The linker abandons linking after this number of errors. (The default is 100.) --verbose_diagnostics Provide verbose diagnostics that display the original source with line-wrap and indicate the position of the error in the source line

8.4.9 Disable Automatic Library Selection (--disable_auto_rts Option)

The --disable_auto_rts option disables the automatic selection of a run-time-support library. See the ARM Optimizing C/C++ Compiler User's Guide for details on the automatic selection process.

8.4.10 Do Not Remove Unused Sections (--unused_section_elimination Option)

In order to minimize the foot print, the ELF linker does not include a section that is not needed to resolve any references in the final executable. Use --unused_section_elimination=off to disable this optimization. The syntax for the option is:

--unused_section_elimination[=on|off]

The linker default behavior is equivalent to --unused_section_elimination=on.

8.4.11 Linker Command File Preprocessing (--disable_pp, --define and --undefine Options)

The linker preprocesses linker command files using a standard C preprocessor. Therefore, the command files can contain well-known preprocessing directives such as #define, #include, and #if / #endif.

Three linker options control the preprocessor:

 --disable_pp Disables preprocessing for command files --define=name[=val] Predefines name as a preprocessor macro --undefine=name Removes the macro name

The compiler has --define and --undefine options with the same meanings. However, the linker options are distinct; only --define and --undefine options specified after --run_linker are passed to the linker. For example:

armcl --define=FOO=1 main.c --run_linker --define=BAR=2 lnk.cmd

The linker sees only the --define for BAR; the compiler only sees the --define for FOO.

When one command file #includes another, preprocessing context is carried from parent to child in the usual way (that is, macros defined in the parent are visible in the child). However, when a command file is invoked other than through #include, either on the command line or by the typical way of being named in another command file, preprocessing context is not carried into the nested file. The exception to this is --define and --undefine options, which apply globally from the point they are encountered. For example:

 --define GLOBAL #define LOCAL #include "incfile.cmd" /* sees GLOBAL and LOCAL */ nestfile.cmd /* only sees GLOBAL */

Two cautions apply to the use of --define and --undefine in command files. First, they have global effect as mentioned above. Second, since they are not actually preprocessing directives themselves, they are subject to macro substitution, probably with unintended consequences. This effect can be defeated by quoting the symbol name. For example:

 --define MYSYM=123 --undefine MYSYM /* expands to --undefine 123 (!) */ --undefine "MYSYM" /* ahh, that's better */

The linker uses the same search paths to find #include files as it does to find libraries. That is, #include files are searched in the following places:

1. If the #include file name is in quotes (rather than <brackets>), in the directory of the current file
2. In the list of directories specified with --Iibrary options or environment variables (see Section 8.4.18)

There are two exceptions: relative pathnames (such as "../name") always search the current directory; and absolute pathnames (such as "/usr/tools/name") bypass search paths entirely.

The linker provides the built-in macro definitions listed in Table 8-10. The availability of these macros within the linker is determined by the command-line options used, not the build attributes of the files being linked. If these macros are not set as expected, confirm that your project's command line uses the correct compiler option settings.

Table 8-10 Predefined ARM Macro Names

Macro Name Description
_ _DATE_ _ Expands to the compilation date in the form mmm dd yyyy
_ _FILE_ _ Expands to the current source filename
_ _TI_COMPILER_VERSION_ _ Defined to a 7-9 digit integer, depending on if X has 1, 2, or 3 digits. The number does not contain a decimal. For example, version 3.2.1 is represented as 3002001. The leading zeros are dropped to prevent the number being interpreted as an octal.
_ _TI_EABI_ _ Defined to 1 if EABI is enabled; otherwise, it is undefined.
_ _TI_ ARM_ _ Always defined
_ _TI_ ARM_V4_ _ Defined to 1 if the v4 architecture (ARM7) is targeted (the -mv4 option is used); otherwise, it is undefined.
_ _TI_ ARM_V5_ _ Defined to 1 if the v5E architecture (ARM9E) is targeted (the -mv5e option is used); otherwise, it is undefined.
_ _TI_ ARM_V6_ _ Defined to 1 if the v6 architecture (ARM11) is targeted (the -mv6 option is used); otherwise, it is undefined.
_ _TI_ ARM_V6M0_ _ Defined to 1 if the v6M0 architecture (Cortex-M0) is targeted (the -mv6M0 option is used); otherwise, it is undefined.
_ _TI_ ARM_V7_ _ Defined to 1 if any v7 architecture (Cortex) is targeted; otherwise, it is undefined.
_ _TI_ ARM_V7A8_ _ Defined to 1 if the v7A8 architecture (Cortex-A8) is targeted (the -mv7A8 option is used); otherwise, it is undefined.
_ _TI_ ARM_V7M_ _ Defined to 1 if any Cortex-M architecture is targeted; otherwise, it is undefined.
_ _TI_ ARM_V7M3_ _ Defined to 1 if the v7M3 architecture (Cortex-M3) is targeted (the -mv7M3 option is used); otherwise, it is undefined.
_ _TI_ ARM_V7M4_ _ Defined to 1 if the v7M4 architecture (Cortex-M4) is targeted (the -mv7M4 option is used); otherwise, it is undefined.
_ _TI_ ARM_V7R4_ _ Defined to 1 if the v7R4 architecture (Cortex-R4) is targeted (the -mv7R4 option is used); otherwise, it is undefined.
_ _TIME_ _ Expands to the compilation time in the form "hh:mm:ss"

8.4.12 Error Correcting Code Testing (--ecc Options)

Error Correcting Codes (ECC) can be generated and placed in separate sections through the linker command file. ECC uses extra bits to allow errors to be detected and/or corrected by a device. The ECC support provided by the linker is compatible with the ECC support in TI Flash memory on various TI devices. TI Flash memory uses a modified Hamming(72,64) code, which uses 8 parity bits for every 64 bits. Check the documentation for your Flash memory to see if ECC is supported. (ECC for read-write memory is handled completely in hardware at run time.)

See Section 8.5.9 for details on linker command file syntax for ECC support.

To test ECC error detection and handling, you can use two command-line options that inject bit errors into the linked executable. These options let you specify an address where an error should appear and a bitmask of bits in the code/data at that address to flip. You can specify the address of the error absolutely or as an offset from a symbol.

When a data error is injected, the ECC parity bits for the data are calculated as if the error were not present. This simulates bit errors that might actually occur and test ECC's ability to correct different levels of errors.

The --ecc:data_error option injects errors into the load image at the specified location. The syntax is:

--ecc:data_error=(symbol+offset|address)[,page],bitmask

The address is the location of the minimum addressable unit where the error is to be injected. A symbol+offset can be used to specify the location of the error to be injected with a signed offset from that symbol. The page number is needed to make the location non-ambiguous if the address occurs on multiple memory pages. The bitmask is a mask of the bits to flip; its width should be the width of an addressable unit.

For example, the following command line flips the least-significant bit in the byte at the address 0x100, making it inconsistent with the ECC parity bits for that byte:

armcl test.c --ecc:data_error=0x100,0x01 -z -o test.out

The following command flips two bits in the third byte of the code for main():

armcl test.c --ecc:data_error=main+2,0x42 -z -o test.out

The --ecc:ecc_error option injects errors into the ECC parity bits that correspond to the specified location. Note that the ecc_error option can therefore only specify locations inside ECC input ranges, whereas the data_error option can also specify errors in the ECC output memory ranges. The syntax is:

--ecc:ecc_error=(symbol+offset|address)[,page],bitmask

The parameters for this option are the same as for --ecc:data_error, except that the bitmask must be exactly 8 bits. Mirrored copies of the affected ECC byte will also contain the same injected error.

An error injected into an ECC byte with --ecc:ecc_error may cause errors to be detected at run time in any of the 8 data bytes covered by that ECC byte.

For example, the following command flips every bit in the ECC byte that contains the parity information for the byte at 0x200:

armcl test.c --ecc:ecc_error=0x200,0xff -z -o test.out

The linker disallows injecting errors into memory ranges that are neither an ECC range nor the input range for an ECC range. The compiler can only inject errors into initialized sections.

8.4.13 Define an Entry Point (--entry_point Option)

The memory address at which a program begins executing is called the entry point. When a loader loads a program into target memory, the program counter (PC) must be initialized to the entry point; the PC then points to the beginning of the program.

The linker can assign one of four values to the entry point. These values are listed below in the order in which the linker tries to use them. If you use one of the first three values, it must be an external symbol in the symbol table.

• The value specified by the --entry_point option. The syntax is:
• --entry_point= global_symbol

where global_symbol defines the entry point and must be defined as an external symbol of the input files. The external symbol name of C or C++ objects may be different than the name as declared in the source language; refer to the ARM Optimizing C/C++ Compiler User's Guide.

• The value of symbol _c_int00 (if present). The _c_int00 symbol must be the entry point if you are linking code produced by the C compiler.
• The value of symbol _main (if present)
• 0 (default value)

This example links file1.obj and file2.obj. The symbol begin is the entry point; begin must be defined as external in file1 or file2.

armcl --run_linker --entry_point=begin file1.obj file2.obj

See Section 8.6.1 for information about referring to linker symbols in C/C++ code.

8.4.14 Set Default Fill Value (--fill_value Option)

The --fill_value option fills the holes formed within output sections. The syntax for the option is:

--fill_value= value

The argument value is a 32-bit constant (up to eight hexadecimal digits). If you do not use --fill_value, the linker uses 0 as the default fill value.

This example fills holes with the hexadecimal value ABCDABCD:

armcl --run_linker --fill_value=0xABCDABCD file1.obj file2.obj

The --generate_dead_funcs_list option creates a list of functions that are never referenced (dead) and writes the list to the specified file. If no filename is specified, the default filename dead_funcs.xml is used. The syntax for the option is:

Refer to the ARM Optimizing C/C++ Compiler User's Guide for details on the --generate_dead_funcs_list option and the corresponding --use_dead_funcs_list option.

8.4.16 Define Heap Size (--heap_size Option)

The C/C++ compiler uses an uninitialized section called .sysmem for the C run-time memory pool used by malloc(). You can set the size of this memory pool at link time by using the --heap_size option. The syntax for the --heap_size option is:

--heap_size= size

The size must be a constant. This example defines a 4K byte heap:

armcl --run_linker --heap_size=0x1000 /* defines a 4k heap (.sysmem section)*/

The linker creates the .sysmem section only if there is a .sysmem section in an input file.

The linker also creates a global symbol __TI_SYSMEM_SIZE and assigns it a value equal to the size of the heap. The default size is 2K bytes. See Section 8.6.1 for information about referring to linker symbols in C/C++ code.

8.4.17 Hiding Symbols

Symbol hiding prevents the symbol from being listed in the output file's symbol table. While localization is used to prevent name space clashes in a link unit, symbol hiding is used to obscure symbols which should not be visible outside a link unit. Such symbol’s names appear only as empty strings or “no name” in object file readers. The linker supports symbol hiding through the --hide and --unhide options.

The syntax for these options are:

--hide=' pattern '

--unhide=' pattern '

The pattern is a string with optional wildcards ? or *. Use ? to match a single character and use * to match zero or more characters.

The --hide option hides global symbols with a linkname matching the pattern. It hides symbols matching the pattern by changing the name to an empty string. A global symbol that is hidden is also localized.

The --unhide option reveals (un-hides) global symbols that match the pattern that are hidden by the --hide option. The --unhide option excludes symbols that match pattern from symbol hiding provided the pattern defined by --unhide is more restrictive than the pattern defined by --hide.

These options have the following properties:

• The --hide and --unhide options can be specified more than once on the command line.
• The order of --hide and --unhide has no significance.
• A symbol is matched by only one pattern defined by either --hide or --unhide.
• A symbol is matched by the most restrictive pattern. Pattern A is considered more restrictive than Pattern B, if Pattern A matches a narrower set than Pattern B.
• It is an error if a symbol matches patterns from --hide and --unhide and one does not supersede the other. Pattern A supersedes pattern B if A can match everything B can and more. If Pattern A supersedes Pattern B, then Pattern B is said to more restrictive than Pattern A.
• These options affect final and partial linking.

In map files these symbols are listed under the Hidden Symbols heading.

8.4.18 Alter the Library Search Algorithm (--library Option, --search_path Option, and TI_ARM_C_DIR Environment Variable)

Usually, when you want to specify a file as linker input, you simply enter the filename; the linker looks for the file in the current directory. For example, suppose the current directory contains the library object.lib. If this library defines symbols that are referenced in the file file1.obj, this is how you link the files:

armcl --run_linker file1.obj object.lib

If you want to use a file that is not in the current directory, use the --library linker option. The --library option's short form is -l. The syntax for this option is:

--library=[pathname] filename

The filename is the name of an archive, an object file, or linker command file. You can specify up to 128 search paths.

The --library option is not required when one or more members of an object library are specified for input to an output section. For more information about allocating archive members, see Section 8.5.5.5.

You can augment the linker's directory search algorithm by using the --search_path linker option or the TI_ARM_C_DIR environment variable. The linker searches for object libraries and command files in the following order:

1. It searches directories named with the --search_path linker option. The --search_path option must appear before the --Iibrary option on the command line or in a command file.
2. It searches directories named with TI_ARM_C_DIR.
3. If TI_ARM_C_DIR is not set, it searches directories named with the assembler's TI_ARM_A_DIR environment variable.
4. It searches the current directory.

NOTE

The TI_ARM_C_DIR environment variable takes precedence over the older TMS470_C_DIR environment variable if both are defined. If only TMS470_C_DIR is set, it will continue to be used. Likewise, the TI_ARM_A_DIR environment variable takes precedence over the older TMS470_A_DIR environment variable if both are defined. If only TMS470_A_DIR is set, it will continue to be used.

8.4.18.1 Name an Alternate Library Directory (--search_path Option)

The --search_path option names an alternate directory that contains input files. The --search_path option's short form is -I. The syntax for this option is:

--search_path= pathname

The pathname names a directory that contains input files.

When the linker is searching for input files named with the --library option, it searches through directories named with --search_path first. Each --search_path option specifies only one directory, but you can have several --search_path options per invocation. When you use the --search_path option to name an alternate directory, it must precede any --library option used on the command line or in a command file.

For example, assume that there are two archive libraries called r.lib and lib2.lib that reside in ld and ld2 directories. The table below shows the directories that r.lib and lib2.lib reside in, how to set environment variable, and how to use both libraries during a link. Select the row for your operating system:

Operating System Enter
UNIX (Bourne shell) armcl --run_linker f1.obj f2.obj --search_path=/ld --search_path=/ld2 --library=r.lib --library=lib2.lib
Windows armcl --run_linker f1.obj f2.obj --search_path=\ld --search_path=\ld2 --library=r.lib --library=lib2.lib
8.4.18.2 Name an Alternate Library Directory (TI_ARM_C_DIR Environment Variable)

An environment variable is a system symbol that you define and assign a string to. The linker uses an environment variable named TI_ARM_C_DIR to name alternate directories that contain object libraries. The command syntaxes for assigning the environment variable are:

Operating System Enter
UNIX (Bourne shell) TI_ARM_C_DIR="pathname1;pathname2; . . ."; export TI_ARM_C_DIR
Windows set TI_ARM_C_DIR= pathname1 ;pathname2 ; . . .

The pathnames are directories that contain input files. Use the --library linker option on the command line or in a command file to tell the linker which library or linker command file to search for. The pathnames must follow these constraints:

• Pathnames must be separated with a semicolon.
• Spaces or tabs at the beginning or end of a path are ignored. For example the space before and after the semicolon in the following is ignored:
•  set TI_ARM_C_DIR= c:\path\one\to\tools ; c:\path\two\to\tools
• Spaces and tabs are allowed within paths to accommodate Windows directories that contain spaces. For example, the pathnames in the following are valid:
•  set TI_ARM_C_DIR=c:\first path\to\tools;d:\second path\to\tools

In the example below, assume that two archive libraries called r.lib and lib2.lib reside in ld and ld2 directories. The table below shows how to set the environment variable, and how to use both libraries during a link. Select the row for your operating system:

Operating System Invocation Command
UNIX (Bourne shell) TI_ARM_C_DIR="/ld ;/ld2"; export TI_ARM_C_DIR; armcl --run_linker f1.obj f2.obj --library=r.lib --library=lib2.lib
Windows TI_ARM_C_DIR=\ld;\ld2armcl --run linker f1.obj f2.obj --library=r.lib --library=lib2.lib

The environment variable remains set until you reboot the system or reset the variable by entering:

Operating System Enter
UNIX (Bourne shell) unset TI_ARM_C_DIR
Windows set TI_ARM_C_DIR=

The assembler uses an environment variable named TI_ARM_A_DIR to name alternate directories that contain copy/include files or macro libraries. If TI_ARM_C_DIR is not set, the linker searches for object libraries in the directories named with TI_ARM_A_DIR. For information about TI_ARM_A_DIR, see Section 4.5.2. For more information about object libraries, see Section 8.6.3.

There are two ways to exhaustively search for unresolved symbols:

• Search libraries in the order that they are specified (--priority).

The linker normally reads input files, including archive libraries, only once when they are encountered on the command line or in the command file. When an archive is read, any members that resolve references to undefined symbols are included in the link. If an input file later references a symbol defined in a previously read archive library, the reference is not resolved.

With the --reread_libs option, you can force the linker to reread all libraries. The linker rereads libraries until no more references can be resolved. Linking using --reread_libs may be slower, so you should use it only as needed. For example, if a.lib contains a reference to a symbol defined in b.lib, and b.lib contains a reference to a symbol defined in a.lib, you can resolve the mutual dependencies by listing one of the libraries twice, as in:

armcl --run_linker --library=a.lib --library=b.lib --library=a.lib

or you can force the linker to do it for you:

The --priority option provides an alternate search mechanism for libraries. Using --priority causes each unresolved reference to be satisfied by the first library that contains a definition for that symbol. For example:

objfile references A lib1 defines B lib2 defines A, B; obj defining A references B % armcl --run_linker objfile lib1 lib2

Under the existing model, objfile resolves its reference to A in lib2, pulling in a reference to B, which resolves to the B in lib2.

Under --priority, objfile resolves its reference to A in lib2, pulling in a reference to B, but now B is resolved by searching the libraries in order and resolves B to the first definition it finds, namely the one in lib1.

The --priority option is useful for libraries that provide overriding definitions for related sets of functions in other libraries without having to provide a complete version of the whole library.

For example, suppose you want to override versions of malloc and free defined in the rtsv4_A_be_eabi.lib without providing a full replacement for rtsv4_A_be_eabi.lib. Using --priority and linking your new library before rtsv4_A_be_eabi.lib guarantees that all references to malloc and free resolve to the new library.

The --priority option is intended to support linking programs with SYS/BIOS where situations like the one illustrated above occur.

8.4.19 Change Symbol Localization

Symbol localization changes symbol linkage from global to local (static). This is used to obscure global symbols in a library which should not be visible outside the library, but must be global because they are accessed by several modules in the library. The linker supports symbol localization through the --localize and --globalize linker options.

The syntax for these options are:

--localize=' pattern '

--globalize=' pattern '

The pattern is a string with optional wildcards ? or *. Use ? to match a single character and use * to match zero or more characters.

The --localize option changes the symbol linkage to local for symbols matching the pattern.

The --globalize option changes the symbol linkage to global for symbols matching the pattern. The --globalize option only affects symbols that are localized by the --localize option. The --globalize option excludes symbols that match the pattern from symbol localization, provided the pattern defined by --globalize is more restrictive than the pattern defined by --localize.

See Section 8.4.2 for information about using C/C++ identifiers in linker options such as --localize and --globalize.

These options have the following properties:

• The --localize and --globalize options can be specified more than once on the command line.
• The order of --localize and --globalize options has no significance.
• A symbol is matched by only one pattern defined by either --localize or --globalize.
• A symbol is matched by the most restrictive pattern. Pattern A is considered more restrictive than Pattern B, if Pattern A matches a narrower set than Pattern B.
• It is an error if a symbol matches patterns from --localize and --globalize and if one does not supersede other. Pattern A supersedes pattern B if A can match everything B can, and some more. If Pattern A supersedes Pattern B, then Pattern B is said to more restrictive than Pattern A.
• These options affect final and partial linking.

In map files these symbols are listed under the Localized Symbols heading.

8.4.19.1 Make All Global Symbols Static (--make_static Option)

The --make_static option makes all global symbols static. Static symbols are not visible to externally linked modules. By making global symbols static, global symbols are essentially hidden. This allows external symbols with the same name (in different files) to be treated as unique.

The --make_static option effectively nullifies all .global assembler directives. All symbols become local to the module in which they are defined, so no external references are possible. For example, assume file1.obj and file2.obj both define global symbols called EXT. By using the --make_static option, you can link these files without conflict. The symbol EXT defined in file1.obj is treated separately from the symbol EXT defined in file2.obj.

armcl --run_linker --make_static file1.obj file2.obj

The --make_static option makes all global symbols static. If you have a symbol that you want to remain global and you use the --make_static option, you can use the --make_global option to declare that symbol to be global. The --make_global option overrides the effect of the --make_static option for the symbol that you specify. The syntax for the --make_global option is:

--make_global= global_symbol

8.4.20 Create a Map File (--map_file Option)

The syntax for the --map_file option is:

--map_file= filename

• Memory configuration
• Input and output section allocation
• Trampolines
• The addresses of external symbols after they have been relocated
• Hidden and localized symbols

The map file contains the name of the output module and the entry point; it can also contain up to three tables:

• A table showing the new memory configuration if any nondefault memory is specified (memory configuration). The table has the following columns; this information is generated on the basis of the information in the MEMORY directive in the linker command file:
• Name. This is the name of the memory range specified with the MEMORY directive.
• Origin. This specifies the starting address of a memory range.
• Length. This specifies the length of a memory range.
• Unused. This specifies the total amount of unused (available) memory in that memory area.
• Attributes. This specifies one to four attributes associated with the named range:
•  R specifies that the memory can be read. W specifies that the memory can be written to. X specifies that the memory can contain executable code. I specifies that the memory can be initialized.

• A table showing the linked addresses of each output section and the input sections that make up the output sections (section placement map). This table has the following columns; this information is generated on the basis of the information in the SECTIONS directive in the linker command file:
• Output section. This is the name of the output section specified with the SECTIONS directive.
• Origin. The first origin listed for each output section is the starting address of that output section. The indented origin value is the starting address of that portion of the output section.
• Length. The first length listed for each output section is the length of that output section. The indented length value is the length of that portion of the output section.
• Attributes/input sections. This lists the input file or value associated with an output section. If the input section could not be allocated, the map file will indicate this with "FAILED TO ALLOCATE".

• A table showing each external symbol and its address sorted by symbol name.
• A table showing each external symbol and its address sorted by symbol address.

The following example links file1.obj and file2.obj and creates a map file called map.out:

armcl --run_linker file1.obj file2.obj --map_file=map.out

shows an example of a map file.

8.4.21 Managing Map File Contents (--mapfile_contents Option)

The --mapfile_contents option assists with managing the content of linker-generated map files. The syntax for the --mapfile_contents option is:

--mapfile_contents= filter[, filter]

When the --map_file option is specified, the linker produces a map file containing information about memory usage, placement information about sections that were created during a link, details about linker-generated copy tables, and symbol values.

The --mapfile_contents option provides a mechanism for you to control what information is included in or excluded from a map file. When you specify --mapfile_contents=help from the command line, a help screen listing available filter options is displayed. The following filter options are available:

Attribute Description Default State
crctables CRC tables On
copytables Copy tables On
entry Entry point On
memory Memory ranges On
modules Module view On
sections Sections On
sym_defs Defined symbols per file Off
sym_dp Symbols sorted by data page On
sym_name Symbols sorted by name On
all Enables all attributes
none Disables all attributes

The --mapfile_contents option controls display filter settings by specifying a comma-delimited list of display attributes. When prefixed with the word no, an attribute is disabled instead of enabled. For example:

--mapfile_contents=copytables,noentry --mapfile_contents=all,nocopytables --mapfile_contents=none,entry

By default, those sections that are currently included in the map file when the --map_file option is specified are included. The filters specified in the --mapfile_contents options are processed in the order that they appear in the command line. In the third example above, the first filter, none, clears all map file content. The second filter, entry, then enables information about entry points to be included in the generated map file. That is, when --mapfile_contents=none,entry is specified, the map file contains only information about entry points.

You can use the sym_defs filter to include information sorted on a file by file basis. You may find it useful to replace the sym_name, sym_dp, and sym_runaddr sections of the map file with the sym_defs section by specifying the following --mapfile_contents option:

--mapfile_contents=nosym_name,nosym_dp,nosym_runaddr,sym_defs

By default, information about global symbols defined in an application are included in tables sorted by name, data page, and run address. If you use the --mapfile_contents=sym_defs option, static variables are also listed.

8.4.22 Disable Name Demangling (--no_demangle)

By default, the linker uses demangled symbol names in diagnostics. For example:

 undefined symbol first referenced in file ANewClass::getValue() test.obj

The --no_demangle option disables the demangling of symbol names in diagnostics. For example:

 undefined symbol first referenced in file _ZN9ANewClass8getValueEv test.obj

8.4.23 Disable Merging of Symbolic Debugging Information (--no_sym_merge Option)

By default, the linker eliminates duplicate entries of symbolic debugging information. Such duplicate information is commonly generated when a C program is compiled for debugging. For example:

-[ header.h ]- typedef struct { <define some structure members>} XYZ; -[ f1.c ]- #include "header.h"... -[ f2.c ]- #include "header.h"...

When these files are compiled for debugging, both f1.obj and f2.obj have symbolic debugging entries to describe type XYZ. For the final output file, only one set of these entries is necessary. The linker eliminates the duplicate entries automatically.

8.4.24 Strip Symbolic Information (--no_symtable Option)

The --no_symtable option creates a smaller output module by omitting symbol table information and line number entries. The --no_sym_table option is useful for production applications when you do not want to disclose symbolic information to the consumer.

This example links file1.obj and file2.obj and creates an output module, stripped of line numbers and symbol table information, named nosym.out:

armcl --run_linker --output_file=nosym.out --no_symtable file1.obj file2.obj

Using the --no_symtable option limits later use of a symbolic debugger.

NOTE

Stripping Symbolic Information

The --no_symtable option is deprecated. To remove symbol table information, use the armstrip utility as described in Section 11.4.

8.4.25 Name an Output Module (--output_file Option)

The linker creates an output module when no errors are encountered. If you do not specify a filename for the output module, the linker gives it the default name a.out. If you want to write the output module to a different file, use the --output_file option. The syntax for the --output_file option is:

--output_file= filename

The filename is the new output module name.

This example links file1.obj and file2.obj and creates an output module named run.out:

armcl --run_linker --output_file=run.out file1.obj file2.obj

8.4.26 Prioritizing Function Placement (--preferred_order Option)

The compiler prioritizes the placement of a function relative to others based on the order in which --preferred_order options are encountered during the linker invocation. The syntax is:

 --preferred_order= function specification

Refer to the ARM Optimizing C/C++ Compiler User's Guide for details on the program cache layout tool, which is impacted by --preferred_option.

8.4.27 C Language Options (--ram_model and --rom_model Options)

The --ram_model and --rom_model options cause the linker to use linking conventions that are required by the C compiler.

• The --ram_model option tells the linker to initialize variables at load time.
• The --rom_model option tells the linker to autoinitialize variables at run time.

8.4.28 Retain Discarded Sections (--retain Option)

When --unused_section_elimination is on, the ELF linker does not include a section in the final link if it is not needed in the executable to resolve references. The --retain option tells the linker to retain a list of sections that would otherwise not be retained. This option accepts the wildcards '*' and '?'. When wildcards are used, the argument should be in quotes. The syntax for this option is:

--retain=sym_or_scn_spec

The --retain option take one of the following forms:

• --retain= symbol_spec
• Specifying the symbol format retains sections that define symbol_spec. For example, this code retains sections that define symbols that start with init:

 --retain='init*'

You cannot specify --retain='*'.

• --retain= file_spec(scn_spec[, scn_spec, ...]
• Specifying the file format retains sections that match one or more scn_spec from files matching the file_spec. For example, this code retains .intvec sections from all input files:

 --retain='*(.int*)'

You can specify --retain='*(*)' to retain all sections from all input files. However, this does not prevent sections from library members from being optimized out.

• --retain= ar_spec<mem_spec, [mem_spec, ...>(scn_spec[, scn_spec, ...]
• Specifying the archive format retains sections matching one or more scn_spec from members matching one or more mem_spec from archive files matching ar_spec. For example, this code retains the .text sections from printf.obj in the rts32eabi.lib library:

 --retain=rts32eabi.lib<printf.obj>(.text)

If the library is specified with the --library option (--library=rts32eabi.lib) the library search path is used to search for the library. You cannot specify '*<*>(*)'.

8.4.29 Create an Absolute Listing File (--run_abs Option)

The --run_abs option produces an output file for each file linked. These files are named with the input filenames and an extension of .abs. Header files, however, do not generate a corresponding .abs file.

8.4.30 Scan All Libraries for Duplicate Symbol Definitions (--scan_libraries)

The --scan_libraries option scans all libraries during a link looking for duplicate symbol definitions to those symbols that are actually included in the link. The scan does not consider absolute symbols or symbols defined in COMDAT sections. The --scan_libraries option helps determine those symbols that were actually chosen by the linker over other existing definitions of the same symbol in a library.

The library scanning feature can be used to check against unintended resolution of a symbol reference to a definition when multiple definitions are available in the libraries.

8.4.31 Define Stack Size (--stack_size Option)

The ARM C/C++ compiler uses an uninitialized section, .stack, to allocate space for the run-time stack. You can set the size of this section in bytes at link time with the --stack_size option. The syntax for the --stack_size option is:

--stack_size= size

The size must be a constant and is in bytes. This example defines a 4K byte stack:

armcl --run_linker --stack_size=0x1000 /* defines a 4K heap (.stack section)*/

If you specified a different stack size in an input section, the input section stack size is ignored. Any symbols defined in the input section remain valid; only the stack size is different.

When the linker defines the .stack section, it also defines a global symbol, __TI_STACK_SIZE, and assigns it a value equal to the size of the section. The default software stack size is 2K bytes. See Section 8.6.1 for information about referring to linker symbols in C/C++ code.

8.4.32 Enforce Strict Compatibility (--strict_compatibility Option)

The linker performs more conservative and rigorous compatibility checking of input object files when you specify the --strict_compatibility option. Using this option guards against additional potential compatibility issues, but may signal false compatibility errors when linking in object files built with an older toolset, or with object files built with another compiler vendor's toolset. To avoid issues with legacy libraries, the --strict_compatibility option is turned off by default.

8.4.33 Mapping of Symbols (--symbol_map Option)

Symbol mapping allows a symbol reference to be resolved by a symbol with a different name. Symbol mapping allows functions to be overridden with alternate definitions. This feature can be used to patch in alternate implementations, which provide patches (bug fixes) or alternate functionality. The syntax for the --symbol_map option is:

--symbol_map= refname=defname

For example, the following code makes the linker resolve any references to foo by the definition foo_patch:

--symbol_map='foo=foo_patch'

The --symbol_map option is now supported even if --opt_level=4 was used when compiling.

8.4.34 Generate Far Call Trampolines (--trampolines Option)

The ARM device has PC-relative call and PC-relative branch instructions whose range is smaller than the entire address space. When these instructions are used, the destination address must be near enough to the instruction that the difference between the call and the destination fits in the available encoding bits. If the called function is too far away from the calling function, the linker generates an error.

The alternative to a PC-relative call is an absolute call, which is often implemented as an indirect call: load the called address into a register, and call that register. This is often undesirable because it takes more instructions (speed- and size-wise) and requires an extra register to contain the address.

By default, the compiler generates near calls. The --trampolines option causes the linker to generate a trampoline code section for each call that is linked out-of-range of its called destination. The trampoline code section contains a sequence of instructions that performs a transparent long branch to the original called address. Each calling instruction that is out-of-range from the called function is redirected to the trampoline.

For example, in a section of C code the bar function calls the foo function. The compiler generates this code for the function:

bar: ... call foo ; call the function "foo" ...

If the foo function is placed out-of-range from the call to foo that is inside of bar, then with --trampolines the linker changes the original call to foo into a call to foo_trampoline as shown:

bar: ... call foo_trampoline ; call a trampoline for foo ...

The above code generates a trampoline code section called foo_trampoline, which contains code that executes a long branch to the original called function, foo. For example:

foo_trampoline: branch_long foo

Trampolines can be shared among calls to the same called function. The only requirement is that all calls to the called function be linked near the called function's trampoline.

The syntax for this option is:

--trampolines[=on|off]

The default setting is on. For ARM, trampolines are turned on by default.

When the linker produces a map file (the --map_file option) and it has produced one or more trampolines, then the map file will contain statistics about what trampolines were generated to reach which functions. A list of calls for each trampoline is also provided in the map file.

NOTE

The Linker Assumes R13 Contains the Stack Pointer

Assembly language programmers must be aware that the linker assumes R13 contains the stack pointer. The linker must save and restore values on the stack in trampoline code that it generates. If you do not use R13 as the stack pointer, you should use the linker option that disables trampolines, --trampolines=off. Otherwise, trampolines could corrupt memory and overwrite register values.

The advantage of using trampolines is that you can treat all calls as near calls, which are faster and more efficient. You will only need to modify those calls that don't reach. In addition, there is little need to consider the relative placement of functions that call each other. Cases where calls must go through a trampoline are less common than near calls.

While generating far call trampolines provides a more straightforward solution, trampolines have the disadvantage that they are somewhat slower than directly calling a function. They require both a call and a branch. Additionally, while inline code could be tailored to the environment of the call, trampolines are generated in a more general manner, and may be slightly less efficient than inline code.

An alternative method to creating a trampoline code section for a call that cannot reach its called function is to actually modify the source code for the call. In some cases this can be done without affecting the size of the code. However, in general, this approach is extremely difficult, especially when the size of the code is affected by the transformation.

8.4.34.2 Minimizing the Number of Trampolines Required (--minimize_trampolines Option)

The --minimize_trampolines option attempts to place sections so as to minimize the number of far call trampolines required, possibly at the expense of optimal memory packing. The syntax is:

--minimize_trampolines=postorder

The argument selects a heuristic to use. The postorder heuristic attempts to place functions before their callers, so that the PC-relative offset to the callee is known when the caller is placed. By placing the callee first, its address is known when the caller is placed so the linker can definitively know if a trampoline is required.

8.4.34.3 Making Trampoline Reservations Adjacent (--trampoline_min_spacing Option)

When a call is placed and the callee's address is unknown, the linker must provisionally reserve space for a far call trampoline in case the callee turns out to be too far away. Even if the callee ends up being close enough, the trampoline reservation can interfere with optimal placement for very large code sections.

When trampoline reservations are spaced more closely than the specified limit, use the --trampoline_min_spacing option to try to make them adjacent. The syntax is:

--trampoline_min_spacing= size

A higher value minimizes fragmentation, but may result in more trampolines. A lower value may reduce trampolines, at the expense of fragmentation and linker running time. Specifying 0 for this option disables coalescing. The default is 16K.

8.4.34.4 Carrying Trampolines From Load Space to Run Space

It is sometimes useful to load code in one location in memory and run it in another. The linker provides the capability to specify separate load and run allocations for a section. The burden of actually copying the code from the load space to the run space is left to you.

A copy function must be executed before the real function can be executed in its run space. To facilitate this copy function, the assembler provides the .label directive, which allows you to define a load-time address. These load-time addresses can then be used to determine the start address and size of the code to be copied. However, this mechanism will not work if the code contains a call that requires a trampoline to reach its called function. This is because the trampoline code is generated at link time, after the load-time addresses associated with the .label directive have been defined. If the linker detects the definition of a .label symbol in an input section that contains a trampoline call, then a warning is generated.

To solve this problem, you can use the START(), END(), and SIZE() operators (see Section 8.5.10.7). These operators allow you to define symbols to represent the load-time start address and size inside the linker command file. These symbols can be referenced by the copy code, and their values are not resolved until link time, after the trampoline sections have been allocated.

Here is an example of how you could use the START() and SIZE() operators in association with an output section to copy the trampoline code section along with the code containing the calls that need trampolines:

SECTIONS { .foo : load = ROM, run = RAM, start(foo_start), size(foo_size) { x.obj(.text) } .text: {} > ROM .far : { --library=rts.lib(.text) } > FAR_MEM }

A function in x.obj contains an run-time-support call. The run-time-support library is placed in far memory and so the call is out-of-range. A trampoline section will be added to the .foo output section by the linker. The copy code can refer to the symbols foo_start and foo_size as parameters for the load start address and size of the entire .foo output section. This allows the copy code to copy the trampoline section along with the original x.obj code in .text from its load space to its run space.

See Section 8.6.1 for information about referring to linker symbols in C/C++ code.

8.4.35 Introduce an Unresolved Symbol (--undef_sym Option)

The --undef_sym option introduces the linkname for an unresolved symbol into the linker's symbol table. This forces the linker to search a library and include the member that defines the symbol. The linker must encounter the --undef_sym option before it links in the member that defines the symbol. The syntax for the --undef_sym option is:

--undef_sym= symbol

For example, suppose a library named rtsv4_A_be_eabi.lib contains a member that defines the symbol symtab; none of the object files being linked reference symtab. However, suppose you plan to relink the output module and you want to include the library member that defines symtab in this link. Using the --undef_sym option as shown below forces the linker to search rtsv4_A_be_eabi.lib for the member that defines symtab and to link in the member.

armcl --run_linker --undef_sym=symtab file1.obj file2.obj rtsv4_A_be_eabi.lib

If you do not use --undef_sym, this member is not included, because there is no explicit reference to it in file1.obj or file2.obj.

8.4.36 Display a Message When an Undefined Output Section Is Created (--warn_sections)

In a linker command file, you can set up a SECTIONS directive that describes how input sections are combined into output sections. However, if the linker encounters one or more input sections that do not have a corresponding output section defined in the SECTIONS directive, the linker combines the input sections that have the same name into an output section with that name. By default, the linker does not display a message to tell you that this occurred.

You can use the --warn_sections option to cause the linker to display a message when it creates a new output section.

The linker supports the generation of an XML link information file through the --xml_link_info=file option. This option causes the linker to generate a well-formed XML file containing detailed information about the result of a link. The information included in this file includes all of the information that is currently produced in a linker generated map file. See Section B-2 for specifics on the contents of the generated XML file.

8.4.38 Zero Initialization (--zero_init Option)

The C and C++ standards require that global and static variables that are not explicitly initialized must be set to 0 before program execution. The C/C++ compiler supports preinitialization of uninitialized variables by default. To turn this off, specify the linker option --zero_init=off.

The syntax for the --zero_init option is:

--zero_init[={on|off}]

NOTE

Disabling Zero Initialization Not Recommended

In general, this option it is not recommended. If you turn off zero initialization, automatic initialization of uninitialized global and static objects to zero will not occur. You are then expected to initialize these variables to zero in some other manner.

Linker command files allow you to put linker options and directives in a file; this is useful when you invoke the linker often with the same options and directives. Linker command files are also useful because they allow you to use the MEMORY and SECTIONS directives to customize your application. You must use these directives in a command file; you cannot use them on the command line.

Linker command files are ASCII files that contain one or more of the following:

• Input filenames, which specify object files, archive libraries, or other command files. (If a command file calls another command file as input, this statement must be the last statement in the calling command file. The linker does not return from called command files.)
• Linker options, which can be used in the command file in the same manner that they are used on the command line
• The MEMORY and SECTIONS linker directives. The MEMORY directive defines the target memory configuration (see Section 8.5.4). The SECTIONS directive controls how sections are built and allocated (see Section 8.5.5.)
• Assignment statements, which define and assign values to global symbols

To invoke the linker with a command file, enter the armcl --run_linker command and follow it with the name of the command file:

The linker processes input files in the order that it encounters them. If the linker recognizes a file as an object file, it links the file. Otherwise, it assumes that a file is a command file and begins reading and processing commands from it. Command filenames are case sensitive, regardless of the system used.

a.obj /* First input filename */ b.obj /* Second input filename */ --output_file=prog.out /* Option to specify output file */ --map_file=prog.map /* Option to specify map file */

The sample file in Example 8-1 contains only filenames and options. (You can place comments in a command file by delimiting them with /* and */.) To invoke the linker with this command file, enter:

 armcl --run_linker link.cmd 

You can place other parameters on the command line when you use a command file:

 armcl --run_linker --relocatable link.cmd c.obj d.obj 

The linker processes the command file as soon as it encounters the filename, so a.obj and b.obj are linked into the output module before c.obj and d.obj.

You can specify multiple command files. If, for example, you have a file called names.lst that contains filenames and another file called dir.cmd that contains linker directives, you could enter:

 armcl --run_linker names.lst dir.cmd 

One command file can call another command file; this type of nesting is limited to 16 levels. If a command file calls another command file as input, this statement must be the last statement in the calling command file.

Blanks and blank lines are insignificant in a command file except as delimiters. This also applies to the format of linker directives in a command file. Example 8-2 shows a sample command file that contains linker directives.

Example 8-2 Command File With Linker Directives

a.obj b.obj c.obj /* Input filenames */ --output_file=prog.out /* Options */ --map_file=prog.map MEMORY /* MEMORY directive */ { FAST_MEM: origin = 0x0100 length = 0x0100 SLOW_MEM: origin = 0x7000 length = 0x1000 } SECTIONS /* SECTIONS directive */ { .text: > SLOW_MEM .data: > SLOW_MEM .bss: > FAST_MEM }

For more information, see Section 8.5.4 for the MEMORY directive, and Section 8.5.5 for the SECTIONS directive.

8.5.1 Reserved Names in Linker Command Files

The following names (in both uppercase and lowercase) are reserved as keywords for linker directives. Do not use them as symbol or section names in a command file.

 ADDRESS_MASK ECC LEN o SECTIONS ALGORITHM END LENGTH ORG SIZE ALIAS f LOAD ORIGIN START ALIGN FILL LOAD_END PAGE TABLE ATTR GROUP LOAD_SIZE PALIGN TYPE BLOCK HAMMING_MASK LOAD_START PARITY_MASK UNION COMPRESSION HIGH MEMORY RUN UNORDERED COPY INPUT_PAGE MIRRORING RUN_END VFILL CRC_TABLE INPUT_RANGE NOINIT RUN_SIZE DSECT l (lowercase L) NOLOAD RUN_START

In addition, any section names used by the TI tools are reserved from being used as the prefix for other names, unless the section will be a subsection of the section name used by the TI tools. For example, section names may not begin with .debug.

8.5.2 Constants in Linker Command Files

You can specify constants with either of two syntax schemes: the scheme used for specifying decimal, octal, or hexadecimal constants (but not binary constants) used in the assembler (see Section 4.7) or the scheme used for integer constants in C syntax.

Examples:

Assembler format 32 40q 020h
C format 32 040 0x20

8.5.3 Accessing Files and Libraries from a Linker Command File

Many applications use custom linker command files (or LCFs) to control the placement of code and data in target memory. For example, you may want to place a specific data object from a specific file into a specific location in target memory. This is simple to do using the available LCF syntax to reference the desired object file or library. However, a problem that many developers run into when they try to do this is a linker generated "file not found" error when accessing an object file or library from inside the LCF that has been specified earlier in the command-line invocation of the linker. Most often, this error occurs because the syntax used to access the file on the linker command-line does not match the syntax that is used to access the same file in the LCF.

Consider a simple example. Imagine that you have an application that requires a table of constants called "app_coeffs" to be defined in a memory area called "DDR". Assume also that the "app_coeffs" data object is defined in a .data section that resides in an object file, app_coeffs.obj. app_coeffs.obj is then included in the object file library app_data.lib. In your LCF, you can control the placement of the "app_coeffs" data object as follows:

SECTIONS { ... .coeffs: { app_data.lib<app_coeffs.obj>(.data) } > DDR ... }

Now assume that the app_data.lib object library resides in a sub-directory called "lib" relative to where you are building the application. In order to gain access to app_data.lib from the build command-line, you can use a combination of the –i and –l options to set up a directory search path which the linker can use to find the app_data.lib library:

%> armcl <compile options/files> -z -i ./lib -l app_data.lib mylnk.cmd <link options/files>

The –i option adds the lib sub-directory to the directory search path and the –l option instructs the linker to look through the directories in the directory search path to find the app_data.lib library. However, if you do not update the reference to app_data.lib in mylnk.cmd, the linker will fail to find the app_data.lib library and generate a "file not found" error. The reason is that when the linker encounters the reference to app_data.lib inside the SECTIONS directive, there is no –l option preceding the reference. Therefore, the linker tries to open app_data.lib in the current working directory.

In essence, the linker has a few different ways of opening files:

• If there is a path specified, the linker will look for the file in the specified location. For an absolute path, the linker will try to open the file in the specified directory. For a relative path, the linker will follow the specified path starting from the current working directory and try to open the file at that location.
• If there is no path specified, the linker will try to open the file in the current working directory.
• If a –l option precedes the file reference, then the linker will try to find and open the referenced file in one of the directories in the directory search path. The directory search path is set up via –i options and environment variables (like C_DIR and C6X_C_DIR).

As long as a file is referenced in a consistent manner on the command line and throughout any applicable LCFs, the linker will be able to find and open your object files and libraries.

Returning to the earlier example, you can insert a –l option in front of the reference to app_data.lib in mylnk.cmd to ensure that the linker will find and open the app_data.lib library when the application is built:

SECTIONS { ... .coeffs: { -l app_data.lib<app_coeffs.obj>(.data) } > DDR ... }

Another benefit to using the –l option when referencing a file from within an LCF is that if the location of the referenced file changes, you can modify the directory search path to incorporate the new location of the file (using –i option on the command line, for example) without having to modify the LCF.

8.5.4 The MEMORY Directive

The linker determines where output sections are allocated into memory; it must have a model of target memory to accomplish this. The MEMORY directive allows you to specify a model of target memory so that you can define the types of memory your system contains and the address ranges they occupy. The linker maintains the model as it allocates output sections and uses it to determine which memory locations can be used for object code.

The memory configurations of ARM systems differ from application to application. The MEMORY directive allows you to specify a variety of configurations. After you use MEMORY to define a memory model, you can use the SECTIONS directive to allocate output sections into defined memory.

8.5.4.1 Default Memory Model

If you do not use the MEMORY directive, the linker uses a default memory model that is based on the ARM architecture. This model assumes that the full 32-bit address space (232 locations) is present in the system and available for use. For more information about the default memory model, see Section 8.7.

8.5.4.2 MEMORY Directive Syntax

The MEMORY directive identifies ranges of memory that are physically present in the target system and can be used by a program. Each range has several characteristics:

• Name
• Length
• Optional set of attributes
• Optional fill specification

When you use the MEMORY directive, be sure to identify all memory ranges that are available for the program to access at run time. Memory defined by the MEMORY directive is configured; any memory that you do not explicitly account for with MEMORY is unconfigured. The linker does not place any part of a program into unconfigured memory. You can represent nonexistent memory spaces by simply not including an address range in a MEMORY directive statement.

The MEMORY directive is specified in a command file by the word MEMORY (uppercase), followed by a list of memory range specifications enclosed in braces. The MEMORY directive in Example 8-3 defines a system that has 4K bytes of fast external memory at address 0x0000 0000, 2K bytes of slow external memory at address 0x0000 1000 and 4K bytes of slow external memory at address 0x1000 0000. It also demonstrates the use of memory range expressions as well as start/end/size address operators (see Example 8-4).

Example 8-3 The MEMORY Directive

/********************************************************/ /* Sample command file with MEMORY directive */ /********************************************************/ file1.obj file2.obj /* Input files */ --output_file=prog.out /* Options */ MEMORY { FAST_MEM (RX): origin = 0x00000000 length = 0x00001000 SLOW_MEM (RW): origin = 0x00001000 length = 0x00000800 EXT_MEM (RX): origin = 0x10000000 length = 0x00001000 
 The general syntax for the MEMORY directive is: MEMORY { name 1 [(attr)] : origin = expression, length = expression [, fill = constant] . . name n [(attr)] : origin = expression, length = expression [, fill = constant] }
 name names a memory range. A memory name can be one to 64 characters; valid characters include A-Z, a-z, , ., and _. The names have no special significance to the linker; they simply identify memory ranges. Memory range names are internal to the linker and are not retained in the output file or in the symbol table. All memory ranges must have unique names and must not overlap. attr specifies one to four attributes associated with the named range. Attributes are optional; when used, they must be enclosed in parentheses. Attributes restrict the allocation of output sections into certain memory ranges. If you do not use any attributes, you can allocate any output section into any range with no restrictions. Any memory for which no attributes are specified (including all memory in the default model) has all four attributes. Valid attributes are: R specifies that the memory can be read. W specifies that the memory can be written to. X specifies that the memory can contain executable code. I specifies that the memory can be initialized. origin specifies the starting address of a memory range; enter as origin, org, or o. The value, specified in bytes, is a 32-bit integer constant expression, which can be decimal, octal, or hexadecimal. length specifies the length of a memory range; enter as length, len, or l. The value, specified in bytes, is a 32-bit integer constant expression, which can be decimal, octal, or hexadecimal. fill specifies a fill character for the memory range; enter as fill or f. Fills are optional. The value is an integer constant and can be decimal, octal, or hexadecimal. The fill value is used to fill areas of the memory range that are not allocated to a section. (See Section 8.5.9.3 for virtual filling of memory ranges when using Error Correcting Code (ECC).) NOTE Filling Memory Ranges If you specify fill values for large memory ranges, your output file will be very large because filling a memory range (even with 0s) causes raw data to be generated for all unallocated blocks of memory in the range. The following example specifies a memory range with the R and W attributes and a fill constant of 0FFFFFFFFh: MEMORY { RFILE (RW) : o = 0x0020, l = 0x1000, f = 0xFFFF } You normally use the MEMORY directive in conjunction with the SECTIONS directive to control placement of output sections. For more information about the SECTIONS directive, see Section 8.5.5. 8.5.4.3 Expressions and Address Operators Memory range origin and length can use expressions of integer constants with the following operators:  Binary operators: * / % + - << >> == = < <= > >= & | && || Unary operators: - ~ ! Expressions are evaluated using standard C operator precedence rules. No checking is done for overflow or underflow, however, expressions are evaluated using a larger integer type. Preprocess directive #define constants can be used in place of integer constants. Global symbols cannot be used in Memory Directive expressions. Three address operators reference memory range properties from prior memory range entries:  START(MR) Returns start address for previously defined memory range MR. SIZE(MR) Returns size of previously defined memory range MR. END(MR) Returns end address for previously defined memory range MR. Example 8-4 Origin and Length as Expressions /********************************************************/ /* Sample command file with MEMORY directive */ /********************************************************/ file1.obj file2.obj /* Input files */ --output_file=prog.out /* Options */ #define ORIGIN 0x00000000 #define BUFFER 0x00000200 #define CACHE 0x0001000 MEMORY { FAST_MEM (RX): origin = ORIGIN + CACHE length = 0x00001000 + BUFFER SLOW_MEM (RW): origin = end(FAST_MEM) length = 0x00001800 - size(FAST_MEM) EXT_MEM (RX): origin = 0x10000000 length = size(FAST_MEM) - CACHE 8.5.4.4 The ALIAS Statement Certain devices, such as the MSP432 Cortex M4, have a region of RAM that can be addressed by two different memory buses--a system bus and an instruction bus. This RAM region, which is located in the DATA region of the memory map (usually at 0x20000000), is internally aliased to the CODE region (usually at 0x01000000). This aliasing takes advantage of the instruction bus to fetch code from RAM while freeing the other system buses. On such devices, your linker command file should use the ALIAS statement so that placements to CODE and DATA are made with no collisions. In order to use the above capability, the linker must be aware of the two addresses that point to the same memory. Use the following syntax within a MEMORY directive to create an ALIAS for a memory range. ALIAS regions must have the same length. MEMORY { ... ALIAS { SRAM_CODE (RWX) : origin = 0x01000000 SRAM_DATA (RW) : origin = 0x20000000 } length = 0x0001000 ... } 8.5.5 The SECTIONS Directive After you use MEMORY to specify the target system's memory model, you can use SECTIONS to allocate output sections into specific named memory ranges or into memory that has specific attributes. For example, you could allocate the .text and .data sections into the area named FAST_MEM and allocate the .bss section into the area named SLOW_MEM. The SECTIONS directive controls your sections in the following ways: • Describes how input sections are combined into output sections • Defines output sections in the executable program • Allows you to control where output sections are placed in memory in relation to each other and to the entire memory space (Note that the memory placement order is not simply the sequence in which sections occur in the SECTIONS directive.) • Permits renaming of output sections For more information, see Section 2.5, Section 2.7, and Section 2.4.6. Subsections allow you to manipulate sections with greater precision. If you do not specify a SECTIONS directive, the linker uses a default algorithm for combining and allocating the sections. Section 8.7 describes this algorithm in detail. 8.5.5.1 SECTIONS Directive Syntax The SECTIONS directive is specified in a command file by the word SECTIONS (uppercase), followed by a list of output section specifications enclosed in braces. The general syntax for the SECTIONS directive is:  SECTIONS { name : [property [, property] [, property] . . . ] name : [property [, property] [, property] . . . ] name : [property [, property] [, property] . . . ] } Each section specification, beginning with name, defines an output section. (An output section is a section in the output file.) Section names can refer to sections, subsections, or archive library members. (See Section 8.5.5.4 for information on multi-level subsections.) After the section name is a list of properties that define the section's contents and how the section is allocated. The properties can be separated by optional commas. Possible properties for a section are as follows:  Load allocation defines where in memory the section is to be loaded. See Section 3.5, Section 3.1.1, and Section 8.5.6. Syntax: load = allocation or > allocation Run allocation defines where in memory the section is to be run. Syntax: run = allocation or run > allocation Input sections defines the input sections (object files) that constitute the output section. See Section 8.5.5.3. Syntax: { input_sections } Section type defines flags for special section types. See Section 8.5.8. Syntax: type = COPY or type = DSECT or type = NOLOAD Fill value defines the value used to fill uninitialized holes. See Section 8.5.11. Syntax: fill = value shows a SECTIONS directive in a sample linker command file. Example 8-5 The SECTIONS Directive /**************************************************/ /* Sample command file with SECTIONS directive */ /**************************************************/ file1.obj file2.obj /* Input files */ --output_file=prog.out /* Options */ SECTIONS { .text: load = EXT_MEM, run = 0x00000800 .const: load = FAST_MEM .bss: load = SLOW_MEM .vectors: load = 0x00000000 { t1.obj(.intvec1) t2.obj(.intvec2) endvec = .; } .data:alpha: align = 16 .data:beta: align = 16 } shows the output sections defined by the SECTIONS directive in Example 8-5 (.vectors, .text, .const, .bss, .data:alpha, and .data:beta) and shows how these sections are allocated in memory using the MEMORY directive given in Example 8-3. 8.5.5.2 Section Allocation and Placement The linker assigns each output section two locations in target memory: the location where the section will be loaded and the location where it will be run. Usually, these are the same, and you can think of each section as having only a single address. The process of locating the output section in the target's memory and assigning its address(es) is called placement. For more information about using separate load and run placement, see Section 8.5.6. If you do not tell the linker how a section is to be allocated, it uses a default algorithm to place the section. Generally, the linker puts sections wherever they fit into configured memory. You can override this default placement for a section by defining it within a SECTIONS directive and providing instructions on how to allocate it. You control placement by specifying one or more allocation parameters. Each parameter consists of a keyword, an optional equal sign or greater-than sign, and a value optionally enclosed in parentheses. If load and run placement are separate, all parameters following the keyword LOAD apply to load placement, and those following the keyword RUN apply to run placement. The allocation parameters are:  Binding allocates a section at a specific address. .text: load = 0x1000  Named memory allocates the section into a range defined in the MEMORY directive with the specified name (like SLOW_MEM) or attributes. .text: load > SLOW_MEM Alignment uses the align or palign keyword to specify the section must start on an address boundary. .text: align = 0x100 Blocking uses the block keyword to specify the section must fit between two address aligned to the blocking factor. If a section is too large, it starts on an address boundary. .text: block(0x100) For the load (usually the only) allocation, use a greater-than sign and omit the load keyword:  .text: > SLOW_MEM .text: {...} > SLOW_MEM .text: > 0x4000 If more than one parameter is used, you can string them together as follows:  .text: > SLOW_MEM align 16 Or if you prefer, use parentheses for readability:  .text: load = (SLOW_MEM align(16)) You can also use an input section specification to identify the sections from input files that are combined to form an output section. See Section 8.5.5.3. Additional information about controlling the order in which code and data are placed in memory is provided in the FAQ topic on section placement. 8.5.5.2.1 Example: Placing Functions in RAM The --ramfunc compiler option and ramfunc function attribute allow the compiler to specify that a function is to be placed in and executed from RAM. Most newer TI linker command files support the ramfunc option and function attribute by placing such functions in the .TI.ramfunc section. If you see a linker error related to this section, you should add the .TI.ramfunc section to your SECTIONS directive as follows. In these examples, RAM and FLASH are names of MEMORY regions for RAM and Flash memory; the names may be different in your linker command file. For RAM-based devices: .TI.ramfunc : {} > RAM For Flash-based devices: .TI.ramfunc : {} load=FLASH, run=RAM, table(BINIT) See the Placing functions in RAM wiki page for details. 8.5.5.2.2 Binding You can set the starting address for an output section by following the section name with an address:  .text: 0x00001000 This example specifies that the .text section must begin at location 0x1000. The binding address must be a 32-bit constant. Output sections can be bound anywhere in configured memory (assuming there is enough space), but they cannot overlap. If there is not enough space to bind a section to a specified address, the linker issues an error message. NOTE Binding is Incompatible With Alignment and Named Memory You cannot bind a section to an address if you use alignment or named memory. If you try to do this, the linker issues an error message. 8.5.5.2.3 Named Memory You can allocate a section into a memory range that is defined by the MEMORY directive (see Section 8.5.4). This example names ranges and links sections into them: MEMORY { SLOW_MEM (RIX) : origin = 0x00000000, length = 0x00001000 FAST_MEM (RWIX) : origin = 0x03000000, length = 0x00000300 } SECTIONS { .text : > SLOW_MEM .data : > FAST_MEM ALIGN(128) .bss : > FAST_MEM } In this example, the linker places .text into the area called SLOW_MEM. The .data and .bss output sections are allocated into FAST_MEM. You can align a section within a named memory range; the .data section is aligned on a 128-byte boundary within the FAST_MEM range. Similarly, you can link a section into an area of memory that has particular attributes. To do this, specify a set of attributes (enclosed in parentheses) instead of a memory name. Using the same MEMORY directive declaration, you can specify: SECTIONS { .text: > (X) /* .text --> executable memory */ .data: > (RI) /* .data --> read or init memory */ .bss : > (RW) /* .bss --> read or write memory */ } In this example, the .text output section can be linked into either the SLOW_MEM or FAST_MEM area because both areas have the X attribute. The .data section can also go into either SLOW_MEM or FAST_MEM because both areas have the R and I attributes. The .bss output section, however, must go into the FAST_MEM area because only FAST_MEM is declared with the W attribute. You cannot control where in a named memory range a section is allocated, although the linker uses lower memory addresses first and avoids fragmentation when possible. In the preceding examples, assuming no conflicting assignments exist, the .text section starts at address 0. If a section must start on a specific address, use binding instead of named memory. 8.5.5.2.4 Controlling Placement Using The HIGH Location Specifier The linker allocates output sections from low to high addresses within a designated memory range by default. Alternatively, you can cause the linker to allocate a section from high to low addresses within a memory range by using the HIGH location specifier in the SECTION directive declaration. You might use the HIGH location specifier in order to keep RTS code separate from application code, so that small changes in the application do not cause large changes to the memory map. For example, given this MEMORY directive: MEMORY { RAM : origin = 0x0200, length = 0x0800 FLASH : origin = 0x1100, length = 0xEEE0 VECTORS : origin = 0xFFE0, length = 0x001E RESET : origin = 0xFFFE, length = 0x0002 } and an accompanying SECTIONS directive: SECTIONS { .bss : {} > RAM .sysmem : {} > RAM .stack : {} > RAM (HIGH) } The HIGH specifier used on the .stack section placement causes the linker to attempt to allocate .stack into the higher addresses within the RAM memory range. The .bss and .sysmem sections are allocated into the lower addresses within RAM. Example 8-6 illustrates a portion of a map file that shows where the given sections are allocated within RAM for a typical program. Example 8-6 Linker Placement With the HIGH Specifier .bss 0 00000200 00000270 UNINITIALIZED 00000200 0000011a rtsxxx.lib : defs.obj (.bss) 0000031a 00000088 : trgdrv.obj (.bss) 000003a2 00000078 : lowlev.obj (.bss) 0000041a 00000046 : exit.obj (.bss) 00000460 00000008 : memory.obj (.bss) 00000468 00000004 : _lock.obj (.bss) 0000046c 00000002 : fopen.obj (.bss) 0000046e 00000002 hello.obj (.bss) .sysmem 0 00000470 00000120 UNINITIALIZED 00000470 00000004 rtsxxx .lib : memory.obj (.sysmem) .stack 0 000008c0 00000140 UNINITIALIZED 000008c0 00000002 rtsxxx .lib : boot.obj (.stack) As shown in Example 8-6 , the .bss and .sysmem sections are allocated at the lower addresses of RAM (0x0200 - 0x0590) and the .stack section is allocated at address 0x08c0, even though lower addresses are available. Without using the HIGH specifier, the linker allocation would result in the code shown in Example 8-7 The HIGH specifier is ignored if it is used with specific address binding or automatic section splitting (>> operator). Example 8-7 Linker Placement Without HIGH Specifier .bss 0 00000200 00000270 UNINITIALIZED 00000200 0000011a rtsxxx.lib : defs.obj (.bss) 0000031a 00000088 : trgdrv.obj (.bss) 000003a2 00000078 : lowlev.obj (.bss) 0000041a 00000046 : exit.obj (.bss) 00000460 00000008 : memory.obj (.bss) 00000468 00000004 : _lock.obj (.bss) 0000046c 00000002 : fopen.obj (.bss) 0000046e 00000002 hello.obj (.bss) .stack 0 00000470 00000140 UNINITIALIZED 00000470 00000002 rtsxxx.lib : boot.obj (.stack) .sysmem 0 000005b0 00000120 UNINITIALIZED 000005b0 00000004 rtsxxx.lib : memory.obj (.sysmem) 8.5.5.2.5 Alignment and Blocking You can tell the linker to place an output section at an address that falls on an n-byte boundary, where n is a power of 2, by using the align keyword. For example, the following code allocates .text so that it falls on a 32-byte boundary:  .text: load = align(32) Blocking is a weaker form of alignment that allocates a section anywhere within a block of size n. The specified block size must be a power of 2. For example, the following code allocates .bss so that the entire section is contained in a single 128-byte block or begins on that boundary: bss: load = block(0x0080) You can use alignment or blocking alone or in conjunction with a memory area, but alignment and blocking cannot be used together. 8.5.5.2.6 Alignment With Padding As with align, you can tell the linker to place an output section at an address that falls on an n-byte boundary, where n is a power of 2, by using the palign keyword. In addition, palign ensures that the size of the section is a multiple of its placement alignment restrictions, padding the section size up to such a boundary, as needed. For example, the following code lines allocate .text on a 2-byte boundary within the PMEM area. The .text section size is guaranteed to be a multiple of 2 bytes. Both statements are equivalent:  .text: palign(2) {} > PMEM .text: palign = 2 {} > PMEM If the linker adds padding to an initialized output section then the padding space is also initialized. By default, padding space is filled with a value of 0 (zero). However, if a fill value is specified for the output section then any padding for the section is also filled with that fill value. For example, consider the following section specification:  .mytext: palign(8), fill = 0xffffffff {} > PMEM In this example, the length of the .mytext section is 6 bytes before the palign operator is applied. The contents of .mytext are as follows: addr content ---- ------- 0000 0x1234 0002 0x1234 0004 0x1234 After the palign operator is applied, the length of .mytext is 8 bytes, and its contents are as follows: addr content ---- ------- 0000 0x1234 0002 0x1234 0004 0x1234 0006 0xffff The size of .mytext has been bumped to a multiple of 8 bytes and the padding created by the linker has been filled with 0xff. The fill value specified in the linker command file is interpreted as a 16-bit constant. If you specify this code:  .mytext: palign(8), fill = 0xff {} > PMEM The fill value assumed by the linker is 0x00ff, and .mytext will then have the following contents: addr content ---- ------- 0000 0x1234 0002 0x1234 0004 0x1234 0006 0x00ff If the palign operator is applied to an uninitialized section, then the size of the section is bumped to the appropriate boundary, as needed, but any padding created is not initialized. The palign operator can also take a parameter of power2. This parameter tells the linker to add padding to increase the section's size to the next power of two boundary. In addition, the section is aligned on that power of 2 as well. For example, consider the following section specification:  .mytext: palign(power2) {} > PMEM Assume that the size of the .mytext section is 120 bytes and PMEM starts at address 0x10020. After applying the palign(power2) operator, the .mytext output section will have the following properties:  name addr size align ------- ---------- ----- ----- .mytext 0x00010080 0x80 128 8.5.5.3 Specifying Input Sections An input section specification identifies the sections from input files that are combined to form an output section. In general, the linker combines input sections by concatenating them in the order in which they are specified. However, if alignment or blocking is specified for an input section, all of the input sections within the output section are ordered as follows: • All aligned sections, from largest to smallest • All blocked sections, from largest to smallest • All other sections, from largest to smallest The size of an output section is the sum of the sizes of the input sections that it comprises. shows the most common type of section specification; note that no input sections are listed. Example 8-8 The Most Common Method of Specifying Section Contents SECTIONS { .text: .data: .bss: } In Example 8-8, the linker takes all the .text sections from the input files and combines them into the .text output section. The linker concatenates the .text input sections in the order that it encounters them in the input files. The linker performs similar operations with the .data and .bss sections. You can use this type of specification for any output section. You can explicitly specify the input sections that form an output section. Each input section is identified by its filename and section name. If the filename is hyphenated (or contains special characters), enclose it within quotes: SECTIONS { .text : /* Build .text output section */ { f1.obj(.text) /* Link .text section from f1.obj */ f2.obj(sec1) /* Link sec1 section from f2.obj */ "f3-new.obj" /* Link ALL sections from f3-new.obj */ f4.obj(.text,sec2) /* Link .text and sec2 from f4.obj */ f5.obj(.task??) /* Link .task00, .task01, .taskXX, etc. from f5.obj */ f6.obj(*_ctable) /* Link sections ending in "_ctable" from f6.obj */ X*.obj(.text) /* Link .text section for all files starting with */ /* "X" and ending in ".obj" */ } } It is not necessary for input sections to have the same name as each other or as the output section they become part of. If a file is listed with no sections,all of its sections are included in the output section. If any additional input sections have the same name as an output section but are not explicitly specified by the SECTIONS directive, they are automatically linked in at the end of the output section. For example, if the linker found more .text sections in the preceding example and these .text sections were not specified anywhere in the SECTIONS directive, the linker would concatenate these extra sections after f4.obj(sec2). The specifications in Example 8-8 are actually a shorthand method for the following: SECTIONS { .text: { *(.text) } .data: { *(.data) } .bss: { *(.bss) } } The specification *(.text) means the unallocated .text sections from all input files. This format is useful if: • You want the output section to contain all input sections that have a specified name, but the output section name is different from the input sections' name. • You want the linker to allocate the input sections before it processes additional input sections or commands within the braces. The following example illustrates the two purposes above: SECTIONS { .text : { abc.obj(xqt) *(.text) } .data : { *(.data) fil.obj(table) } } In this example, the .text output section contains a named section xqt from file abc.obj, which is followed by all the .text input sections. The .data section contains all the .data input sections, followed by a named section table from the file fil.obj. This method includes all the unallocated sections. For example, if one of the .text input sections was already included in another output section when the linker encountered *(.text), the linker could not include that first .text input section in the second output section. Each input section acts as a prefix and gathers longer-named sections. For example, the pattern *(.data) matches .dataspecial. This mechanism enables the use of subsections, which are described in the following section. 8.5.5.4 Using Multi-Level Subsections Subsections can be identified with the base section name and one or more subsection names separated by colons. For example, A:B and A:B:C name subsections of the base section A. In certain places in a linker command file specifying a base name, such as A, selects the section A as well as any subsections of A, such as A:B or A:C:D. A name such as A:B can specify a (sub)section of that name as well as any (multi-level) subsections beginning with that name, such as A:B:C, A:B:OTHER, etc. All subsections of A:B are also subsections of A. A and A:B are supersections of A:B:C. Among a group of supersections of a subsection, the nearest supersection is the supersection with the longest name. Thus, among {A, A:B} the nearest supersection of A:B:C:D is A:B. With multiple levels of subsections, the constraints are the following: 1. When specifying input sections within a file (or library unit) the section name selects an input section of the same name and any subsections of that name. 2. Input sections that are not explicitly allocated are allocated in an existing output section of the same name or in the nearest existing supersection of such an output section. An exception to this rule is that during a partial link (specified by the --relocatable linker option) a subsection is allocated only to an existing output section of the same name. 3. If no such output section described in 2) is defined, the input section is put in a newly created output section with the same name as the base name of the input section  Consider linking input sections with the following names: europe:north:norway europe:central:france europe:south:spain europe:north:sweden europe:central:germany europe:south:italy europe:north:finland europe:central:denmark europe:south:malta europe:north:iceland This SECTIONS specification allocates the input sections as indicated in the comments:  SECTIONS { nordic: {*(europe:north) *(europe:central:denmark)} /* the nordic countries */ central: {*(europe:central)} /* france, germany */ therest: {*(europe)} /* spain, italy, malta */ } This SECTIONS specification allocates the input sections as indicated in the comments:  SECTIONS { islands: {*(europe:south:malta) *(europe:north:iceland)} /* malta, iceland */ europe:north:finland : {} /* finland */ europe:north : {} /* norway, sweden */ europe:central : {} /* germany, denmark */ europe:central:france: {} /* france */ /* (italy, spain) go into a linker-generated output section "europe" */ } NOTE Upward Compatibility of Multi-Level Subsections Existing linker commands that use the existing single-level subsection features and which do not contain section names containing multiple colon characters continue to behave as before. However, if section names in a linker command file or in the input sections supplied to the linker contain multiple colon characters, some change in behavior could be possible. You should carefully consider the impact of the rules for multiple levels to see if it affects a particular system link. 8.5.5.5 Specifying Library or Archive Members as Input to Output Sections You can specify one or more members of an object library or archive for input to an output section. Consider this SECTIONS directive: Example 8-9 Archive Members to Output Sections SECTIONS { boot > BOOT1 { --library=rtsXX.lib<boot.obj> (.text) --library=rtsXX.lib<exit.obj strcpy.obj> (.text) } .rts > BOOT2 { --library=rtsXX.lib (.text) } .text > RAM { * (.text) } } In Example 8-9, the .text sections of boot.obj, exit.obj, and strcpy.obj are extracted from the run-time-support library and placed in the .boot output section. The remainder of the run-time-support library object that is referenced is allocated to the .rts output section. Finally, the remainder of all other .text sections are to be placed in section .text. An archive member or a list of members is specified by surrounding the member name(s) with angle brackets < and > after the library name. Any object files separated by commas or spaces from the specified archive file are legal within the angle brackets. The --library option (which normally implies a library path search be made for the named file following the option) listed before each library in Example 8-9 is optional when listing specific archive members inside < >. Using < > implies that you are referring to a library. To collect a set of the input sections from a library in one place, use the --library option within the SECTIONS directive. For example, the following collects all the .text sections from rtsv4_A_be_eabi.lib into the .rtstest section: SECTIONS { .rtstest { --library=rtsv4_A_be_eabi.lib(.text) } > RAM } NOTE SECTIONS Directive Effect on --priority Specifying a library in a SECTIONS directive causes that library to be entered in the list of libraries that the linker searches to resolve references. If you use the --priority option, the first library specified in the command file will be searched first. 8.5.5.6 Allocation Using Multiple Memory Ranges The linker allows you to specify an explicit list of memory ranges into which an output section can be allocated. Consider the following example: MEMORY { P_MEM1 : origin = 0x02000, length = 0x01000 P_MEM2 : origin = 0x04000, length = 0x01000 P_MEM3 : origin = 0x06000, length = 0x01000 P_MEM4 : origin = 0x08000, length = 0x01000 } SECTIONS { .text : { } > P_MEM1 | P_MEM2 | P_MEM4 } The | operator is used to specify the multiple memory ranges. The .text output section is allocated as a whole into the first memory range in which it fits. The memory ranges are accessed in the order specified. In this example, the linker first tries to allocate the section in P_MEM1. If that attempt fails, the linker tries to place the section into P_MEM2, and so on. If the output section is not successfully allocated in any of the named memory ranges, the linker issues an error message. With this type of SECTIONS directive specification, the linker can seamlessly handle an output section that grows beyond the available space of the memory range in which it is originally allocated. Instead of modifying the linker command file, you can let the linker move the section into one of the other areas. 8.5.5.7 Automatic Splitting of Output Sections Among Non-Contiguous Memory Ranges The linker can split output sections among multiple memory ranges for efficient allocation. Use the >> operator to indicate that an output section can be split, if necessary, into the specified memory ranges: MEMORY { P_MEM1 : origin = 0x2000, length = 0x1000 P_MEM2 : origin = 0x4000, length = 0x1000 P_MEM3 : origin = 0x6000, length = 0x1000 P_MEM4 : origin = 0x8000, length = 0x1000 } SECTIONS { .text: { *(.text) } >> P_MEM1 | P_MEM2 | P_MEM3 | P_MEM4 } In this example, the >> operator indicates that the .text output section can be split among any of the listed memory areas. If the .text section grows beyond the available memory in P_MEM1, it is split on an input section boundary, and the remainder of the output section is allocated to P_MEM2 | P_MEM3 | P_MEM4. The | operator is used to specify the list of multiple memory ranges. You can also use the >> operator to indicate that an output section can be split within a single memory range. This functionality is useful when several output sections must be allocated into the same memory range, but the restrictions of one output section cause the memory range to be partitioned. Consider the following example: MEMORY { RAM : origin = 0x1000, length = 0x8000 } SECTIONS { .special: { f1.obj(.text) } load = 0x4000 .text: { *(.text) } >> RAM } The .special output section is allocated near the middle of the RAM memory range. This leaves two unused areas in RAM: from 0x1000 to 0x4000, and from the end of f1.obj(.text) to 0x8000. The specification for the .text section allows the linker to split the .text section around the .special section and use the available space in RAM on either side of .special. The >> operator can also be used to split an output section among all memory ranges that match a specified attribute combination. For example: MEMORY { P_MEM1 (RWX) : origin = 0x1000, length = 0x2000 P_MEM2 (RWI) : origin = 0x4000, length = 0x1000 } SECTIONS { .text: { *(.text) } >> (RW) } The linker attempts to allocate all or part of the output section into any memory range whose attributes match the attributes specified in the SECTIONS directive. This SECTIONS directive has the same effect as: SECTIONS { .text: { *(.text) } >> P_MEM1 | P_MEM2} } Certain sections should not be split: • Certain sections created by the compiler, including • The .cinit section, which contains the autoinitialization table for C/C++ programs • The .pinit section, which contains the list of global constructors for C++ programs • An output section with an input section specification that includes an expression to be evaluated. The expression may define a symbol that is used in the program to manage the output section at run time. • An output section that has a START(), END(), OR SIZE() operator applied to it. These operators provide information about a section's load or run address, and size. Splitting the section may compromise the integrity of the operation. • The run allocation of a UNION. (Splitting the load allocation of a UNION is allowed.) If you use the >> operator on any of these sections, the linker issues a warning and ignores the operator. 8.5.6 Placing a Section at Different Load and Run Addresses At times, you may want to load code into one area of memory and run it in another. For example, you may have performance-critical code in slow external memory. The code must be loaded into slow external memory, but it would run faster in fast external memory. The linker provides a simple way to accomplish this. You can use the SECTIONS directive to direct the linker to allocate a section twice: once to set its load address and again to set its run address. For example:  .fir: load = SLOW_MEM, run = FAST_MEM Use the load keyword for the load address and the run keyword for the run address. See Section 3.5 for an overview on run-time relocation. The application must copy the section from its load address to its run address; this does not happen automatically when you specify a separate run address. (The TABLE operator instructs the linker to produce a copy table; see Section 8.8.4.1.) 8.5.6.1 Specifying Load and Run Addresses The load address determines where a loader places the raw data for the section. Any references to the section (such as labels in it) refer to its run address. See Section 3.1.1 for an overview of load and run addresses. If you provide only one allocation (either load or run) for a section, the section is allocated only once and loads and runs at the same address. If you provide both allocations, the section is allocated as if it were two sections of the same size. This means that both allocations occupy space in the memory map and cannot overlay each other or other sections. (The UNION directive provides a way to overlay sections; see Section 8.5.7.2.) If either the load or run address has additional parameters, such as alignment or blocking, list them after the appropriate keyword. Everything related to allocation after the keyword load affects the load address until the keyword run is seen, after which, everything affects the run address. The load and run allocations are completely independent, so any qualification of one (such as alignment) has no effect on the other. You can also specify run first, then load. Use parentheses to improve readability. The examples that follow specify load and run addresses. In this example, align applies only to load:  .data: load = SLOW_MEM, align = 32, run = FAST_MEM The following example uses parentheses, but has effects that are identical to the previous example:  .data: load = (SLOW_MEM align 32), run = FAST_MEM The following example aligns FAST_MEM to 32 bits for run allocations and aligns all load allocations to 16 bits:  .data: run = FAST_MEM, align 32, load = align 16 For more information on run-time relocation see Section 3.5. Uninitialized sections (such as .bss) are not loaded, so their only significant address is the run address. The linker allocates uninitialized sections only once: if you specify both run and load addresses, the linker warns you and ignores the load address. Otherwise, if you specify only one address, the linker treats it as a run address, regardless of whether you call it load or run. This example specifies load and run addresses for an uninitialized section:  .bss: load = 0x1000, run = FAST_MEM A warning is issued, load is ignored, and space is allocated in FAST_MEM. All of the following examples have the same effect. The .bss section is allocated in FAST_MEM.  .dbss: load = FAST_MEM .bss: run = FAST_MEM .bss: > FAST_MEM 8.5.6.2 Referring to the Load Address by Using the .label Directive Normally, any reference to a symbol refers to its run-time address. However, it may be necessary at run time to refer to a load-time address. Specifically, the code that copies a section from its load address to its run address must have access to the load address. The .label directive defines a special symbol that refers to the section's load address. Thus, whereas normal symbols are relocated with respect to the run address, .label symbols are relocated with respect to the load address. See Create a Load-Time Address Label for more information on the .label directive. and Example 8-11 show the use of the .label directive to copy a section from its load address in SLOW_MEM to its run address in FAST_MEM. Figure 8-3 illustrates the run-time execution of Example 8-10. If you use the table operator, the .label directive is not needed. See Section 8.8.4.1. Example 8-10 Moving a Function from Slow to Fast Memory at Run Time ;----------------------------------------------------------- ; define a section to be copied from SLOW_MEM to FAST_MEM ;----------------------------------------------------------- .sect ".fir" .label fir_src ; load address of section fir: ; run address of section <code here> ; code for section .label fir_end ; load address of section end ;----------------------------------------------------------- ; copy .fir section from SLOW_MEM to FAST_MEM ;----------------------------------------------------------- .text LDR r4, fir_s ; get fir load address start LDR r5, fir_e ; get fir load address stop LDR r3, fir_a ; get fir run address1: CMP r4, r5 LDRCC r0, [r4], #4 ; copy fir routine to its ; run address STRCC r0, [r3], #4 BCC 1 ;----------------------------------------------------------- ; jump to fir routine, now in FAST_MEM ;----------------------------------------------------------- B fir fir_a .word fir fir_s .word fir_start fir_e .word fir_end Example 8-11 Linker Command File for Example 8-10 /******************************************************/ /* PARTIAL LINKER COMMAND FILE FOR FIR EXAMPLE */ /******************************************************/ MEMORY { FAST_MEM : origin = 0x00001000, length = 0x00001000 SLOW_MEM : origin = 0x10000000, length = 0x00001000 } SECTIONS { .text: load = FAST_MEM .fir: load = SLOW_MEM, run FAST_MEM } See Section 8.6.1 for information about referring to linker symbols in C/C++ code. 8.5.7 Using GROUP and UNION Statements Two SECTIONS statements allow you to organize or conserve memory: GROUP and UNION. Grouping sections causes the linker to allocate them contiguously in memory. Unioning sections causes the linker to allocate them to the same run address. 8.5.7.1 Grouping Output Sections Together The SECTIONS directive's GROUP option forces several output sections to be allocated contiguously and in the order listed, unless the UNORDERED operator is used. For example, assume that a section named term_rec contains a termination record for a table in the .data section. You can force the linker to allocate .data and term_rec together: Example 8-12 Allocate Sections Together SECTIONS { .text /* Normal output section */ .bss /* Normal output section */ GROUP 0x00001000 : /* Specify a group of sections */ { .data /* First section in the group */ term_rec /* Allocated immediately after .data */ } } You can use binding, alignment, or named memory to allocate a GROUP in the same manner as a single output section. In the preceding example, the GROUP is bound to address 0x1000. This means that .data is allocated at 0x1000, and term_rec follows it in memory. NOTE You Cannot Specify Addresses for Sections Within a GROUP When you use the GROUP option, binding, alignment, or allocation into named memory can be specified for the group only. You cannot use binding, named memory, or alignment for sections within a group. 8.5.7.2 Overlaying Sections With the UNION Statement For some applications, you may want to allocate more than one section that occupies the same address during run time. For example, you may have several routines you want in fast external memory at different stages of execution. Or you may want several data objects that are not active at the same time to share a block of memory. The UNION statement within the SECTIONS directive provides a way to allocate several sections at the same run-time address. In Example 8-13, the .bss sections from file1.obj and file2.obj are allocated at the same address in FAST_MEM. In the memory map, the union occupies as much space as its largest component. The components of a union remain independent sections; they are simply allocated together as a unit. Example 8-13 The UNION Statement  SECTIONS { .text: load = SLOW_MEM UNION: run = FAST_MEM { .bss:part1: { file1.obj(.bss) } .bss:part2: { file2.obj(.bss) } } .bss:part3: run = FAST_MEM { globals.obj(.bss) } } Allocation of a section as part of a union affects only its run address. Under no circumstances can sections be overlaid for loading. If an initialized section is a union member (an initialized section, such as .text, has raw data), its load allocation must be separately specified. See Example 8-14. Example 8-14 Separate Load Addresses for UNION Sections  UNION run = FAST_MEM { .text:part1: load = SLOW_MEM, { file1.obj(.text) } .text:part2: load = SLOW_MEM, { file2.obj(.text) } } Since the .text sections contain raw data, they cannot load as a union, although they can be run as a union. Therefore, each requires its own load address. If you fail to provide a load allocation for an initialized section within a UNION, the linker issues a warning and allocates load space anywhere it can in configured memory. Uninitialized sections are not loaded and do not require load addresses. The UNION statement applies only to allocation of run addresses, so it is meaningless to specify a load address for the union itself. For purposes of allocation, the union is treated as an uninitialized section: any one allocation specified is considered a run address, and if both run and load addresses are specified, the linker issues a warning and ignores the load address. 8.5.7.3 Nesting UNIONs and GROUPs The linker allows arbitrary nesting of GROUP and UNION statements with the SECTIONS directive. By nesting GROUP and UNION statements, you can express hierarchical overlays and groupings of sections. Example 8-15 shows how two overlays can be grouped together. Example 8-15 Nesting GROUP and UNION Statements SECTIONS { GROUP 0x1000 : run = FAST_MEM { UNION: { mysect1: load = SLOW_MEM mysect2: load = SLOW_MEM } UNION: { mysect3: load = SLOW_MEM mysect4: load = SLOW_MEM } } } For this example, the linker performs the following allocations: • The four sections (mysect1, mysect2, mysect3, mysect4) are assigned unique, non-overlapping load addresses. The name you defined with the .label directive is used in the SLOW_MEM memory region. This assignment is determined by the particular load allocations given for each section. • Sections mysect1 and mysect2 are assigned the same run address in FAST_MEM. • Sections mysect3 and mysect4 are assigned the same run address in FAST_MEM. • The run addresses of mysect1/mysect2 and mysect3/mysect4 are allocated contiguously, as directed by the GROUP statement (subject to alignment and blocking restrictions). To refer to groups and unions, linker diagnostic messages use the notation: GROUP_n UNION_n where n is a sequential number (beginning at 1) that represents the lexical ordering of the group or union in the linker control file without regard to nesting. Groups and unions each have their own counter. 8.5.7.4 Checking the Consistency of Allocators The linker checks the consistency of load and run allocations specified for unions, groups, and sections. The following rules are used: • Run allocations are only allowed for top-level sections, groups, or unions (sections, groups, or unions that are not nested under any other groups or unions). The linker uses the run address of the top-level structure to compute the run addresses of the components within groups and unions. • The linker does not accept a load allocation for UNIONs. • The linker does not accept a load allocation for uninitialized sections. • In most cases, you must provide a load allocation for an initialized section. However, the linker does not accept a load allocation for an initialized section that is located within a group that already defines a load allocator. • As a shortcut, you can specify a load allocation for an entire group, to determine the load allocations for every initialized section or subgroup nested within the group. However, a load allocation is accepted for an entire group only if all of the following conditions are true: • The group is initialized (that is, it has at least one initialized member). • The group is not nested inside another group that has a load allocator. • The group does not contain a union containing initialized sections. • If the group contains a union with initialized sections, it is necessary to specify the load allocation for each initialized section nested within the group. Consider the following example: •  SECTIONS { GROUP: load = SLOW_MEM, run = SLOW_MEM { .text1: UNION: { .text2: .text3: } } } The load allocator given for the group does not uniquely specify the load allocation for the elements within the union: .text2 and .text3. In this case, the linker issues a diagnostic message to request that these load allocations be specified explicitly. 8.5.7.5 Naming UNIONs and GROUPs You can give a name to a UNION or GROUP by entering the name in parentheses after the declaration. For example:  GROUP(BSS_SYSMEM_STACK_GROUP) { .bss :{} .sysmem :{} .stack :{} } load=D_MEM, run=D_MEM The name you defined is used in diagnostics for easy identification of the problem LCF area. For example: warning: LOAD placement ignored for "BSS_SYSMEM_STACK_GROUP": object is uninitialized UNION(TEXT_CINIT_UNION) { .const :{}load=D_MEM, table(table1) .pinit :{}load=D_MEM, table(table1) }run=P_MEM warning:table(table1) operator ignored: table(table1) has already been applied to a section in the "UNION(TEXT_CINIT_UNION)" in which ".pinit" is a descendant 8.5.8 Special Section Types (DSECT, COPY, NOLOAD, and NOINIT) You can assign the following special types to output sections: DSECT, COPY, NOLOAD, and NOINIT. These types affect the way that the program is treated when it is linked and loaded. You can assign a type to a section by placing the type after the section definition. For example: SECTIONS { sec1: load = 0x00002000, type = DSECT {f1.obj} sec2: load = 0x00004000, type = COPY {f2.obj} sec3: load = 0x00006000, type = NOLOAD {f3.obj} sec4: load = 0x00008000, type = NOINIT {f4.obj} } • The DSECT type creates a dummy section with the following characteristics: • It is not included in the output section memory allocation. It takes up no memory and is not included in the memory map listing. • It can overlay other output sections, other DSECTs, and unconfigured memory. • Global symbols defined in a dummy section are relocated normally. They appear in the output module's symbol table with the same value they would have if the DSECT had actually been loaded. These symbols can be referenced by other input sections. • Undefined external symbols found in a DSECT cause specified archive libraries to be searched. • The section's contents, relocation information, and line number information are not placed in the output module. • In the preceding example, none of the sections from f1.obj are allocated, but all the symbols are relocated as though the sections were linked at address 0x2000. The other sections can refer to any of the global symbols in sec1. • A COPY section is similar to a DSECT section, except that its contents and associated information are written to the output module. The .cinit section that contains initialization tables for the ARM C/C++ compiler has this attribute under the run-time initialization model. • A NOLOAD section differs from a normal output section in one respect: the section's contents, relocation information, and line number information are not placed in the output module. The linker allocates space for the section, and it appears in the memory map listing. • A NOINIT section is not C auto-initialized by the linker. It is your responsibility to initialize this section as needed. 8.5.9 Configuring Error Correcting Code (ECC) with the Linker Error Correcting Codes (ECC) can be generated and placed in separate sections through the linker command file. ECC uses extra bits to allow errors to be detected and/or corrected by a device. The ECC support provided by the linker is compatible with the ECC support in TI Flash memory on various TI devices. TI Flash memory uses a modified Hamming(72,64) code, which uses 8 parity bits for every 64 bits. Check the documentation for your Flash memory to see if ECC is supported. (ECC for read-write memory is handled completely in hardware at run time.) See Section 8.4.12 for command-line options that introduce bit errors into code that has a corresponding ECC section or into the ECC parity bits themselves. You can use these options to test your ECC error handling code. ECC can be generated during linking. The ECC data is included in the resulting object file, alongside code and data, as a data section located at the appropriate address. No extra ECC generation step is required after compilation, and the ECC can be uploaded to the device along with everything else. You can control the generation of ECC data using the ECC specifier in the memory map (Section 8.5.9.1) and the ECC directive (Section 8.5.9.2). 8.5.9.1 Using the ECC Specifier in the Memory Map To generate ECC, add a separate memory range to your memory map to hold ECC data and to indicate which memory range contains the Flash data that corresponds to this ECC data. If you have multiple memory ranges for Flash data, you should add a separate ECC memory range for each Flash data range. The definition of an ECC memory range can also provide parameters for how to generate the ECC data. The memory map for a device supporting Flash ECC may look something like this: MEMORY { VECTORS : origin=0x00000000 length=0x000020 FLASH0 : origin=0x00000020 length=0x17FFE0 FLASH1 : origin=0x00180000 length=0x180000 STACKS : origin=0x08000000 length=0x000500 RAM : origin=0x08000500 length=0x03FB00 ECC_VEC : origin=0xf0400000 length=0x000004 ECC={ input_range=VECTORS } ECC_FLA0 : origin=0xf0400004 length=0x02FFFC ECC={ input_range=FLASH0 } ECC_FLA1 : origin=0xf0430000 length=0x030000 ECC={ input_range=FLASH1 } } The "ECC" specifier attached to the ECC memory ranges indicates the data memory range that the ECC range covers. The ECC specifier supports the following parameters:  input_range = The data memory range covered by this ECC data range. Required. input_page = The page number of the input range. Required only if the input range's name is ambiguous. algorithm = The name of an ECC algorithm defined later in the command file using the ECC directive. Optional if only one algorithm is defined. (See Section 8.5.9.2.) fill = true | false Whether to generate ECC data for holes in the initialized data of the input range. The default is "true". Using fill=false produces behavior similar to the nowECC tool. The input range can be filled normally or using a virtual fill (see Section 8.5.9.3). 8.5.9.2 Using the ECC Directive In addition to specifying ECC memory ranges in the memory map, the linker command file must specify parameters for the algorithm that generates ECC data. You might need multiple ECC algorithm specifications if you have multiple Flash devices. Each TI device supporting Flash ECC has exactly one set of valid values for these parameters. The linker command files provided with Code Composer Studio include the ECC parameters necessary for ECC support on the Flash memory accessible by the device. Documentation is provided here for completeness. You specify algorithm parameters with the top-level ECC directive in the linker command file. For example: ECC { algo_name : address_mask = 0x003ffff8 hamming_mask = FMC parity_mask = 0xfc mirroring = F021 } This ECC directive accepts the following attributes:  address_mask = <32-bit mask> This mask determines which bits of the address of each 64-bit piece of memory are used in the calculation of the ECC byte for that memory. Default is 0. hamming_mask = FMC | R4 This setting determines for which data bits the ECC bits encode parity. Default is FMC. parity_mask = <8-bit mask> This mask determines which ECC bits encode even parity and which bits encode odd parity. Default is 0, meaning that all bits encode even parity. mirroring = F021 | F035 This setting determines the order of the ECC bytes and their duplication pattern for redundancy. Default is F021. 8.5.9.3 Using the VFILL Specifier in the Memory Map Normally, specifying a fill value for a MEMORY range creates initialized data sections to cover any previously uninitialized areas of memory. To generate ECC data for an entire memory range, the linker either needs to have initialized data in the entire range, or needs to know what value uninitialized memory areas will have at run time. In cases where you want to generate ECC for an entire memory range, but do not want to initialize the entire range by specifying a fill value, you can use the "vfill" specifier instead of a "fill" specifier to virtually fill the range: MEMORY { FLASH : origin=0x0000 length=0x4000 vfill=0xffffffff } The vfill specifier is functionally equivalent to omitting a fill specifier, except that it allows ECC data to be generated for areas of the input memory range that remain uninitialized. This has the benefit of reducing the size of the resulting object file. The vfill specifier has no effect other than in ECC data generation. It cannot be specified along with a fill specifier, since that would introduce ambiguity. 8.5.10 Assigning Symbols at Link Time Linker assignment statements allow you to define external (global) symbols and assign values to them at link time. You can use this feature to initialize a variable or pointer to an allocation-dependent value. See Section 8.6.1 for information about referring to linker symbols in C/C++ code. 8.5.10.1 Syntax of Assignment Statements The syntax of assignment statements in the linker is similar to that of assignment statements in the C language:  symbol = expression; assigns the value of expression to symbol symbol + = expression; adds the value of expression to symbol symbol - = expression; subtracts the value of expression from symbol symbol * = expression; multiplies symbol by expression symbol / = expression; divides symbol by expression The symbol should be defined externally. If it is not, the linker defines a new symbol and enters it into the symbol table. The expression must follow the rules defined in Section 8.5.10.3. Assignment statements must terminate with a semicolon. The linker processes assignment statements after it allocates all the output sections. Therefore, if an expression contains a symbol, the address used for that symbol reflects the symbol's address in the executable output file. For example, suppose a program reads data from one of two tables identified by two external symbols, Table1 and Table2. The program uses the symbol cur_tab as the address of the current table. The cur_tab symbol must point to either Table1 or Table2. You could accomplish this in the assembly code, but you would need to reassemble the program to change tables. Instead, you can use a linker assignment statement to assign cur_tab at link time: prog.obj /* Input file */ cur_tab = Table1; /* Assign cur_tab to one of the tables */ 8.5.10.2 Assigning the SPC to a Symbol A special symbol, denoted by a dot (.), represents the current value of the section program counter (SPC) during allocation. The SPC keeps track of the current location within a section. The linker's . symbol is analogous to the assembler's symbol. The . symbol can be used only in assignment statements within a SECTIONS directive because . is meaningful only during allocation and SECTIONS controls the allocation process. (See Section 8.5.5.)

The . symbol refers to the current run address, not the current load address, of the section.

For example, suppose a program needs to know the address of the beginning of the .data section. By using the .global directive (see Identify Global Symbols), you can create an external undefined variable called Dstart in the program. Then, assign the value of . to Dstart:

SECTIONS { .text: {} .data: {Dstart = .;} .bss : {} }

This defines Dstart to be the first linked address of the .data section. (Dstart is assigned before .data is allocated.) The linker relocates all references to Dstart.

A special type of assignment assigns a value to the . symbol. This adjusts the SPC within an output section and creates a hole between two input sections. Any value assigned to . to create a hole is relative to the beginning of the section, not to the address actually represented by the . symbol. Holes and assignments to . are described in Section 8.5.11.

8.5.10.3 Assignment Expressions

These rules apply to linker expressions:

• Expressions can contain global symbols, constants, and the C language operators listed in Table 8-11.
• All numbers are treated as long (32-bit) integers.
• Constants are identified by the linker in the same way as by the assembler. That is, numbers are recognized as decimal unless they have a suffix (H or h for hexadecimal and Q or q for octal). C language prefixes are also recognized (0 for octal and 0x for hex). Hexadecimal constants must begin with a digit. No binary constants are allowed.
• Symbols within an expression have only the value of the symbol's address. No type-checking is performed.
• Linker expressions can be absolute or relocatable. If an expression contains any relocatable symbols (and 0 or more constants or absolute symbols), it is relocatable. Otherwise, the expression is absolute. If a symbol is assigned the value of a relocatable expression, it is relocatable; if it is assigned the value of an absolute expression, it is absolute.

The linker supports the C language operators listed in in order of precedence. Operators in the same group have the same precedence. Besides the operators listed in Table 8-11, the linker also has an align operator that allows a symbol to be aligned on an n-byte boundary within an output section (n is a power of 2). For example, the following expression aligns the SPC within the current section on the next 16-byte boundary. Because the align operator is a function of the current SPC, it can be used only in the same context as . —that is, within a SECTIONS directive.

 . = align(16);

Table 8-11 Groups of Operators Used in Expressions (Precedence)

Group 1 (Highest Precedence) Group 6
!
~
-
Logical NOT
Bitwise NOT
Negation
& Bitwise AND
Group 2 Group 7
*
/
%
Multiplication
Division
Modulus
| Bitwise OR
Group 3 Group 8
+
-
Subtraction
&& Logical AND
Group 4 Group 9
>>
<<
Arithmetic right shift
Arithmetic left shift
|| Logical OR
Group 5 Group 10 (Lowest Precedence)
==
! =
>
<
< =
> =
Equal to
Not equal to
Greater than
Less than
Less than or equal to
Greater than or equal to
=
+ =
- =
* =
/ =
Assignment
A + = B
A - = B
A * = B
A / = B

is equivalent to
is equivalent to
is equivalent to
is equivalent to

A = A + B
A = A - B
A = A * B
A = A / B
8.5.10.4 Symbols Defined by the Linker

The linker automatically defines several symbols based on which sections are used in your assembly source. A program can use these symbols at run time to determine where a section is linked. Since these symbols are external, they appear in the linker map. Each symbol can be accessed in any assembly language module if it is declared with a .global directive (see Identify Global Symbols). You must have used the corresponding section in a source module for the symbol to be created. Values are assigned to these symbols as follows:

 .text is assigned the first address of the .text output section. (It marks the beginning of executable code.) etext is assigned the first address following the .text output section. (It marks the end of executable code.) .data is assigned the first address of the .data output section. (It marks the beginning of initialized data tables.) edata is assigned the first address following the .data output section. (It marks the end of initialized data tables.) .bss is assigned the first address of the .bss output section. (It marks the beginning of uninitialized data.) end is assigned the first address following the .bss output section. (It marks the end of uninitialized data.)

The following symbols are defined only for C/C++ support when the --ram_model or --rom_model option is used.

 __TI_STACK_END is assigned the end of the .stack size. __TI_STACK_SIZE is assigned the size of the .stack section for. __TI_SYSMEM_SIZE is assigned the size of the .sysmem section.

See Section 8.6.1 for information about referring to linker symbols in C/C++ code.

8.5.10.5 Assigning Exact Start, End, and Size Values of a Section to a Symbol

The code generation tools currently support the ability to load program code in one area of (slow) memory and run it in another (faster) area. This is done by specifying separate load and run addresses for an output section or group in the linker command file. Then execute a sequence of instructions (the copying code in Example 8-10) that moves the program code from its load area to its run area before it is needed.

There are several responsibilities that a programmer must take on when setting up a system with this feature. One of these responsibilities is to determine the size and run-time address of the program code to be moved. The current mechanisms to do this involve use of the .label directives in the copying code. A simple example is illustrated in Example 8-10.

This method of specifying the size and load address of the program code has limitations. While it works fine for an individual input section that is contained entirely within one source file, this method becomes more complicated if the program code is spread over several source files or if the programmer wants to copy an entire output section from load space to run space.

Another problem with this method is that it does not account for the possibility that the section being moved may have an associated far call trampoline section that needs to be moved with it.

8.5.10.6 Why the Dot Operator Does Not Always Work

The dot operator (.) is used to define symbols at link-time with a particular address inside of an output section. It is interpreted like a PC. Whatever the current offset within the current section is, that is the value associated with the dot. Consider an output section specification within a SECTIONS directive:

outsect: { s1.obj(.text) end_of_s1 = .; start_of_s2 = .; s2.obj(.text) end_of_s2 = .; }

This statement creates three symbols:

• end_of_s1—the end address of .text in s1.obj
• start_of_s2—the start address of .text in s2.obj
• end_of_s2—the end address of .text in s2.obj

Suppose there is padding between s1.obj and s2.obj created as a result of alignment. Then start_of_s2 is not really the start address of the .text section in s2.obj, but it is the address before the padding needed to align the .text section in s2.obj. This is due to the linker's interpretation of the dot operator as the current PC. It is also true because the dot operator is evaluated independently of the input sections around it.

Another potential problem in the above example is that end_of_s2 may not account for any padding that was required at the end of the output section. You cannot reliably use end_of_s2 as the end address of the output section. One way to get around this problem is to create a dummy section immediately after the output section in question. For example:

GROUP { outsect: { start_of_outsect = .; ... } dummy: { size_of_outsect = . - start_of_outsect; } }

Six operators allow you to define symbols for load-time and run-time addresses and sizes:

 LOAD_START(sym)START(sym) Defines sym with the load-time start address of related allocation unit LOAD_END(sym)END(sym) Defines sym with the load-time end address of related allocation unit LOAD_SIZE(sym)SIZE(sym) Defines sym with the load-time size of related allocation unit RUN_START(sym) Defines sym with the run-time start address of related allocation unit RUN_END(sym) Defines sym with the run-time end address of related allocation unit RUN_SIZE(sym) Defines sym with the run-time size of related allocation unit

NOTE

Linker Command File Operator Equivalencies --

These address and dimension operators can be associated with several different kinds of allocation units, including input items, output sections, GROUPs, and UNIONs. The following sections provide some examples of how the operators can be used in each case.

These symbols defined by the linker can be accessed at runtime using the _symval operator, which is essentially a cast operation. For example, suppose your linker command file contains the following:

.text: RUN_START(text_run_start), RUN_SIZE(text_run_size) { *(.text) } 

Your C program can access these symbols as follows:

extern char text_run_start, text_run_size; printf(".text load start is %lx\n", _symval(&text_run_start)); printf(".text load size is %lx\n", _symval(&text_run_size));

8.5.10.7.1 Input Items

Consider an output section specification within a SECTIONS directive:

outsect: { s1.obj(.text) end_of_s1 = .; start_of_s2 = .; s2.obj(.text) end_of_s2 = .; }

This can be rewritten using the START and END operators as follows:

outsect: { s1.obj(.text) { END(end_of_s1) } s2.obj(.text) { START(start_of_s2), END(end_of_s2) } }

The values of end_of_s1 and end_of_s2 will be the same as if you had used the dot operator in the original example, but start_of_s2 would be defined after any necessary padding that needs to be added between the two .text sections. Remember that the dot operator would cause start_of_s2 to be defined before any necessary padding is inserted between the two input sections.

The syntax for using these operators in association with input sections calls for braces { } to enclose the operator list. The operators in the list are applied to the input item that occurs immediately before the list.

8.5.10.7.2 Output Section

The START, END, and SIZE operators can also be associated with an output section. Here is an example:

outsect: START(start_of_outsect), SIZE(size_of_outsect) { <list of input items>}

In this case, the SIZE operator defines size_of_outsect to incorporate any padding that is required in the output section to conform to any alignment requirements that are imposed.

The syntax for specifying the operators with an output section does not require braces to enclose the operator list. The operator list is simply included as part of the allocation specification for an output section.

8.5.10.7.3 GROUPs

Here is another use of the START and SIZE operators in the context of a GROUP specification:

GROUP { outsect1: { ... } outsect2: { ... } } load = ROM, run = RAM, START(group_start), SIZE(group_size);

This can be useful if the whole GROUP is to be loaded in one location and run in another. The copying code can use group_start and group_size as parameters for where to copy from and how much is to be copied. This makes the use of .label in the source code unnecessary.

8.5.10.7.4 UNIONs

The RUN_SIZE and LOAD_SIZE operators provide a mechanism to distinguish between the size of a UNION's load space and the size of the space where its constituents are going to be copied before they are run. Here is an example:

UNION: run = RAM, LOAD_START(union_load_addr), LOAD_SIZE(union_ld_sz), RUN_SIZE(union_run_sz) { .text1: load = ROM, SIZE(text1_size) { f1.obj(.text) } .text2: load = ROM, SIZE(text2_size) { f2.obj(.text) } }

Here union_ld_sz is going to be equal to the sum of the sizes of all output sections placed in the union. The union_run_sz value is equivalent to the largest output section in the union. Both of these symbols incorporate any padding due to blocking or alignment requirements.

8.5.11 Creating and Filling Holes

The linker provides you with the ability to create areas within output sections that have nothing linked into them. These areas are called holes. In special cases, uninitialized sections can also be treated as holes. This section describes how the linker handles holes and how you can fill holes (and uninitialized sections) with values.

8.5.11.1 Initialized and Uninitialized Sections

There are two rules to remember about the contents of output sections. An output section contains either:

• Raw data for the entire section
• No raw data

A section that has raw data is referred to as initialized. This means that the object file contains the actual memory image contents of the section. When the section is loaded, this image is loaded into memory at the section's specified starting address. The .text and .data sections always have raw data if anything was assembled into them. Named sections defined with the .sect assembler directive also have raw data.

By default, the .bss section and sections defined with the .usect directive (see Reserve Uninitialized Space) have no raw data (they are uninitialized). They occupy space in the memory map but have no actual contents. Uninitialized sections typically reserve space in fast external memory for variables. In the object file, an uninitialized section has a normal section header and can have symbols defined in it; no memory image, however, is stored in the section.

8.5.11.2 Creating Holes

You can create a hole in an initialized output section. A hole is created when you force the linker to leave extra space between input sections within an output section. When such a hole is created, the linker must supply raw data for the hole.

Holes can be created only within output sections. Space can exist between output sections, but such space is not a hole. To fill the space between output sections, see Section 8.5.4.2.

To create a hole in an output section, you must use a special type of linker assignment statement within an output section definition. The assignment statement modifies the SPC (denoted by .) by adding to it, assigning a greater value to it, or aligning it on an address boundary. The operators, expressions, and syntaxes of assignment statements are described in Section 8.5.10.

The following example uses assignment statements to create holes in output sections:

SECTIONS { outsect: { file1.obj(.text) . += 0x0100 /* Create a hole with size 0x0100 */ file2.obj(.text) . = align(16); /* Create a hole to align the SPC */ file3.obj(.text) } }

The output section outsect is built as follows:

1. The .text section from file1.obj is linked in.
2. The linker creates a 256-byte hole.
3. The .text section from file2.obj is linked in after the hole.
4. The linker creates another hole by aligning the SPC on a 16-byte boundary.
5. Finally, the .text section from file3.obj is linked in.

All values assigned to the . symbol within a section refer to the relative address within the section. The linker handles assignments to the . symbol as if the section started at address 0 (even if you have specified a binding address). Consider the statement . = align(16) in the example. This statement effectively aligns the file3.obj .text section to start on a 16-byte boundary within outsect. If outsect is ultimately allocated to start on an address that is not aligned, the file3.obj .text section will not be aligned either.

The . symbol refers to the current run address, not the current load address, of the section.

Expressions that decrement the . symbol are illegal. For example, it is invalid to use the -= operator in an assignment to the . symbol. The most common operators used in assignments to the . symbol are += and align.

If an output section contains all input sections of a certain type (such as .text), you can use the following statements to create a hole at the beginning or end of the output section.

 .text: { .+= 0x0100; } /* Hole at the beginning */ .data: { *(.data) . += 0x0100; } /* Hole at the end */

Another way to create a hole in an output section is to combine an uninitialized section with an initialized section to form a single output section. In this case, the linker treats the uninitialized section as a hole and supplies data for it. The following example illustrates this method:

SECTIONS { outsect: { file1.obj(.text) file1.obj(.bss) /* This becomes a hole */ } }

Because the .text section has raw data, all of outsect must also contain raw data. Therefore, the uninitialized .bss section becomes a hole.

Uninitialized sections become holes only when they are combined with initialized sections. If several uninitialized sections are linked together, the resulting output section is also uninitialized.

8.5.11.3 Filling Holes

When a hole exists in an initialized output section, the linker must supply raw data to fill it. The linker fills holes with a 32-bit fill value that is replicated through memory until it fills the hole. The linker determines the fill value as follows:

1. If the hole is formed by combining an uninitialized section with an initialized section, you can specify a fill value for the uninitialized section. Follow the section name with an = sign and a 32-bit constant. For example:
2.  SECTIONS { outsect: { file1.obj(.text) file2.obj(.bss)= 0xFF00FF00 /* Fill this hole with 0xFF00FF00 */ } }
3. You can also specify a fill value for all the holes in an output section by supplying the fill value after the section definition:
4.  SECTIONS { outsect:fill = 0xFF00FF00 /* Fills holes with 0xFF00FF00 */ { . += 0x0010; /* This creates a hole */ file1.obj(.text) file1.obj(.bss) /* This creates another hole */ } }
5. If you do not specify an initialization value for a hole, the linker fills the hole with the value specified with the --fill_value option (see Section 8.4.14). For example, suppose the command file link.cmd contains the following SECTIONS directive:
6.  SECTIONS { .text: { .= 0x0100; } /* Create a 100 word hole */ } 

Now invoke the linker with the --fill_value option:

 armcl --run_linker --fill_value=0xFFFFFFFF link.cmd 

This fills the hole with 0xFFFFFFFF.

7. If you do not invoke the linker with the --fill_value option or otherwise specify a fill value, the linker fills holes with 0s.

Whenever a hole is created and filled in an initialized output section, the hole is identified in the link map along with the value the linker uses to fill it.

8.5.11.4 Explicit Initialization of Uninitialized Sections

You can force the linker to initialize an uninitialized section by specifying an explicit fill value for it in the SECTIONS directive. This causes the entire section to have raw data (the fill value). For example:

SECTIONS { .bss: fill = 0x12341234 /* Fills .bss with 0x12341234 */ }

NOTE

Filling Sections

Because filling a section (even with 0s) causes raw data to be generated for the entire section in the output file, your output file will be very large if you specify fill values for large sections or holes.

8.6.1 Using Linker Symbols in C/C++ Applications

Linker symbols have a name and a value. The value is a 32-bit unsigned integer, even if it represents a pointer value on a target that has pointers smaller than 32 bits.

The most common kind of symbol is generated by the compiler for each function and variable. The value represents the target address where that function or variable is located. When you refer to the symbol by name in the linker command file or in an assembly file, you get that 32-bit integer value.

However, in C and C++ names mean something different. If you have a variable named x that contains the value Y, and you use the name "x" in your C program, you are actually referring to the contents of variable x. If "x" is used on the right-hand side of an expression, the compiler fetches the value Y. To realize this variable, the compiler generates a linker symbol named x with the value &x. Even though the C/C++ variable and the linker symbol have the same name, they don't represent the same thing. In C, x is a variable name with the address &x and content Y. For linker symbols, x is an address, and that address contains the value Y.

Because of this difference, there are some tricks to referring to linker symbols in C code. The basic technique is to cause the compiler to creating a "fake" C variable or function and take its address. The details differ depending on the type of linker symbol.

Linker symbols that represent a function address: In C code, declare the function as an extern function. Then, refer to the value of the linker symbol using the same name. This works because function pointers "decay" to their address value when used without adornment. For example:

extern void _c_int00(void); printf("_c_int00 %lx\n", (unsigned long)&_c_int00);

func_sym=printf+100;

Your C application can refer to this symbol as follows:

 extern void func_sym(void); printf("func_sym %lx\n", _symval(&func_sym)); /* these two are equivalent */ printf("func_sym %lx\n", (unsigned long)&func_sym);

Linker symbols that represent a data address: In C code, declare the variable as an extern variable. Then, refer to the value of the linker symbol using the & operator. Because the variable is at a valid data address, we know that a data pointer can represent the value.

data_sym=.data+100; xyz=12345

Your C application can refer to these symbols as follows:

extern char data_sym; extern int xyz; printf("data_sym %lx\n", _symval(&data_sym)); /* these two are equivalent */ printf("data_sym %p\n", &data_sym); myvar = &xyz;

Linker symbols for an arbitrary address: In C code, declare this as an extern symbol. The type does not matter. If you are using GCC extensions, declare it as "extern void". If you are not using GCC extensions, declare it as "extern char". Then, refer to the value of the linker symbol mySymbol as _symval(&mySymbol). You must use the _symval operator, which is equivalent to a cast, because the 32-bit value of the linker symbol could be wider than a data pointer. The compiler treats _symval(&mySymbol) in a special way that can represent all 32 bits, even when pointers are 16 bits. Targets that have 32-bit pointers can usually use &mySymbol instead of the _symval operator. However, the portable way to access such linker symbols across TI targets is to use _symval(&mySymbol).

abs_sym=0x12345678;

Your C application can refer to this symbol as follows:

 extern char abs_sym; printf("abs_sym %lx\n", _symval(&abs_sym));

8.6.2 Declaring Weak Symbols

In a linker command file, an assignment expression outside a MEMORY or SECTIONS directive can be used to define a linker-defined symbol. To define a weak symbol in a linker command file, use the "weak" operator in an assignment expression to designate that the symbol as eligible for removal from the output file's symbol table if it is not referenced. For example, you can define "ext_addr_sym" as follows:

weak(ext_addr_sym) = 0x12345678;

When the linker command file is used to perform the final link, then "ext_addr_sym" is presented to the linker as a weak absolute symbol; it will not be included in the resulting output file if the symbol is not referenced.

See Section 2.6.2 for details about how weak symbols are handled by the linker.

8.6.3 Resolving Symbols with Object Libraries

An object library is a partitioned archive file that contains object files as members. Usually, a group of related modules are grouped together into a library. When you specify an object library as linker input, the linker includes any members of the library that define existing unresolved symbol references. You can use the archiver to build and maintain libraries. Section 7.1 contains more information about the archiver.

Using object libraries can reduce link time and the size of the executable module. Normally, if an object file that contains a function is specified at link time, the file is linked whether the function is used or not; however, if that same function is placed in an archive library, the file is included only if the function is referenced.

The order in which libraries are specified is important, because the linker includes only those members that resolve symbols that are undefined at the time the library is searched. The same library can be specified as often as necessary; it is searched each time it is included. Alternatively, you can use the --reread_libs option to reread libraries until no more references can be resolved (see Section 8.4.18.3). A library has a table that lists all external symbols defined in the library; the linker searches through the table until it determines that it cannot use the library to resolve any more references.

The following examples link several files and libraries, using these assumptions:

• Input files f1.obj and f2.obj both reference an external function named clrscr.
• Input file f1.obj references the symbol origin.
• Input file f2.obj references the symbol fillclr.
• Member 0 of library libc.lib contains a definition of origin.
• Member 3 of library liba.lib contains a definition of fillclr.
• Member 1 of both libraries defines clrscr.

If you enter:

 armcl --run_linker f1.obj f2.obj liba.lib libc.lib 

then:

• Member 1 of liba.lib satisfies the f1.obj and f2.obj references to clrscr because the library is searched and the definition of clrscr is found.
• Member 0 of libc.lib satisfies the reference to origin.
• Member 3 of liba.lib satisfies the reference to fillclr.

If, however, you enter:

 armcl --run_linker f1.obj f2.obj libc.lib liba.lib 

then the references to clrscr are satisfied by member 1 of libc.lib.

If none of the linked files reference symbols defined in a library, you can use the --undef_sym option to force the linker to include a library member. (See Section 8.4.35.) The next example creates an undefined symbol rout1 in the linker's global symbol table:

 armcl --run_linker --undef_sym=rout1 libc.lib 

If any member of libc.lib defines rout1, the linker includes that member.

Library members are allocated according to the SECTIONS directive default allocation algorithm; see Section 8.5.5.

describes methods for specifying directories that contain object libraries.

8.7 Default Placement Algorithm

The MEMORY and SECTIONS directives provide flexible methods for building, combining, and allocating sections. However, any memory locations or sections you choose not to specify must still be handled by the linker. The linker uses algorithms to build and allocate sections in coordination with any specifications you do supply.

If you do not use the MEMORY and SECTIONS directives, the linker allocates output sections as though the memory map and section definitions were as shown in Example 8-16 were specified.

Example 8-16 Default Allocation for ARM Devices

{ RAM : origin = 0x00000000, length = 0xFFFFFFFF } SECTIONS { .text : ALIGN(4) {} > RAM .const: ALIGN(4) {} > RAM .data : ALIGN(4) {} > RAM .bss : ALIGN(4) {} > RAM .cinit: ALIGN(4) {} > RAM /* -c option only */ .pinit: ALIGN(4) {} > RAM /* -c option only */ }

Also see Section 2.5.1 for information about default memory allocation.

All .text input sections are concatenated to form a .text output section in the executable output file, and all .data input sections are combined to form a .data output section.

If you use a SECTIONS directive, the linker performs no part of this default allocation. Instead, allocation is performed according to the rules specified by the SECTIONS directive and the general algorithm described next in Section 8.7.1.

8.7.1 How the Allocation Algorithm Creates Output Sections

An output section can be formed in one of two ways:

 Method 1 As the result of a SECTIONS directive definition Method 2 By combining input sections with the same name into an output section that is not defined in a SECTIONS directive

If an output section is formed as a result of a SECTIONS directive, this definition completely determines the section's contents. (See Section 8.5.5 for examples of how to define an output section's content.)

If an output section is formed by combining input sections not specified by a SECTIONS directive, the linker combines all such input sections that have the same name into an output section with that name. For example, suppose the files f1.obj and f2.obj both contain named sections called Vectors and that the SECTIONS directive does not define an output section for them. The linker combines the two Vectors sections from the input files into a single output section named Vectors, allocates it into memory, and includes it in the output file.

By default, the linker does not display a message when it creates an output section that is not defined in the SECTIONS directive. You can use the --warn_sections linker option (see Section 8.4.36) to cause the linker to display a message when it creates a new output section.

After the linker determines the composition of all output sections, it must allocate them into configured memory. The MEMORY directive specifies which portions of memory are configured. If there is no MEMORY directive, the linker uses the default configuration as shown in Example 8-16. (See Section 8.5.4 for more information on configuring memory.)

8.7.2 Reducing Memory Fragmentation

The linker's allocation algorithm attempts to minimize memory fragmentation. This allows memory to be used more efficiently and increases the probability that your program will fit into memory. The algorithm comprises these steps:

1. Each output section for which you supply a specific binding address is placed in memory at that address.
2. Each output section that is included in a specific, named memory range or that has memory attribute restrictions is allocated. Each output section is placed into the first available space within the named area, considering alignment where necessary.
3. Any remaining sections are allocated in the order in which they are defined. Sections not defined in a SECTIONS directive are allocated in the order in which they are encountered. Each output section is placed into the first available memory space, considering alignment where necessary.

If you want to control the order in which code and data are placed in memory, see the FAQ topic on section placement.

The linker supports extensions to the linker command file syntax that enable the following:

• Make it easier for you to copy objects from load-space to run-space at boot time
• Make it easier for you to manage memory overlays at run time
• Allow you to split GROUPs and output sections that have separate load and run addresses

In some embedded applications, there is a need to copy or download code and/or data from one location to another at boot time before the application actually begins its main execution thread. For example, an application may have its code and/or data in FLASH memory and need to copy it into on-chip memory before the application begins execution.

One way to develop such an application is to create a copy table in assembly code that contains three elements for each block of code or data that needs to be moved from FLASH to on-chip memory at boot time:

• The size

The process you follow to develop such an application might look like this:

1. Build the application to produce a .map file that contains the load and run addresses of each section that has a separate load and run placement.
2. Edit the copy table (used by the boot loader) to correct the load and run addresses as well as the size of each block of code or data that needs to be moved at boot time.
3. Build the application again, incorporating the updated copy table.
4. Run the application.

This process puts a heavy burden on you to maintain the copy table (by hand, no less). Each time a piece of code or data is added or removed from the application, you must repeat the process in order to keep the contents of the copy table up to date.

8.8.2 Using Built-in Link Operators in Copy Tables

You can avoid some of this maintenance burden by using the LOAD_START(), RUN_START(), and SIZE() operators that are already part of the linker command file syntax . For example, instead of building the application to generate a .map file, the linker command file can be annotated:

SECTIONS { .flashcode: { app_tasks.obj(.text) } load = FLASH, run = PMEM, LOAD_START(_flash_code_ld_start), RUN_START(_flash_code_rn_start), SIZE(_flash_code_size) ... }

In this example, the LOAD_START(), RUN_START(), and SIZE() operators instruct the linker to create three symbols:

Symbol Description
_flash_code_rn_start Run address of .flashcode section
_flash_code_size Size of .flashcode section

These symbols can then be referenced from the copy table. The actual data in the copy table will be updated automatically each time the application is linked. This approach removes step 1 of the process described in Section 8.8.1.

While maintenance of the copy table is reduced markedly, you must still carry the burden of keeping the copy table contents in sync with the symbols that are defined in the linker command file. Ideally, the linker would generate the boot copy table automatically. This would avoid having to build the application twice and free you from having to explicitly manage the contents of the boot copy table.

8.8.3 Overlay Management Example

Consider an application that contains a memory overlay that must be managed at run time. The memory overlay is defined using a UNION in the linker command file as illustrated in Example 8-17:

Example 8-17 Using a UNION for Memory Overlay

SECTIONS { ... UNION { GROUP { .task1: { task1.obj(.text) } .task2: { task2.obj(.text) } } load = ROM, LOAD_START(_task12_load_start), SIZE(_task12_size) GROUP { .task3: { task3.obj(.text) } .task4: { task4.obj(.text) } } load = ROM, LOAD_START(_task34_load_start), SIZE(_task_34_size) } run = RAM, RUN_START(_task_run_start) ... }

The application must manage the contents of the memory overlay at run time. That is, whenever any services from .task1 or .task2 are needed, the application must first ensure that .task1 and .task2 are resident in the memory overlay. Similarly for .task3 and .task4.

8.8.4 Generating Copy Tables With the table() Operator

The linker supports extensions to the linker command file syntax that enable you to do the following:

• Identify any object components that may need to be copied from load space to run space at some point during the run of an application
• Instruct the linker to automatically generate a copy table that contains (at least) the load address, run address, and size of the component that needs to be copied
• Instruct the linker to generate a symbol specified by you that provides the address of a linker-generated copy table. For instance, Example 8-17 can be written as shown in Example 8-18:

SECTIONS { ... UNION { GROUP { .task1: { task1.obj(.text) } .task2: { task2.obj(.text) } } load = ROM, table(_task12_copy_table) GROUP { .task3: { task3.obj(.text) } .task4: { task4.obj(.text) } } load = ROM, table(_task34_copy_table) } run = RAM ... }

Using this method, you need not worry about the creation or maintenance of a copy table. You can reference the address of any copy table generated by the linker in C/C++ or assembly source code, passing that value to a general purpose copy routine, which will process the copy table and affect the actual copy.

8.8.4.1 The table() Operator

You can use the table() operator to instruct the linker to produce a copy table. A table() operator can be applied to an output section, a GROUP, or a UNION member. The copy table generated for a particular table() specification can be accessed through a symbol specified by you that is provided as an argument to the table() operator. The linker creates a symbol with this name and assigns it the address of the copy table as the value of the symbol. The copy table can then be accessed from the application using the linker-generated symbol.

Each table() specification you apply to members of a given UNION must contain a unique name. If a table() operator is applied to a GROUP, then none of that GROUP's members may be marked with a table() specification. The linker detects violations of these rules and reports them as warnings, ignoring each offending use of the table() specification. The linker does not generate a copy table for erroneous table() operator specifications.

Copy tables can be generated automatically; see Section 8.8.4. The table operator can be used with compression; see Section 8.8.5.

8.8.4.2 Boot-Time Copy Tables

The linker supports a special copy table name, BINIT (or binit), that you can use to create a boot-time copy table. This table is handled before the .cinit section is used to initialize variables at startup. For example, the linker command file for the boot-loaded application described in Section 8.8.2 can be rewritten as follows:

SECTIONS { .flashcode: { app_tasks.obj(.text) } load = FLASH, run = PMEM, table(BINIT) ... }

For this example, the linker creates a copy table that can be accessed through a special linker-generated symbol, __binit__, which contains the list of all object components that need to be copied from their load location to their run location at boot-time. If a linker command file does not contain any uses of table(BINIT), then the __binit__ symbol is given a value of -1 to indicate that a boot-time copy table does not exist for a particular application.

You can apply the table(BINIT) specification to an output section, GROUP, or UNION member. If used in the context of a UNION, only one member of the UNION can be designated with table(BINIT). If applied to a GROUP, then none of that GROUP's members may be marked with table(BINIT).The linker detects violations of these rules and reports them as warnings, ignoring each offending use of the table(BINIT) specification.

8.8.4.3 Using the table() Operator to Manage Object Components

If you have several pieces of code that need to be managed together, then you can apply the same table() operator to several different object components. In addition, if you want to manage a particular object component in multiple ways, you can apply more than one table() operator to it. Consider the linker command file excerpt in Example 8-19:

Example 8-19 Linker Command File to Manage Object Components

SECTIONS { UNION { .first: { a1.obj(.text), b1.obj(.text), c1.obj(.text) } load = EMEM, run = PMEM, table(BINIT), table(_first_ctbl) .second: { a2.obj(.text), b2.obj(.text) } load = EMEM, run = PMEM, table(_second_ctbl) } .extra: load = EMEM, run = PMEM, table(BINIT) ... }

In this example, the output sections .first and .extra are copied from external memory (EMEM) into program memory (PMEM) at boot time while processing the BINIT copy table. After the application has started executing its main thread, it can then manage the contents of the overlay using the two overlay copy tables named: _first_ctbl and _second_ctbl.

8.8.4.4 Linker-Generated Copy Table Sections and Symbols

The linker creates and allocates a separate input section for each copy table that it generates. Each copy table symbol is defined with the address value of the input section that contains the corresponding copy table.

The linker generates a unique name for each overlay copy table input section. For example, table(_first_ctbl) would place the copy table for the .first section into an input section called .ovly:_first_ctbl. The linker creates a single input section, .binit, to contain the entire boot-time copy table.

illustrates how you can control the placement of the linker-generated copy table sections using the input section names in the linker command file.

Example 8-20 Controlling the Placement of the Linker-Generated Copy Table Sections

SECTIONS { UNION { .first: { a1.obj(.text), b1.obj(.text), c1.obj(.text) } load = EMEM, run = PMEM, table(BINIT), table(_first_ctbl) .second: { a2.obj(.text), b2.obj(.text) } load = EMEM, run = PMEM, table(_second_ctbl) } .extra: load = EMEM, run = PMEM, table(BINIT) ... .ovly: { } > BMEM .binit: { } > BMEM }

For the linker command file in Example 8-20, the boot-time copy table is generated into a .binit input section, which is collected into the .binit output section, which is mapped to an address in the BMEM memory area. The _first_ctbl is generated into the .ovly:_first_ctbl input section and the _second_ctbl is generated into the .ovly:_second_ctbl input section. Since the base names of these input sections match the name of the .ovly output section, the input sections are collected into the .ovly output section, which is then mapped to an address in the BMEM memory area.

If you do not provide explicit placement instructions for the linker-generated copy table sections, they are allocated according to the linker's default placement algorithm.

The linker does not allow other types of input sections to be combined with a copy table input section in the same output section. The linker does not allow a copy table section that was created from a partial link session to be used as input to a succeeding link session.

8.8.4.5 Splitting Object Components and Overlay Management

It is possible to split sections that have separate load and run placement instructions. The linker can access both the load address and run address of every piece of a split object component. Using the table() operator, you can tell the linker to generate this information into a copy table. The linker gives each piece of the split object component a COPY_RECORD entry in the copy table object.

For example, consider an application which has seven tasks. Tasks 1 through 3 are overlaid with tasks 4 through 7 (using a UNION directive). The load placement of all of the tasks is split among four different memory areas (LMEM1, LMEM2, LMEM3, and LMEM4). The overlay is defined as part of memory area PMEM. You must move each set of tasks into the overlay at run time before any services from the set are used.

You can use table() operators in combination with splitting operators, >>, to create copy tables that have all the information needed to move either group of tasks into the memory overlay as shown in Example 8-21.

Example 8-21 Creating a Copy Table to Access a Split Object Component

SECTIONS { UNION { .task1to3: { *(.task1), *(.task2), *(.task3) } load >> LMEM1 | LMEM2 | LMEM4, table(_task13_ctbl) GROUP { .task4: { *(.task4) } .task5: { *(.task5) } .task6: { *(.task6) } .task7: { *(.task7) } } load >> LMEM1 | LMEM3 | LMEM4, table(_task47_ctbl) } run = PMEM ... .ovly: > LMEM4 }

illustrates a possible driver for such an application.

Example 8-22 Split Object Component Driver

#include <cpy_tbl.h>extern far COPY_TABLE task13_ctbl; extern far COPY_TABLE task47_ctbl; extern void task1(void); ... extern void task7(void); main() { ... copy_in(&task13_ctbl); task1(); task2(); task3(); ... copy_in(&task47_ctbl); task4(); task5(); task6(); task7(); ... }

You must declare a COPY_TABLE object as far to allow the overlay copy table section placement to be independent from the other sections containing data objects (such as .bss).

The contents of the .task1to3 section are split in the section's load space and contiguous in its run space. The linker-generated copy table, _task13_ctbl, contains a separate COPY_RECORD for each piece of the split section .task1to3. When the address of _task13_ctbl is passed to copy_in(), each piece of .task1to3 is copied from its load location into the run location.

The contents of the GROUP containing tasks 4 through 7 are also split in load space. The linker performs the GROUP split by applying the split operator to each member of the GROUP in order. The copy table for the GROUP then contains a COPY_RECORD entry for every piece of every member of the GROUP. These pieces are copied into the memory overlay when the _task47_ctbl is processed by copy_in().

The split operator can be applied to an output section, GROUP, or the load placement of a UNION or UNION member. The linker does not permit a split operator to be applied to the run placement of either a UNION or of a UNION member. The linker detects such violations, emits a warning, and ignores the offending split operator usage.

8.8.5 Compression

When automatically generating copy tables, the linker provides a way to compress the load-space data. This can reduce the read-only memory foot print. This compressed data can be decompressed while copying the data from load space to run space.

You can specify compression in two ways:

• The linker command line option --copy_compression=compression_kind can be used to apply the specified compression to any output section that has a table() operator applied to it.
• The table() operator accepts an optional compression parameter. The syntax is: .
• table( name , compression= compression_kind )

The compression_kind can be one of the following types:

• off. Don't compress the data.
• rle. Compress data using Run Length Encoding.
• lzss. Compress data using Lempel-Ziv-Storer-Szymanski compression.

A table() operator without the compression keyword uses the compression kind specified using the command line option --copy_compression.

When you choose compression, it is not guaranteed that the linker will compress the load data. The linker compresses load data only when such compression reduces the overall size of the load space. In some cases even if the compression results in smaller load section size the linker does not compress the data if the decompression routine offsets for the savings.

For example, assume RLE compression reduces the size of section1 by 30 bytes. Also assume the RLE decompression routine takes up 40 bytes in load space. By choosing to compress section1 the load space is increased by 10 bytes. Therefore, the linker will not compress section1. On the other hand, if there is another section (say section2) that can benefit by more than 10 bytes from applying the same compression then both sections can be compressed and the overall load space is reduced. In such cases the linker compresses both the sections.

You cannot force the linker to compress the data when doing so does not result in savings.

You cannot compress the decompression routines or any member of a GROUP containing .cinit.

8.8.5.1 Compressed Copy Table Format

The copy table format is the same irrespective of the compression. The size field of the copy record is overloaded to support compression. Figure 8-5 illustrates the compressed copy table layout.

In Figure 8-5, if the size in the copy record is non-zero it represents the size of the data to be copied, and also means that the size of the load data is the same as the run data. When the size is 0, it means that the load data is compressed.

8.8.5.2 Compressed Section Representation in the Object File

When the load data is not compressed, the object file can have only one section with a different load and run address.

Consider the following table() operation in the linker command file.

SECTIONS { .task1: load = ROM, run = RAM, table(_task1_table) }

The output object file has one output section named .task1 which has a different load and run addresses. This is possible because the load space and run space have identical data when the section is not compressed.

Alternatively, consider the following:

SECTIONS { .task1: load = ROM, run = RAM, table(_task1_table, compression=rle) }

If the linker compresses the .task1 section then the load space data and the run space data are different. The linker creates the following two sections:

• .task1 : This section is uninitialized. This output section represents the run space image of section task1.
• .task1.load : This section is initialized. This output section represents the load space image of the section task1. This section usually is considerably smaller in size than .task1 output section.
8.8.5.3 Compressed Data Layout

The compressed load data has the following layout:

 8-bit index Compressed data

The first eight bits of the load data are the handler index. This handler index is used to index into a handler table to get the address of a handler function that knows how to decode the data that follows. The handler table is a list of 32-bit function pointers as shown in Figure 8-6.

The linker creates a separate output section for the load and run space. For example, if .task1.load is compressed using RLE, the handler index points to an entry in the handler table that has the address of the run-time-support routine __TI_decompress_rle().

8.8.5.4 Run-Time Decompression

During run time you call the run-time-support routine copy_in() to copy the data from load space to run space. The address of the copy table is passed to this routine. First the routine reads the record count. Then it repeats the following steps for each record:

2. If size is zero go to step 5.
4. Go to step 1 if there are more records to read.
8. Go to step 1 if there are more records to read.

The routines to handle the decompression of load data are provided in the run-time-support library.

8.8.5.5 Compression Algorithms

Run Length Encoding (RLE):

 8-bit index Initialization data compressed using run length encoding

The data following the 8-bit index is compressed using run length encoded (RLE) format. ARM uses a simple run length encoding that can be decompressed using the following algorithm:

1. Read the first byte, Delimiter (D).
2. Read the next byte (B).
3. If B != D, copy B to the output buffer and go to step 2.
4. Read the next byte (L).
1. If L == 0, then length is either a 16-bit, a 24-bit value, or we’ve reached the end of the data, read next byte (L).
1. If L == 0, length is a 24-bit value or the end of the data is reached, read next byte (L).
1. If L == 0, the end of the data is reached, go to step 7.
2. Else L <<= 16, read next two bytes into lower 16 bits of L to complete 24-bit value for L.
2. Else L <<= 8, read next byte into lower 8 bits of L to complete 16-bit value for L.
2. Else if L > 0 and L < 4, copy D to the output buffer L times. Go to step 2.
3. Else, length is 8-bit value (L).
5. Read the next byte (C); C is the repeat character.
6. Write C to the output buffer L times; go to step 2.
7. End of processing.

The ARM run-time support library has a routine __TI_decompress_rle24() to decompress data compressed using RLE. The first argument to this function is the address pointing to the byte after the 8-bit index. The second argument is the run address from the C auto initialization record.

NOTE

RLE Decompression Routine

The previous decompression routine, __TI_decompress_rle(), is included in the run-time-support library for decompressing RLE encodings that are generated by older versions of the linker.

Lempel-Ziv-Storer-Szymanski Compression (LZSS):

 8-bit index Data compressed using LZSS

The data following the 8-bit index is compressed using LZSS compression. The ARM run-time-support library has the routine __TI_decompress_lzss() to decompress the data compressed using LZSS. The first argument to this function is the address pointing to the byte after the 8-bit Index, and the second argument is the run address from the C auto initialization record.

8.8.6 Copy Table Contents

To use a copy table generated by the linker, you must know the contents of the copy table. This information is included in a run-time-support library header file, cpy_tbl.h, which contains a C source representation of the copy table data structure that is generated by the linker. Example 8-23 shows the copy table header file.

Example 8-23 ARM cpy_tbl.h File

/*****************************************************************************/ /* cpy_tbl.h v##### */ /* Copyright (c) 2003 Texas Instruments Incorporated */ /* */ /* Specification of copy table data structures which can be automatically */ /* generated by the linker (using the table() operator in the LCF). */ /*****************************************************************************/ #ifndef _CPY_TBL #define _CPY_TBL #ifdef __cplusplus extern "C" namespace std { #endif /* __cplusplus */ /*****************************************************************************/ /* Copy Record Data Structure */ /*****************************************************************************/ typedef struct copy_record { unsigned int load_addr; unsigned int run_addr; unsigned int size; } COPY_RECORD; /*****************************************************************************/ /* Copy Table Data Structure */ /*****************************************************************************/ typedef struct copy_table { unsigned short rec_size; unsigned short num_recs; COPY_RECORD recs[1]; } COPY_TABLE; /*****************************************************************************/ /* Prototype for general purpose copy routine. */ /*****************************************************************************/ extern void copy_in(COPY_TABLE *tp); #ifdef __cplusplus } /* extern "C" namespace std */ #ifndef _CPP_STYLE_HEADER using std::COPY_RECORD; using std::COPY_TABLE; using std::copy_in; #endif /* _CPP_STYLE_HEADER */ #endif /* __cplusplus */ #endif /* !_CPY_TBL */

For each object component that is marked for a copy, the linker creates a COPY_RECORD object for it. Each COPY_RECORD contains at least the following information for the object component:

• The size

The linker collects all COPY_RECORDs that are associated with the same copy table into a COPY_TABLE object. The COPY_TABLE object contains the size of a given COPY_RECORD, the number of COPY_RECORDs in the table, and the array of COPY_RECORDs in the table. For instance, in the BINIT example in Section 8.8.4.2, the .first and .extra output sections will each have their own COPY_RECORD entries in the BINIT copy table. The BINIT copy table will then look like this:

COPY_TABLE __binit__ = { 12, 2, { <load address of .first>, <run address of .first>, <size of .first> }, { <load address of .extra>, <run address of .extra>, <size of .extra> } };

8.8.7 General Purpose Copy Routine

The cpy_tbl.h file in Example 8-23 also contains a prototype for a general-purpose copy routine, copy_in(), which is provided as part of the run-time-support library. The copy_in() routine takes a single argument: the address of a linker-generated copy table. The routine then processes the copy table data object and performs the copy of each object component specified in the copy table.

The copy_in() function definition is provided in the cpy_tbl.c run-time-support source file shown in Example 8-24.

Example 8-24 Run-Time-Support cpy_tbl.c File

/*****************************************************************************/ /* cpy_tbl.c v##### */ /* Copyright (c) 2003 Texas Instruments Incorporated */ /* */ /* General purpose copy routine. Given the address of a linker-generated */ /* COPY_TABLE data structure, effect the copy of all object components */ /* that are designated for copy via the corresponding LCF table() operator. */ /*****************************************************************************/ #include <cpy_tbl.h>#include <string.h>typedef void (*handler_fptr)(const unsigned char *in, unsigned char *out) /*****************************************************************************/ /* COPY_IN() */ /*****************************************************************************/ void copy_in(COPY_TABLE *tp) { unsigned short I; for (I = 0; I < tp->num_recs; I++) { COPY_RECORD crp = tp->recs[i]; unsigned char *ld_addr = (unsigned char *)crp.load_addr; unsigned char *rn_addr = (unsigned char *)crp.run_addr; if (crp.size) { /*------------------------------------------------------------------*/ /* Copy record has a non-zero size so the data is not compressed. */ /* Just copy the data. */ /*------------------------------------------------------------------*/ memcpy(rn_addr, ld_addr, crp.size); } } }

The linker supports an extension to the linker command file syntax that enables the verification of code or data by means of Cyclic Redundancy Code (CRC). The linker computes a CRC value for the specified region at link time, and stores that value in target memory such that it is accessible at boot or run time. The application code can then compute the CRC for that region and ensure that the value matches the linker-computed value. The run-time-support library does not supply a routine to calculate CRC values at boot or run time.

8.9.1 The crc_table() Operator

For any section that should be verified with a CRC, the linker command file must be modified to include the crc_table() operator. The specification of a CRC algorithm is optional. The syntax is:

crc_table( user_specified_table_name[, algorithm=xxx])

The linker uses the CRC algorithm from any specification given in a crc_table() operator. If that specification is omitted, the TMS570_CRC64_ISO algorithm is used. The linker includes CRC table information in the map file. This includes the CRC value as well as the algorithm used for the calculation.

The CRC table generated for a particular crc_table() instance can be accessed through the table name provided as an argument to the crc_table() operator. The linker creates a symbol with this name and assigns the address of the CRC table as the value of the symbol. The CRC table can then be accessed from the application using the linker-generated symbol.

The crc_table() operator can be applied to an output section, a GROUP, a GROUP member, a UNION, or a UNION member. If applied to a GROUP or UNION, the operator is applied to each member of the GROUP or UNION.

You can include calls in your application to a routine that will verify CRC values for relevant sections. You must provide this routine. See below for more details on the data structures and suggested interface.

8.9.2 Restrictions

It is important to note that the CRC generator used by the linker is parameterized as described in the crc_tbl.h header file (see Example 8-29). Any CRC calculation routine employed outside of the linker must function in the same way to ensure matching CRC values. The linker cannot detect a mismatch in the parameters. To understand these parameters, see A Painless Guide to CRC Error Detection Algorithms by Ross Williams, which is likely located at http://www.ross.net/crc/download/crc_v3.txt.

Only the CRC algorithm names and identifiers specified in crc_tbl.h are supported. All other names and ID values are reserved for future use. Your system may not include built-in hardware that computes all these CRC algorithms. Consult the documentation for your hardware for more detail. The following CRC algorithms are supported:

• CRC8_PRIME
• CRC16_ALT
• CRC16_802_15_4
• CRC_CCITT
• CRC24_FLEXRAY
• CRC32_PRIME
• CRC32_C
• CRC64_ISO

The TMS570_CRC64_ISO algorithm has an initial value of 0. The details of the algorithm are available in the MCRC documentation.

There are also restrictions which will be enforced by the linker:

• CRC can only be requested at final link time.
• CRC can only be applied to initialized sections.
• Certain restrictions also apply to CRC table names. For example, BINIT may not be used as a CRC table name.

8.9.3 Examples

The crc_table() operator is similar in syntax to the table() operator used for copy tables. A few simple examples of linker command files follow.

Example 8-25 Using crc_table() Operator to Compute the CRC Value for .text Data

... SECTIONS { ... .section_to_be_verified: {a1.obj(.text)} crc_table(_my_crc_table_for_a1) } 

defines a section named “.section_to_be_verified”, which contains the .text data from the a1.obj file. The crc_table() operator requests that the linker compute the CRC value for the .text data and store that value in a table named “my_crc_table_for_a1”. This table will contain all the information needed to invoke a user-supplied CRC calculation routine, and verify that the CRC calculated at run time matches the linker-generated CRC. The table can be accessed from application code using the symbol my_crc_table_for_a1, which should be declared of type “extern CRC_TABLE”. This symbol will be defined by the linker. The application code might resemble the following.

#include "crc_tbl.h"extern CRC_TABLE my_crc_table_for_a1; verify_a1_text_contents() { ... /* Verify CRC value for .text sections of a1.obj. */ if (my_check_CRC(&my_crc_table_for_a1)) puts("OK"); } 

The my_check_CRC() routine is discussed in detail in Section 8.9.4, Example 8-30.

Example 8-26 Specifying an Algorithm in the crc_table() Operator

... SECTIONS { ... .section_to_be_verified_2: {b1.obj(.text)} load=SLOW_MEM, run=FAST_MEM, crc_table(_my_crc_table_for_b1, algorithm=TMS570_CRC64_ISO) .TI.crctab: > CRCMEM } ...

In Example 8-26, the CRC algorithm is specified in the crc_table() operator. The specified algorithm is used to compute the CRC of the text data from b1.obj. The CRC tables generated by the linker are created in the special section .TI.crctab, which can be placed in the same manner as other sections. In this case, the CRC table _my_crc_table_for_b1 is created in section .TI.crctab:_my_crc_table_for_b1, and that section is placed in the CRCMEM memory region.

Example 8-27 Using a Single Table for Multiple Sections

... SECTIONS { .section_to_be_verified_1: {a1.obj(.text)} crc_table(_my_crc_table_for_a1_and_c1) .section_to_be_verified_3: {c1.obj(.text)} crc_table(_my_crc_table_for_a1_and_c1, algorithm=TMS570_CRC64_ISO) } ...

In Example 8-27 the same identifier, _my_crc_table_for_a1_and_c1, is specified for both a1.obj and c1.obj. The linker creates a single table that contains entries for both text sections.

Example 8-28 Applying the crc_table() Operator to a GROUP or UNION

... SECTIONS { UNION { section1: {} crc_table(table1) section2: } crc_table(table2) }

When the crc_table() operator is applied to a GROUP or a UNION, the linker applies the table specification to the members of the GROUP or UNION.

In Example 8-28 the linker creates two CRC tables, table1 and table2. table1 contains one entry for section1. Because both sections are members of the UNION, table2 contains entries for section1 and section2. The order of the entries in table2 is unspecified.

8.9.4 Interface

The CRC generation function uses a mechanism similar to the copy table functionality. Using the syntax shown above in the linker command file allows specification of code/data sections that have CRC values computed and stored in the run time image. This section describes the table data structures created by the linker, and how to access this information from application code.

The CRC tables contain entries as detailed in the run-time-support header file crc_tbl.h, as illustrated in Figure 8-7.

The crc_tbl.h header file is included in Example 8-29. This file specifies the C structures created by the linker to manage CRC information. It also includes the specifications of the supported CRC algorithms. A full discussion of CRC algorithms is beyond the scope of this document, and the interested reader should consult the referenced document for a description of the fields shown in the table. The following fields are relevant to this document.

• Name – text identifier of the algorithm, used by the programmer in the linker command file.
• ID – the numeric identifier of the algorithm, stored by the linker in the crc_alg_ID member of each table entry.
• Order – the number of bits used by the CRC calculation.
• Polynomial – used by the CRC computation engine.
• Initial Value – the initial value given to the CRC computation engine.

Example 8-29 The CRC Table Header, crc_tbl.h

/*****************************************************************************/ /* crc_tbl.h */ /* */ /* Specification of CRC table data structures which can be automatically */ /* generated by the linker (using the crc_table() operator in the linker */ /* command file). */ /*****************************************************************************/ /* */ /* The CRC generator used by the linker is based on concepts from the */ /* document: */ /* "A Painless Guide to CRC Error Detection Algorithms" */ /* */ /* Author : Ross Williams (ross@guest.adelaide.edu.au.). */ /* Date : 3 June 1993. */ /* Status : Public domain (C code). */ /* */ /* Description : For more information on the Rocksoft^tm Model CRC */ /* Algorithm, see the document titled "A Painless Guide to CRC Error */ /* Detection Algorithms" by Ross Williams (ross@guest.adelaide.edu.au.). */ /* This document is likely to be in "ftp.adelaide.edu.au/pub/rocksoft" or */ /* at http:www.ross.net/crc/download/crc_v3.txt. */ /* */ /* Note: Rocksoft is a trademark of Rocksoft Pty Ltd, Adelaide, Australia. */ /*****************************************************************************/ #include <stdint.h> /* For uintXX_t */ /*****************************************************************************/ /* CRC Algorithm Specifiers */ /* */ /* The following specifications, based on the above cited document, are used */ /* by the linker to generate CRC values. */ /* ID Name Order Polynomial Initial Ref Ref CRC XOR Zero Value In Out Value Pad -------------------------------------------------------------------------------- 10 "TMS570_CRC64_ISO", 64, 0x0000001b, 0x00000000, 0, 0, 0x00000000, 1 */ /* Users should specify the name, such as TMS570_CRC64_ISO, in the linker */ /* command file. The resulting CRC_RECORD structure will contain the */ /* corresponding ID value in the crc_alg_ID field. */ /*****************************************************************************/ #define TMS570_CRC64_ISO 10 /*********************************************************/ /* CRC Record Data Structure */ /* NOTE: The list of fields and the size of each field */ /* varies by target and memory model. */ /*********************************************************/ typedef struct crc_record { uint64_t crc_value; uint32_t crc_alg_ID; /* CRC algorithm ID */ uint32_t addr; /* Starting address */ uint32_t size; /* size of data in bytes */ uint32_t padding; /* explicit padding so layout is the same */ /* for ELF */ } CRC_RECORD;

In the CRC_TABLE struct, the array recs[1] is dynamically sized by the linker to accommodate the number of records contained in the table (num_recs). A user-supplied routine to verify CRC values should take a table name and check the CRC values for all entries in the table. An outline of such a routine is shown in Example 8-30.

Example 8-30 General Purpose CRC Check Routine

/**************************************************************/ /* General purpose CRC check routine. Given the address of a */ /* linker-generated CRC_TABLE data structure, verify the CRC */ /* of all object components that are designated with the */ /* corresponding LCF crc_table() operator. */ /**************************************************************/ #include <crc_tbl.h>/*********************************************************/ /* MY_CHECK_CRC() - returns 1 if CRCs match, 0 otherwise */ /*********************************************************/ unsigned int my_check_CRC(CRC_TABLE *tp) { int i; for (i = 0; i < tp-> num_recs; i++) { CRC_RECORD crc_rec = tp->recs[i]; /**************************************************/ /* COMPUTE CRC OF DATA STARTING AT crc_rec.addr */ /* FOR crc_rec.size UNITS. USE */ /* crc_rec.crc_alg_ID to select algorithm. */ /* COMPARE COMPUTED VALUE TO crc_rec.crc_value. */ /**************************************************/ } if all CRCs match, return 1; else return 0; } 

8.9.5 A Note on the TMS570_CRC64_ISO Algorithm

The MCRC module calculates CRCs on 64-bit chunks of data. This is accomplished by writing a long long value to two memory mapped registers. In C this looks like a normal write of a long long to memory. The code generated to read/write a long long to memory is something like the following, where R2 contains the most significant word and R3 contains the least significant word. So the most significant word is written to the low address and the least significant word is written to the high address:

 LDM R0, {R2, R3} STM R1, {R2, R3}

The CRC memory mapped registers are in the reverse order from how the compiler performs the store. The least significant word is mapped to the low address and the most significant word is mapped to the high address.

This means that the words are actually swapped before performing the CRC calculation. It also means that the calculated CRC value has the words swapped. The TMS570_CRC64_ISO algorithm takes these issues into consideration and performs the swap when calculating the CRC value. The computed CRC value stored in the table has the words swapped so the value is the same as it is in memory.

For the end user, these details should be transparent. If the run-time CRC routine is written in C, the long long loads and stores will be generated correctly. The DMA mode of the MCRC module will also work correctly.

Another issue with the algorithm is that it requires the run-time CRC calculation to be done with 64-bit chunks. The MCRC module allows smaller chunks of data, but the values are padded to 64-bits. The TMS570_CRC64_ISO algorithm does not perform any padding, so all CRC computations must be done with 64-bit values. The algorithm will automatically pad the end of the data with zeros if it does not end on a 64-bit boundary.

An output file that has been linked can be linked again with additional modules. This is known as partial linking or incremental linking. Partial linking allows you to partition large applications, link each part separately, and then link all the parts together to create the final executable program.

• The intermediate files produced by the linker must have relocation information. Use the --relocatable option when you link the file the first time. (See Section 8.4.3.2.)
• Intermediate files must have symbolic information. By default, the linker retains symbolic information in its output. Do not use the --no_sym_table option if you plan to relink a file, because --no_sym_table strips symbolic information from the output module. (See Section 8.4.24.)
• Intermediate link operations should be concerned only with the formation of output sections and not with allocation. All allocation, binding, and MEMORY directives should be performed in the final link.
• Since the ELF object file format is used, input sections are not combined into output sections during a partial link unless a matching SECTIONS directive is specified in the link step command file.

• If the intermediate files have global symbols that have the same name as global symbols in other files and you want them to be treated as static (visible only within the intermediate file), you must link the files with the --make_static option (see Section 8.4.19.1).
• If you are linking C code, do not use --ram_model or --rom_model until the final linker. Every time you invoke the linker with the --ram_model or --rom_model option, the linker attempts to create an entry point. (See Section 8.4.27.)

The following example shows how you can use partial linking:

 Step 1: Link the file file1.com; use the --relocatable option to retain relocation information in the output file tempout1.out. armcl --run_linker --relocatable --output_file=tempout1 file1.com file1.com contains: SECTIONS{ ss1: { f1.obj f2.obj . . . fn.obj }} Step 2: Link the file file2.com; use the --relocatable option to retain relocation information in the output file tempout2.out. armcl --run_linker --relocatable --output_file=tempout2 file2.com file2.com contains: SECTIONS{ ss2: { g1.obj g2.obj . . . gn.obj }} Step 3: Link tempout1.out and tempout2.out. armcl --run_linker --map_file=final.map --output_file=final.out tempout1.out tempout2.out

The C/C++ compiler produces assembly language source code that can be assembled and linked. For example, a C program consisting of modules prog1, prog2, etc., can be assembled and then linked to produce an executable file called prog.out:

armcl --run_linker --rom_model --output_file prog.out prog1.obj prog2.obj ... rtsv4_A_be_eabi.lib

The --rom_model option tells the linker to use special conventions that are defined by the C/C++ environment.

The archive libraries shipped by TI contain C/C++ run-time-support functions.

C, C++, and mixed C and C++ programs can use the same run-time-support library. Run-time-support functions and variables that can be called and referenced from both C and C++ will have the same linkage.

For more information about the ARM C/C++ language, including the run-time environment and run-time-support functions, see the ARM Optimizing C/C++ Compiler User's Guide.

8.11.1 Run-Time Initialization

All C/C++ programs must be linked with code to initialize and execute the program, called a bootstrap routine, also known as the boot.obj object module. The symbol _c_int00 is defined as the program entry point and is the start of the C boot routine in boot.obj; referencing _c_int00 ensures that boot.obj is automatically linked in from the run-time-support library. When a program begins running, it executes boot.obj first. The boot.obj symbol contains code and data for initializing the run-time environment and performs the following tasks:

• Changes from system mode to user mode
• Sets up the user mode stack
• Processes the run-time .cinit initialization table and autoinitializes global variables (when the linker is invoked with the --rom_model option)
• Calls main

The run-time-support object libraries contain boot.obj. You can:

• Use the archiver to extract boot.obj from the library and then link the module in directly.
• Include the appropriate run-time-support library as an input file (the linker automatically extracts boot.obj when you use the --ram_model or --rom_model option).

8.11.2 Object Libraries and Run-Time Support

The ARM Optimizing C/C++ Compiler User's Guide describes additional run-time-support functions that are included in rts.src. If your program uses any of these functions, you must link the appropriate run-time-support library with your object files.

You can also create your own object libraries and link them. The linker includes and links only those library members that resolve undefined references.

8.11.3 Setting the Size of the Stack and Heap Sections

The C/C++ language uses two uninitialized sections called .sysmem and .stack for the memory pool used by the malloc( ) functions and the run-time stacks, respectively. You can set the size of these by using the --heap_size or --stack_size option and specifying the size of the section as a 4-byte constant immediately after the option. If the options are not used, the default size of the heap is 2K bytes and the default size of the stack is 2K bytes.

See Section 8.4.16 for setting heap sizes andSection 8.4.31 for setting stack sizes.

8.11.4 Initializing and AutoInitialzing Variables at Run Time

Autoinitializing variables at run time is the default method of autoinitialization. To use this method, invoke the linker with the --rom_model option. See Section 3.3.2.1 for details.

Initialization of variables at load time enhances performance by reducing boot time and by saving the memory used by the initialization tables. To use this method, invoke the linker with the --ram_model option. See Section 3.3.2.2 for details.

See Section 3.3.2.3 for information about the steps that are performed when you invoke the linker with the --ram_model or --rom_model option.

8.11.5 Initialization of Cinit and Watchdog Timer Hold

You can use the --cinit_hold_wdt option on some devices to specify whether the watchdog timer should be held (on) or not held (off) during cinit auto-initialization. Setting this option causes an RTS auto-initialization routine to be linked in with the program to handle the desired watchdog timer behavior.

This example links three object files named demo.obj, ctrl.obj, and tables.obj and creates a program called demo.out.

Assume that target memory has the following program memory configuration:

0x00000000 to 0x00001000 SLOW_MEM
0x00001000 to 0x00002000 FAST_MEM
0x08000000 to 0x08000400 EEPROM

The output sections are constructed in the following manner:

• Executable code, contained in the .text sections of demo.obj, fft.obj, and tables.obj, is linked into program memory ROM.
• Variables, contained in the var_defs section of demo.obj, are linked into data memory in block FAST_MEM_2.
• Tables of coefficients in the .data sections of demo.obj, tables.obj, and fft.obj are linked into FAST_MEM_1. A hole is created with a length of 100 and a fill value of 0x07A1C.
• The xy section form demo.obj, which contains buffers and variables, is linked by default into page 1 of the block STACK, since it is not explicitly linked.
• Executable code, contained in the .text sections of demo.obj, ctrl.obj, and tables.obj, must be linked into FAST_MEM.
• A set of interrupt vectors, contained in the .intvecs section of tables.obj, must be linked at address FAST_MEM.
• A table of coefficients, contained in the .data section of tables.obj, must be linked into EEPROM. The remainder of block FLASH must be initialized to the value 0xFF00FF00.
• A set of variables, contained in the .bss section of ctrl.obj, must be linked into SLOW_MEM and preinitialized to 0x00000100.
• The .bss sections of demo.obj and tables.obj must be linked into SLOW_MEM.

shows the linker command file for this example. Example 8-32 shows the map file.

Example 8-31 Linker Command File, demo.cmd

/*****************************************************************************/ /*** Specify Link Options ***/ /*****************************************************************************/ --entry_point SETUP /* Define the program entry point */ --output_file=demo.out /* Name the output file */ --map_file=demo.map /* Create an output map file */ /*****************************************************************************/ /*** Specify the Input Files ***/ /*****************************************************************************/ demo.obj ctrl.obj tables.obj /*****************************************************************************/ /*** Specify the Memory Configurations ***/ /*****************************************************************************/ MEMORY { FAST_MEM : org = 0x00000000 len = 0x00001000 /* PROGRAM MEMORY (ROM) */ SLOW_MEM : org = 0x00001000 len = 0x00001000 /* DATA MEMORY (RAM) */ EEPROM : org = 0x08000000 len = 0x00000400 /* COEFFICIENTS (EEPROM) */ } /*****************************************************************************/ /* Specify the Output Sections */ /*****************************************************************************/ SECTIONS { .text : {} > FAST_MEM /* Link all .text sections into ROM */ .intvecs : {} > 0x0 /* Link interrupt vectors at 0x0 */ .data : /* Link .data sections */ { tables.obj(.data) . = 0x400; /* Create hole at end of block */ } > EEPROM, fill = 0xFF00FF00 /* Fill and link into EEPROM */ ctrl_vars: /* Create new sections for ctrl variables */ { ctrl.obj(.bss) } > SLOW_MEM, fill = 0x00000100 /* Fill with 0x100 and link into RAM */ .bss : {} > SLOW_MEM /* Link remaining .bss sections into RAM */ } /*****************************************************************************/ /*** End of Command File ***/ /*****************************************************************************/

Invoke the linker by entering the following command:

 armcl --run_linker demo.cmd 

This creates the map file shown in Example 8-32 and an output file called demo.out that can be run on an ARM device.

Example 8-32 Output Map File, demo.map

OUTPUT FILE NAME: <demo.out>ENTRY POINT SYMBOL: "SETUP" address: 000000d4 MEMORY CONFIGURATION name origin length attributes fill -------- -------- --------- ---------- -------- FAST_MEM 00000000 000001000 RWIX SLOW_MEM 00001000 000001000 RWIX EEPROM 08000000 000000400 RWIX SECTION ALLOCATION MAP output attributes/ section page origin length input sections -------- ---- ---------- ---------- ---------------- .text 0 00000020 00000138 00000020 000000a0 ctrl.obj (.text) 000000c0 00000000 tables.obj (.text) 000000c0 00000098 demo.obj (.text) .intvecs 0 00000000 00000020 00000000 00000020 tables.obj (.intvecs) .data 0 08000000 00000400 08000000 00000168 tables.obj (.data) 08000168 00000298 --HOLE-- [fill = ff00ff00] 08000400 00000000 ctrl.obj (.data) 08000400 00000000 demo.obj (.data) ctrl_var 0 00001000 00000500 00001000 00000500 ctrl.obj (.bss) [fill = 00000100] .bss 0 00001500 00000100 UNINITIALIZED 00001500 00000100 demo.obj (.bss) 00001600 00000000 tables.obj (.bss) GLOBAL SYMBOLS address name address name -------- ---- -------- ---- 00001500 .bss 00000020 clear 08000000 .data 00000020 .text 00000020 .text 000000b8 set 000000d4 SETUP 000000c0 x42 00000020 clear 000000d4 SETUP 08000400 edata 00000158 etext 00001600 end 00001500 .bss 00000158 etext 00001600 end 000000b8 set 08000000 .data 000000c0 x42 08000400 edata [10 symbols] 
Submit Documentation Feedback

Copyright© 2016, Texas Instruments Incorporated. An IMPORTANT NOTICE for this document addresses availability, warranty, changes, use in safety-critical applications, intellectual property matters and other important disclaimers.