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

4. Machine Dependent Features

ld has additional features on some platforms; the following sections describe them. Machines where ld has no additional functionality are not listed.

4.1 ld and the H8/300  
4.2 ld and the Intel 960 Family  ld and the Intel 960 family
4.3 ld and the ARM family  
4.4 ld and HPPA 32-bit ELF Support  ld and HPPA 32-bit ELF
4.5 ld and MMIX  
4.6 ld and MSP430  
4.7 ld's Support for Various TI COFF Versions  ld and TI COFF
4.8 ld and WIN32 (cygwin/mingw)  
4.9 ld and Xtensa Processors  


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

4.1 ld and the H8/300

For the H8/300, ld can perform these global optimizations when you specify the `--relax' command-line option.

relaxing address modes
ld finds all jsr and jmp instructions whose targets are within eight bits, and turns them into eight-bit program-counter relative bsr and bra instructions, respectively.

synthesizing instructions
ld finds all mov.b instructions which use the sixteen-bit absolute address form, but refer to the top page of memory, and changes them to use the eight-bit address form. (That is: the linker turns `mov.b @aa:16' into `mov.b @aa:8' whenever the address aa is in the top page of memory).

bit manipulation instructions
ld finds all bit manipulation instructions like band, bclr, biand, bild, bior, bist, bixor, bld, bnot, bor, bset, bst, btst, bxor which use 32 bit and 16 bit absolute address form, but refer to the top page of memory, and changes them to use the 8 bit address form. (That is: the linker turns `bset #xx:3,@aa:32' into `bset #xx:3,@aa:8' whenever the address aa is in the top page of memory).

system control instructions
ld finds all ldc.w, stc.w instrcutions which use the 32 bit absolute address form, but refer to the top page of memory, and changes them to use 16 bit address form. (That is: the linker turns `ldc.w @aa:32,ccr' into `ldc.w @aa:16,ccr' whenever the address aa is in the top page of memory).


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

4.2 ld and the Intel 960 Family

You can use the `-Aarchitecture' command line option to specify one of the two-letter names identifying members of the 960 family; the option specifies the desired output target, and warns of any incompatible instructions in the input files. It also modifies the linker's search strategy for archive libraries, to support the use of libraries specific to each particular architecture, by including in the search loop names suffixed with the string identifying the architecture.

For example, if your ld command line included `-ACA' as well as `-ltry', the linker would look (in its built-in search paths, and in any paths you specify with `-L') for a library with the names

 
try
libtry.a
tryca
libtryca.a

The first two possibilities would be considered in any event; the last two are due to the use of `-ACA'.

You can meaningfully use `-A' more than once on a command line, since the 960 architecture family allows combination of target architectures; each use will add another pair of name variants to search for when `-l' specifies a library.

ld supports the `--relax' option for the i960 family. If you specify `--relax', ld finds all balx and calx instructions whose targets are within 24 bits, and turns them into 24-bit program-counter relative bal and cal instructions, respectively. ld also turns cal instructions into bal instructions when it determines that the target subroutine is a leaf routine (that is, the target subroutine does not itself call any subroutines).


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

4.3 ld and the ARM family

For the ARM, ld will generate code stubs to allow functions calls betweem ARM and Thumb code. These stubs only work with code that has been compiled and assembled with the `-mthumb-interwork' command line option. If it is necessary to link with old ARM object files or libraries, which have not been compiled with the -mthumb-interwork option then the `--support-old-code' command line switch should be given to the linker. This will make it generate larger stub functions which will work with non-interworking aware ARM code. Note, however, the linker does not support generating stubs for function calls to non-interworking aware Thumb code.

The `--thumb-entry' switch is a duplicate of the generic `--entry' switch, in that it sets the program's starting address. But it also sets the bottom bit of the address, so that it can be branched to using a BX instruction, and the program will start executing in Thumb mode straight away.

The `--be8' switch instructs ld to generate BE8 format executables. This option is only valid when linking big-endian objects. The resulting image will contain big-endian data and little-endian code.

The `R_ARM_TARGET1' relocation is typically used for entries in the `.init_array' section. It is interpreted as either `R_ARM_REL32' or `R_ARM_ABS32', depending on the target. The `--target1-rel' and `--target1-abs' switches override the default.

The `--target2=type' switch overrides the default definition of the `R_ARM_TARGET2' relocation. Valid values for `type', their meanings, and target defaults are as follows:

`rel'
`R_ARM_REL32' (arm*-*-elf, arm*-*-eabi)
`abs'
`R_ARM_ABS32' (arm*-*-symbianelf)
`got-rel'
`R_ARM_GOT_PREL' (arm*-*-linux, arm*-*-*bsd)


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

4.4 ld and HPPA 32-bit ELF Support

When generating a shared library, ld will by default generate import stubs suitable for use with a single sub-space application. The `--multi-subspace' switch causes ld to generate export stubs, and different (larger) import stubs suitable for use with multiple sub-spaces.

Long branch stubs and import/export stubs are placed by ld in stub sections located between groups of input sections. `--stub-group-size' specifies the maximum size of a group of input sections handled by one stub section. Since branch offsets are signed, a stub section may serve two groups of input sections, one group before the stub section, and one group after it. However, when using conditional branches that require stubs, it may be better (for branch prediction) that stub sections only serve one group of input sections. A negative value for `N' chooses this scheme, ensuring that branches to stubs always use a negative offset. Two special values of `N' are recognized, `1' and `-1'. These both instruct ld to automatically size input section groups for the branch types detected, with the same behaviour regarding stub placement as other positive or negative values of `N' respectively.

Note that `--stub-group-size' does not split input sections. A single input section larger than the group size specified will of course create a larger group (of one section). If input sections are too large, it may not be possible for a branch to reach its stub.


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

4.5 ld and MMIX

For MMIX, there is a choice of generating ELF object files or mmo object files when linking. The simulator mmix understands the mmo format. The binutils objcopy utility can translate between the two formats.

There is one special section, the `.MMIX.reg_contents' section. Contents in this section is assumed to correspond to that of global registers, and symbols referring to it are translated to special symbols, equal to registers. In a final link, the start address of the `.MMIX.reg_contents' section corresponds to the first allocated global register multiplied by 8. Register $255 is not included in this section; it is always set to the program entry, which is at the symbol Main for mmo files.

Symbols with the prefix __.MMIX.start., for example __.MMIX.start..text and __.MMIX.start..data are special; there must be only one each, even if they are local. The default linker script uses these to set the default start address of a section.

Initial and trailing multiples of zero-valued 32-bit words in a section, are left out from an mmo file.


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

4.6 ld and MSP430

For the MSP430 it is possible to select the MPU architecture. The flag `-m [mpu type]' will select an appropriate linker script for selected MPU type. (To get a list of known MPUs just pass `-m help' option to the linker).

The linker will recognize some extra sections which are MSP430 specific:

`.vectors'
Defines a portion of ROM where interrupt vectors located.

`.bootloader'
Defines the bootloader portion of the ROM (if applicable). Any code in this section will be uploaded to the MPU.

`.infomem'
Defines an information memory section (if applicable). Any code in this section will be uploaded to the MPU.

`.infomemnobits'
This is the same as the `.infomem' section except that any code in this section will not be uploaded to the MPU.

`.noinit'
Denotes a portion of RAM located above `.bss' section.

The last two sections are used by gcc.


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

4.7 ld's Support for Various TI COFF Versions

The `--format' switch allows selection of one of the various TI COFF versions. The latest of this writing is 2; versions 0 and 1 are also supported. The TI COFF versions also vary in header byte-order format; ld will read any version or byte order, but the output header format depends on the default specified by the specific target.


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

4.8 ld and WIN32 (cygwin/mingw)

This section describes some of the win32 specific ld issues. See Command Line Options for detailed decription of the command line options mentioned here.

import libraries
The standard Windows linker creates and uses so-called import libraries, which contains information for linking to dll's. They are regular static archives and are handled as any other static archive. The cygwin and mingw ports of ld have specific support for creating such libraries provided with the `--out-implib' command line option.

exporting DLL symbols
The cygwin/mingw ld has several ways to export symbols for dll's.

using auto-export functionality
By default ld exports symbols with the auto-export functionality, which is controlled by the following command line options:

  • --export-all-symbols [This is the default]
  • --exclude-symbols
  • --exclude-libs

If, however, `--export-all-symbols' is not given explicitly on the command line, then the default auto-export behavior will be disabled if either of the following are true:

  • A DEF file is used.
  • Any symbol in any object file was marked with the __declspec(dllexport) attribute.

using a DEF file
Another way of exporting symbols is using a DEF file. A DEF file is an ASCII file containing definitions of symbols which should be exported when a dll is created. Usually it is named `<dll name>.def' and is added as any other object file to the linker's command line. The file's name must end in `.def' or `.DEF'.

 
gcc -o <output> <objectfiles> <dll name>.def

Using a DEF file turns off the normal auto-export behavior, unless the `--export-all-symbols' option is also used.

Here is an example of a DEF file for a shared library called `xyz.dll':

 
LIBRARY "xyz.dll" BASE=0x10000000

EXPORTS
foo
bar
_bar = bar

This example defines a base address and three symbols. The third symbol is an alias for the second. For the complete format specification see ld/deffilep.y in the binutils sources.

While linking a shared dll, ld is able to create a DEF file with the `--output-def <file>' command line option.

Using decorations
Another way of marking symbols for export is to modify the source code itself, so that when building the DLL each symbol to be exported is declared as:

 
__declspec(dllexport) int a_variable
__declspec(dllexport) void a_function(int with_args)

All such symbols will be exported from the DLL. If, however, any of the object files in the DLL contain symbols decorated in this way, then the normal auto-export behavior is disabled, unless the `--export-all-symbols' option is also used.

Note that object files that wish to access these symbols must not decorate them with dllexport. Instead, they should use dllimport, instead:

 
__declspec(dllimport) int a_variable
__declspec(dllimport) void a_function(int with_args)

This complicates the structure of library header files, because when included by the library itself the header must declare the variables and functions as dllexport, but when included by client code the header must declare them as dllimport. There are a number of idioms that are typically used to do this; often client code can omit the __declspec() declaration completely. See `--enable-auto-import' and `automatic data imports' for more imformation.

automatic data imports
The standard Windows dll format supports data imports from dlls only by adding special decorations (dllimport/dllexport), which let the compiler produce specific assembler instructions to deal with this issue. This increases the effort necessary to port existing Un*x code to these platforms, especially for large c++ libraries and applications. The auto-import feature, which was initially provided by Paul Sokolovsky, allows one to omit the decorations to archieve a behavior that conforms to that on POSIX/Un*x platforms. This feature is enabled with the `--enable-auto-import' command-line option, although it is enabled by default on cygwin/mingw. The `--enable-auto-import' option itself now serves mainly to suppress any warnings that are ordinarily emitted when linked objects trigger the feature's use.

auto-import of variables does not always work flawlessly without additional assistance. Sometimes, you will see this message

"variable '<var>' can't be auto-imported. Please read the documentation for ld's --enable-auto-import for details."

The `--enable-auto-import' documentation explains why this error occurs, and several methods that can be used to overcome this difficulty. One of these methods is the runtime pseudo-relocs feature, described below.

For complex variables imported from DLLs (such as structs or classes), object files typically contain a base address for the variable and an offset (addend) within the variable--to specify a particular field or public member, for instance. Unfortunately, the runtime loader used in win32 environments is incapable of fixing these references at runtime without the additional information supplied by dllimport/dllexport decorations. The standard auto-import feature described above is unable to resolve these references.

The `--enable-runtime-pseudo-relocs' switch allows these references to be resolved without error, while leaving the task of adjusting the references themselves (with their non-zero addends) to specialized code provided by the runtime environment. Recent versions of the cygwin and mingw environments and compilers provide this runtime support; older versions do not. However, the support is only necessary on the developer's platform; the compiled result will run without error on an older system.

`--enable-runtime-pseudo-relocs' is not the default; it must be explicitly enabled as needed.

direct linking to a dll
The cygwin/mingw ports of ld support the direct linking, including data symbols, to a dll without the usage of any import libraries. This is much faster and uses much less memory than does the traditional import library method, expecially when linking large libraries or applications. When ld creates an import lib, each function or variable exported from the dll is stored in its own bfd, even though a single bfd could contain many exports. The overhead involved in storing, loading, and processing so many bfd's is quite large, and explains the tremendous time, memory, and storage needed to link against particularly large or complex libraries when using import libs.

Linking directly to a dll uses no extra command-line switches other than `-L' and `-l', because ld already searches for a number of names to match each library. All that is needed from the developer's perspective is an understanding of this search, in order to force ld to select the dll instead of an import library.

For instance, when ld is called with the argument `-lxxx' it will attempt to find, in the first directory of its search path,

 
libxxx.dll.a 
xxx.dll.a 
libxxx.a 
cygxxx.dll (*)
libxxx.dll 
xxx.dll 

before moving on to the next directory in the search path.

(*) Actually, this is not `cygxxx.dll' but in fact is `<prefix>xxx.dll', where `<prefix>' is set by the ld option `--dll-search-prefix=<prefix>'. In the case of cygwin, the standard gcc spec file includes `--dll-search-prefix=cyg', so in effect we actually search for `cygxxx.dll'.

Other win32-based unix environments, such as mingw or pw32, may use other `<prefix>'es, although at present only cygwin makes use of this feature. It was originally intended to help avoid name conflicts among dll's built for the various win32/un*x environments, so that (for example) two versions of a zlib dll could coexist on the same machine.

The generic cygwin/mingw path layout uses a `bin' directory for applications and dll's and a `lib' directory for the import libraries (using cygwin nomenclature):

 
bin/
	cygxxx.dll
lib/
	libxxx.dll.a   (in case of dll's)
	libxxx.a       (in case of static archive) 

Linking directly to a dll without using the import library can be done two ways:

1. Use the dll directly by adding the `bin' path to the link line

 
gcc -Wl,-verbose  -o a.exe -L../bin/ -lxxx

However, as the dll's often have version numbers appended to their names (`cygncurses-5.dll') this will often fail, unless one specifies `-L../bin -lncurses-5' to include the version. Import libs are generally not versioned, and do not have this difficulty.

2. Create a symbolic link from the dll to a file in the `lib' directory according to the above mentioned search pattern. This should be used to avoid unwanted changes in the tools needed for making the app/dll.

 
ln -s bin/cygxxx.dll lib/[cyg|lib|]xxx.dll[.a]

Then you can link without any make environment changes.

 
gcc -Wl,-verbose  -o a.exe -L../lib/ -lxxx

This technique also avoids the version number problems, because the following is perfectly legal

 
bin/
	cygxxx-5.dll
lib/
	libxxx.dll.a -> ../bin/cygxxx-5.dll 

Linking directly to a dll without using an import lib will work even when auto-import features are exercised, and even when `--enable-runtime-pseudo-relocs' is used.

Given the improvements in speed and memory usage, one might justifiably wonder why import libraries are used at all. There are two reasons:

1. Until recently, the link-directly-to-dll functionality did not work with auto-imported data.

2. Sometimes it is necessary to include pure static objects within the import library (which otherwise contains only bfd's for indirection symbols that point to the exports of a dll). Again, the import lib for the cygwin kernel makes use of this ability, and it is not possible to do this without an import lib.

So, import libs are not going away. But the ability to replace true import libs with a simple symbolic link to (or a copy of) a dll, in most cases, is a useful addition to the suite of tools binutils makes available to the win32 developer. Given the massive improvements in memory requirements during linking, storage requirements, and linking speed, we expect that many developers will soon begin to use this feature whenever possible.

symbol aliasing
adding additional names
Sometimes, it is useful to export symbols with additional names. A symbol `foo' will be exported as `foo', but it can also be exported as `_foo' by using special directives in the DEF file when creating the dll. This will affect also the optional created import library. Consider the following DEF file:

 
LIBRARY "xyz.dll" BASE=0x61000000

EXPORTS
foo 
_foo = foo

The line `_foo = foo' maps the symbol `foo' to `_foo'.

Another method for creating a symbol alias is to create it in the source code using the "weak" attribute:

 
void foo () { /* Do something.  */; } 
void _foo () __attribute__ ((weak, alias ("foo")));

See the gcc manual for more information about attributes and weak symbols.

renaming symbols
Sometimes it is useful to rename exports. For instance, the cygwin kernel does this regularly. A symbol `_foo' can be exported as `foo' but not as `_foo' by using special directives in the DEF file. (This will also affect the import library, if it is created). In the following example:

 
LIBRARY "xyz.dll" BASE=0x61000000

EXPORTS
_foo = foo

The line `_foo = foo' maps the exported symbol `foo' to `_foo'.

Note: using a DEF file disables the default auto-export behavior, unless the `--export-all-symbols' command line option is used. If, however, you are trying to rename symbols, then you should list all desired exports in the DEF file, including the symbols that are not being renamed, and do not use the `--export-all-symbols' option. If you list only the renamed symbols in the DEF file, and use `--export-all-symbols' to handle the other symbols, then the both the new names and the original names for the renamed symbols will be exported. In effect, you'd be aliasing those symbols, not renaming them, which is probably not what you wanted.

weak externals
The Windows object format, PE, specifies a form of weak symbols called weak externals. When a weak symbol is linked and the symbol is not defined, the weak symbol becomes an alias for some other symbol. There are three variants of weak externals: As a GNU extension, weak symbols that do not specify an alternate symbol are supported. If the symbol is undefined when linking, the symbol uses a default value.


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

4.9 ld and Xtensa Processors

The default ld behavior for Xtensa processors is to interpret SECTIONS commands so that lists of explicitly named sections in a specification with a wildcard file will be interleaved when necessary to keep literal pools within the range of PC-relative load offsets. For example, with the command:

 
SECTIONS
{
  .text : {
    *(.literal .text)
  }
}

ld may interleave some of the .literal and .text sections from different object files to ensure that the literal pools are within the range of PC-relative load offsets. A valid interleaving might place the .literal sections from an initial group of files followed by the .text sections of that group of files. Then, the .literal sections from the rest of the files and the .text sections from the rest of the files would follow.

Relaxation is enabled by default for the Xtensa version of ld and provides two important link-time optimizations. The first optimization is to combine identical literal values to reduce code size. A redundant literal will be removed and all the L32R instructions that use it will be changed to reference an identical literal, as long as the location of the replacement literal is within the offset range of all the L32R instructions. The second optimization is to remove unnecessary overhead from assembler-generated "longcall" sequences of L32R/CALLXn when the target functions are within range of direct CALLn instructions.

For each of these cases where an indirect call sequence can be optimized to a direct call, the linker will change the CALLXn instruction to a CALLn instruction, remove the L32R instruction, and remove the literal referenced by the L32R instruction if it is not used for anything else. Removing the L32R instruction always reduces code size but can potentially hurt performance by changing the alignment of subsequent branch targets. By default, the linker will always preserve alignments, either by switching some instructions between 24-bit encodings and the equivalent density instructions or by inserting a no-op in place of the L32R instruction that was removed. If code size is more important than performance, the `--size-opt' option can be used to prevent the linker from widening density instructions or inserting no-ops, except in a few cases where no-ops are required for correctness.

The following Xtensa-specific command-line options can be used to control the linker:

`--no-relax'
Since the Xtensa version of ld enables the `--relax' option by default, the `--no-relax' option is provided to disable relaxation.

`--size-opt'
When optimizing indirect calls to direct calls, optimize for code size more than performance. With this option, the linker will not insert no-ops or widen density instructions to preserve branch target alignment. There may still be some cases where no-ops are required to preserve the correctness of the code.


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

This document was generated by MIPS Technologies, Inc. on April, 20 2007 using texi2html