[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.2 `scripttempl' scripts

Each linker target uses a `scripttempl' script to generate the default linker scripts. The name of the `scripttempl' script is set by the SCRIPT_NAME variable in the `emulparams' script. If SCRIPT_NAME is set to script, genscripts.sh will invoke `scripttempl/script.sc'.

The `genscripts.sh' script will invoke the `scripttempl' script 5 to 8 times. Each time it will set the shell variable LD_FLAG to a different value. When the linker is run, the options used will direct it to select a particular script. (Script selection is controlled by the get_script emulation entry point; this describes the conventional behaviour).

The `scripttempl' script should just write a linker script, written in the linker command language, to standard output. If the emulation name--the name of the `emulparams' file without the `.sc' extension--is emul, then the output will be directed to `ldscripts/emul.extension' in the build directory, where extension changes each time the `scripttempl' script is invoked.

Here is the list of values assigned to LD_FLAG.

(empty)
The script generated is used by default (when none of the following cases apply). The output has an extension of `.x'.
n
The script generated is used when the linker is invoked with the -n option. The output has an extension of `.xn'.
N
The script generated is used when the linker is invoked with the -N option. The output has an extension of `.xbn'.
r
The script generated is used when the linker is invoked with the -r option. The output has an extension of `.xr'.
u
The script generated is used when the linker is invoked with the -Ur option. The output has an extension of `.xu'.
shared
The `scripttempl' script is only invoked with LD_FLAG set to this value if GENERATE_SHLIB_SCRIPT is defined in the `emulparams' file. The `emultempl' script must arrange to use this script at the appropriate time, normally when the linker is invoked with the -shared option. The output has an extension of `.xs'.
c
The `scripttempl' script is only invoked with LD_FLAG set to this value if GENERATE_COMBRELOC_SCRIPT is defined in the `emulparams' file or if SCRIPT_NAME is elf. The `emultempl' script must arrange to use this script at the appropriate time, normally when the linker is invoked with the -z combreloc option. The output has an extension of `.xc'.
cshared
The `scripttempl' script is only invoked with LD_FLAG set to this value if GENERATE_COMBRELOC_SCRIPT is defined in the `emulparams' file or if SCRIPT_NAME is elf and GENERATE_SHLIB_SCRIPT is defined in the `emulparms' file. The `emultempl' script must arrange to use this script at the appropriate time, normally when the linker is invoked with the -shared -z combreloc option. The output has an extension of `.xsc'.

Besides the shell variables set by the `emulparams' script, and the LD_FLAG variable, the `genscripts.sh' script will set certain variables for each run of the `scripttempl' script.

RELOCATING
This will be set to a non-empty string when the linker is doing a final relocation (e.g., all scripts other than -r and -Ur).

CONSTRUCTING
This will be set to a non-empty string when the linker is building global constructor and destructor tables (e.g., all scripts other than -r).

DATA_ALIGNMENT
This will be set to an ALIGN expression when the output should be page aligned, or to `.' when generating the -N script.

CREATE_SHLIB
This will be set to a non-empty string when generating a -shared script.

COMBRELOC
This will be set to a non-empty string when generating -z combreloc scripts to a temporary file name which can be used during script generation.

The conventional way to write a `scripttempl' script is to first set a few shell variables, and then write out a linker script using cat with a here document. The linker script will use variable substitutions, based on the above variables and those set in the `emulparams' script, to control its behaviour.

When there are parts of the `scripttempl' script which should only be run when doing a final relocation, they should be enclosed within a variable substitution based on RELOCATING. For example, on many targets special symbols such as _end should be defined when doing a final link. Naturally, those symbols should not be defined when doing a relocatable link using -r. The `scripttempl' script could use a construct like this to define those symbols:
 
  ${RELOCATING+ _end = .;}
This will do the symbol assignment only if the RELOCATING variable is defined.

The basic job of the linker script is to put the sections in the correct order, and at the correct memory addresses. For some targets, the linker script may have to do some other operations.

For example, on most MIPS platforms, the linker is responsible for defining the special symbol _gp, used to initialize the $gp register. It must be set to the start of the small data section plus 0x8000. Naturally, it should only be defined when doing a final relocation. This will typically be done like this:
 
  ${RELOCATING+ _gp = ALIGN(16) + 0x8000;}
This line would appear just before the sections which compose the small data section (`.sdata', `.sbss'). All those sections would be contiguous in memory.

Many COFF systems build constructor tables in the linker script. The compiler will arrange to output the address of each global constructor in a `.ctor' section, and the address of each global destructor in a `.dtor' section (this is done by defining ASM_OUTPUT_CONSTRUCTOR and ASM_OUTPUT_DESTRUCTOR in the gcc configuration files). The gcc runtime support routines expect the constructor table to be named __CTOR_LIST__. They expect it to be a list of words, with the first word being the count of the number of entries. There should be a trailing zero word. (Actually, the count may be -1 if the trailing word is present, and the trailing word may be omitted if the count is correct, but, as the gcc behaviour has changed slightly over the years, it is safest to provide both). Here is a typical way that might be handled in a `scripttempl' file.
 
    ${CONSTRUCTING+ __CTOR_LIST__ = .;}
    ${CONSTRUCTING+ LONG((__CTOR_END__ - __CTOR_LIST__) / 4 - 2)}
    ${CONSTRUCTING+ *(.ctors)}
    ${CONSTRUCTING+ LONG(0)}
    ${CONSTRUCTING+ __CTOR_END__ = .;}
    ${CONSTRUCTING+ __DTOR_LIST__ = .;}
    ${CONSTRUCTING+ LONG((__DTOR_END__ - __DTOR_LIST__) / 4 - 2)}
    ${CONSTRUCTING+ *(.dtors)}
    ${CONSTRUCTING+ LONG(0)}
    ${CONSTRUCTING+ __DTOR_END__ = .;}
The use of CONSTRUCTING ensures that these linker script commands will only appear when the linker is supposed to be building the constructor and destructor tables. This example is written for a target which uses 4 byte pointers.

Embedded systems often need to set a stack address. This is normally best done by using the PROVIDE construct with a default stack address. This permits the user to easily override the stack address using the --defsym option. Here is an example:
 
  ${RELOCATING+ PROVIDE (__stack = 0x80000000);}
The value of the symbol __stack would then be used in the startup code to initialize the stack pointer.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

This document was generated by system on December, 2 2004 using texi2html