10.4.5. Linker Output Options

The options listed in the subsections below control how the linker generates output. On the tiarmclang command-line they should be passed to the linker using the -Wl or -Xlinker option as described in Passing Options to the Linker.

10.4.5.1. Option Summary

--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. See Producing an Absolute Output Module (--absolute_exe option).

--ecc={ on \| off }

Enable linker-generated Error Correcting Codes (ECC). The default is off. See Error Correcting Code Testing (--ecc Options) and Configuring Error Correcting Code (ECC) with the Linker.

--ecc:data_error

Inject the specified errors into the output file for testing. See Error Correcting Code Testing (--ecc Options) and Configuring Error Correcting Code (ECC) with the Linker.

--ecc:ecc_error

Inject the specified errors into the Error Correcting Code (ECC) for testing. See Error Correcting Code Testing (--ecc Options) and Configuring Error Correcting Code (ECC) with the Linker.

--mapfile_contents

Controls the information that appears in the map file. See Managing Map File Contents (--mapfile_contents Option).

--relocatable (-r)

Produces a nonexecutable, relocatable output module. See Producing a Relocatable Output Module (--relocatable option).

Generates a well-formed XML file containing detailed information about the result of a link. See Generate XML Link Information File (--xml_link_info Option).

--gen_xml_func_hash

When the –gen_xml_func_hash linker option is combined with the –xml_link_info linker option, the linker will include a function hash table in the –xml_link_info output. See Generate XML Function Hash Table (--gen_xml_func_hash).

10.4.5.2. 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 (Symbolic Relocations).

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).

10.4.5.2.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:

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

tiarmclang -Wl,--absolute_exe file1.c.o file2.c.o

Note

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

10.4.5.2.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.c.o and file2.c.o and creates a relocatable output module called a.out:

tiarmclang -Wl,--relocatable file1.c.o file2.c.o

The output file a.out can be relinked with other object files or relocated at load time. (Linking a file that will be relinked with other files is called partial linking. For more information, see Partial (Incremental) Linking.)

10.4.5.2.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.c.o and file2.c.o to create an executable, relocatable output module called xr.out:

tiarmclang -Wl,-ar,--output_file=xr.out file1.c.o file2.c.o

10.4.5.3. Error Correcting Code Testing (--ecc Options)

Error Correcting Codes (ECC) can be generated and placed in separate sections through the linker command file.

To enable ECC support, include --ecc=on as a linker option on the command line. By default ECC generation is off, even if the ECC directive and ECC specifiers are used in the linker command file. This allows you to fully configure ECC in the linker command file while still being able to quickly turn the code generation on and off via the command line. See Configuring Error Correcting Code (ECC) with the Linker for details on linker command file syntax to configure ECC support.

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.)

After enabling ECC with the --ecc=on option, you can use the following command-line options to test ECC by injecting 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 tests 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:

tiarmclang test.c -Xlinker --ecc:data_error=0x100,0x01 -Xlinker -o=test.out

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

tiarmclang test.c -Xlinker --ecc:data_error=main+2,0x42 -Xlinker -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:

tiarmclang test.c -Xlinker --ecc:ecc_error=0x200,0xff -Xlinker -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.

10.4.5.4. 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

load_addr

Display load addresses

Off

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

sym_runaddr

Symbols sorted by run address

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.

The load_addr and sym_defs attributes are both disabled by default.

If you turn on the load_addr filter, the map file includes the load address of symbols that are included in the symbol list in addition to the run address (if the load address is different from the run address).

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.

10.4.5.6. Generate XML Function Hash Table (--gen_xml_func_hash)

In the Sitara OpTI-Flash multicore context, the ability to identify common functions across multiple executables is desired in order to allow users to abstract these functions out and place them in shared memory in order reduce individual executable size. This is also known as “OpTI-SHARE”. In order to identify common functions in a meaningful way (where function name and size are not enough), the tiarmclang version 3.0.0.STS linker can now generate an MD5 hash based on the function’s raw data prior to relocation and emit it within a table of function symbols in the linker-generated XML link info file.

The linker will also generate a list of referenced data sections from each global function uniquely identified by their object component IDs. Common read-only data sections can also be allocated in shared memory. However, writes to read-write data sections from common code must be managed through hardware address translation available on the device (aka “RAT”). These referenced data section lists can also be used in conjunction with “Smart Placement” where fast data access from frequently executed functions is desired.

When linking an application, the aforementioned table and referenced section lists will be generated when the -–xml_link_info option is used in conjunction with --gen_xml_func_hash. The –-xml_link_info option can be given a specified file name to use for the output.

The generated table is designated by a func_symbol_table XML tag, with each global function represented by a symbol tag. The associated MD5 hash is indicated by a value tag and the referenced data section lists indicated in refd_ro_sections and refd_rw_sections tags for read-only (constant) data and read-write data, respectively. For example:

<func_symbol_table>
  <symbol>
    <name>func0</name>
    <sectname>.text.main</sectname>
    <value>b6e5b51736000aef4da6e8afb91846e4</value>
  </symbol>
  <symbol>
    <name>func1</name>
    <sectname>.text.foo</sectname>
    <value>b1b9d95dd364df1b53f4e8c571ddaf68</value>
  </symbol>
  <symbol>
    <name>func2</name>
    <refd_ro_sections>
      <object_component_ref idref="oc-92"/>
      <object_component_ref idref="oc-99"/>
    </refd_ro_sections>
    <refd_rw_sections>
      <object_component_ref idref="oc-94"/>
      <object_component_ref idref="oc-96"/>
      <object_component_ref idref="oc-97"/>
      <object_component_ref idref="oc-98"/>
    </refd_rw_sections>
  </symbol>
</func_symbol_table>