10.4.1. Basic Options¶

The options listed in the subsections below control basic linker behavior. 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.

Option Summary
Name an Output Module (--output_file Option)
Create a Map File (--map_file Option)
Define Stack Size (--stack_size Option)
Define Heap Size (--heap_size Option)

10.4.1.1. Option Summary ¶

--output_file (-o)¶: Names the executable output module. The default filename is a.out. See Name an Output Module (--output_file Option).

--map_file (-m)¶: Produces a map or listing of the input and output sections, including holes, and places the listing in filename. See Create a Map File (--map_file Option).

--stack_size (-stack)¶: Sets C system stack size to size bytes and defines a global symbol that specifies the stack size. Default = 2K bytes. See Define Stack Size (--stack_size Option).

--heap_size (-heap)¶: Sets heap size (for the dynamic memory allocation in C) to size bytes and defines a global symbol that specifies the heap size. Default = 2K bytes. See Define Heap Size (--heap_size Option).

10.4.1.2. 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.c.o and file2.c.o and creates an output module named run.out:

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

10.4.1.3. Create a Map File (--map_file Option)¶

The syntax for the --map_file option is:

--map_file=filename

The linker map describes:

Memory configuration
Input and output section allocation
Linker-generated copy tables
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 non-default memory is specified (memory configuration). This information is generated on the basis of the information in the MEMORY directive in the linker command file. For more about the MEMORY directive, see The MEMORY Directive. The table has the following columns;
- 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 information is generated on the basis of the information in the SECTIONS directive in the linker command file. For more about the SECTIONS directive, see The SECTIONS Directive. This table has the following columns:
- 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.c.o and file2.c.o and creates a map file called map.out:

tiarmclang file1.c.o file2.c.o -Wl,--map_file=a.map

Linker Example shows an example of a map file.

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

tiarmclang -Wl,--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 Using Linker Symbols in C/C++ Applications for information about referring to linker symbols in C/C++ code.

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

tiarmclang -Wl,--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 Using Linker Symbols in C/C++ Applications for information about referring to linker symbols in C/C++ code.