6 Accessing and Managing Symbols with armlink

6.4 Image$$ execution region symbols

The linker generates Image$$ symbols for every execution region present in the image.

The following table shows the symbols that the linker generates for every execution region present in the image. All the symbols refer to execution addresses after the C library is initialized.

Table 6-1 Image$$ execution region symbols

Symbol	Description
Image$$region_name$$Base	Execution address of the region.
Image$$region_name$$Length	Execution region length in bytes excluding ZI length.
Image$$region_name$$Limit	Address of the byte beyond the end of the non-ZI part of the execution region.
Image$$region_name$$RO$$Base	Execution address of the RO output section in this region.
Image$$region_name$$RO$$Length	Length of the RO output section in bytes.
Image$$region_name$$RO$$Limit	Address of the byte beyond the end of the RO output section in the execution region.
Image$$region_name$$RW$$Base	Execution address of the RW output section in this region.
Image$$region_name$$RW$$Length	Length of the RW output section in bytes.
Image$$region_name$$RW$$Limit	Address of the byte beyond the end of the RW output section in the execution region.
Image$$region_name$$XO$$Base	Execution address of the XO output section in this region.
Image$$region_name$$XO$$Length	Length of the XO output section in bytes.
Image$$region_name$$XO$$Limit	Address of the byte beyond the end of the XO output section in the execution region.
Image$$region_name$$ZI$$Base	Execution address of the ZI output section in this region.
Image$$region_name$$ZI$$Length	Length of the ZI output section in bytes.
Image$$region_name$$ZI$$Limit	Address of the byte beyond the end of the ZI output section in the execution region.

6.5 Load$$ execution region symbols

The linker generates Load$$ symbols for every execution region present in the image.

Note

Load$$region_name symbols apply only to execution regions. Load$$LR$$load_region_name symbols apply only to load regions.

The following table shows the symbols that the linker generates for every Load$$ execution region present in the image. All the symbols refer to load addresses after the C library is initialized.

Table 6-2 Load$$ execution region symbols

Symbol	Description
Load$$region_name$$Base	Load address of the region.
Load$$region_name$$Length	Region length in bytes.
Load$$region_name$$Limit	Address of the byte beyond the end of the execution region.
Load$$region_name$$RO$$Base	Address of the RO output section in this execution region.
Load$$region_name$$RO$$Length	Length of the RO output section in bytes.
Load$$region_name$$RO$$Limit	Address of the byte beyond the end of the RO output section in the execution region.
Load$$region_name$$RW$$Base	Address of the RW output section in this execution region.
Load$$region_name$$RW$$Length	Length of the RW output section in bytes.
Load$$region_name$$RW$$Limit	Address of the byte beyond the end of the RW output section in the execution region.
Load$$region_name$$XO$$Base	Address of the XO output section in this execution region.
Load$$region_name$$XO$$Length	Length of the XO output section in bytes.
Load$$region_name$$XO$$Limit	Address of the byte beyond the end of the XO output section in the execution region.
Load$$region_name$$ZI$$Base	Load address of the ZI output section in this execution region.
Load$$region_name$$ZI$$Length	Load length of the ZI output section in bytes. The Load Length of ZI is zero unless region_name has the ZEROPAD scatter-loading keyword set. If ZEROPAD is set then: Load Length = Image$$region_name$$ZI$$Length
Load$$region_name$$ZI$$Limit	Load address of the byte beyond the end of the ZI output section in the execution region.

All symbols in this table refer to load addresses before the C library is initialized. Be aware of the following:

• The symbols are absolute because section-relative symbols can only have execution addresses.
• The symbols take into account RW compression.
• References to linker-defined symbols from RW compressed execution regions must be to symbols that are resolvable before RW compression is applied.
• If the linker detects a relocation from an RW-compressed region to a linker-defined symbol that depends on RW compression, then the linker disables compression for that region.
• Any Zero Initialized data that is written to the file is taken into account by the Limit and Length values. Zero Initialized data is written into the file when the ZEROPAD scatter-loading keyword is used.

6.6 Load$$LR$$ load region symbols

The linker generates Load$$LR$$ symbols for every load region present in the image.

A Load$$LR$$ load region can contain many execution regions, so there are no separate $$RO and $$RW components.

Note

Load$$LR$$load_region_name symbols apply only to load regions. Load$$region_name symbols apply only to execution regions.

The following table shows the symbols that the linker generates for every Load$$LR$$ load region present in the image.

Table 6-3 Load$$LR$$ load region symbols

Symbol	Description
Load$$LR$$load_region_name$$Base	Address of the load region.
Load$$LR$$load_region_name$$Length	Length of the load region.
Load$$LR$$load_region_name$$Limit	Address of the byte beyond the end of the load region.

6.7 Region name values when not scatter-loading

When scatter-loading is not used when linking, the linker uses default region name values.

If you are not using scatter-loading, the linker uses region name values of:

• ER_XO, for an execute-only execution region, if present.
• ER_RO, for the read-only execution region.
• ER_RW, for the read-write execution region.
• ER_ZI, for the zero-initialized execution region.

You can insert these names into the following symbols to obtain the required address:

• Image$$ execution region symbols.
• Load$$ execution region symbols.

For example, Load$$ER_RO$$Base.

Note

• The ZI output sections of an image are not created statically, but are automatically created dynamically at runtime. Therefore, there is no load address symbol for ZI output sections.
• It is recommended that you use region-related symbols in preference to section-related symbols.

6.9 Methods of importing linker-defined symbols in C and C++

You can import linker-defined symbols into your C or C++ source code either by value or by reference.

Import by value

extern unsigned int symbol_name;

Import by reference

extern void *symbol_name;

If you declare a symbol as an int, then you must use the address-of operator (&) to obtain the correct value as shown in these examples:

Importing a linker-defined symbol

extern unsigned int Image$$ZI$$Limit;
config.heap_base = (unsigned int) &Image$$ZI$$Limit;

Importing symbols that define a ZI output section

extern unsigned int Image$$ZI$$Length;
extern char Image$$ZI$$Base[];
memset(Image$$ZI$$Base,,(unsigned int)&Image$$Length);

6.11 Section-related symbols

Section-related symbols are symbols generated by the linker when it creates an image without scatter-loading.

The linker generates the following types of section-related symbols:

• Image symbols, if you do not use scatter-loading to create a simple image. A simple image has up to four output sections (XO, RO, RW, and ZI) that produce the corresponding execution regions.
• Input section symbols, for every input section present in the image.

The linker sorts sections within an execution region first by attribute RO, RW, or ZI, then by name. So, for example, all .text sections are placed in one contiguous block. A contiguous block of sections with the same attribute and name is known as a consolidated section.

6.21 Steering file command summary

A summary of the commands you can use in a streering file.

The steering file commands are:

Table 6-6 Steering file command summary

Command	Description
EXPORT	Specifies that a symbol can be accessed by other shared objects or executables.
HIDE	Makes defined global symbols in the symbol table anonymous.
IMPORT	Specifies that a symbol is defined in a shared object at runtime.
RENAME	Renames defined and undefined global symbol names.
REQUIRE	Creates a DT_NEEDED tag in the dynamic array. DT_NEEDED tags specify dependencies to other shared objects used by the application, for example, a shared library.
RESOLVE	Matches specific undefined references to a defined global symbol.
SHOW	Makes global symbols visible. This command is useful if you want to make a specific symbol visible that is hidden using a HIDE command with a wildcard.

Note

The steering file commands control only global symbols. Local symbols are not affected by any of these commands.