10.13. XML Link Information File Description¶

The linker supports the generation of an XML link information file via 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 in this file includes all of the information that is produced in a linker-generated map file.

See Generate XML Link Information File (--xml_link_info Option) for information about using the --xml_link_info option.

10.13.1. XML Information File Element Types¶

These types of elements are generated by the linker:

Container elements represent an object that contains other elements that describe the object. Container elements have an id attribute that makes them accessible from other elements.
String elements contain a string representation of their value.
Constant elements contain a 64-bit unsigned long representation of their value (with a 0x prefix).
Reference elements are empty elements that contain an idref attribute that specifies a link to another container element.

10.13.2. Document Elements¶

The root element, also called the document element, is <link_info>. All other elements contained in the XML link information file are children of the <link_info> element.

The following sections describe the elements that an XML information file can contain. In the following sections, the data type of each element value is specified in parentheses following the element description. For example: The <address> is the entry point address (constant).

10.13.2.1. Header Elements¶

Within the <link_info> element, the first elements in the XML link information file provide general information about the linker and the link session:

The <banner> element lists the name of the executable and the version information (string).
The <copyright> element lists the TI copyright information (string).
The <link_time> is a timestamp representation of the link time (unsigned 32-bit int).
The <output_file> element lists the absolute path and name of the linked output file generated (string).
The <entry_point> element specifies the program entry point, as determined by the linker (container) with two entries:
- The <name> is the entry point symbol name, if any (string).
- The <address> is the entry point address (constant).

Example Header Elements in the hi.out Output File

<banner>Linker Version x.xx (Mar 15 2024)</banner>
<copyright>Copyright (c) 1996-2024 Texas Instruments Incorporated</copyright>
<link_time>0x65f8a4ec</link_time>
<output_file>/usr/mycode/hi.out</output_file>
<entry_point>
    <name>_c_int00</name>
    <address>0xaf80</address>
</entry_point>

10.13.2.2. Input File List¶

After the header elements, the next section in the XML link information file is the input file list, which is delimited with an <input_file_list> container element. The <input_file_list> can contain any number of <input_file> elements.

Each <input_file> instance specifies the input file involved in the link. Each <input_file> has an id attribute that can be referenced by other elements, such as an <object_component>. An <input_file> is a container element enclosing the following elements:

The <path> element names an absolute directory path, if applicable (string).
The <kind> element specifies a file type, either archive or object (string).
The <file> element specifies an archive name or filename (string).
The <name> element specifies an object file name, or archive member name (string).

Input File List for the hi.out Output File

<input_file_list>
    <input_file id="fl-1">
        <kind>object</kind>
        <file>hi.obj</file>
        <name>hi.obj</name>
    </input_file>
    <input_file id="fl-2">
        <path>/usr/tools/lib/</path>
        <kind>archive</kind>
        <file>rtsxxx.lib</file>
        <name>boot.obj</name>
    </input_file>
    <input_file id="fl-3">
        <path>/usr/tools/lib/</path>
        <kind>archive</kind>
        <file>rtsxxx.lib</file>
        <name>exit.obj</name>
    </input_file>
    <input_file id="fl-4">
        <path>/usr/tools/lib/</path>
        <kind>archive</kind>
        <file>rtsxxx.lib</file>
        <name>printf.obj</name>
    </input_file>
    ...
</input_file_list>

10.13.2.3. Object Component List¶

The next section of the XML link information file contains a specification of all of the object components that are involved in the link. An example of an object component is an input section. In general, an object component is the smallest piece of object that can be manipulated by the linker.

The <object_component_list> is a container element enclosing any number of <object_component> elements.

Each <object_component> specifies a single object component. Each <object_component> has an id attribute so that it can be referenced directly from other elements, such as a <logical_group>. An <object_component> is a container element enclosing the following elements:

The <name> element names the object component (string).
The <load_address> element specifies the load-time address of the object component (constant).
The <run_address> element specifies the run-time address of the object component (constant).
The <alignment> element specifies the alignment of the object component (unsigned int).
The <size> element specifies the size of the object component (constant).
The <executable> element specifies whether the object component allows execute access (string). If an object has executable access, it cannot also have read-write access. While “false” is a valid value, the linker emits this element only if it is “true” for this object component.
The <readonly> element specifies whether the object component allows read-only access (string). If an object has read-only access, it cannot also have read-write access. While “false” is a valid value, the linker emits this element only if it is “true” for this object component.
The <readwrite> element specifies whether the object component allows read-write access (string). If an object has read-write access, it cannot also have read-only access or executable access. While “false” is a valid value, the linker emits this element only if it is “true” for this object component.
The <uninitialized> element specifies whether the object component is initialized (string). While “false” is a valid value, the linker emits this element only if it is “true” for this object component.
The <input_file_ref> element specifies the source file where the object component originated (reference).

Object Component List for the fl-4 Input File

<object_component id="oc-20">
    <name>.text</name>
    <load_address>0xac00</load_address>
    <run_address>0xac00</run_address>
    <alignment>0x1</alignment>
    <size>0xc0</size>
    <readonly>true</readonly>
    <executable>false</executable>
    <input_file_ref idref="fl-4"/>
</object_component>
<object_component id="oc-21">
    <name>.data</name>
    <load_address>0x80000000</load_address>
    <run_address>0x80000000</run_address>
    <alignment>0x1</alignment>
    <size>0x0</size>
    <readwrite>true</readwrite>
    <input_file_ref idref="fl-4"/>
</object_component>
<object_component id="oc-22">
    <name>.bss</name>
    <load_address>0x80000000</load_address>
    <run_address>0x80000000</run_address>
    <alignment>0x1</alignment>
    <size>0x0</size>
    <readwrite>true</readwrite>
    <uninitialized>true</uninitialized>
    <input_file_ref idref="fl-4"/>
</object_component>

10.13.2.4. Logical Group List¶

The <logical_group_list> section of the XML link information file is similar to the output section listing in a linker-generated map file. However, the XML link information file contains a specification of GROUP and UNION output sections, which are not represented in a map file. There are several kinds of list items that can occur in a <logical_group_list>:

The <logical_group> is the specification of a section or GROUP that contains a list of object components or logical group members. Each <logical_group> element is given an id so that it may be referenced from other elements. Each <logical_group> is a container element enclosing the following elements:
- The <name> element names the logical group (string).
- The <load_address> element specifies the load-time address of the logical group (constant).
- The <run_address> element specifies the run-time address of the logical group (constant).
- The <size> element specifies the size of the logical group (constant).
- The <output_section_group> specifies whether the logical group is a GROUP of output sections (string). While “false” is a valid value, the linker emits this element only if it is “true” for this logical group.
- The <contents> element lists elements contained in this logical group (container). These elements refer to each of the member objects contained in this logical group:
  - The <object_component_ref> is an object component that is contained in this logical group (reference).
  - The <logical_group_ref> is a logical group that is contained in this logical group (reference).
The <overlay> is a special kind of logical group that represents a UNION, or a set of objects that share the same memory space (container). Each <overlay> element is given an id so that it may be referenced from other elements (like from an <allocated_space> element in the placement map). Each <overlay> contains the following elements:
- The <name> element names the overlay (string).
- The <run_address> element specifies the run-time address of overlay (constant).
- The <size> element specifies the size of logical group (constant).
- The <contents> container element lists elements contained in this overlay. These elements refer to each of the member objects contained in this logical group:
  - The <object_component_ref> is an object component that is contained in this logical group (reference).
  - The <logical_group_ref> is a logical group that is contained in this logical group (reference).
The <split_section> is another special kind of logical group that represents a collection of logical groups that is split among multiple memory areas. Each <split_section> element is given an id so that it may be referenced from other elements. Each <<split_section> contains the following elements:
- The <name> element names the split section (string).
- The <contents> container element lists elements contained in this split section. The <logical_group_ref> elements refer to each of the member objects contained in this split section, and each element referenced is a logical group that is contained in this split section (reference).

Logical Group List for the fl-4 Input File

<logical_group_list>
...
<logical_group id="lg-7">
    <name>.text</name>
    <output_section_group>true</output_section_group>
    <load_address>0x20</load_address>
    <run_address>0x20</run_address>
    <size>0xb240</size>
    <contents>
        <object_component_ref idref="oc-34"/>
        <object_component_ref idref="oc-108"/>
        <object_component_ref idref="oc-e2"/>
        ...
    </contents>
</logical_group>
...
<overlay id="lg-b">
    <name>UNION_1</name>
    <run_address>0xb600</run_address>
    <size>0xc0</size>
    <contents>
        <object_component_ref idref="oc-45"/>
        <logical_group_ref idref="lg-8"/>
    </contents>
</overlay>
...
<split_section id="lg-12">
    <name>.task_scn</name>
    <size>0x120</size>
    <contents>
        <logical_group_ref idref="lg-10"/>
        <logical_group_ref idref="lg-11"/>
    </contents>
</split_section>
...
</logical_group_list>

10.13.2.5. Placement Map¶

The <placement_map> element describes the memory placement details of all named memory areas in the application, including unused spaces between logical groups that have been placed in a particular memory area.

The <memory_area> is a description of the placement details within a named memory area (container). The description consists of these items:

The <name> names the memory area (string).
The <page_id> gives the id of the memory page in which this memory area is defined (constant).
The <origin> specifies the beginning address of the memory area (constant).
The <length> specifies the length of the memory area (constant).
The <used_space> specifies the amount of allocated space in this area (constant).
The <unused_space> specifies the amount of available space in this area (constant).
The <attributes> lists the RWXI attributes that are associated with this area, if any (string).
The <fill_value> specifies the fill value that is to be placed in unused space, if the fill directive is specified with the memory area (constant).
The <usage_details> lists details of each allocated or available fragment in this memory area. If the fragment is allocated to a logical group, then a <logical_group_ref> element is provided to facilitate access to the details of that logical group. All fragment specifications include <start_address> and <size> elements.
- The <allocated_space> element provides details of an allocated fragment within this memory area (container):
  - The <start_address> specifies the address of the fragment (constant).
  - The <size> specifies the size of the fragment (constant).
  - The <logical_group_ref> provides a reference to the logical group that is allocated to this fragment (reference).
The <available_space> element provides details of an available fragment within this memory area (container):
- The <start_address> specifies the address of the fragment (constant).
- The <size> specifies the size of the fragment (constant).

Placement Map for the fl-4 Input File

<placement_map>
    <memory_area>
        <name>PMEM</name>
        <page_id>0x0</page_id>
        <origin>0x20</origin>
        <length>0x100000</length>
        <used_space>0xb240</used_space>
        <unused_space>0xf4dc0</unused_space>
        <attributes>RWXI</attributes>
        <usage_details>
            <allocated_space>
                <start_address>0x20</start_address>
                <size>0xb240</size>
                <logical_group_ref idref="lg-7"/>
            </allocated_space>
            <available_space>
                <start_address>0xb260</start_address>
                <size>0xf4dc0</size>
            </available_space>
        </usage_details>
    </memory_area>
    ...
</placement_map>

10.13.2.6. Far Call Trampoline List¶

The <far_call_trampoline_list> is a list of <far_call_trampoline> elements. The linker supports the generation of far call trampolines to help a call site reach a destination that is out of range. A far call trampoline function is guaranteed to reach the called function (callee) as it may utilize an indirect call to the called function.

The <far_call_trampoline_list> enumerates all of the far call trampolines that are generated by the linker for a particular link. The <far_call_trampoline_list> can contain any number of <far_call_trampoline> elements. Each <far_call_trampoline> is a container enclosing the following elements:

The <callee_name> element names the destination function (string).
The <callee_address> is the address of the called function (constant).
The <trampoline_object_component_ref> is a reference to an object component that contains the definition of the trampoline function (reference).
The <trampoline_address> is the address of the trampoline function (constant).
The <caller_list> enumerates all call sites that utilize this trampoline to reach the called function (container).
The <trampoline_call_site> provides the details of a trampoline call site (container) and consists of these items:
- The <caller_address> specifies the call site address (constant).
- The <caller_object_component_ref> is the object component where the call site resides (reference).

Fall Call Trampoline List for the fl-4 Input File

<far_call_trampoline_list>
    ...
    <far_call_trampoline>
        <callee_name>_foo</callee_name>
        <callee_address>0x08000030</callee_address>
        <trampoline_object_component_ref idref="oc-123"/>
        <trampoline_address>0x2020</trampoline_address>
        <caller_list>
            <call_site>
                <caller_address>0x1800</caller_address>
                <caller_object_component_ref idref="oc-23"/>
            </call_site>
            <call_site>
                <caller_address>0x1810</caller_address>
                <caller_object_component_ref idref="oc-23"/>
            </call_site>
        </caller_list>
    </far_call_trampoline>
    ...
</far_call_trampoline_list>

10.13.2.7. Symbol Table¶

The <symbol_table> contains a list of all of the global symbols that are included in the link. The list provides information about a symbol’s name and value. In the future, the symbol_table list may provide type information, the object component in which the symbol is defined, storage class, etc.

The <symbol> is a container element that specifies the name and value of a symbol with these elements:

The <name> element specifies the symbol name (string).
The <value> element specifies the symbol value (constant).
The <local> element specifies whether the symbol has local binding (string). While “false” is a valid value, the linker emits this element only if it is “true” for this symbol.

Symbol Table for the fl-4 Input File

<symbol_table>
    <symbol>
        <name>_c_int00</name>
        <value>0xaf80</value>
    </symbol>
    <symbol>
        <name>_main</name>
        <value>0xb1e0</value>
    </symbol>
    <symbol>
        <name>_printf</name>
        <value>0xac00</value>
        <local>true</local>
    </symbol>
    ...
</symbol_table>