mirror of
https://sourceware.org/git/binutils-gdb.git
synced 2024-11-30 21:44:19 +08:00
f37b21b481
gold/ * options.h (class General_options): Add --dependency-file option. * fileread.cc (File_read::files_read): New static variable. (File_read::open): Add the file to the files_read list. (File_read::record_file_read): New static member function. (File_read::write_dependency_file): New static member function. * fileread.h (class File_read): Declare them. * layout.cc (Layout::read_layout_from_file): Call record_file_read. (Close_task_runner::run): Call write_dependency_file if --dependency-file was passed. ld/ * NEWS: Note --dependency-file. * ld.texi (Options): Document --dependency-file. * ldlex.h (enum option_values): Add OPTION_DEPENDENCY_FILE. * ld.h (ld_config_type): New member dependency_file. * lexsup.c (ld_options, parse_args): Parse --dependency-file. * ldmain.c (struct dependency_file): New type. (dependency_files, dependency_files_tail): New static variables. (track_dependency_files): New function. (write_dependency_file): New function. (main): Call it when --dependency-file was passed. * ldfile.c (ldfile_try_open_bfd): Call track_dependency_files. (ldfile_open_command_file_1): Likewise. * ldelf.c (ldelf_try_needed): Likewise. * pe-dll.c (pe_implied_import_dll): Likewise.
9006 lines
340 KiB
Plaintext
9006 lines
340 KiB
Plaintext
\input texinfo
|
|
@setfilename ld.info
|
|
@c Copyright (C) 1991-2020 Free Software Foundation, Inc.
|
|
@syncodeindex ky cp
|
|
@c man begin INCLUDE
|
|
@include configdoc.texi
|
|
@c (configdoc.texi is generated by the Makefile)
|
|
@include bfdver.texi
|
|
@c man end
|
|
|
|
@c @smallbook
|
|
|
|
@macro gcctabopt{body}
|
|
@code{\body\}
|
|
@end macro
|
|
|
|
@c man begin NAME
|
|
@ifset man
|
|
@c Configure for the generation of man pages
|
|
@set UsesEnvVars
|
|
@set GENERIC
|
|
@set ARM
|
|
@set C6X
|
|
@set CSKY
|
|
@set H8300
|
|
@set HPPA
|
|
@set M68HC11
|
|
@set M68K
|
|
@set MIPS
|
|
@set MMIX
|
|
@set MSP430
|
|
@set NDS32
|
|
@set NIOSII
|
|
@set PDP11
|
|
@set POWERPC
|
|
@set POWERPC64
|
|
@set Renesas
|
|
@set S/390
|
|
@set SPU
|
|
@set TICOFF
|
|
@set WIN32
|
|
@set XTENSA
|
|
@end ifset
|
|
@c man end
|
|
|
|
@ifnottex
|
|
@dircategory Software development
|
|
@direntry
|
|
* Ld: (ld). The GNU linker.
|
|
@end direntry
|
|
@end ifnottex
|
|
|
|
@copying
|
|
This file documents the @sc{gnu} linker LD
|
|
@ifset VERSION_PACKAGE
|
|
@value{VERSION_PACKAGE}
|
|
@end ifset
|
|
version @value{VERSION}.
|
|
|
|
Copyright @copyright{} 1991-2020 Free Software Foundation, Inc.
|
|
|
|
Permission is granted to copy, distribute and/or modify this document
|
|
under the terms of the GNU Free Documentation License, Version 1.3
|
|
or any later version published by the Free Software Foundation;
|
|
with no Invariant Sections, with no Front-Cover Texts, and with no
|
|
Back-Cover Texts. A copy of the license is included in the
|
|
section entitled ``GNU Free Documentation License''.
|
|
@end copying
|
|
@iftex
|
|
@finalout
|
|
@setchapternewpage odd
|
|
@settitle The GNU linker
|
|
@titlepage
|
|
@title The GNU linker
|
|
@sp 1
|
|
@subtitle @code{ld}
|
|
@ifset VERSION_PACKAGE
|
|
@subtitle @value{VERSION_PACKAGE}
|
|
@end ifset
|
|
@subtitle Version @value{VERSION}
|
|
@author Steve Chamberlain
|
|
@author Ian Lance Taylor
|
|
@page
|
|
|
|
@tex
|
|
{\parskip=0pt
|
|
\hfill Red Hat Inc\par
|
|
\hfill nickc\@credhat.com, doc\@redhat.com\par
|
|
\hfill {\it The GNU linker}\par
|
|
\hfill Edited by Jeffrey Osier (jeffrey\@cygnus.com)\par
|
|
}
|
|
\global\parindent=0pt % Steve likes it this way.
|
|
@end tex
|
|
|
|
@vskip 0pt plus 1filll
|
|
@c man begin COPYRIGHT
|
|
Copyright @copyright{} 1991-2020 Free Software Foundation, Inc.
|
|
|
|
Permission is granted to copy, distribute and/or modify this document
|
|
under the terms of the GNU Free Documentation License, Version 1.3
|
|
or any later version published by the Free Software Foundation;
|
|
with no Invariant Sections, with no Front-Cover Texts, and with no
|
|
Back-Cover Texts. A copy of the license is included in the
|
|
section entitled ``GNU Free Documentation License''.
|
|
@c man end
|
|
|
|
@end titlepage
|
|
@end iftex
|
|
@contents
|
|
@c FIXME: Talk about importance of *order* of args, cmds to linker!
|
|
|
|
@ifnottex
|
|
@node Top
|
|
@top LD
|
|
This file documents the @sc{gnu} linker ld
|
|
@ifset VERSION_PACKAGE
|
|
@value{VERSION_PACKAGE}
|
|
@end ifset
|
|
version @value{VERSION}.
|
|
|
|
This document is distributed under the terms of the GNU Free
|
|
Documentation License version 1.3. A copy of the license is included
|
|
in the section entitled ``GNU Free Documentation License''.
|
|
|
|
@menu
|
|
* Overview:: Overview
|
|
* Invocation:: Invocation
|
|
* Scripts:: Linker Scripts
|
|
@ifset GENERIC
|
|
* Machine Dependent:: Machine Dependent Features
|
|
@end ifset
|
|
@ifclear GENERIC
|
|
@ifset H8300
|
|
* H8/300:: ld and the H8/300
|
|
@end ifset
|
|
@ifset Renesas
|
|
* Renesas:: ld and other Renesas micros
|
|
@end ifset
|
|
@ifset ARM
|
|
* ARM:: ld and the ARM family
|
|
@end ifset
|
|
@ifset M68HC11
|
|
* M68HC11/68HC12:: ld and the Motorola 68HC11 and 68HC12 families
|
|
@end ifset
|
|
@ifset HPPA
|
|
* HPPA ELF32:: ld and HPPA 32-bit ELF
|
|
@end ifset
|
|
@ifset M68K
|
|
* M68K:: ld and Motorola 68K family
|
|
@end ifset
|
|
@ifset MIPS
|
|
* MIPS:: ld and MIPS family
|
|
@end ifset
|
|
@ifset POWERPC
|
|
* PowerPC ELF32:: ld and PowerPC 32-bit ELF Support
|
|
@end ifset
|
|
@ifset POWERPC64
|
|
* PowerPC64 ELF64:: ld and PowerPC64 64-bit ELF Support
|
|
@end ifset
|
|
@ifset S/390
|
|
* S/390 ELF:: ld and S/390 ELF Support
|
|
@end ifset
|
|
@ifset SPU
|
|
* SPU ELF:: ld and SPU ELF Support
|
|
@end ifset
|
|
@ifset TICOFF
|
|
* TI COFF:: ld and the TI COFF
|
|
@end ifset
|
|
@ifset WIN32
|
|
* Win32:: ld and WIN32 (cygwin/mingw)
|
|
@end ifset
|
|
@ifset XTENSA
|
|
* Xtensa:: ld and Xtensa Processors
|
|
@end ifset
|
|
@end ifclear
|
|
@ifclear SingleFormat
|
|
* BFD:: BFD
|
|
@end ifclear
|
|
@c Following blank line required for remaining bug in makeinfo conds/menus
|
|
|
|
* Reporting Bugs:: Reporting Bugs
|
|
* MRI:: MRI Compatible Script Files
|
|
* GNU Free Documentation License:: GNU Free Documentation License
|
|
* LD Index:: LD Index
|
|
@end menu
|
|
@end ifnottex
|
|
|
|
@node Overview
|
|
@chapter Overview
|
|
|
|
@cindex @sc{gnu} linker
|
|
@cindex what is this?
|
|
|
|
@ifset man
|
|
@c man begin SYNOPSIS
|
|
ld [@b{options}] @var{objfile} @dots{}
|
|
@c man end
|
|
|
|
@c man begin SEEALSO
|
|
ar(1), nm(1), objcopy(1), objdump(1), readelf(1) and
|
|
the Info entries for @file{binutils} and
|
|
@file{ld}.
|
|
@c man end
|
|
@end ifset
|
|
|
|
@c man begin DESCRIPTION
|
|
|
|
@command{ld} combines a number of object and archive files, relocates
|
|
their data and ties up symbol references. Usually the last step in
|
|
compiling a program is to run @command{ld}.
|
|
|
|
@command{ld} accepts Linker Command Language files written in
|
|
a superset of AT&T's Link Editor Command Language syntax,
|
|
to provide explicit and total control over the linking process.
|
|
|
|
@ifset man
|
|
@c For the man only
|
|
This man page does not describe the command language; see the
|
|
@command{ld} entry in @code{info} for full details on the command
|
|
language and on other aspects of the GNU linker.
|
|
@end ifset
|
|
|
|
@ifclear SingleFormat
|
|
This version of @command{ld} uses the general purpose BFD libraries
|
|
to operate on object files. This allows @command{ld} to read, combine, and
|
|
write object files in many different formats---for example, COFF or
|
|
@code{a.out}. Different formats may be linked together to produce any
|
|
available kind of object file. @xref{BFD}, for more information.
|
|
@end ifclear
|
|
|
|
Aside from its flexibility, the @sc{gnu} linker is more helpful than other
|
|
linkers in providing diagnostic information. Many linkers abandon
|
|
execution immediately upon encountering an error; whenever possible,
|
|
@command{ld} continues executing, allowing you to identify other errors
|
|
(or, in some cases, to get an output file in spite of the error).
|
|
|
|
@c man end
|
|
|
|
@node Invocation
|
|
@chapter Invocation
|
|
|
|
@c man begin DESCRIPTION
|
|
|
|
The @sc{gnu} linker @command{ld} is meant to cover a broad range of situations,
|
|
and to be as compatible as possible with other linkers. As a result,
|
|
you have many choices to control its behavior.
|
|
|
|
@c man end
|
|
|
|
@ifset UsesEnvVars
|
|
@menu
|
|
* Options:: Command-line Options
|
|
* Environment:: Environment Variables
|
|
@end menu
|
|
|
|
@node Options
|
|
@section Command-line Options
|
|
@end ifset
|
|
|
|
@cindex command line
|
|
@cindex options
|
|
|
|
@c man begin OPTIONS
|
|
|
|
The linker supports a plethora of command-line options, but in actual
|
|
practice few of them are used in any particular context.
|
|
@cindex standard Unix system
|
|
For instance, a frequent use of @command{ld} is to link standard Unix
|
|
object files on a standard, supported Unix system. On such a system, to
|
|
link a file @code{hello.o}:
|
|
|
|
@smallexample
|
|
ld -o @var{output} /lib/crt0.o hello.o -lc
|
|
@end smallexample
|
|
|
|
This tells @command{ld} to produce a file called @var{output} as the
|
|
result of linking the file @code{/lib/crt0.o} with @code{hello.o} and
|
|
the library @code{libc.a}, which will come from the standard search
|
|
directories. (See the discussion of the @samp{-l} option below.)
|
|
|
|
Some of the command-line options to @command{ld} may be specified at any
|
|
point in the command line. However, options which refer to files, such
|
|
as @samp{-l} or @samp{-T}, cause the file to be read at the point at
|
|
which the option appears in the command line, relative to the object
|
|
files and other file options. Repeating non-file options with a
|
|
different argument will either have no further effect, or override prior
|
|
occurrences (those further to the left on the command line) of that
|
|
option. Options which may be meaningfully specified more than once are
|
|
noted in the descriptions below.
|
|
|
|
@cindex object files
|
|
Non-option arguments are object files or archives which are to be linked
|
|
together. They may follow, precede, or be mixed in with command-line
|
|
options, except that an object file argument may not be placed between
|
|
an option and its argument.
|
|
|
|
Usually the linker is invoked with at least one object file, but you can
|
|
specify other forms of binary input files using @samp{-l}, @samp{-R},
|
|
and the script command language. If @emph{no} binary input files at all
|
|
are specified, the linker does not produce any output, and issues the
|
|
message @samp{No input files}.
|
|
|
|
If the linker cannot recognize the format of an object file, it will
|
|
assume that it is a linker script. A script specified in this way
|
|
augments the main linker script used for the link (either the default
|
|
linker script or the one specified by using @samp{-T}). This feature
|
|
permits the linker to link against a file which appears to be an object
|
|
or an archive, but actually merely defines some symbol values, or uses
|
|
@code{INPUT} or @code{GROUP} to load other objects. Specifying a
|
|
script in this way merely augments the main linker script, with the
|
|
extra commands placed after the main script; use the @samp{-T} option
|
|
to replace the default linker script entirely, but note the effect of
|
|
the @code{INSERT} command. @xref{Scripts}.
|
|
|
|
For options whose names are a single letter,
|
|
option arguments must either follow the option letter without intervening
|
|
whitespace, or be given as separate arguments immediately following the
|
|
option that requires them.
|
|
|
|
For options whose names are multiple letters, either one dash or two can
|
|
precede the option name; for example, @samp{-trace-symbol} and
|
|
@samp{--trace-symbol} are equivalent. Note---there is one exception to
|
|
this rule. Multiple letter options that start with a lower case 'o' can
|
|
only be preceded by two dashes. This is to reduce confusion with the
|
|
@samp{-o} option. So for example @samp{-omagic} sets the output file
|
|
name to @samp{magic} whereas @samp{--omagic} sets the NMAGIC flag on the
|
|
output.
|
|
|
|
Arguments to multiple-letter options must either be separated from the
|
|
option name by an equals sign, or be given as separate arguments
|
|
immediately following the option that requires them. For example,
|
|
@samp{--trace-symbol foo} and @samp{--trace-symbol=foo} are equivalent.
|
|
Unique abbreviations of the names of multiple-letter options are
|
|
accepted.
|
|
|
|
Note---if the linker is being invoked indirectly, via a compiler driver
|
|
(e.g. @samp{gcc}) then all the linker command-line options should be
|
|
prefixed by @samp{-Wl,} (or whatever is appropriate for the particular
|
|
compiler driver) like this:
|
|
|
|
@smallexample
|
|
gcc -Wl,--start-group foo.o bar.o -Wl,--end-group
|
|
@end smallexample
|
|
|
|
This is important, because otherwise the compiler driver program may
|
|
silently drop the linker options, resulting in a bad link. Confusion
|
|
may also arise when passing options that require values through a
|
|
driver, as the use of a space between option and argument acts as
|
|
a separator, and causes the driver to pass only the option to the linker
|
|
and the argument to the compiler. In this case, it is simplest to use
|
|
the joined forms of both single- and multiple-letter options, such as:
|
|
|
|
@smallexample
|
|
gcc foo.o bar.o -Wl,-eENTRY -Wl,-Map=a.map
|
|
@end smallexample
|
|
|
|
Here is a table of the generic command-line switches accepted by the GNU
|
|
linker:
|
|
|
|
@table @gcctabopt
|
|
@include at-file.texi
|
|
|
|
@kindex -a @var{keyword}
|
|
@item -a @var{keyword}
|
|
This option is supported for HP/UX compatibility. The @var{keyword}
|
|
argument must be one of the strings @samp{archive}, @samp{shared}, or
|
|
@samp{default}. @samp{-aarchive} is functionally equivalent to
|
|
@samp{-Bstatic}, and the other two keywords are functionally equivalent
|
|
to @samp{-Bdynamic}. This option may be used any number of times.
|
|
|
|
@kindex --audit @var{AUDITLIB}
|
|
@item --audit @var{AUDITLIB}
|
|
Adds @var{AUDITLIB} to the @code{DT_AUDIT} entry of the dynamic section.
|
|
@var{AUDITLIB} is not checked for existence, nor will it use the DT_SONAME
|
|
specified in the library. If specified multiple times @code{DT_AUDIT}
|
|
will contain a colon separated list of audit interfaces to use. If the linker
|
|
finds an object with an audit entry while searching for shared libraries,
|
|
it will add a corresponding @code{DT_DEPAUDIT} entry in the output file.
|
|
This option is only meaningful on ELF platforms supporting the rtld-audit
|
|
interface.
|
|
|
|
@ifclear SingleFormat
|
|
@cindex binary input format
|
|
@kindex -b @var{format}
|
|
@kindex --format=@var{format}
|
|
@cindex input format
|
|
@cindex input format
|
|
@item -b @var{input-format}
|
|
@itemx --format=@var{input-format}
|
|
@command{ld} may be configured to support more than one kind of object
|
|
file. If your @command{ld} is configured this way, you can use the
|
|
@samp{-b} option to specify the binary format for input object files
|
|
that follow this option on the command line. Even when @command{ld} is
|
|
configured to support alternative object formats, you don't usually need
|
|
to specify this, as @command{ld} should be configured to expect as a
|
|
default input format the most usual format on each machine.
|
|
@var{input-format} is a text string, the name of a particular format
|
|
supported by the BFD libraries. (You can list the available binary
|
|
formats with @samp{objdump -i}.)
|
|
@xref{BFD}.
|
|
|
|
You may want to use this option if you are linking files with an unusual
|
|
binary format. You can also use @samp{-b} to switch formats explicitly (when
|
|
linking object files of different formats), by including
|
|
@samp{-b @var{input-format}} before each group of object files in a
|
|
particular format.
|
|
|
|
The default format is taken from the environment variable
|
|
@code{GNUTARGET}.
|
|
@ifset UsesEnvVars
|
|
@xref{Environment}.
|
|
@end ifset
|
|
You can also define the input format from a script, using the command
|
|
@code{TARGET};
|
|
@ifclear man
|
|
see @ref{Format Commands}.
|
|
@end ifclear
|
|
@end ifclear
|
|
|
|
@kindex -c @var{MRI-cmdfile}
|
|
@kindex --mri-script=@var{MRI-cmdfile}
|
|
@cindex compatibility, MRI
|
|
@item -c @var{MRI-commandfile}
|
|
@itemx --mri-script=@var{MRI-commandfile}
|
|
For compatibility with linkers produced by MRI, @command{ld} accepts script
|
|
files written in an alternate, restricted command language, described in
|
|
@ifclear man
|
|
@ref{MRI,,MRI Compatible Script Files}.
|
|
@end ifclear
|
|
@ifset man
|
|
the MRI Compatible Script Files section of GNU ld documentation.
|
|
@end ifset
|
|
Introduce MRI script files with
|
|
the option @samp{-c}; use the @samp{-T} option to run linker
|
|
scripts written in the general-purpose @command{ld} scripting language.
|
|
If @var{MRI-cmdfile} does not exist, @command{ld} looks for it in the directories
|
|
specified by any @samp{-L} options.
|
|
|
|
@cindex common allocation
|
|
@kindex -d
|
|
@kindex -dc
|
|
@kindex -dp
|
|
@item -d
|
|
@itemx -dc
|
|
@itemx -dp
|
|
These three options are equivalent; multiple forms are supported for
|
|
compatibility with other linkers. They assign space to common symbols
|
|
even if a relocatable output file is specified (with @samp{-r}). The
|
|
script command @code{FORCE_COMMON_ALLOCATION} has the same effect.
|
|
@xref{Miscellaneous Commands}.
|
|
|
|
@kindex --depaudit @var{AUDITLIB}
|
|
@kindex -P @var{AUDITLIB}
|
|
@item --depaudit @var{AUDITLIB}
|
|
@itemx -P @var{AUDITLIB}
|
|
Adds @var{AUDITLIB} to the @code{DT_DEPAUDIT} entry of the dynamic section.
|
|
@var{AUDITLIB} is not checked for existence, nor will it use the DT_SONAME
|
|
specified in the library. If specified multiple times @code{DT_DEPAUDIT}
|
|
will contain a colon separated list of audit interfaces to use. This
|
|
option is only meaningful on ELF platforms supporting the rtld-audit interface.
|
|
The -P option is provided for Solaris compatibility.
|
|
|
|
@kindex --enable-non-contiguous-regions
|
|
@item --enable-non-contiguous-regions
|
|
This option avoids generating an error if an input section does not
|
|
fit a matching output section. The linker tries to allocate the input
|
|
section to subseque nt matching output sections, and generates an
|
|
error only if no output section is large enough. This is useful when
|
|
several non-contiguous memory regions are available and the input
|
|
section does not require a particular one. The order in which input
|
|
sections are evaluated does not change, for instance:
|
|
|
|
@smallexample
|
|
MEMORY @{
|
|
MEM1 (rwx) : ORIGIN : 0x1000, LENGTH = 0x14
|
|
MEM2 (rwx) : ORIGIN : 0x1000, LENGTH = 0x40
|
|
MEM3 (rwx) : ORIGIN : 0x2000, LENGTH = 0x40
|
|
@}
|
|
SECTIONS @{
|
|
mem1 : @{ *(.data.*); @} > MEM1
|
|
mem2 : @{ *(.data.*); @} > MEM2
|
|
mem3 : @{ *(.data.*); @} > MEM2
|
|
@}
|
|
|
|
with input sections:
|
|
.data.1: size 8
|
|
.data.2: size 0x10
|
|
.data.3: size 4
|
|
|
|
results in .data.1 affected to mem1, and .data.2 and .data.3
|
|
affected to mem2, even though .data.3 would fit in mem3.
|
|
@end smallexample
|
|
|
|
This option is incompatible with INSERT statements because it changes
|
|
the way input sections are mapped to output sections.
|
|
|
|
@kindex --enable-non-contiguous-regions-warnings
|
|
@item --enable-non-contiguous-regions-warnings
|
|
This option enables warnings when
|
|
@code{--enable-non-contiguous-regions} allows possibly unexpected
|
|
matches in sections mapping, potentially leading to silently
|
|
discarding a section instead of failing because it does not fit any
|
|
output region.
|
|
|
|
@cindex entry point, from command line
|
|
@kindex -e @var{entry}
|
|
@kindex --entry=@var{entry}
|
|
@item -e @var{entry}
|
|
@itemx --entry=@var{entry}
|
|
Use @var{entry} as the explicit symbol for beginning execution of your
|
|
program, rather than the default entry point. If there is no symbol
|
|
named @var{entry}, the linker will try to parse @var{entry} as a number,
|
|
and use that as the entry address (the number will be interpreted in
|
|
base 10; you may use a leading @samp{0x} for base 16, or a leading
|
|
@samp{0} for base 8). @xref{Entry Point}, for a discussion of defaults
|
|
and other ways of specifying the entry point.
|
|
|
|
@kindex --exclude-libs
|
|
@item --exclude-libs @var{lib},@var{lib},...
|
|
Specifies a list of archive libraries from which symbols should not be automatically
|
|
exported. The library names may be delimited by commas or colons. Specifying
|
|
@code{--exclude-libs ALL} excludes symbols in all archive libraries from
|
|
automatic export. This option is available only for the i386 PE targeted
|
|
port of the linker and for ELF targeted ports. For i386 PE, symbols
|
|
explicitly listed in a .def file are still exported, regardless of this
|
|
option. For ELF targeted ports, symbols affected by this option will
|
|
be treated as hidden.
|
|
|
|
@kindex --exclude-modules-for-implib
|
|
@item --exclude-modules-for-implib @var{module},@var{module},...
|
|
Specifies a list of object files or archive members, from which symbols
|
|
should not be automatically exported, but which should be copied wholesale
|
|
into the import library being generated during the link. The module names
|
|
may be delimited by commas or colons, and must match exactly the filenames
|
|
used by @command{ld} to open the files; for archive members, this is simply
|
|
the member name, but for object files the name listed must include and
|
|
match precisely any path used to specify the input file on the linker's
|
|
command-line. This option is available only for the i386 PE targeted port
|
|
of the linker. Symbols explicitly listed in a .def file are still exported,
|
|
regardless of this option.
|
|
|
|
@cindex dynamic symbol table
|
|
@kindex -E
|
|
@kindex --export-dynamic
|
|
@kindex --no-export-dynamic
|
|
@item -E
|
|
@itemx --export-dynamic
|
|
@itemx --no-export-dynamic
|
|
When creating a dynamically linked executable, using the @option{-E}
|
|
option or the @option{--export-dynamic} option causes the linker to add
|
|
all symbols to the dynamic symbol table. The dynamic symbol table is the
|
|
set of symbols which are visible from dynamic objects at run time.
|
|
|
|
If you do not use either of these options (or use the
|
|
@option{--no-export-dynamic} option to restore the default behavior), the
|
|
dynamic symbol table will normally contain only those symbols which are
|
|
referenced by some dynamic object mentioned in the link.
|
|
|
|
If you use @code{dlopen} to load a dynamic object which needs to refer
|
|
back to the symbols defined by the program, rather than some other
|
|
dynamic object, then you will probably need to use this option when
|
|
linking the program itself.
|
|
|
|
You can also use the dynamic list to control what symbols should
|
|
be added to the dynamic symbol table if the output format supports it.
|
|
See the description of @samp{--dynamic-list}.
|
|
|
|
Note that this option is specific to ELF targeted ports. PE targets
|
|
support a similar function to export all symbols from a DLL or EXE; see
|
|
the description of @samp{--export-all-symbols} below.
|
|
|
|
@kindex --export-dynamic-symbol=@var{glob}
|
|
@cindex export dynamic symbol
|
|
@item --export-dynamic-symbol=@var{glob}
|
|
When creating a dynamically linked executable, symbols matching
|
|
@var{glob} will be added to the dynamic symbol table. When creating a
|
|
shared library, references to symbols matching @var{glob} will not be
|
|
bound to the definitions within the shared library. This option is a
|
|
no-op when creating a shared library and @samp{-Bsymbolic} or
|
|
@samp{--dynamic-list} are not specified. This option is only meaningful
|
|
on ELF platforms which support shared libraries.
|
|
|
|
@kindex --export-dynamic-symbol-list=@var{file}
|
|
@cindex export dynamic symbol list
|
|
@item --export-dynamic-symbol-list=@var{file}
|
|
Specify a @samp{--export-dynamic-symbol} for each pattern in the file.
|
|
The format of the file is the same as the version node without
|
|
scope and node name. See @ref{VERSION} for more information.
|
|
|
|
@ifclear SingleFormat
|
|
@cindex big-endian objects
|
|
@cindex endianness
|
|
@kindex -EB
|
|
@item -EB
|
|
Link big-endian objects. This affects the default output format.
|
|
|
|
@cindex little-endian objects
|
|
@kindex -EL
|
|
@item -EL
|
|
Link little-endian objects. This affects the default output format.
|
|
@end ifclear
|
|
|
|
@kindex -f @var{name}
|
|
@kindex --auxiliary=@var{name}
|
|
@item -f @var{name}
|
|
@itemx --auxiliary=@var{name}
|
|
When creating an ELF shared object, set the internal DT_AUXILIARY field
|
|
to the specified name. This tells the dynamic linker that the symbol
|
|
table of the shared object should be used as an auxiliary filter on the
|
|
symbol table of the shared object @var{name}.
|
|
|
|
If you later link a program against this filter object, then, when you
|
|
run the program, the dynamic linker will see the DT_AUXILIARY field. If
|
|
the dynamic linker resolves any symbols from the filter object, it will
|
|
first check whether there is a definition in the shared object
|
|
@var{name}. If there is one, it will be used instead of the definition
|
|
in the filter object. The shared object @var{name} need not exist.
|
|
Thus the shared object @var{name} may be used to provide an alternative
|
|
implementation of certain functions, perhaps for debugging or for
|
|
machine-specific performance.
|
|
|
|
This option may be specified more than once. The DT_AUXILIARY entries
|
|
will be created in the order in which they appear on the command line.
|
|
|
|
@kindex -F @var{name}
|
|
@kindex --filter=@var{name}
|
|
@item -F @var{name}
|
|
@itemx --filter=@var{name}
|
|
When creating an ELF shared object, set the internal DT_FILTER field to
|
|
the specified name. This tells the dynamic linker that the symbol table
|
|
of the shared object which is being created should be used as a filter
|
|
on the symbol table of the shared object @var{name}.
|
|
|
|
If you later link a program against this filter object, then, when you
|
|
run the program, the dynamic linker will see the DT_FILTER field. The
|
|
dynamic linker will resolve symbols according to the symbol table of the
|
|
filter object as usual, but it will actually link to the definitions
|
|
found in the shared object @var{name}. Thus the filter object can be
|
|
used to select a subset of the symbols provided by the object
|
|
@var{name}.
|
|
|
|
Some older linkers used the @option{-F} option throughout a compilation
|
|
toolchain for specifying object-file format for both input and output
|
|
object files.
|
|
@ifclear SingleFormat
|
|
The @sc{gnu} linker uses other mechanisms for this purpose: the
|
|
@option{-b}, @option{--format}, @option{--oformat} options, the
|
|
@code{TARGET} command in linker scripts, and the @code{GNUTARGET}
|
|
environment variable.
|
|
@end ifclear
|
|
The @sc{gnu} linker will ignore the @option{-F} option when not
|
|
creating an ELF shared object.
|
|
|
|
@cindex finalization function
|
|
@kindex -fini=@var{name}
|
|
@item -fini=@var{name}
|
|
When creating an ELF executable or shared object, call NAME when the
|
|
executable or shared object is unloaded, by setting DT_FINI to the
|
|
address of the function. By default, the linker uses @code{_fini} as
|
|
the function to call.
|
|
|
|
@kindex -g
|
|
@item -g
|
|
Ignored. Provided for compatibility with other tools.
|
|
|
|
@kindex -G @var{value}
|
|
@kindex --gpsize=@var{value}
|
|
@cindex object size
|
|
@item -G @var{value}
|
|
@itemx --gpsize=@var{value}
|
|
Set the maximum size of objects to be optimized using the GP register to
|
|
@var{size}. This is only meaningful for object file formats such as
|
|
MIPS ELF that support putting large and small objects into different
|
|
sections. This is ignored for other object file formats.
|
|
|
|
@cindex runtime library name
|
|
@kindex -h @var{name}
|
|
@kindex -soname=@var{name}
|
|
@item -h @var{name}
|
|
@itemx -soname=@var{name}
|
|
When creating an ELF shared object, set the internal DT_SONAME field to
|
|
the specified name. When an executable is linked with a shared object
|
|
which has a DT_SONAME field, then when the executable is run the dynamic
|
|
linker will attempt to load the shared object specified by the DT_SONAME
|
|
field rather than the using the file name given to the linker.
|
|
|
|
@kindex -i
|
|
@cindex incremental link
|
|
@item -i
|
|
Perform an incremental link (same as option @samp{-r}).
|
|
|
|
@cindex initialization function
|
|
@kindex -init=@var{name}
|
|
@item -init=@var{name}
|
|
When creating an ELF executable or shared object, call NAME when the
|
|
executable or shared object is loaded, by setting DT_INIT to the address
|
|
of the function. By default, the linker uses @code{_init} as the
|
|
function to call.
|
|
|
|
@cindex archive files, from cmd line
|
|
@kindex -l @var{namespec}
|
|
@kindex --library=@var{namespec}
|
|
@item -l @var{namespec}
|
|
@itemx --library=@var{namespec}
|
|
Add the archive or object file specified by @var{namespec} to the
|
|
list of files to link. This option may be used any number of times.
|
|
If @var{namespec} is of the form @file{:@var{filename}}, @command{ld}
|
|
will search the library path for a file called @var{filename}, otherwise it
|
|
will search the library path for a file called @file{lib@var{namespec}.a}.
|
|
|
|
On systems which support shared libraries, @command{ld} may also search for
|
|
files other than @file{lib@var{namespec}.a}. Specifically, on ELF
|
|
and SunOS systems, @command{ld} will search a directory for a library
|
|
called @file{lib@var{namespec}.so} before searching for one called
|
|
@file{lib@var{namespec}.a}. (By convention, a @code{.so} extension
|
|
indicates a shared library.) Note that this behavior does not apply
|
|
to @file{:@var{filename}}, which always specifies a file called
|
|
@var{filename}.
|
|
|
|
The linker will search an archive only once, at the location where it is
|
|
specified on the command line. If the archive defines a symbol which
|
|
was undefined in some object which appeared before the archive on the
|
|
command line, the linker will include the appropriate file(s) from the
|
|
archive. However, an undefined symbol in an object appearing later on
|
|
the command line will not cause the linker to search the archive again.
|
|
|
|
See the @option{-(} option for a way to force the linker to search
|
|
archives multiple times.
|
|
|
|
You may list the same archive multiple times on the command line.
|
|
|
|
@ifset GENERIC
|
|
This type of archive searching is standard for Unix linkers. However,
|
|
if you are using @command{ld} on AIX, note that it is different from the
|
|
behaviour of the AIX linker.
|
|
@end ifset
|
|
|
|
@cindex search directory, from cmd line
|
|
@kindex -L @var{dir}
|
|
@kindex --library-path=@var{dir}
|
|
@item -L @var{searchdir}
|
|
@itemx --library-path=@var{searchdir}
|
|
Add path @var{searchdir} to the list of paths that @command{ld} will search
|
|
for archive libraries and @command{ld} control scripts. You may use this
|
|
option any number of times. The directories are searched in the order
|
|
in which they are specified on the command line. Directories specified
|
|
on the command line are searched before the default directories. All
|
|
@option{-L} options apply to all @option{-l} options, regardless of the
|
|
order in which the options appear. @option{-L} options do not affect
|
|
how @command{ld} searches for a linker script unless @option{-T}
|
|
option is specified.
|
|
|
|
If @var{searchdir} begins with @code{=} or @code{$SYSROOT}, then this
|
|
prefix will be replaced by the @dfn{sysroot prefix}, controlled by the
|
|
@samp{--sysroot} option, or specified when the linker is configured.
|
|
|
|
@ifset UsesEnvVars
|
|
The default set of paths searched (without being specified with
|
|
@samp{-L}) depends on which emulation mode @command{ld} is using, and in
|
|
some cases also on how it was configured. @xref{Environment}.
|
|
@end ifset
|
|
|
|
The paths can also be specified in a link script with the
|
|
@code{SEARCH_DIR} command. Directories specified this way are searched
|
|
at the point in which the linker script appears in the command line.
|
|
|
|
@cindex emulation
|
|
@kindex -m @var{emulation}
|
|
@item -m @var{emulation}
|
|
Emulate the @var{emulation} linker. You can list the available
|
|
emulations with the @samp{--verbose} or @samp{-V} options.
|
|
|
|
If the @samp{-m} option is not used, the emulation is taken from the
|
|
@code{LDEMULATION} environment variable, if that is defined.
|
|
|
|
Otherwise, the default emulation depends upon how the linker was
|
|
configured.
|
|
|
|
@cindex link map
|
|
@kindex -M
|
|
@kindex --print-map
|
|
@item -M
|
|
@itemx --print-map
|
|
Print a link map to the standard output. A link map provides
|
|
information about the link, including the following:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
Where object files are mapped into memory.
|
|
@item
|
|
How common symbols are allocated.
|
|
@item
|
|
All archive members included in the link, with a mention of the symbol
|
|
which caused the archive member to be brought in.
|
|
@item
|
|
The values assigned to symbols.
|
|
|
|
Note - symbols whose values are computed by an expression which
|
|
involves a reference to a previous value of the same symbol may not
|
|
have correct result displayed in the link map. This is because the
|
|
linker discards intermediate results and only retains the final value
|
|
of an expression. Under such circumstances the linker will display
|
|
the final value enclosed by square brackets. Thus for example a
|
|
linker script containing:
|
|
|
|
@smallexample
|
|
foo = 1
|
|
foo = foo * 4
|
|
foo = foo + 8
|
|
@end smallexample
|
|
|
|
will produce the following output in the link map if the @option{-M}
|
|
option is used:
|
|
|
|
@smallexample
|
|
0x00000001 foo = 0x1
|
|
[0x0000000c] foo = (foo * 0x4)
|
|
[0x0000000c] foo = (foo + 0x8)
|
|
@end smallexample
|
|
|
|
See @ref{Expressions} for more information about expressions in linker
|
|
scripts.
|
|
|
|
@item
|
|
How GNU properties are merged.
|
|
|
|
When the linker merges input .note.gnu.property sections into one output
|
|
.note.gnu.property section, some properties are removed or updated.
|
|
These actions are reported in the link map. For example:
|
|
|
|
@smallexample
|
|
Removed property 0xc0000002 to merge foo.o (0x1) and bar.o (not found)
|
|
@end smallexample
|
|
|
|
This indicates that property 0xc0000002 is removed from output when
|
|
merging properties in @file{foo.o}, whose property 0xc0000002 value
|
|
is 0x1, and @file{bar.o}, which doesn't have property 0xc0000002.
|
|
|
|
@smallexample
|
|
Updated property 0xc0010001 (0x1) to merge foo.o (0x1) and bar.o (0x1)
|
|
@end smallexample
|
|
|
|
This indicates that property 0xc0010001 value is updated to 0x1 in output
|
|
when merging properties in @file{foo.o}, whose 0xc0010001 property value
|
|
is 0x1, and @file{bar.o}, whose 0xc0010001 property value is 0x1.
|
|
@end itemize
|
|
|
|
@cindex link map discarded
|
|
@kindex --print-map-discarded
|
|
@kindex --no-print-map-discarded
|
|
@item --print-map-discarded
|
|
@itemx --no-print-map-discarded
|
|
Print (or do not print) the list of discarded and garbage collected sections
|
|
in the link map. Enabled by default.
|
|
|
|
@kindex -n
|
|
@cindex read-only text
|
|
@cindex NMAGIC
|
|
@kindex --nmagic
|
|
@item -n
|
|
@itemx --nmagic
|
|
Turn off page alignment of sections, and disable linking against shared
|
|
libraries. If the output format supports Unix style magic numbers,
|
|
mark the output as @code{NMAGIC}.
|
|
|
|
@kindex -N
|
|
@kindex --omagic
|
|
@cindex read/write from cmd line
|
|
@cindex OMAGIC
|
|
@item -N
|
|
@itemx --omagic
|
|
Set the text and data sections to be readable and writable. Also, do
|
|
not page-align the data segment, and disable linking against shared
|
|
libraries. If the output format supports Unix style magic numbers,
|
|
mark the output as @code{OMAGIC}. Note: Although a writable text section
|
|
is allowed for PE-COFF targets, it does not conform to the format
|
|
specification published by Microsoft.
|
|
|
|
@kindex --no-omagic
|
|
@cindex OMAGIC
|
|
@item --no-omagic
|
|
This option negates most of the effects of the @option{-N} option. It
|
|
sets the text section to be read-only, and forces the data segment to
|
|
be page-aligned. Note - this option does not enable linking against
|
|
shared libraries. Use @option{-Bdynamic} for this.
|
|
|
|
@kindex -o @var{output}
|
|
@kindex --output=@var{output}
|
|
@cindex naming the output file
|
|
@item -o @var{output}
|
|
@itemx --output=@var{output}
|
|
Use @var{output} as the name for the program produced by @command{ld}; if this
|
|
option is not specified, the name @file{a.out} is used by default. The
|
|
script command @code{OUTPUT} can also specify the output file name.
|
|
|
|
@kindex --dependency-file=@var{depfile}
|
|
@cindex dependency file
|
|
@item --dependency-file=@var{depfile}
|
|
Write a @dfn{dependency file} to @var{depfile}. This file contains a rule
|
|
suitable for @code{make} describing the output file and all the input files
|
|
that were read to produce it. The output is similar to the compiler's
|
|
output with @samp{-M -MP} (@pxref{Preprocessor Options,, Options
|
|
Controlling the Preprocessor, gcc.info, Using the GNU Compiler
|
|
Collection}). Note that there is no option like the compiler's @samp{-MM},
|
|
to exclude ``system files'' (which is not a well-specified concept in the
|
|
linker, unlike ``system headers'' in the compiler). So the output from
|
|
@samp{--dependency-file} is always specific to the exact state of the
|
|
installation where it was produced, and should not be copied into
|
|
distributed makefiles without careful editing.
|
|
|
|
@kindex -O @var{level}
|
|
@cindex generating optimized output
|
|
@item -O @var{level}
|
|
If @var{level} is a numeric values greater than zero @command{ld} optimizes
|
|
the output. This might take significantly longer and therefore probably
|
|
should only be enabled for the final binary. At the moment this
|
|
option only affects ELF shared library generation. Future releases of
|
|
the linker may make more use of this option. Also currently there is
|
|
no difference in the linker's behaviour for different non-zero values
|
|
of this option. Again this may change with future releases.
|
|
|
|
@kindex -plugin @var{name}
|
|
@item -plugin @var{name}
|
|
Involve a plugin in the linking process. The @var{name} parameter is
|
|
the absolute filename of the plugin. Usually this parameter is
|
|
automatically added by the complier, when using link time
|
|
optimization, but users can also add their own plugins if they so
|
|
wish.
|
|
|
|
Note that the location of the compiler originated plugins is different
|
|
from the place where the @command{ar}, @command{nm} and
|
|
@command{ranlib} programs search for their plugins. In order for
|
|
those commands to make use of a compiler based plugin it must first be
|
|
copied into the @file{$@{libdir@}/bfd-plugins} directory. All gcc
|
|
based linker plugins are backward compatible, so it is sufficient to
|
|
just copy in the newest one.
|
|
|
|
@kindex --push-state
|
|
@cindex push state governing input file handling
|
|
@item --push-state
|
|
The @option{--push-state} allows to preserve the current state of the
|
|
flags which govern the input file handling so that they can all be
|
|
restored with one corresponding @option{--pop-state} option.
|
|
|
|
The option which are covered are: @option{-Bdynamic}, @option{-Bstatic},
|
|
@option{-dn}, @option{-dy}, @option{-call_shared}, @option{-non_shared},
|
|
@option{-static}, @option{-N}, @option{-n}, @option{--whole-archive},
|
|
@option{--no-whole-archive}, @option{-r}, @option{-Ur},
|
|
@option{--copy-dt-needed-entries}, @option{--no-copy-dt-needed-entries},
|
|
@option{--as-needed}, @option{--no-as-needed}, and @option{-a}.
|
|
|
|
One target for this option are specifications for @file{pkg-config}. When
|
|
used with the @option{--libs} option all possibly needed libraries are
|
|
listed and then possibly linked with all the time. It is better to return
|
|
something as follows:
|
|
|
|
@smallexample
|
|
-Wl,--push-state,--as-needed -libone -libtwo -Wl,--pop-state
|
|
@end smallexample
|
|
|
|
@kindex --pop-state
|
|
@cindex pop state governing input file handling
|
|
@item --pop-state
|
|
Undoes the effect of --push-state, restores the previous values of the
|
|
flags governing input file handling.
|
|
|
|
@kindex -q
|
|
@kindex --emit-relocs
|
|
@cindex retain relocations in final executable
|
|
@item -q
|
|
@itemx --emit-relocs
|
|
Leave relocation sections and contents in fully linked executables.
|
|
Post link analysis and optimization tools may need this information in
|
|
order to perform correct modifications of executables. This results
|
|
in larger executables.
|
|
|
|
This option is currently only supported on ELF platforms.
|
|
|
|
@kindex --force-dynamic
|
|
@cindex forcing the creation of dynamic sections
|
|
@item --force-dynamic
|
|
Force the output file to have dynamic sections. This option is specific
|
|
to VxWorks targets.
|
|
|
|
@cindex partial link
|
|
@cindex relocatable output
|
|
@kindex -r
|
|
@kindex --relocatable
|
|
@item -r
|
|
@itemx --relocatable
|
|
Generate relocatable output---i.e., generate an output file that can in
|
|
turn serve as input to @command{ld}. This is often called @dfn{partial
|
|
linking}. As a side effect, in environments that support standard Unix
|
|
magic numbers, this option also sets the output file's magic number to
|
|
@code{OMAGIC}.
|
|
@c ; see @option{-N}.
|
|
If this option is not specified, an absolute file is produced. When
|
|
linking C++ programs, this option @emph{will not} resolve references to
|
|
constructors; to do that, use @samp{-Ur}.
|
|
|
|
When an input file does not have the same format as the output file,
|
|
partial linking is only supported if that input file does not contain any
|
|
relocations. Different output formats can have further restrictions; for
|
|
example some @code{a.out}-based formats do not support partial linking
|
|
with input files in other formats at all.
|
|
|
|
This option does the same thing as @samp{-i}.
|
|
|
|
@kindex -R @var{file}
|
|
@kindex --just-symbols=@var{file}
|
|
@cindex symbol-only input
|
|
@item -R @var{filename}
|
|
@itemx --just-symbols=@var{filename}
|
|
Read symbol names and their addresses from @var{filename}, but do not
|
|
relocate it or include it in the output. This allows your output file
|
|
to refer symbolically to absolute locations of memory defined in other
|
|
programs. You may use this option more than once.
|
|
|
|
For compatibility with other ELF linkers, if the @option{-R} option is
|
|
followed by a directory name, rather than a file name, it is treated as
|
|
the @option{-rpath} option.
|
|
|
|
@kindex -s
|
|
@kindex --strip-all
|
|
@cindex strip all symbols
|
|
@item -s
|
|
@itemx --strip-all
|
|
Omit all symbol information from the output file.
|
|
|
|
@kindex -S
|
|
@kindex --strip-debug
|
|
@cindex strip debugger symbols
|
|
@item -S
|
|
@itemx --strip-debug
|
|
Omit debugger symbol information (but not all symbols) from the output file.
|
|
|
|
@kindex --strip-discarded
|
|
@kindex --no-strip-discarded
|
|
@item --strip-discarded
|
|
@itemx --no-strip-discarded
|
|
Omit (or do not omit) global symbols defined in discarded sections.
|
|
Enabled by default.
|
|
|
|
@kindex -t
|
|
@kindex --trace
|
|
@cindex input files, displaying
|
|
@item -t
|
|
@itemx --trace
|
|
Print the names of the input files as @command{ld} processes them. If
|
|
@samp{-t} is given twice then members within archives are also printed.
|
|
@samp{-t} output is useful to generate a list of all the object files
|
|
and scripts involved in linking, for example, when packaging files for
|
|
a linker bug report.
|
|
|
|
@kindex -T @var{script}
|
|
@kindex --script=@var{script}
|
|
@cindex script files
|
|
@item -T @var{scriptfile}
|
|
@itemx --script=@var{scriptfile}
|
|
Use @var{scriptfile} as the linker script. This script replaces
|
|
@command{ld}'s default linker script (rather than adding to it), so
|
|
@var{commandfile} must specify everything necessary to describe the
|
|
output file. @xref{Scripts}. If @var{scriptfile} does not exist in
|
|
the current directory, @code{ld} looks for it in the directories
|
|
specified by any preceding @samp{-L} options. Multiple @samp{-T}
|
|
options accumulate.
|
|
|
|
@kindex -dT @var{script}
|
|
@kindex --default-script=@var{script}
|
|
@cindex script files
|
|
@item -dT @var{scriptfile}
|
|
@itemx --default-script=@var{scriptfile}
|
|
Use @var{scriptfile} as the default linker script. @xref{Scripts}.
|
|
|
|
This option is similar to the @option{--script} option except that
|
|
processing of the script is delayed until after the rest of the
|
|
command line has been processed. This allows options placed after the
|
|
@option{--default-script} option on the command line to affect the
|
|
behaviour of the linker script, which can be important when the linker
|
|
command line cannot be directly controlled by the user. (eg because
|
|
the command line is being constructed by another tool, such as
|
|
@samp{gcc}).
|
|
|
|
@kindex -u @var{symbol}
|
|
@kindex --undefined=@var{symbol}
|
|
@cindex undefined symbol
|
|
@item -u @var{symbol}
|
|
@itemx --undefined=@var{symbol}
|
|
Force @var{symbol} to be entered in the output file as an undefined
|
|
symbol. Doing this may, for example, trigger linking of additional
|
|
modules from standard libraries. @samp{-u} may be repeated with
|
|
different option arguments to enter additional undefined symbols. This
|
|
option is equivalent to the @code{EXTERN} linker script command.
|
|
|
|
If this option is being used to force additional modules to be pulled
|
|
into the link, and if it is an error for the symbol to remain
|
|
undefined, then the option @option{--require-defined} should be used
|
|
instead.
|
|
|
|
@kindex --require-defined=@var{symbol}
|
|
@cindex symbols, require defined
|
|
@cindex defined symbol
|
|
@item --require-defined=@var{symbol}
|
|
Require that @var{symbol} is defined in the output file. This option
|
|
is the same as option @option{--undefined} except that if @var{symbol}
|
|
is not defined in the output file then the linker will issue an error
|
|
and exit. The same effect can be achieved in a linker script by using
|
|
@code{EXTERN}, @code{ASSERT} and @code{DEFINED} together. This option
|
|
can be used multiple times to require additional symbols.
|
|
|
|
@kindex -Ur
|
|
@cindex constructors
|
|
@item -Ur
|
|
For anything other than C++ programs, this option is equivalent to
|
|
@samp{-r}: it generates relocatable output---i.e., an output file that can in
|
|
turn serve as input to @command{ld}. When linking C++ programs, @samp{-Ur}
|
|
@emph{does} resolve references to constructors, unlike @samp{-r}.
|
|
It does not work to use @samp{-Ur} on files that were themselves linked
|
|
with @samp{-Ur}; once the constructor table has been built, it cannot
|
|
be added to. Use @samp{-Ur} only for the last partial link, and
|
|
@samp{-r} for the others.
|
|
|
|
@kindex --orphan-handling=@var{MODE}
|
|
@cindex orphan sections
|
|
@cindex sections, orphan
|
|
@item --orphan-handling=@var{MODE}
|
|
Control how orphan sections are handled. An orphan section is one not
|
|
specifically mentioned in a linker script. @xref{Orphan Sections}.
|
|
|
|
@var{MODE} can have any of the following values:
|
|
|
|
@table @code
|
|
@item place
|
|
Orphan sections are placed into a suitable output section following
|
|
the strategy described in @ref{Orphan Sections}. The option
|
|
@samp{--unique} also affects how sections are placed.
|
|
|
|
@item discard
|
|
All orphan sections are discarded, by placing them in the
|
|
@samp{/DISCARD/} section (@pxref{Output Section Discarding}).
|
|
|
|
@item warn
|
|
The linker will place the orphan section as for @code{place} and also
|
|
issue a warning.
|
|
|
|
@item error
|
|
The linker will exit with an error if any orphan section is found.
|
|
@end table
|
|
|
|
The default if @samp{--orphan-handling} is not given is @code{place}.
|
|
|
|
@kindex --unique[=@var{SECTION}]
|
|
@item --unique[=@var{SECTION}]
|
|
Creates a separate output section for every input section matching
|
|
@var{SECTION}, or if the optional wildcard @var{SECTION} argument is
|
|
missing, for every orphan input section. An orphan section is one not
|
|
specifically mentioned in a linker script. You may use this option
|
|
multiple times on the command line; It prevents the normal merging of
|
|
input sections with the same name, overriding output section assignments
|
|
in a linker script.
|
|
|
|
@kindex -v
|
|
@kindex -V
|
|
@kindex --version
|
|
@cindex version
|
|
@item -v
|
|
@itemx --version
|
|
@itemx -V
|
|
Display the version number for @command{ld}. The @option{-V} option also
|
|
lists the supported emulations.
|
|
|
|
@kindex -x
|
|
@kindex --discard-all
|
|
@cindex deleting local symbols
|
|
@item -x
|
|
@itemx --discard-all
|
|
Delete all local symbols.
|
|
|
|
@kindex -X
|
|
@kindex --discard-locals
|
|
@cindex local symbols, deleting
|
|
@item -X
|
|
@itemx --discard-locals
|
|
Delete all temporary local symbols. (These symbols start with
|
|
system-specific local label prefixes, typically @samp{.L} for ELF systems
|
|
or @samp{L} for traditional a.out systems.)
|
|
|
|
@kindex -y @var{symbol}
|
|
@kindex --trace-symbol=@var{symbol}
|
|
@cindex symbol tracing
|
|
@item -y @var{symbol}
|
|
@itemx --trace-symbol=@var{symbol}
|
|
Print the name of each linked file in which @var{symbol} appears. This
|
|
option may be given any number of times. On many systems it is necessary
|
|
to prepend an underscore.
|
|
|
|
This option is useful when you have an undefined symbol in your link but
|
|
don't know where the reference is coming from.
|
|
|
|
@kindex -Y @var{path}
|
|
@item -Y @var{path}
|
|
Add @var{path} to the default library search path. This option exists
|
|
for Solaris compatibility.
|
|
|
|
@kindex -z @var{keyword}
|
|
@item -z @var{keyword}
|
|
The recognized keywords are:
|
|
@table @samp
|
|
|
|
@item bndplt
|
|
Always generate BND prefix in PLT entries. Supported for Linux/x86_64.
|
|
|
|
@item call-nop=prefix-addr
|
|
@itemx call-nop=suffix-nop
|
|
@itemx call-nop=prefix-@var{byte}
|
|
@itemx call-nop=suffix-@var{byte}
|
|
Specify the 1-byte @code{NOP} padding when transforming indirect call
|
|
to a locally defined function, foo, via its GOT slot.
|
|
@option{call-nop=prefix-addr} generates @code{0x67 call foo}.
|
|
@option{call-nop=suffix-nop} generates @code{call foo 0x90}.
|
|
@option{call-nop=prefix-@var{byte}} generates @code{@var{byte} call foo}.
|
|
@option{call-nop=suffix-@var{byte}} generates @code{call foo @var{byte}}.
|
|
Supported for i386 and x86_64.
|
|
|
|
@item cet-report=none
|
|
@itemx cet-report=warning
|
|
@itemx cet-report=error
|
|
Specify how to report the missing GNU_PROPERTY_X86_FEATURE_1_IBT and
|
|
GNU_PROPERTY_X86_FEATURE_1_SHSTK properties in input .note.gnu.property
|
|
section. @option{cet-report=none}, which is the default, will make the
|
|
linker not report missing properties in input files.
|
|
@option{cet-report=warning} will make the linker issue a warning for
|
|
missing properties in input files. @option{cet-report=error} will make
|
|
the linker issue an error for missing properties in input files.
|
|
Note that @option{ibt} will turn off the missing
|
|
GNU_PROPERTY_X86_FEATURE_1_IBT property report and @option{shstk} will
|
|
turn off the missing GNU_PROPERTY_X86_FEATURE_1_SHSTK property report.
|
|
Supported for Linux/i386 and Linux/x86_64.
|
|
|
|
@item combreloc
|
|
@itemx nocombreloc
|
|
Combine multiple dynamic relocation sections and sort to improve
|
|
dynamic symbol lookup caching. Do not do this if @samp{nocombreloc}.
|
|
|
|
@item common
|
|
@itemx nocommon
|
|
Generate common symbols with STT_COMMON type during a relocatable
|
|
link. Use STT_OBJECT type if @samp{nocommon}.
|
|
|
|
@item common-page-size=@var{value}
|
|
Set the page size most commonly used to @var{value}. Memory image
|
|
layout will be optimized to minimize memory pages if the system is
|
|
using pages of this size.
|
|
|
|
@item defs
|
|
Report unresolved symbol references from regular object files. This
|
|
is done even if the linker is creating a non-symbolic shared library.
|
|
This option is the inverse of @samp{-z undefs}.
|
|
|
|
@item dynamic-undefined-weak
|
|
@itemx nodynamic-undefined-weak
|
|
Make undefined weak symbols dynamic when building a dynamic object,
|
|
if they are referenced from a regular object file and not forced local
|
|
by symbol visibility or versioning. Do not make them dynamic if
|
|
@samp{nodynamic-undefined-weak}. If neither option is given, a target
|
|
may default to either option being in force, or make some other
|
|
selection of undefined weak symbols dynamic. Not all targets support
|
|
these options.
|
|
|
|
@item execstack
|
|
Marks the object as requiring executable stack.
|
|
|
|
@item global
|
|
This option is only meaningful when building a shared object. It makes
|
|
the symbols defined by this shared object available for symbol resolution
|
|
of subsequently loaded libraries.
|
|
|
|
@item globalaudit
|
|
This option is only meaningful when building a dynamic executable.
|
|
This option marks the executable as requiring global auditing by
|
|
setting the @code{DF_1_GLOBAUDIT} bit in the @code{DT_FLAGS_1} dynamic
|
|
tag. Global auditing requires that any auditing library defined via
|
|
the @option{--depaudit} or @option{-P} command-line options be run for
|
|
all dynamic objects loaded by the application.
|
|
|
|
@item ibtplt
|
|
Generate Intel Indirect Branch Tracking (IBT) enabled PLT entries.
|
|
Supported for Linux/i386 and Linux/x86_64.
|
|
|
|
@item ibt
|
|
Generate GNU_PROPERTY_X86_FEATURE_1_IBT in .note.gnu.property section
|
|
to indicate compatibility with IBT. This also implies @option{ibtplt}.
|
|
Supported for Linux/i386 and Linux/x86_64.
|
|
|
|
@item initfirst
|
|
This option is only meaningful when building a shared object.
|
|
It marks the object so that its runtime initialization will occur
|
|
before the runtime initialization of any other objects brought into
|
|
the process at the same time. Similarly the runtime finalization of
|
|
the object will occur after the runtime finalization of any other
|
|
objects.
|
|
|
|
@item interpose
|
|
Specify that the dynamic loader should modify its symbol search order
|
|
so that symbols in this shared library interpose all other shared
|
|
libraries not so marked.
|
|
|
|
@item lazy
|
|
When generating an executable or shared library, mark it to tell the
|
|
dynamic linker to defer function call resolution to the point when
|
|
the function is called (lazy binding), rather than at load time.
|
|
Lazy binding is the default.
|
|
|
|
@item loadfltr
|
|
Specify that the object's filters be processed immediately at runtime.
|
|
|
|
@item max-page-size=@var{value}
|
|
Set the maximum memory page size supported to @var{value}.
|
|
|
|
@item muldefs
|
|
Allow multiple definitions.
|
|
|
|
@item nocopyreloc
|
|
Disable linker generated .dynbss variables used in place of variables
|
|
defined in shared libraries. May result in dynamic text relocations.
|
|
|
|
@item nodefaultlib
|
|
Specify that the dynamic loader search for dependencies of this object
|
|
should ignore any default library search paths.
|
|
|
|
@item nodelete
|
|
Specify that the object shouldn't be unloaded at runtime.
|
|
|
|
@item nodlopen
|
|
Specify that the object is not available to @code{dlopen}.
|
|
|
|
@item nodump
|
|
Specify that the object can not be dumped by @code{dldump}.
|
|
|
|
@item noexecstack
|
|
Marks the object as not requiring executable stack.
|
|
|
|
@item noextern-protected-data
|
|
Don't treat protected data symbols as external when building a shared
|
|
library. This option overrides the linker backend default. It can be
|
|
used to work around incorrect relocations against protected data symbols
|
|
generated by compiler. Updates on protected data symbols by another
|
|
module aren't visible to the resulting shared library. Supported for
|
|
i386 and x86-64.
|
|
|
|
@item noreloc-overflow
|
|
Disable relocation overflow check. This can be used to disable
|
|
relocation overflow check if there will be no dynamic relocation
|
|
overflow at run-time. Supported for x86_64.
|
|
|
|
@item now
|
|
When generating an executable or shared library, mark it to tell the
|
|
dynamic linker to resolve all symbols when the program is started, or
|
|
when the shared library is loaded by dlopen, instead of deferring
|
|
function call resolution to the point when the function is first
|
|
called.
|
|
|
|
@item origin
|
|
Specify that the object requires @samp{$ORIGIN} handling in paths.
|
|
|
|
@item relro
|
|
@itemx norelro
|
|
Create an ELF @code{PT_GNU_RELRO} segment header in the object. This
|
|
specifies a memory segment that should be made read-only after
|
|
relocation, if supported. Specifying @samp{common-page-size} smaller
|
|
than the system page size will render this protection ineffective.
|
|
Don't create an ELF @code{PT_GNU_RELRO} segment if @samp{norelro}.
|
|
|
|
@item separate-code
|
|
@itemx noseparate-code
|
|
Create separate code @code{PT_LOAD} segment header in the object. This
|
|
specifies a memory segment that should contain only instructions and must
|
|
be in wholly disjoint pages from any other data. Don't create separate
|
|
code @code{PT_LOAD} segment if @samp{noseparate-code} is used.
|
|
|
|
@item shstk
|
|
Generate GNU_PROPERTY_X86_FEATURE_1_SHSTK in .note.gnu.property section
|
|
to indicate compatibility with Intel Shadow Stack. Supported for
|
|
Linux/i386 and Linux/x86_64.
|
|
|
|
@item stack-size=@var{value}
|
|
Specify a stack size for an ELF @code{PT_GNU_STACK} segment.
|
|
Specifying zero will override any default non-zero sized
|
|
@code{PT_GNU_STACK} segment creation.
|
|
|
|
@item start-stop-visibility=@var{value}
|
|
@cindex visibility
|
|
@cindex ELF symbol visibility
|
|
Specify the ELF symbol visibility for synthesized
|
|
@code{__start_SECNAME} and @code{__stop_SECNAME} symbols (@pxref{Input
|
|
Section Example}). @var{value} must be exactly @samp{default},
|
|
@samp{internal}, @samp{hidden}, or @samp{protected}. If no @samp{-z
|
|
start-stop-visibility} option is given, @samp{protected} is used for
|
|
compatibility with historical practice. However, it's highly
|
|
recommended to use @samp{-z start-stop-visibility=hidden} in new
|
|
programs and shared libraries so that these symbols are not exported
|
|
between shared objects, which is not usually what's intended.
|
|
|
|
@item text
|
|
@itemx notext
|
|
@itemx textoff
|
|
Report an error if DT_TEXTREL is set, i.e., if the position-independent
|
|
or shared object has dynamic relocations in read-only sections. Don't
|
|
report an error if @samp{notext} or @samp{textoff}.
|
|
|
|
@item undefs
|
|
Do not report unresolved symbol references from regular object files,
|
|
either when creating an executable, or when creating a shared library.
|
|
This option is the inverse of @samp{-z defs}.
|
|
|
|
@end table
|
|
|
|
Other keywords are ignored for Solaris compatibility.
|
|
|
|
@kindex -(
|
|
@cindex groups of archives
|
|
@item -( @var{archives} -)
|
|
@itemx --start-group @var{archives} --end-group
|
|
The @var{archives} should be a list of archive files. They may be
|
|
either explicit file names, or @samp{-l} options.
|
|
|
|
The specified archives are searched repeatedly until no new undefined
|
|
references are created. Normally, an archive is searched only once in
|
|
the order that it is specified on the command line. If a symbol in that
|
|
archive is needed to resolve an undefined symbol referred to by an
|
|
object in an archive that appears later on the command line, the linker
|
|
would not be able to resolve that reference. By grouping the archives,
|
|
they will all be searched repeatedly until all possible references are
|
|
resolved.
|
|
|
|
Using this option has a significant performance cost. It is best to use
|
|
it only when there are unavoidable circular references between two or
|
|
more archives.
|
|
|
|
@kindex --accept-unknown-input-arch
|
|
@kindex --no-accept-unknown-input-arch
|
|
@item --accept-unknown-input-arch
|
|
@itemx --no-accept-unknown-input-arch
|
|
Tells the linker to accept input files whose architecture cannot be
|
|
recognised. The assumption is that the user knows what they are doing
|
|
and deliberately wants to link in these unknown input files. This was
|
|
the default behaviour of the linker, before release 2.14. The default
|
|
behaviour from release 2.14 onwards is to reject such input files, and
|
|
so the @samp{--accept-unknown-input-arch} option has been added to
|
|
restore the old behaviour.
|
|
|
|
@kindex --as-needed
|
|
@kindex --no-as-needed
|
|
@item --as-needed
|
|
@itemx --no-as-needed
|
|
This option affects ELF DT_NEEDED tags for dynamic libraries mentioned
|
|
on the command line after the @option{--as-needed} option. Normally
|
|
the linker will add a DT_NEEDED tag for each dynamic library mentioned
|
|
on the command line, regardless of whether the library is actually
|
|
needed or not. @option{--as-needed} causes a DT_NEEDED tag to only be
|
|
emitted for a library that @emph{at that point in the link} satisfies a
|
|
non-weak undefined symbol reference from a regular object file or, if
|
|
the library is not found in the DT_NEEDED lists of other needed libraries, a
|
|
non-weak undefined symbol reference from another needed dynamic library.
|
|
Object files or libraries appearing on the command line @emph{after}
|
|
the library in question do not affect whether the library is seen as
|
|
needed. This is similar to the rules for extraction of object files
|
|
from archives. @option{--no-as-needed} restores the default behaviour.
|
|
|
|
@kindex --add-needed
|
|
@kindex --no-add-needed
|
|
@item --add-needed
|
|
@itemx --no-add-needed
|
|
These two options have been deprecated because of the similarity of
|
|
their names to the @option{--as-needed} and @option{--no-as-needed}
|
|
options. They have been replaced by @option{--copy-dt-needed-entries}
|
|
and @option{--no-copy-dt-needed-entries}.
|
|
|
|
@kindex -assert @var{keyword}
|
|
@item -assert @var{keyword}
|
|
This option is ignored for SunOS compatibility.
|
|
|
|
@kindex -Bdynamic
|
|
@kindex -dy
|
|
@kindex -call_shared
|
|
@item -Bdynamic
|
|
@itemx -dy
|
|
@itemx -call_shared
|
|
Link against dynamic libraries. This is only meaningful on platforms
|
|
for which shared libraries are supported. This option is normally the
|
|
default on such platforms. The different variants of this option are
|
|
for compatibility with various systems. You may use this option
|
|
multiple times on the command line: it affects library searching for
|
|
@option{-l} options which follow it.
|
|
|
|
@kindex -Bgroup
|
|
@item -Bgroup
|
|
Set the @code{DF_1_GROUP} flag in the @code{DT_FLAGS_1} entry in the dynamic
|
|
section. This causes the runtime linker to handle lookups in this
|
|
object and its dependencies to be performed only inside the group.
|
|
@option{--unresolved-symbols=report-all} is implied. This option is
|
|
only meaningful on ELF platforms which support shared libraries.
|
|
|
|
@kindex -Bstatic
|
|
@kindex -dn
|
|
@kindex -non_shared
|
|
@kindex -static
|
|
@item -Bstatic
|
|
@itemx -dn
|
|
@itemx -non_shared
|
|
@itemx -static
|
|
Do not link against shared libraries. This is only meaningful on
|
|
platforms for which shared libraries are supported. The different
|
|
variants of this option are for compatibility with various systems. You
|
|
may use this option multiple times on the command line: it affects
|
|
library searching for @option{-l} options which follow it. This
|
|
option also implies @option{--unresolved-symbols=report-all}. This
|
|
option can be used with @option{-shared}. Doing so means that a
|
|
shared library is being created but that all of the library's external
|
|
references must be resolved by pulling in entries from static
|
|
libraries.
|
|
|
|
@kindex -Bsymbolic
|
|
@item -Bsymbolic
|
|
When creating a shared library, bind references to global symbols to the
|
|
definition within the shared library, if any. Normally, it is possible
|
|
for a program linked against a shared library to override the definition
|
|
within the shared library. This option is only meaningful on ELF
|
|
platforms which support shared libraries.
|
|
|
|
@kindex -Bsymbolic-functions
|
|
@item -Bsymbolic-functions
|
|
When creating a shared library, bind references to global function
|
|
symbols to the definition within the shared library, if any.
|
|
This option is only meaningful on ELF platforms which support shared
|
|
libraries.
|
|
|
|
@kindex --dynamic-list=@var{dynamic-list-file}
|
|
@item --dynamic-list=@var{dynamic-list-file}
|
|
Specify the name of a dynamic list file to the linker. This is
|
|
typically used when creating shared libraries to specify a list of
|
|
global symbols whose references shouldn't be bound to the definition
|
|
within the shared library, or creating dynamically linked executables
|
|
to specify a list of symbols which should be added to the symbol table
|
|
in the executable. This option is only meaningful on ELF platforms
|
|
which support shared libraries.
|
|
|
|
The format of the dynamic list is the same as the version node without
|
|
scope and node name. See @ref{VERSION} for more information.
|
|
|
|
@kindex --dynamic-list-data
|
|
@item --dynamic-list-data
|
|
Include all global data symbols to the dynamic list.
|
|
|
|
@kindex --dynamic-list-cpp-new
|
|
@item --dynamic-list-cpp-new
|
|
Provide the builtin dynamic list for C++ operator new and delete. It
|
|
is mainly useful for building shared libstdc++.
|
|
|
|
@kindex --dynamic-list-cpp-typeinfo
|
|
@item --dynamic-list-cpp-typeinfo
|
|
Provide the builtin dynamic list for C++ runtime type identification.
|
|
|
|
@kindex --check-sections
|
|
@kindex --no-check-sections
|
|
@item --check-sections
|
|
@itemx --no-check-sections
|
|
Asks the linker @emph{not} to check section addresses after they have
|
|
been assigned to see if there are any overlaps. Normally the linker will
|
|
perform this check, and if it finds any overlaps it will produce
|
|
suitable error messages. The linker does know about, and does make
|
|
allowances for sections in overlays. The default behaviour can be
|
|
restored by using the command-line switch @option{--check-sections}.
|
|
Section overlap is not usually checked for relocatable links. You can
|
|
force checking in that case by using the @option{--check-sections}
|
|
option.
|
|
|
|
@kindex --copy-dt-needed-entries
|
|
@kindex --no-copy-dt-needed-entries
|
|
@item --copy-dt-needed-entries
|
|
@itemx --no-copy-dt-needed-entries
|
|
This option affects the treatment of dynamic libraries referred to
|
|
by DT_NEEDED tags @emph{inside} ELF dynamic libraries mentioned on the
|
|
command line. Normally the linker won't add a DT_NEEDED tag to the
|
|
output binary for each library mentioned in a DT_NEEDED tag in an
|
|
input dynamic library. With @option{--copy-dt-needed-entries}
|
|
specified on the command line however any dynamic libraries that
|
|
follow it will have their DT_NEEDED entries added. The default
|
|
behaviour can be restored with @option{--no-copy-dt-needed-entries}.
|
|
|
|
This option also has an effect on the resolution of symbols in dynamic
|
|
libraries. With @option{--copy-dt-needed-entries} dynamic libraries
|
|
mentioned on the command line will be recursively searched, following
|
|
their DT_NEEDED tags to other libraries, in order to resolve symbols
|
|
required by the output binary. With the default setting however
|
|
the searching of dynamic libraries that follow it will stop with the
|
|
dynamic library itself. No DT_NEEDED links will be traversed to resolve
|
|
symbols.
|
|
|
|
@cindex cross reference table
|
|
@kindex --cref
|
|
@item --cref
|
|
Output a cross reference table. If a linker map file is being
|
|
generated, the cross reference table is printed to the map file.
|
|
Otherwise, it is printed on the standard output.
|
|
|
|
The format of the table is intentionally simple, so that it may be
|
|
easily processed by a script if necessary. The symbols are printed out,
|
|
sorted by name. For each symbol, a list of file names is given. If the
|
|
symbol is defined, the first file listed is the location of the
|
|
definition. If the symbol is defined as a common value then any files
|
|
where this happens appear next. Finally any files that reference the
|
|
symbol are listed.
|
|
|
|
@cindex common allocation
|
|
@kindex --no-define-common
|
|
@item --no-define-common
|
|
This option inhibits the assignment of addresses to common symbols.
|
|
The script command @code{INHIBIT_COMMON_ALLOCATION} has the same effect.
|
|
@xref{Miscellaneous Commands}.
|
|
|
|
The @samp{--no-define-common} option allows decoupling
|
|
the decision to assign addresses to Common symbols from the choice
|
|
of the output file type; otherwise a non-Relocatable output type
|
|
forces assigning addresses to Common symbols.
|
|
Using @samp{--no-define-common} allows Common symbols that are referenced
|
|
from a shared library to be assigned addresses only in the main program.
|
|
This eliminates the unused duplicate space in the shared library,
|
|
and also prevents any possible confusion over resolving to the wrong
|
|
duplicate when there are many dynamic modules with specialized search
|
|
paths for runtime symbol resolution.
|
|
|
|
@cindex group allocation in linker script
|
|
@cindex section groups
|
|
@cindex COMDAT
|
|
@kindex --force-group-allocation
|
|
@item --force-group-allocation
|
|
This option causes the linker to place section group members like
|
|
normal input sections, and to delete the section groups. This is the
|
|
default behaviour for a final link but this option can be used to
|
|
change the behaviour of a relocatable link (@samp{-r}). The script
|
|
command @code{FORCE_GROUP_ALLOCATION} has the same
|
|
effect. @xref{Miscellaneous Commands}.
|
|
|
|
@cindex symbols, from command line
|
|
@kindex --defsym=@var{symbol}=@var{exp}
|
|
@item --defsym=@var{symbol}=@var{expression}
|
|
Create a global symbol in the output file, containing the absolute
|
|
address given by @var{expression}. You may use this option as many
|
|
times as necessary to define multiple symbols in the command line. A
|
|
limited form of arithmetic is supported for the @var{expression} in this
|
|
context: you may give a hexadecimal constant or the name of an existing
|
|
symbol, or use @code{+} and @code{-} to add or subtract hexadecimal
|
|
constants or symbols. If you need more elaborate expressions, consider
|
|
using the linker command language from a script (@pxref{Assignments}).
|
|
@emph{Note:} there should be no white space between @var{symbol}, the
|
|
equals sign (``@key{=}''), and @var{expression}.
|
|
|
|
@cindex demangling, from command line
|
|
@kindex --demangle[=@var{style}]
|
|
@kindex --no-demangle
|
|
@item --demangle[=@var{style}]
|
|
@itemx --no-demangle
|
|
These options control whether to demangle symbol names in error messages
|
|
and other output. When the linker is told to demangle, it tries to
|
|
present symbol names in a readable fashion: it strips leading
|
|
underscores if they are used by the object file format, and converts C++
|
|
mangled symbol names into user readable names. Different compilers have
|
|
different mangling styles. The optional demangling style argument can be used
|
|
to choose an appropriate demangling style for your compiler. The linker will
|
|
demangle by default unless the environment variable @samp{COLLECT_NO_DEMANGLE}
|
|
is set. These options may be used to override the default.
|
|
|
|
@cindex dynamic linker, from command line
|
|
@kindex -I@var{file}
|
|
@kindex --dynamic-linker=@var{file}
|
|
@item -I@var{file}
|
|
@itemx --dynamic-linker=@var{file}
|
|
Set the name of the dynamic linker. This is only meaningful when
|
|
generating dynamically linked ELF executables. The default dynamic
|
|
linker is normally correct; don't use this unless you know what you are
|
|
doing.
|
|
|
|
@kindex --no-dynamic-linker
|
|
@item --no-dynamic-linker
|
|
When producing an executable file, omit the request for a dynamic
|
|
linker to be used at load-time. This is only meaningful for ELF
|
|
executables that contain dynamic relocations, and usually requires
|
|
entry point code that is capable of processing these relocations.
|
|
|
|
@kindex --embedded-relocs
|
|
@item --embedded-relocs
|
|
This option is similar to the @option{--emit-relocs} option except
|
|
that the relocs are stored in a target-specific section. This option
|
|
is only supported by the @samp{BFIN}, @samp{CR16} and @emph{M68K}
|
|
targets.
|
|
|
|
@kindex --disable-multiple-abs-defs
|
|
@item --disable-multiple-abs-defs
|
|
Do not allow multiple definitions with symbols included
|
|
in filename invoked by -R or --just-symbols
|
|
|
|
@kindex --fatal-warnings
|
|
@kindex --no-fatal-warnings
|
|
@item --fatal-warnings
|
|
@itemx --no-fatal-warnings
|
|
Treat all warnings as errors. The default behaviour can be restored
|
|
with the option @option{--no-fatal-warnings}.
|
|
|
|
@kindex --force-exe-suffix
|
|
@item --force-exe-suffix
|
|
Make sure that an output file has a .exe suffix.
|
|
|
|
If a successfully built fully linked output file does not have a
|
|
@code{.exe} or @code{.dll} suffix, this option forces the linker to copy
|
|
the output file to one of the same name with a @code{.exe} suffix. This
|
|
option is useful when using unmodified Unix makefiles on a Microsoft
|
|
Windows host, since some versions of Windows won't run an image unless
|
|
it ends in a @code{.exe} suffix.
|
|
|
|
@kindex --gc-sections
|
|
@kindex --no-gc-sections
|
|
@cindex garbage collection
|
|
@item --gc-sections
|
|
@itemx --no-gc-sections
|
|
Enable garbage collection of unused input sections. It is ignored on
|
|
targets that do not support this option. The default behaviour (of not
|
|
performing this garbage collection) can be restored by specifying
|
|
@samp{--no-gc-sections} on the command line. Note that garbage
|
|
collection for COFF and PE format targets is supported, but the
|
|
implementation is currently considered to be experimental.
|
|
|
|
@samp{--gc-sections} decides which input sections are used by
|
|
examining symbols and relocations. The section containing the entry
|
|
symbol and all sections containing symbols undefined on the
|
|
command-line will be kept, as will sections containing symbols
|
|
referenced by dynamic objects. Note that when building shared
|
|
libraries, the linker must assume that any visible symbol is
|
|
referenced. Once this initial set of sections has been determined,
|
|
the linker recursively marks as used any section referenced by their
|
|
relocations. See @samp{--entry}, @samp{--undefined}, and
|
|
@samp{--gc-keep-exported}.
|
|
|
|
This option can be set when doing a partial link (enabled with option
|
|
@samp{-r}). In this case the root of symbols kept must be explicitly
|
|
specified either by one of the options @samp{--entry},
|
|
@samp{--undefined}, or @samp{--gc-keep-exported} or by a @code{ENTRY}
|
|
command in the linker script.
|
|
|
|
@kindex --print-gc-sections
|
|
@kindex --no-print-gc-sections
|
|
@cindex garbage collection
|
|
@item --print-gc-sections
|
|
@itemx --no-print-gc-sections
|
|
List all sections removed by garbage collection. The listing is
|
|
printed on stderr. This option is only effective if garbage
|
|
collection has been enabled via the @samp{--gc-sections}) option. The
|
|
default behaviour (of not listing the sections that are removed) can
|
|
be restored by specifying @samp{--no-print-gc-sections} on the command
|
|
line.
|
|
|
|
@kindex --gc-keep-exported
|
|
@cindex garbage collection
|
|
@item --gc-keep-exported
|
|
When @samp{--gc-sections} is enabled, this option prevents garbage
|
|
collection of unused input sections that contain global symbols having
|
|
default or protected visibility. This option is intended to be used for
|
|
executables where unreferenced sections would otherwise be garbage
|
|
collected regardless of the external visibility of contained symbols.
|
|
Note that this option has no effect when linking shared objects since
|
|
it is already the default behaviour. This option is only supported for
|
|
ELF format targets.
|
|
|
|
@kindex --print-output-format
|
|
@cindex output format
|
|
@item --print-output-format
|
|
Print the name of the default output format (perhaps influenced by
|
|
other command-line options). This is the string that would appear
|
|
in an @code{OUTPUT_FORMAT} linker script command (@pxref{File Commands}).
|
|
|
|
@kindex --print-memory-usage
|
|
@cindex memory usage
|
|
@item --print-memory-usage
|
|
Print used size, total size and used size of memory regions created with
|
|
the @ref{MEMORY} command. This is useful on embedded targets to have a
|
|
quick view of amount of free memory. The format of the output has one
|
|
headline and one line per region. It is both human readable and easily
|
|
parsable by tools. Here is an example of an output:
|
|
|
|
@smallexample
|
|
Memory region Used Size Region Size %age Used
|
|
ROM: 256 KB 1 MB 25.00%
|
|
RAM: 32 B 2 GB 0.00%
|
|
@end smallexample
|
|
|
|
@cindex help
|
|
@cindex usage
|
|
@kindex --help
|
|
@item --help
|
|
Print a summary of the command-line options on the standard output and exit.
|
|
|
|
@kindex --target-help
|
|
@item --target-help
|
|
Print a summary of all target-specific options on the standard output and exit.
|
|
|
|
@kindex -Map=@var{mapfile}
|
|
@item -Map=@var{mapfile}
|
|
Print a link map to the file @var{mapfile}. See the description of the
|
|
@option{-M} option, above. Specifying a directory as @var{mapfile}
|
|
causes the linker map to be written into a file inside the directory.
|
|
The name of the file is based upon the @var{output} filename with
|
|
@code{.map} appended.
|
|
|
|
@cindex memory usage
|
|
@kindex --no-keep-memory
|
|
@item --no-keep-memory
|
|
@command{ld} normally optimizes for speed over memory usage by caching the
|
|
symbol tables of input files in memory. This option tells @command{ld} to
|
|
instead optimize for memory usage, by rereading the symbol tables as
|
|
necessary. This may be required if @command{ld} runs out of memory space
|
|
while linking a large executable.
|
|
|
|
@kindex --no-undefined
|
|
@kindex -z defs
|
|
@kindex -z undefs
|
|
@item --no-undefined
|
|
@itemx -z defs
|
|
Report unresolved symbol references from regular object files. This
|
|
is done even if the linker is creating a non-symbolic shared library.
|
|
The switch @option{--[no-]allow-shlib-undefined} controls the
|
|
behaviour for reporting unresolved references found in shared
|
|
libraries being linked in.
|
|
|
|
The effects of this option can be reverted by using @code{-z undefs}.
|
|
|
|
@kindex --allow-multiple-definition
|
|
@kindex -z muldefs
|
|
@item --allow-multiple-definition
|
|
@itemx -z muldefs
|
|
Normally when a symbol is defined multiple times, the linker will
|
|
report a fatal error. These options allow multiple definitions and the
|
|
first definition will be used.
|
|
|
|
@kindex --allow-shlib-undefined
|
|
@kindex --no-allow-shlib-undefined
|
|
@item --allow-shlib-undefined
|
|
@itemx --no-allow-shlib-undefined
|
|
Allows or disallows undefined symbols in shared libraries.
|
|
This switch is similar to @option{--no-undefined} except that it
|
|
determines the behaviour when the undefined symbols are in a
|
|
shared library rather than a regular object file. It does not affect
|
|
how undefined symbols in regular object files are handled.
|
|
|
|
The default behaviour is to report errors for any undefined symbols
|
|
referenced in shared libraries if the linker is being used to create
|
|
an executable, but to allow them if the linker is being used to create
|
|
a shared library.
|
|
|
|
The reasons for allowing undefined symbol references in shared
|
|
libraries specified at link time are that:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
A shared library specified at link time may not be the same as the one
|
|
that is available at load time, so the symbol might actually be
|
|
resolvable at load time.
|
|
@item
|
|
There are some operating systems, eg BeOS and HPPA, where undefined
|
|
symbols in shared libraries are normal.
|
|
|
|
The BeOS kernel for example patches shared libraries at load time to
|
|
select whichever function is most appropriate for the current
|
|
architecture. This is used, for example, to dynamically select an
|
|
appropriate memset function.
|
|
@end itemize
|
|
|
|
@kindex --no-undefined-version
|
|
@item --no-undefined-version
|
|
Normally when a symbol has an undefined version, the linker will ignore
|
|
it. This option disallows symbols with undefined version and a fatal error
|
|
will be issued instead.
|
|
|
|
@kindex --default-symver
|
|
@item --default-symver
|
|
Create and use a default symbol version (the soname) for unversioned
|
|
exported symbols.
|
|
|
|
@kindex --default-imported-symver
|
|
@item --default-imported-symver
|
|
Create and use a default symbol version (the soname) for unversioned
|
|
imported symbols.
|
|
|
|
@kindex --no-warn-mismatch
|
|
@item --no-warn-mismatch
|
|
Normally @command{ld} will give an error if you try to link together input
|
|
files that are mismatched for some reason, perhaps because they have
|
|
been compiled for different processors or for different endiannesses.
|
|
This option tells @command{ld} that it should silently permit such possible
|
|
errors. This option should only be used with care, in cases when you
|
|
have taken some special action that ensures that the linker errors are
|
|
inappropriate.
|
|
|
|
@kindex --no-warn-search-mismatch
|
|
@item --no-warn-search-mismatch
|
|
Normally @command{ld} will give a warning if it finds an incompatible
|
|
library during a library search. This option silences the warning.
|
|
|
|
@kindex --no-whole-archive
|
|
@item --no-whole-archive
|
|
Turn off the effect of the @option{--whole-archive} option for subsequent
|
|
archive files.
|
|
|
|
@cindex output file after errors
|
|
@kindex --noinhibit-exec
|
|
@item --noinhibit-exec
|
|
Retain the executable output file whenever it is still usable.
|
|
Normally, the linker will not produce an output file if it encounters
|
|
errors during the link process; it exits without writing an output file
|
|
when it issues any error whatsoever.
|
|
|
|
@kindex -nostdlib
|
|
@item -nostdlib
|
|
Only search library directories explicitly specified on the
|
|
command line. Library directories specified in linker scripts
|
|
(including linker scripts specified on the command line) are ignored.
|
|
|
|
@ifclear SingleFormat
|
|
@kindex --oformat=@var{output-format}
|
|
@item --oformat=@var{output-format}
|
|
@command{ld} may be configured to support more than one kind of object
|
|
file. If your @command{ld} is configured this way, you can use the
|
|
@samp{--oformat} option to specify the binary format for the output
|
|
object file. Even when @command{ld} is configured to support alternative
|
|
object formats, you don't usually need to specify this, as @command{ld}
|
|
should be configured to produce as a default output format the most
|
|
usual format on each machine. @var{output-format} is a text string, the
|
|
name of a particular format supported by the BFD libraries. (You can
|
|
list the available binary formats with @samp{objdump -i}.) The script
|
|
command @code{OUTPUT_FORMAT} can also specify the output format, but
|
|
this option overrides it. @xref{BFD}.
|
|
@end ifclear
|
|
|
|
@kindex --out-implib
|
|
@item --out-implib @var{file}
|
|
Create an import library in @var{file} corresponding to the executable
|
|
the linker is generating (eg. a DLL or ELF program). This import
|
|
library (which should be called @code{*.dll.a} or @code{*.a} for DLLs)
|
|
may be used to link clients against the generated executable; this
|
|
behaviour makes it possible to skip a separate import library creation
|
|
step (eg. @code{dlltool} for DLLs). This option is only available for
|
|
the i386 PE and ELF targetted ports of the linker.
|
|
|
|
@kindex -pie
|
|
@kindex --pic-executable
|
|
@item -pie
|
|
@itemx --pic-executable
|
|
@cindex position independent executables
|
|
Create a position independent executable. This is currently only supported on
|
|
ELF platforms. Position independent executables are similar to shared
|
|
libraries in that they are relocated by the dynamic linker to the virtual
|
|
address the OS chooses for them (which can vary between invocations). Like
|
|
normal dynamically linked executables they can be executed and symbols
|
|
defined in the executable cannot be overridden by shared libraries.
|
|
|
|
@kindex -qmagic
|
|
@item -qmagic
|
|
This option is ignored for Linux compatibility.
|
|
|
|
@kindex -Qy
|
|
@item -Qy
|
|
This option is ignored for SVR4 compatibility.
|
|
|
|
@kindex --relax
|
|
@cindex synthesizing linker
|
|
@cindex relaxing addressing modes
|
|
@cindex --no-relax
|
|
@item --relax
|
|
@itemx --no-relax
|
|
An option with machine dependent effects.
|
|
@ifset GENERIC
|
|
This option is only supported on a few targets.
|
|
@end ifset
|
|
@ifset H8300
|
|
@xref{H8/300,,@command{ld} and the H8/300}.
|
|
@end ifset
|
|
@ifset XTENSA
|
|
@xref{Xtensa,, @command{ld} and Xtensa Processors}.
|
|
@end ifset
|
|
@ifset M68HC11
|
|
@xref{M68HC11/68HC12,,@command{ld} and the 68HC11 and 68HC12}.
|
|
@end ifset
|
|
@ifset NIOSII
|
|
@xref{Nios II,,@command{ld} and the Altera Nios II}.
|
|
@end ifset
|
|
@ifset POWERPC
|
|
@xref{PowerPC ELF32,,@command{ld} and PowerPC 32-bit ELF Support}.
|
|
@end ifset
|
|
|
|
On some platforms the @samp{--relax} option performs target-specific,
|
|
global optimizations that become possible when the linker resolves
|
|
addressing in the program, such as relaxing address modes,
|
|
synthesizing new instructions, selecting shorter version of current
|
|
instructions, and combining constant values.
|
|
|
|
On some platforms these link time global optimizations may make symbolic
|
|
debugging of the resulting executable impossible.
|
|
@ifset GENERIC
|
|
This is known to be the case for the Matsushita MN10200 and MN10300
|
|
family of processors.
|
|
@end ifset
|
|
|
|
@ifset GENERIC
|
|
On platforms where this is not supported, @samp{--relax} is accepted,
|
|
but ignored.
|
|
@end ifset
|
|
|
|
On platforms where @samp{--relax} is accepted the option
|
|
@samp{--no-relax} can be used to disable the feature.
|
|
|
|
@cindex retaining specified symbols
|
|
@cindex stripping all but some symbols
|
|
@cindex symbols, retaining selectively
|
|
@kindex --retain-symbols-file=@var{filename}
|
|
@item --retain-symbols-file=@var{filename}
|
|
Retain @emph{only} the symbols listed in the file @var{filename},
|
|
discarding all others. @var{filename} is simply a flat file, with one
|
|
symbol name per line. This option is especially useful in environments
|
|
@ifset GENERIC
|
|
(such as VxWorks)
|
|
@end ifset
|
|
where a large global symbol table is accumulated gradually, to conserve
|
|
run-time memory.
|
|
|
|
@samp{--retain-symbols-file} does @emph{not} discard undefined symbols,
|
|
or symbols needed for relocations.
|
|
|
|
You may only specify @samp{--retain-symbols-file} once in the command
|
|
line. It overrides @samp{-s} and @samp{-S}.
|
|
|
|
@ifset GENERIC
|
|
@item -rpath=@var{dir}
|
|
@cindex runtime library search path
|
|
@kindex -rpath=@var{dir}
|
|
Add a directory to the runtime library search path. This is used when
|
|
linking an ELF executable with shared objects. All @option{-rpath}
|
|
arguments are concatenated and passed to the runtime linker, which uses
|
|
them to locate shared objects at runtime.
|
|
|
|
The @option{-rpath} option is also used when locating shared objects which
|
|
are needed by shared objects explicitly included in the link; see the
|
|
description of the @option{-rpath-link} option. Searching @option{-rpath}
|
|
in this way is only supported by native linkers and cross linkers which
|
|
have been configured with the @option{--with-sysroot} option.
|
|
|
|
If @option{-rpath} is not used when linking an ELF executable, the
|
|
contents of the environment variable @code{LD_RUN_PATH} will be used if it
|
|
is defined.
|
|
|
|
The @option{-rpath} option may also be used on SunOS. By default, on
|
|
SunOS, the linker will form a runtime search path out of all the
|
|
@option{-L} options it is given. If a @option{-rpath} option is used, the
|
|
runtime search path will be formed exclusively using the @option{-rpath}
|
|
options, ignoring the @option{-L} options. This can be useful when using
|
|
gcc, which adds many @option{-L} options which may be on NFS mounted
|
|
file systems.
|
|
|
|
For compatibility with other ELF linkers, if the @option{-R} option is
|
|
followed by a directory name, rather than a file name, it is treated as
|
|
the @option{-rpath} option.
|
|
@end ifset
|
|
|
|
@ifset GENERIC
|
|
@cindex link-time runtime library search path
|
|
@kindex -rpath-link=@var{dir}
|
|
@item -rpath-link=@var{dir}
|
|
When using ELF or SunOS, one shared library may require another. This
|
|
happens when an @code{ld -shared} link includes a shared library as one
|
|
of the input files.
|
|
|
|
When the linker encounters such a dependency when doing a non-shared,
|
|
non-relocatable link, it will automatically try to locate the required
|
|
shared library and include it in the link, if it is not included
|
|
explicitly. In such a case, the @option{-rpath-link} option
|
|
specifies the first set of directories to search. The
|
|
@option{-rpath-link} option may specify a sequence of directory names
|
|
either by specifying a list of names separated by colons, or by
|
|
appearing multiple times.
|
|
|
|
The tokens @var{$ORIGIN} and @var{$LIB} can appear in these search
|
|
directories. They will be replaced by the full path to the directory
|
|
containing the program or shared object in the case of @var{$ORIGIN}
|
|
and either @samp{lib} - for 32-bit binaries - or @samp{lib64} - for
|
|
64-bit binaries - in the case of @var{$LIB}.
|
|
|
|
The alternative form of these tokens - @var{$@{ORIGIN@}} and
|
|
@var{$@{LIB@}} can also be used. The token @var{$PLATFORM} is not
|
|
supported.
|
|
|
|
This option should be used with caution as it overrides the search path
|
|
that may have been hard compiled into a shared library. In such a case it
|
|
is possible to use unintentionally a different search path than the
|
|
runtime linker would do.
|
|
|
|
The linker uses the following search paths to locate required shared
|
|
libraries:
|
|
|
|
@enumerate
|
|
@item
|
|
Any directories specified by @option{-rpath-link} options.
|
|
@item
|
|
Any directories specified by @option{-rpath} options. The difference
|
|
between @option{-rpath} and @option{-rpath-link} is that directories
|
|
specified by @option{-rpath} options are included in the executable and
|
|
used at runtime, whereas the @option{-rpath-link} option is only effective
|
|
at link time. Searching @option{-rpath} in this way is only supported
|
|
by native linkers and cross linkers which have been configured with
|
|
the @option{--with-sysroot} option.
|
|
@item
|
|
On an ELF system, for native linkers, if the @option{-rpath} and
|
|
@option{-rpath-link} options were not used, search the contents of the
|
|
environment variable @code{LD_RUN_PATH}.
|
|
@item
|
|
On SunOS, if the @option{-rpath} option was not used, search any
|
|
directories specified using @option{-L} options.
|
|
@item
|
|
For a native linker, search the contents of the environment
|
|
variable @code{LD_LIBRARY_PATH}.
|
|
@item
|
|
For a native ELF linker, the directories in @code{DT_RUNPATH} or
|
|
@code{DT_RPATH} of a shared library are searched for shared
|
|
libraries needed by it. The @code{DT_RPATH} entries are ignored if
|
|
@code{DT_RUNPATH} entries exist.
|
|
@item
|
|
The default directories, normally @file{/lib} and @file{/usr/lib}.
|
|
@item
|
|
For a linker for a Linux system, if the file @file{/etc/ld.so.conf}
|
|
exists, the list of directories found in that file. Note: the path
|
|
to this file is prefixed with the @code{sysroot} value, if that is
|
|
defined, and then any @code{prefix} string if the linker was
|
|
configured with the @command{--prefix=<path>} option.
|
|
@item
|
|
For a native linker on a FreeBSD system, any directories specified by
|
|
the @code{_PATH_ELF_HINTS} macro defined in the @file{elf-hints.h}
|
|
header file.
|
|
@item
|
|
Any directories specifed by a @code{SEARCH_DIR} command in the
|
|
linker script being used.
|
|
@end enumerate
|
|
|
|
If the required shared library is not found, the linker will issue a
|
|
warning and continue with the link.
|
|
@end ifset
|
|
|
|
@kindex -shared
|
|
@kindex -Bshareable
|
|
@item -shared
|
|
@itemx -Bshareable
|
|
@cindex shared libraries
|
|
Create a shared library. This is currently only supported on ELF, XCOFF
|
|
and SunOS platforms. On SunOS, the linker will automatically create a
|
|
shared library if the @option{-e} option is not used and there are
|
|
undefined symbols in the link.
|
|
|
|
@kindex --sort-common
|
|
@item --sort-common
|
|
@itemx --sort-common=ascending
|
|
@itemx --sort-common=descending
|
|
This option tells @command{ld} to sort the common symbols by alignment in
|
|
ascending or descending order when it places them in the appropriate output
|
|
sections. The symbol alignments considered are sixteen-byte or larger,
|
|
eight-byte, four-byte, two-byte, and one-byte. This is to prevent gaps
|
|
between symbols due to alignment constraints. If no sorting order is
|
|
specified, then descending order is assumed.
|
|
|
|
@kindex --sort-section=name
|
|
@item --sort-section=name
|
|
This option will apply @code{SORT_BY_NAME} to all wildcard section
|
|
patterns in the linker script.
|
|
|
|
@kindex --sort-section=alignment
|
|
@item --sort-section=alignment
|
|
This option will apply @code{SORT_BY_ALIGNMENT} to all wildcard section
|
|
patterns in the linker script.
|
|
|
|
@kindex --spare-dynamic-tags
|
|
@item --spare-dynamic-tags=@var{count}
|
|
This option specifies the number of empty slots to leave in the
|
|
.dynamic section of ELF shared objects. Empty slots may be needed by
|
|
post processing tools, such as the prelinker. The default is 5.
|
|
|
|
@kindex --split-by-file
|
|
@item --split-by-file[=@var{size}]
|
|
Similar to @option{--split-by-reloc} but creates a new output section for
|
|
each input file when @var{size} is reached. @var{size} defaults to a
|
|
size of 1 if not given.
|
|
|
|
@kindex --split-by-reloc
|
|
@item --split-by-reloc[=@var{count}]
|
|
Tries to creates extra sections in the output file so that no single
|
|
output section in the file contains more than @var{count} relocations.
|
|
This is useful when generating huge relocatable files for downloading into
|
|
certain real time kernels with the COFF object file format; since COFF
|
|
cannot represent more than 65535 relocations in a single section. Note
|
|
that this will fail to work with object file formats which do not
|
|
support arbitrary sections. The linker will not split up individual
|
|
input sections for redistribution, so if a single input section contains
|
|
more than @var{count} relocations one output section will contain that
|
|
many relocations. @var{count} defaults to a value of 32768.
|
|
|
|
@kindex --stats
|
|
@item --stats
|
|
Compute and display statistics about the operation of the linker, such
|
|
as execution time and memory usage.
|
|
|
|
@kindex --sysroot=@var{directory}
|
|
@item --sysroot=@var{directory}
|
|
Use @var{directory} as the location of the sysroot, overriding the
|
|
configure-time default. This option is only supported by linkers
|
|
that were configured using @option{--with-sysroot}.
|
|
|
|
@kindex --task-link
|
|
@item --task-link
|
|
This is used by COFF/PE based targets to create a task-linked object
|
|
file where all of the global symbols have been converted to statics.
|
|
|
|
@kindex --traditional-format
|
|
@cindex traditional format
|
|
@item --traditional-format
|
|
For some targets, the output of @command{ld} is different in some ways from
|
|
the output of some existing linker. This switch requests @command{ld} to
|
|
use the traditional format instead.
|
|
|
|
@cindex dbx
|
|
For example, on SunOS, @command{ld} combines duplicate entries in the
|
|
symbol string table. This can reduce the size of an output file with
|
|
full debugging information by over 30 percent. Unfortunately, the SunOS
|
|
@code{dbx} program can not read the resulting program (@code{gdb} has no
|
|
trouble). The @samp{--traditional-format} switch tells @command{ld} to not
|
|
combine duplicate entries.
|
|
|
|
@kindex --section-start=@var{sectionname}=@var{org}
|
|
@item --section-start=@var{sectionname}=@var{org}
|
|
Locate a section in the output file at the absolute
|
|
address given by @var{org}. You may use this option as many
|
|
times as necessary to locate multiple sections in the command
|
|
line.
|
|
@var{org} must be a single hexadecimal integer;
|
|
for compatibility with other linkers, you may omit the leading
|
|
@samp{0x} usually associated with hexadecimal values. @emph{Note:} there
|
|
should be no white space between @var{sectionname}, the equals
|
|
sign (``@key{=}''), and @var{org}.
|
|
|
|
@kindex -Tbss=@var{org}
|
|
@kindex -Tdata=@var{org}
|
|
@kindex -Ttext=@var{org}
|
|
@cindex segment origins, cmd line
|
|
@item -Tbss=@var{org}
|
|
@itemx -Tdata=@var{org}
|
|
@itemx -Ttext=@var{org}
|
|
Same as @option{--section-start}, with @code{.bss}, @code{.data} or
|
|
@code{.text} as the @var{sectionname}.
|
|
|
|
@kindex -Ttext-segment=@var{org}
|
|
@item -Ttext-segment=@var{org}
|
|
@cindex text segment origin, cmd line
|
|
When creating an ELF executable, it will set the address of the first
|
|
byte of the text segment.
|
|
|
|
@kindex -Trodata-segment=@var{org}
|
|
@item -Trodata-segment=@var{org}
|
|
@cindex rodata segment origin, cmd line
|
|
When creating an ELF executable or shared object for a target where
|
|
the read-only data is in its own segment separate from the executable
|
|
text, it will set the address of the first byte of the read-only data segment.
|
|
|
|
@kindex -Tldata-segment=@var{org}
|
|
@item -Tldata-segment=@var{org}
|
|
@cindex ldata segment origin, cmd line
|
|
When creating an ELF executable or shared object for x86-64 medium memory
|
|
model, it will set the address of the first byte of the ldata segment.
|
|
|
|
@kindex --unresolved-symbols
|
|
@item --unresolved-symbols=@var{method}
|
|
Determine how to handle unresolved symbols. There are four possible
|
|
values for @samp{method}:
|
|
|
|
@table @samp
|
|
@item ignore-all
|
|
Do not report any unresolved symbols.
|
|
|
|
@item report-all
|
|
Report all unresolved symbols. This is the default.
|
|
|
|
@item ignore-in-object-files
|
|
Report unresolved symbols that are contained in shared libraries, but
|
|
ignore them if they come from regular object files.
|
|
|
|
@item ignore-in-shared-libs
|
|
Report unresolved symbols that come from regular object files, but
|
|
ignore them if they come from shared libraries. This can be useful
|
|
when creating a dynamic binary and it is known that all the shared
|
|
libraries that it should be referencing are included on the linker's
|
|
command line.
|
|
@end table
|
|
|
|
The behaviour for shared libraries on their own can also be controlled
|
|
by the @option{--[no-]allow-shlib-undefined} option.
|
|
|
|
Normally the linker will generate an error message for each reported
|
|
unresolved symbol but the option @option{--warn-unresolved-symbols}
|
|
can change this to a warning.
|
|
|
|
@kindex --verbose[=@var{NUMBER}]
|
|
@cindex verbose[=@var{NUMBER}]
|
|
@item --dll-verbose
|
|
@itemx --verbose[=@var{NUMBER}]
|
|
Display the version number for @command{ld} and list the linker emulations
|
|
supported. Display which input files can and cannot be opened. Display
|
|
the linker script being used by the linker. If the optional @var{NUMBER}
|
|
argument > 1, plugin symbol status will also be displayed.
|
|
|
|
@kindex --version-script=@var{version-scriptfile}
|
|
@cindex version script, symbol versions
|
|
@item --version-script=@var{version-scriptfile}
|
|
Specify the name of a version script to the linker. This is typically
|
|
used when creating shared libraries to specify additional information
|
|
about the version hierarchy for the library being created. This option
|
|
is only fully supported on ELF platforms which support shared libraries;
|
|
see @ref{VERSION}. It is partially supported on PE platforms, which can
|
|
use version scripts to filter symbol visibility in auto-export mode: any
|
|
symbols marked @samp{local} in the version script will not be exported.
|
|
@xref{WIN32}.
|
|
|
|
@kindex --warn-common
|
|
@cindex warnings, on combining symbols
|
|
@cindex combining symbols, warnings on
|
|
@item --warn-common
|
|
Warn when a common symbol is combined with another common symbol or with
|
|
a symbol definition. Unix linkers allow this somewhat sloppy practice,
|
|
but linkers on some other operating systems do not. This option allows
|
|
you to find potential problems from combining global symbols.
|
|
Unfortunately, some C libraries use this practice, so you may get some
|
|
warnings about symbols in the libraries as well as in your programs.
|
|
|
|
There are three kinds of global symbols, illustrated here by C examples:
|
|
|
|
@table @samp
|
|
@item int i = 1;
|
|
A definition, which goes in the initialized data section of the output
|
|
file.
|
|
|
|
@item extern int i;
|
|
An undefined reference, which does not allocate space.
|
|
There must be either a definition or a common symbol for the
|
|
variable somewhere.
|
|
|
|
@item int i;
|
|
A common symbol. If there are only (one or more) common symbols for a
|
|
variable, it goes in the uninitialized data area of the output file.
|
|
The linker merges multiple common symbols for the same variable into a
|
|
single symbol. If they are of different sizes, it picks the largest
|
|
size. The linker turns a common symbol into a declaration, if there is
|
|
a definition of the same variable.
|
|
@end table
|
|
|
|
The @samp{--warn-common} option can produce five kinds of warnings.
|
|
Each warning consists of a pair of lines: the first describes the symbol
|
|
just encountered, and the second describes the previous symbol
|
|
encountered with the same name. One or both of the two symbols will be
|
|
a common symbol.
|
|
|
|
@enumerate
|
|
@item
|
|
Turning a common symbol into a reference, because there is already a
|
|
definition for the symbol.
|
|
@smallexample
|
|
@var{file}(@var{section}): warning: common of `@var{symbol}'
|
|
overridden by definition
|
|
@var{file}(@var{section}): warning: defined here
|
|
@end smallexample
|
|
|
|
@item
|
|
Turning a common symbol into a reference, because a later definition for
|
|
the symbol is encountered. This is the same as the previous case,
|
|
except that the symbols are encountered in a different order.
|
|
@smallexample
|
|
@var{file}(@var{section}): warning: definition of `@var{symbol}'
|
|
overriding common
|
|
@var{file}(@var{section}): warning: common is here
|
|
@end smallexample
|
|
|
|
@item
|
|
Merging a common symbol with a previous same-sized common symbol.
|
|
@smallexample
|
|
@var{file}(@var{section}): warning: multiple common
|
|
of `@var{symbol}'
|
|
@var{file}(@var{section}): warning: previous common is here
|
|
@end smallexample
|
|
|
|
@item
|
|
Merging a common symbol with a previous larger common symbol.
|
|
@smallexample
|
|
@var{file}(@var{section}): warning: common of `@var{symbol}'
|
|
overridden by larger common
|
|
@var{file}(@var{section}): warning: larger common is here
|
|
@end smallexample
|
|
|
|
@item
|
|
Merging a common symbol with a previous smaller common symbol. This is
|
|
the same as the previous case, except that the symbols are
|
|
encountered in a different order.
|
|
@smallexample
|
|
@var{file}(@var{section}): warning: common of `@var{symbol}'
|
|
overriding smaller common
|
|
@var{file}(@var{section}): warning: smaller common is here
|
|
@end smallexample
|
|
@end enumerate
|
|
|
|
@kindex --warn-constructors
|
|
@item --warn-constructors
|
|
Warn if any global constructors are used. This is only useful for a few
|
|
object file formats. For formats like COFF or ELF, the linker can not
|
|
detect the use of global constructors.
|
|
|
|
@kindex --warn-multiple-gp
|
|
@item --warn-multiple-gp
|
|
Warn if multiple global pointer values are required in the output file.
|
|
This is only meaningful for certain processors, such as the Alpha.
|
|
Specifically, some processors put large-valued constants in a special
|
|
section. A special register (the global pointer) points into the middle
|
|
of this section, so that constants can be loaded efficiently via a
|
|
base-register relative addressing mode. Since the offset in
|
|
base-register relative mode is fixed and relatively small (e.g., 16
|
|
bits), this limits the maximum size of the constant pool. Thus, in
|
|
large programs, it is often necessary to use multiple global pointer
|
|
values in order to be able to address all possible constants. This
|
|
option causes a warning to be issued whenever this case occurs.
|
|
|
|
@kindex --warn-once
|
|
@cindex warnings, on undefined symbols
|
|
@cindex undefined symbols, warnings on
|
|
@item --warn-once
|
|
Only warn once for each undefined symbol, rather than once per module
|
|
which refers to it.
|
|
|
|
@kindex --warn-section-align
|
|
@cindex warnings, on section alignment
|
|
@cindex section alignment, warnings on
|
|
@item --warn-section-align
|
|
Warn if the address of an output section is changed because of
|
|
alignment. Typically, the alignment will be set by an input section.
|
|
The address will only be changed if it not explicitly specified; that
|
|
is, if the @code{SECTIONS} command does not specify a start address for
|
|
the section (@pxref{SECTIONS}).
|
|
|
|
@kindex --warn-textrel
|
|
@item --warn-textrel
|
|
Warn if the linker adds DT_TEXTREL to a position-independent executable
|
|
or shared object.
|
|
|
|
@kindex --warn-alternate-em
|
|
@item --warn-alternate-em
|
|
Warn if an object has alternate ELF machine code.
|
|
|
|
@kindex --warn-unresolved-symbols
|
|
@item --warn-unresolved-symbols
|
|
If the linker is going to report an unresolved symbol (see the option
|
|
@option{--unresolved-symbols}) it will normally generate an error.
|
|
This option makes it generate a warning instead.
|
|
|
|
@kindex --error-unresolved-symbols
|
|
@item --error-unresolved-symbols
|
|
This restores the linker's default behaviour of generating errors when
|
|
it is reporting unresolved symbols.
|
|
|
|
@kindex --whole-archive
|
|
@cindex including an entire archive
|
|
@item --whole-archive
|
|
For each archive mentioned on the command line after the
|
|
@option{--whole-archive} option, include every object file in the archive
|
|
in the link, rather than searching the archive for the required object
|
|
files. This is normally used to turn an archive file into a shared
|
|
library, forcing every object to be included in the resulting shared
|
|
library. This option may be used more than once.
|
|
|
|
Two notes when using this option from gcc: First, gcc doesn't know
|
|
about this option, so you have to use @option{-Wl,-whole-archive}.
|
|
Second, don't forget to use @option{-Wl,-no-whole-archive} after your
|
|
list of archives, because gcc will add its own list of archives to
|
|
your link and you may not want this flag to affect those as well.
|
|
|
|
@kindex --wrap=@var{symbol}
|
|
@item --wrap=@var{symbol}
|
|
Use a wrapper function for @var{symbol}. Any undefined reference to
|
|
@var{symbol} will be resolved to @code{__wrap_@var{symbol}}. Any
|
|
undefined reference to @code{__real_@var{symbol}} will be resolved to
|
|
@var{symbol}.
|
|
|
|
This can be used to provide a wrapper for a system function. The
|
|
wrapper function should be called @code{__wrap_@var{symbol}}. If it
|
|
wishes to call the system function, it should call
|
|
@code{__real_@var{symbol}}.
|
|
|
|
Here is a trivial example:
|
|
|
|
@smallexample
|
|
void *
|
|
__wrap_malloc (size_t c)
|
|
@{
|
|
printf ("malloc called with %zu\n", c);
|
|
return __real_malloc (c);
|
|
@}
|
|
@end smallexample
|
|
|
|
If you link other code with this file using @option{--wrap malloc}, then
|
|
all calls to @code{malloc} will call the function @code{__wrap_malloc}
|
|
instead. The call to @code{__real_malloc} in @code{__wrap_malloc} will
|
|
call the real @code{malloc} function.
|
|
|
|
You may wish to provide a @code{__real_malloc} function as well, so that
|
|
links without the @option{--wrap} option will succeed. If you do this,
|
|
you should not put the definition of @code{__real_malloc} in the same
|
|
file as @code{__wrap_malloc}; if you do, the assembler may resolve the
|
|
call before the linker has a chance to wrap it to @code{malloc}.
|
|
|
|
Only undefined references are replaced by the linker. So, translation unit
|
|
internal references to @var{symbol} are not resolved to
|
|
@code{__wrap_@var{symbol}}. In the next example, the call to @code{f} in
|
|
@code{g} is not resolved to @code{__wrap_f}.
|
|
|
|
@smallexample
|
|
int
|
|
f (void)
|
|
@{
|
|
return 123;
|
|
@}
|
|
|
|
int
|
|
g (void)
|
|
@{
|
|
return f();
|
|
@}
|
|
@end smallexample
|
|
|
|
@kindex --eh-frame-hdr
|
|
@kindex --no-eh-frame-hdr
|
|
@item --eh-frame-hdr
|
|
@itemx --no-eh-frame-hdr
|
|
Request (@option{--eh-frame-hdr}) or suppress
|
|
(@option{--no-eh-frame-hdr}) the creation of @code{.eh_frame_hdr}
|
|
section and ELF @code{PT_GNU_EH_FRAME} segment header.
|
|
|
|
@kindex --ld-generated-unwind-info
|
|
@item --no-ld-generated-unwind-info
|
|
Request creation of @code{.eh_frame} unwind info for linker
|
|
generated code sections like PLT. This option is on by default
|
|
if linker generated unwind info is supported.
|
|
|
|
@kindex --enable-new-dtags
|
|
@kindex --disable-new-dtags
|
|
@item --enable-new-dtags
|
|
@itemx --disable-new-dtags
|
|
This linker can create the new dynamic tags in ELF. But the older ELF
|
|
systems may not understand them. If you specify
|
|
@option{--enable-new-dtags}, the new dynamic tags will be created as needed
|
|
and older dynamic tags will be omitted.
|
|
If you specify @option{--disable-new-dtags}, no new dynamic tags will be
|
|
created. By default, the new dynamic tags are not created. Note that
|
|
those options are only available for ELF systems.
|
|
|
|
@kindex --hash-size=@var{number}
|
|
@item --hash-size=@var{number}
|
|
Set the default size of the linker's hash tables to a prime number
|
|
close to @var{number}. Increasing this value can reduce the length of
|
|
time it takes the linker to perform its tasks, at the expense of
|
|
increasing the linker's memory requirements. Similarly reducing this
|
|
value can reduce the memory requirements at the expense of speed.
|
|
|
|
@kindex --hash-style=@var{style}
|
|
@item --hash-style=@var{style}
|
|
Set the type of linker's hash table(s). @var{style} can be either
|
|
@code{sysv} for classic ELF @code{.hash} section, @code{gnu} for
|
|
new style GNU @code{.gnu.hash} section or @code{both} for both
|
|
the classic ELF @code{.hash} and new style GNU @code{.gnu.hash}
|
|
hash tables. The default depends upon how the linker was configured,
|
|
but for most Linux based systems it will be @code{both}.
|
|
|
|
@kindex --compress-debug-sections=none
|
|
@kindex --compress-debug-sections=zlib
|
|
@kindex --compress-debug-sections=zlib-gnu
|
|
@kindex --compress-debug-sections=zlib-gabi
|
|
@item --compress-debug-sections=none
|
|
@itemx --compress-debug-sections=zlib
|
|
@itemx --compress-debug-sections=zlib-gnu
|
|
@itemx --compress-debug-sections=zlib-gabi
|
|
On ELF platforms, these options control how DWARF debug sections are
|
|
compressed using zlib.
|
|
|
|
@option{--compress-debug-sections=none} doesn't compress DWARF debug
|
|
sections. @option{--compress-debug-sections=zlib-gnu} compresses
|
|
DWARF debug sections and renames them to begin with @samp{.zdebug}
|
|
instead of @samp{.debug}. @option{--compress-debug-sections=zlib-gabi}
|
|
also compresses DWARF debug sections, but rather than renaming them it
|
|
sets the SHF_COMPRESSED flag in the sections' headers.
|
|
|
|
The @option{--compress-debug-sections=zlib} option is an alias for
|
|
@option{--compress-debug-sections=zlib-gabi}.
|
|
|
|
Note that this option overrides any compression in input debug
|
|
sections, so if a binary is linked with @option{--compress-debug-sections=none}
|
|
for example, then any compressed debug sections in input files will be
|
|
uncompressed before they are copied into the output binary.
|
|
|
|
The default compression behaviour varies depending upon the target
|
|
involved and the configure options used to build the toolchain. The
|
|
default can be determined by examining the output from the linker's
|
|
@option{--help} option.
|
|
|
|
@kindex --reduce-memory-overheads
|
|
@item --reduce-memory-overheads
|
|
This option reduces memory requirements at ld runtime, at the expense of
|
|
linking speed. This was introduced to select the old O(n^2) algorithm
|
|
for link map file generation, rather than the new O(n) algorithm which uses
|
|
about 40% more memory for symbol storage.
|
|
|
|
Another effect of the switch is to set the default hash table size to
|
|
1021, which again saves memory at the cost of lengthening the linker's
|
|
run time. This is not done however if the @option{--hash-size} switch
|
|
has been used.
|
|
|
|
The @option{--reduce-memory-overheads} switch may be also be used to
|
|
enable other tradeoffs in future versions of the linker.
|
|
|
|
@kindex --build-id
|
|
@kindex --build-id=@var{style}
|
|
@item --build-id
|
|
@itemx --build-id=@var{style}
|
|
Request the creation of a @code{.note.gnu.build-id} ELF note section
|
|
or a @code{.buildid} COFF section. The contents of the note are
|
|
unique bits identifying this linked file. @var{style} can be
|
|
@code{uuid} to use 128 random bits, @code{sha1} to use a 160-bit
|
|
@sc{SHA1} hash on the normative parts of the output contents,
|
|
@code{md5} to use a 128-bit @sc{MD5} hash on the normative parts of
|
|
the output contents, or @code{0x@var{hexstring}} to use a chosen bit
|
|
string specified as an even number of hexadecimal digits (@code{-} and
|
|
@code{:} characters between digit pairs are ignored). If @var{style}
|
|
is omitted, @code{sha1} is used.
|
|
|
|
The @code{md5} and @code{sha1} styles produces an identifier
|
|
that is always the same in an identical output file, but will be
|
|
unique among all nonidentical output files. It is not intended
|
|
to be compared as a checksum for the file's contents. A linked
|
|
file may be changed later by other tools, but the build ID bit
|
|
string identifying the original linked file does not change.
|
|
|
|
Passing @code{none} for @var{style} disables the setting from any
|
|
@code{--build-id} options earlier on the command line.
|
|
@end table
|
|
|
|
@c man end
|
|
|
|
@subsection Options Specific to i386 PE Targets
|
|
|
|
@c man begin OPTIONS
|
|
|
|
The i386 PE linker supports the @option{-shared} option, which causes
|
|
the output to be a dynamically linked library (DLL) instead of a
|
|
normal executable. You should name the output @code{*.dll} when you
|
|
use this option. In addition, the linker fully supports the standard
|
|
@code{*.def} files, which may be specified on the linker command line
|
|
like an object file (in fact, it should precede archives it exports
|
|
symbols from, to ensure that they get linked in, just like a normal
|
|
object file).
|
|
|
|
In addition to the options common to all targets, the i386 PE linker
|
|
support additional command-line options that are specific to the i386
|
|
PE target. Options that take values may be separated from their
|
|
values by either a space or an equals sign.
|
|
|
|
@table @gcctabopt
|
|
|
|
@kindex --add-stdcall-alias
|
|
@item --add-stdcall-alias
|
|
If given, symbols with a stdcall suffix (@@@var{nn}) will be exported
|
|
as-is and also with the suffix stripped.
|
|
[This option is specific to the i386 PE targeted port of the linker]
|
|
|
|
@kindex --base-file
|
|
@item --base-file @var{file}
|
|
Use @var{file} as the name of a file in which to save the base
|
|
addresses of all the relocations needed for generating DLLs with
|
|
@file{dlltool}.
|
|
[This is an i386 PE specific option]
|
|
|
|
@kindex --dll
|
|
@item --dll
|
|
Create a DLL instead of a regular executable. You may also use
|
|
@option{-shared} or specify a @code{LIBRARY} in a given @code{.def}
|
|
file.
|
|
[This option is specific to the i386 PE targeted port of the linker]
|
|
|
|
@kindex --enable-long-section-names
|
|
@kindex --disable-long-section-names
|
|
@item --enable-long-section-names
|
|
@itemx --disable-long-section-names
|
|
The PE variants of the COFF object format add an extension that permits
|
|
the use of section names longer than eight characters, the normal limit
|
|
for COFF. By default, these names are only allowed in object files, as
|
|
fully-linked executable images do not carry the COFF string table required
|
|
to support the longer names. As a GNU extension, it is possible to
|
|
allow their use in executable images as well, or to (probably pointlessly!)
|
|
disallow it in object files, by using these two options. Executable images
|
|
generated with these long section names are slightly non-standard, carrying
|
|
as they do a string table, and may generate confusing output when examined
|
|
with non-GNU PE-aware tools, such as file viewers and dumpers. However,
|
|
GDB relies on the use of PE long section names to find Dwarf-2 debug
|
|
information sections in an executable image at runtime, and so if neither
|
|
option is specified on the command-line, @command{ld} will enable long
|
|
section names, overriding the default and technically correct behaviour,
|
|
when it finds the presence of debug information while linking an executable
|
|
image and not stripping symbols.
|
|
[This option is valid for all PE targeted ports of the linker]
|
|
|
|
@kindex --enable-stdcall-fixup
|
|
@kindex --disable-stdcall-fixup
|
|
@item --enable-stdcall-fixup
|
|
@itemx --disable-stdcall-fixup
|
|
If the link finds a symbol that it cannot resolve, it will attempt to
|
|
do ``fuzzy linking'' by looking for another defined symbol that differs
|
|
only in the format of the symbol name (cdecl vs stdcall) and will
|
|
resolve that symbol by linking to the match. For example, the
|
|
undefined symbol @code{_foo} might be linked to the function
|
|
@code{_foo@@12}, or the undefined symbol @code{_bar@@16} might be linked
|
|
to the function @code{_bar}. When the linker does this, it prints a
|
|
warning, since it normally should have failed to link, but sometimes
|
|
import libraries generated from third-party dlls may need this feature
|
|
to be usable. If you specify @option{--enable-stdcall-fixup}, this
|
|
feature is fully enabled and warnings are not printed. If you specify
|
|
@option{--disable-stdcall-fixup}, this feature is disabled and such
|
|
mismatches are considered to be errors.
|
|
[This option is specific to the i386 PE targeted port of the linker]
|
|
|
|
@kindex --leading-underscore
|
|
@kindex --no-leading-underscore
|
|
@item --leading-underscore
|
|
@itemx --no-leading-underscore
|
|
For most targets default symbol-prefix is an underscore and is defined
|
|
in target's description. By this option it is possible to
|
|
disable/enable the default underscore symbol-prefix.
|
|
|
|
@cindex DLLs, creating
|
|
@kindex --export-all-symbols
|
|
@item --export-all-symbols
|
|
If given, all global symbols in the objects used to build a DLL will
|
|
be exported by the DLL. Note that this is the default if there
|
|
otherwise wouldn't be any exported symbols. When symbols are
|
|
explicitly exported via DEF files or implicitly exported via function
|
|
attributes, the default is to not export anything else unless this
|
|
option is given. Note that the symbols @code{DllMain@@12},
|
|
@code{DllEntryPoint@@0}, @code{DllMainCRTStartup@@12}, and
|
|
@code{impure_ptr} will not be automatically
|
|
exported. Also, symbols imported from other DLLs will not be
|
|
re-exported, nor will symbols specifying the DLL's internal layout
|
|
such as those beginning with @code{_head_} or ending with
|
|
@code{_iname}. In addition, no symbols from @code{libgcc},
|
|
@code{libstd++}, @code{libmingw32}, or @code{crtX.o} will be exported.
|
|
Symbols whose names begin with @code{__rtti_} or @code{__builtin_} will
|
|
not be exported, to help with C++ DLLs. Finally, there is an
|
|
extensive list of cygwin-private symbols that are not exported
|
|
(obviously, this applies on when building DLLs for cygwin targets).
|
|
These cygwin-excludes are: @code{_cygwin_dll_entry@@12},
|
|
@code{_cygwin_crt0_common@@8}, @code{_cygwin_noncygwin_dll_entry@@12},
|
|
@code{_fmode}, @code{_impure_ptr}, @code{cygwin_attach_dll},
|
|
@code{cygwin_premain0}, @code{cygwin_premain1}, @code{cygwin_premain2},
|
|
@code{cygwin_premain3}, and @code{environ}.
|
|
[This option is specific to the i386 PE targeted port of the linker]
|
|
|
|
@kindex --exclude-symbols
|
|
@item --exclude-symbols @var{symbol},@var{symbol},...
|
|
Specifies a list of symbols which should not be automatically
|
|
exported. The symbol names may be delimited by commas or colons.
|
|
[This option is specific to the i386 PE targeted port of the linker]
|
|
|
|
@kindex --exclude-all-symbols
|
|
@item --exclude-all-symbols
|
|
Specifies no symbols should be automatically exported.
|
|
[This option is specific to the i386 PE targeted port of the linker]
|
|
|
|
@kindex --file-alignment
|
|
@item --file-alignment
|
|
Specify the file alignment. Sections in the file will always begin at
|
|
file offsets which are multiples of this number. This defaults to
|
|
512.
|
|
[This option is specific to the i386 PE targeted port of the linker]
|
|
|
|
@cindex heap size
|
|
@kindex --heap
|
|
@item --heap @var{reserve}
|
|
@itemx --heap @var{reserve},@var{commit}
|
|
Specify the number of bytes of memory to reserve (and optionally commit)
|
|
to be used as heap for this program. The default is 1MB reserved, 4K
|
|
committed.
|
|
[This option is specific to the i386 PE targeted port of the linker]
|
|
|
|
@cindex image base
|
|
@kindex --image-base
|
|
@item --image-base @var{value}
|
|
Use @var{value} as the base address of your program or dll. This is
|
|
the lowest memory location that will be used when your program or dll
|
|
is loaded. To reduce the need to relocate and improve performance of
|
|
your dlls, each should have a unique base address and not overlap any
|
|
other dlls. The default is 0x400000 for executables, and 0x10000000
|
|
for dlls.
|
|
[This option is specific to the i386 PE targeted port of the linker]
|
|
|
|
@kindex --kill-at
|
|
@item --kill-at
|
|
If given, the stdcall suffixes (@@@var{nn}) will be stripped from
|
|
symbols before they are exported.
|
|
[This option is specific to the i386 PE targeted port of the linker]
|
|
|
|
@kindex --large-address-aware
|
|
@item --large-address-aware
|
|
If given, the appropriate bit in the ``Characteristics'' field of the COFF
|
|
header is set to indicate that this executable supports virtual addresses
|
|
greater than 2 gigabytes. This should be used in conjunction with the /3GB
|
|
or /USERVA=@var{value} megabytes switch in the ``[operating systems]''
|
|
section of the BOOT.INI. Otherwise, this bit has no effect.
|
|
[This option is specific to PE targeted ports of the linker]
|
|
|
|
@kindex --disable-large-address-aware
|
|
@item --disable-large-address-aware
|
|
Reverts the effect of a previous @samp{--large-address-aware} option.
|
|
This is useful if @samp{--large-address-aware} is always set by the compiler
|
|
driver (e.g. Cygwin gcc) and the executable does not support virtual
|
|
addresses greater than 2 gigabytes.
|
|
[This option is specific to PE targeted ports of the linker]
|
|
|
|
@kindex --major-image-version
|
|
@item --major-image-version @var{value}
|
|
Sets the major number of the ``image version''. Defaults to 1.
|
|
[This option is specific to the i386 PE targeted port of the linker]
|
|
|
|
@kindex --major-os-version
|
|
@item --major-os-version @var{value}
|
|
Sets the major number of the ``os version''. Defaults to 4.
|
|
[This option is specific to the i386 PE targeted port of the linker]
|
|
|
|
@kindex --major-subsystem-version
|
|
@item --major-subsystem-version @var{value}
|
|
Sets the major number of the ``subsystem version''. Defaults to 4.
|
|
[This option is specific to the i386 PE targeted port of the linker]
|
|
|
|
@kindex --minor-image-version
|
|
@item --minor-image-version @var{value}
|
|
Sets the minor number of the ``image version''. Defaults to 0.
|
|
[This option is specific to the i386 PE targeted port of the linker]
|
|
|
|
@kindex --minor-os-version
|
|
@item --minor-os-version @var{value}
|
|
Sets the minor number of the ``os version''. Defaults to 0.
|
|
[This option is specific to the i386 PE targeted port of the linker]
|
|
|
|
@kindex --minor-subsystem-version
|
|
@item --minor-subsystem-version @var{value}
|
|
Sets the minor number of the ``subsystem version''. Defaults to 0.
|
|
[This option is specific to the i386 PE targeted port of the linker]
|
|
|
|
@cindex DEF files, creating
|
|
@cindex DLLs, creating
|
|
@kindex --output-def
|
|
@item --output-def @var{file}
|
|
The linker will create the file @var{file} which will contain a DEF
|
|
file corresponding to the DLL the linker is generating. This DEF file
|
|
(which should be called @code{*.def}) may be used to create an import
|
|
library with @code{dlltool} or may be used as a reference to
|
|
automatically or implicitly exported symbols.
|
|
[This option is specific to the i386 PE targeted port of the linker]
|
|
|
|
@cindex DLLs, creating
|
|
@kindex --enable-auto-image-base
|
|
@item --enable-auto-image-base
|
|
@itemx --enable-auto-image-base=@var{value}
|
|
Automatically choose the image base for DLLs, optionally starting with base
|
|
@var{value}, unless one is specified using the @code{--image-base} argument.
|
|
By using a hash generated from the dllname to create unique image bases
|
|
for each DLL, in-memory collisions and relocations which can delay program
|
|
execution are avoided.
|
|
[This option is specific to the i386 PE targeted port of the linker]
|
|
|
|
@kindex --disable-auto-image-base
|
|
@item --disable-auto-image-base
|
|
Do not automatically generate a unique image base. If there is no
|
|
user-specified image base (@code{--image-base}) then use the platform
|
|
default.
|
|
[This option is specific to the i386 PE targeted port of the linker]
|
|
|
|
@cindex DLLs, linking to
|
|
@kindex --dll-search-prefix
|
|
@item --dll-search-prefix @var{string}
|
|
When linking dynamically to a dll without an import library,
|
|
search for @code{<string><basename>.dll} in preference to
|
|
@code{lib<basename>.dll}. This behaviour allows easy distinction
|
|
between DLLs built for the various "subplatforms": native, cygwin,
|
|
uwin, pw, etc. For instance, cygwin DLLs typically use
|
|
@code{--dll-search-prefix=cyg}.
|
|
[This option is specific to the i386 PE targeted port of the linker]
|
|
|
|
@kindex --enable-auto-import
|
|
@item --enable-auto-import
|
|
Do sophisticated linking of @code{_symbol} to @code{__imp__symbol} for
|
|
DATA imports from DLLs, thus making it possible to bypass the dllimport
|
|
mechanism on the user side and to reference unmangled symbol names.
|
|
[This option is specific to the i386 PE targeted port of the linker]
|
|
|
|
The following remarks pertain to the original implementation of the
|
|
feature and are obsolete nowadays for Cygwin and MinGW targets.
|
|
|
|
Note: Use of the 'auto-import' extension will cause the text section
|
|
of the image file to be made writable. This does not conform to the
|
|
PE-COFF format specification published by Microsoft.
|
|
|
|
Note - use of the 'auto-import' extension will also cause read only
|
|
data which would normally be placed into the .rdata section to be
|
|
placed into the .data section instead. This is in order to work
|
|
around a problem with consts that is described here:
|
|
http://www.cygwin.com/ml/cygwin/2004-09/msg01101.html
|
|
|
|
Using 'auto-import' generally will 'just work' -- but sometimes you may
|
|
see this message:
|
|
|
|
"variable '<var>' can't be auto-imported. Please read the
|
|
documentation for ld's @code{--enable-auto-import} for details."
|
|
|
|
This message occurs when some (sub)expression accesses an address
|
|
ultimately given by the sum of two constants (Win32 import tables only
|
|
allow one). Instances where this may occur include accesses to member
|
|
fields of struct variables imported from a DLL, as well as using a
|
|
constant index into an array variable imported from a DLL. Any
|
|
multiword variable (arrays, structs, long long, etc) may trigger
|
|
this error condition. However, regardless of the exact data type
|
|
of the offending exported variable, ld will always detect it, issue
|
|
the warning, and exit.
|
|
|
|
There are several ways to address this difficulty, regardless of the
|
|
data type of the exported variable:
|
|
|
|
One way is to use --enable-runtime-pseudo-reloc switch. This leaves the task
|
|
of adjusting references in your client code for runtime environment, so
|
|
this method works only when runtime environment supports this feature.
|
|
|
|
A second solution is to force one of the 'constants' to be a variable --
|
|
that is, unknown and un-optimizable at compile time. For arrays,
|
|
there are two possibilities: a) make the indexee (the array's address)
|
|
a variable, or b) make the 'constant' index a variable. Thus:
|
|
|
|
@example
|
|
extern type extern_array[];
|
|
extern_array[1] -->
|
|
@{ volatile type *t=extern_array; t[1] @}
|
|
@end example
|
|
|
|
or
|
|
|
|
@example
|
|
extern type extern_array[];
|
|
extern_array[1] -->
|
|
@{ volatile int t=1; extern_array[t] @}
|
|
@end example
|
|
|
|
For structs (and most other multiword data types) the only option
|
|
is to make the struct itself (or the long long, or the ...) variable:
|
|
|
|
@example
|
|
extern struct s extern_struct;
|
|
extern_struct.field -->
|
|
@{ volatile struct s *t=&extern_struct; t->field @}
|
|
@end example
|
|
|
|
or
|
|
|
|
@example
|
|
extern long long extern_ll;
|
|
extern_ll -->
|
|
@{ volatile long long * local_ll=&extern_ll; *local_ll @}
|
|
@end example
|
|
|
|
A third method of dealing with this difficulty is to abandon
|
|
'auto-import' for the offending symbol and mark it with
|
|
@code{__declspec(dllimport)}. However, in practice that
|
|
requires using compile-time #defines to indicate whether you are
|
|
building a DLL, building client code that will link to the DLL, or
|
|
merely building/linking to a static library. In making the choice
|
|
between the various methods of resolving the 'direct address with
|
|
constant offset' problem, you should consider typical real-world usage:
|
|
|
|
Original:
|
|
@example
|
|
--foo.h
|
|
extern int arr[];
|
|
--foo.c
|
|
#include "foo.h"
|
|
void main(int argc, char **argv)@{
|
|
printf("%d\n",arr[1]);
|
|
@}
|
|
@end example
|
|
|
|
Solution 1:
|
|
@example
|
|
--foo.h
|
|
extern int arr[];
|
|
--foo.c
|
|
#include "foo.h"
|
|
void main(int argc, char **argv)@{
|
|
/* This workaround is for win32 and cygwin; do not "optimize" */
|
|
volatile int *parr = arr;
|
|
printf("%d\n",parr[1]);
|
|
@}
|
|
@end example
|
|
|
|
Solution 2:
|
|
@example
|
|
--foo.h
|
|
/* Note: auto-export is assumed (no __declspec(dllexport)) */
|
|
#if (defined(_WIN32) || defined(__CYGWIN__)) && \
|
|
!(defined(FOO_BUILD_DLL) || defined(FOO_STATIC))
|
|
#define FOO_IMPORT __declspec(dllimport)
|
|
#else
|
|
#define FOO_IMPORT
|
|
#endif
|
|
extern FOO_IMPORT int arr[];
|
|
--foo.c
|
|
#include "foo.h"
|
|
void main(int argc, char **argv)@{
|
|
printf("%d\n",arr[1]);
|
|
@}
|
|
@end example
|
|
|
|
A fourth way to avoid this problem is to re-code your
|
|
library to use a functional interface rather than a data interface
|
|
for the offending variables (e.g. set_foo() and get_foo() accessor
|
|
functions).
|
|
|
|
@kindex --disable-auto-import
|
|
@item --disable-auto-import
|
|
Do not attempt to do sophisticated linking of @code{_symbol} to
|
|
@code{__imp__symbol} for DATA imports from DLLs.
|
|
[This option is specific to the i386 PE targeted port of the linker]
|
|
|
|
@kindex --enable-runtime-pseudo-reloc
|
|
@item --enable-runtime-pseudo-reloc
|
|
If your code contains expressions described in --enable-auto-import section,
|
|
that is, DATA imports from DLL with non-zero offset, this switch will create
|
|
a vector of 'runtime pseudo relocations' which can be used by runtime
|
|
environment to adjust references to such data in your client code.
|
|
[This option is specific to the i386 PE targeted port of the linker]
|
|
|
|
@kindex --disable-runtime-pseudo-reloc
|
|
@item --disable-runtime-pseudo-reloc
|
|
Do not create pseudo relocations for non-zero offset DATA imports from DLLs.
|
|
[This option is specific to the i386 PE targeted port of the linker]
|
|
|
|
@kindex --enable-extra-pe-debug
|
|
@item --enable-extra-pe-debug
|
|
Show additional debug info related to auto-import symbol thunking.
|
|
[This option is specific to the i386 PE targeted port of the linker]
|
|
|
|
@kindex --section-alignment
|
|
@item --section-alignment
|
|
Sets the section alignment. Sections in memory will always begin at
|
|
addresses which are a multiple of this number. Defaults to 0x1000.
|
|
[This option is specific to the i386 PE targeted port of the linker]
|
|
|
|
@cindex stack size
|
|
@kindex --stack
|
|
@item --stack @var{reserve}
|
|
@itemx --stack @var{reserve},@var{commit}
|
|
Specify the number of bytes of memory to reserve (and optionally commit)
|
|
to be used as stack for this program. The default is 2MB reserved, 4K
|
|
committed.
|
|
[This option is specific to the i386 PE targeted port of the linker]
|
|
|
|
@kindex --subsystem
|
|
@item --subsystem @var{which}
|
|
@itemx --subsystem @var{which}:@var{major}
|
|
@itemx --subsystem @var{which}:@var{major}.@var{minor}
|
|
Specifies the subsystem under which your program will execute. The
|
|
legal values for @var{which} are @code{native}, @code{windows},
|
|
@code{console}, @code{posix}, and @code{xbox}. You may optionally set
|
|
the subsystem version also. Numeric values are also accepted for
|
|
@var{which}.
|
|
[This option is specific to the i386 PE targeted port of the linker]
|
|
|
|
The following options set flags in the @code{DllCharacteristics} field
|
|
of the PE file header:
|
|
[These options are specific to PE targeted ports of the linker]
|
|
|
|
@kindex --high-entropy-va
|
|
@item --high-entropy-va
|
|
Image is compatible with 64-bit address space layout randomization
|
|
(ASLR).
|
|
This option also implies @option{--dynamicbase} and
|
|
@option{--enable-reloc-section}.
|
|
|
|
@kindex --dynamicbase
|
|
@item --dynamicbase
|
|
The image base address may be relocated using address space layout
|
|
randomization (ASLR). This feature was introduced with MS Windows
|
|
Vista for i386 PE targets.
|
|
This option also implies @option{--enable-reloc-section}.
|
|
|
|
@kindex --forceinteg
|
|
@item --forceinteg
|
|
Code integrity checks are enforced.
|
|
|
|
@kindex --nxcompat
|
|
@item --nxcompat
|
|
The image is compatible with the Data Execution Prevention.
|
|
This feature was introduced with MS Windows XP SP2 for i386 PE targets.
|
|
|
|
@kindex --no-isolation
|
|
@item --no-isolation
|
|
Although the image understands isolation, do not isolate the image.
|
|
|
|
@kindex --no-seh
|
|
@item --no-seh
|
|
The image does not use SEH. No SE handler may be called from
|
|
this image.
|
|
|
|
@kindex --no-bind
|
|
@item --no-bind
|
|
Do not bind this image.
|
|
|
|
@kindex --wdmdriver
|
|
@item --wdmdriver
|
|
The driver uses the MS Windows Driver Model.
|
|
|
|
@kindex --tsaware
|
|
@item --tsaware
|
|
The image is Terminal Server aware.
|
|
|
|
@kindex --insert-timestamp
|
|
@item --insert-timestamp
|
|
@itemx --no-insert-timestamp
|
|
Insert a real timestamp into the image. This is the default behaviour
|
|
as it matches legacy code and it means that the image will work with
|
|
other, proprietary tools. The problem with this default is that it
|
|
will result in slightly different images being produced each time the
|
|
same sources are linked. The option @option{--no-insert-timestamp}
|
|
can be used to insert a zero value for the timestamp, this ensuring
|
|
that binaries produced from identical sources will compare
|
|
identically.
|
|
|
|
@kindex --enable-reloc-section
|
|
@item --enable-reloc-section
|
|
Create the base relocation table, which is necessary if the image
|
|
is loaded at a different image base than specified in the PE header.
|
|
@end table
|
|
|
|
@c man end
|
|
|
|
@ifset C6X
|
|
@subsection Options specific to C6X uClinux targets
|
|
|
|
@c man begin OPTIONS
|
|
|
|
The C6X uClinux target uses a binary format called DSBT to support shared
|
|
libraries. Each shared library in the system needs to have a unique index;
|
|
all executables use an index of 0.
|
|
|
|
@table @gcctabopt
|
|
|
|
@kindex --dsbt-size
|
|
@item --dsbt-size @var{size}
|
|
This option sets the number of entries in the DSBT of the current executable
|
|
or shared library to @var{size}. The default is to create a table with 64
|
|
entries.
|
|
|
|
@kindex --dsbt-index
|
|
@item --dsbt-index @var{index}
|
|
This option sets the DSBT index of the current executable or shared library
|
|
to @var{index}. The default is 0, which is appropriate for generating
|
|
executables. If a shared library is generated with a DSBT index of 0, the
|
|
@code{R_C6000_DSBT_INDEX} relocs are copied into the output file.
|
|
|
|
@kindex --no-merge-exidx-entries
|
|
The @samp{--no-merge-exidx-entries} switch disables the merging of adjacent
|
|
exidx entries in frame unwind info.
|
|
|
|
@end table
|
|
|
|
@c man end
|
|
@end ifset
|
|
|
|
@ifset CSKY
|
|
@subsection Options specific to C-SKY targets
|
|
|
|
@c man begin OPTIONS
|
|
|
|
@table @gcctabopt
|
|
|
|
@kindex --branch-stub on C-SKY
|
|
@item --branch-stub
|
|
This option enables linker branch relaxation by inserting branch stub
|
|
sections when needed to extend the range of branches. This option is
|
|
usually not required since C-SKY supports branch and call instructions that
|
|
can access the full memory range and branch relaxation is normally handled by
|
|
the compiler or assembler.
|
|
|
|
@kindex --stub-group-size on C-SKY
|
|
@item --stub-group-size=@var{N}
|
|
This option allows finer control of linker branch stub creation.
|
|
It sets the maximum size of a group of input sections that can
|
|
be handled by one stub section. A negative value of @var{N} locates
|
|
stub sections after their branches, while a positive value allows stub
|
|
sections to appear either before or after the branches. Values of
|
|
@samp{1} or @samp{-1} indicate that the
|
|
linker should choose suitable defaults.
|
|
|
|
@end table
|
|
|
|
@c man end
|
|
@end ifset
|
|
|
|
@ifset M68HC11
|
|
@subsection Options specific to Motorola 68HC11 and 68HC12 targets
|
|
|
|
@c man begin OPTIONS
|
|
|
|
The 68HC11 and 68HC12 linkers support specific options to control the
|
|
memory bank switching mapping and trampoline code generation.
|
|
|
|
@table @gcctabopt
|
|
|
|
@kindex --no-trampoline
|
|
@item --no-trampoline
|
|
This option disables the generation of trampoline. By default a trampoline
|
|
is generated for each far function which is called using a @code{jsr}
|
|
instruction (this happens when a pointer to a far function is taken).
|
|
|
|
@kindex --bank-window
|
|
@item --bank-window @var{name}
|
|
This option indicates to the linker the name of the memory region in
|
|
the @samp{MEMORY} specification that describes the memory bank window.
|
|
The definition of such region is then used by the linker to compute
|
|
paging and addresses within the memory window.
|
|
|
|
@end table
|
|
|
|
@c man end
|
|
@end ifset
|
|
|
|
@ifset M68K
|
|
@subsection Options specific to Motorola 68K target
|
|
|
|
@c man begin OPTIONS
|
|
|
|
The following options are supported to control handling of GOT generation
|
|
when linking for 68K targets.
|
|
|
|
@table @gcctabopt
|
|
|
|
@kindex --got
|
|
@item --got=@var{type}
|
|
This option tells the linker which GOT generation scheme to use.
|
|
@var{type} should be one of @samp{single}, @samp{negative},
|
|
@samp{multigot} or @samp{target}. For more information refer to the
|
|
Info entry for @file{ld}.
|
|
|
|
@end table
|
|
|
|
@c man end
|
|
@end ifset
|
|
|
|
@ifset MIPS
|
|
@subsection Options specific to MIPS targets
|
|
|
|
@c man begin OPTIONS
|
|
|
|
The following options are supported to control microMIPS instruction
|
|
generation and branch relocation checks for ISA mode transitions when
|
|
linking for MIPS targets.
|
|
|
|
@table @gcctabopt
|
|
|
|
@kindex --insn32
|
|
@item --insn32
|
|
@kindex --no-insn32
|
|
@itemx --no-insn32
|
|
These options control the choice of microMIPS instructions used in code
|
|
generated by the linker, such as that in the PLT or lazy binding stubs,
|
|
or in relaxation. If @samp{--insn32} is used, then the linker only uses
|
|
32-bit instruction encodings. By default or if @samp{--no-insn32} is
|
|
used, all instruction encodings are used, including 16-bit ones where
|
|
possible.
|
|
|
|
@kindex --ignore-branch-isa
|
|
@item --ignore-branch-isa
|
|
@kindex --no-ignore-branch-isa
|
|
@itemx --no-ignore-branch-isa
|
|
These options control branch relocation checks for invalid ISA mode
|
|
transitions. If @samp{--ignore-branch-isa} is used, then the linker
|
|
accepts any branch relocations and any ISA mode transition required
|
|
is lost in relocation calculation, except for some cases of @code{BAL}
|
|
instructions which meet relaxation conditions and are converted to
|
|
equivalent @code{JALX} instructions as the associated relocation is
|
|
calculated. By default or if @samp{--no-ignore-branch-isa} is used
|
|
a check is made causing the loss of an ISA mode transition to produce
|
|
an error.
|
|
|
|
@kindex --compact-branches
|
|
@item --compact-branches
|
|
@kindex --no-compact-branches
|
|
@itemx --no-compact-branches
|
|
These options control the generation of compact instructions by the linker
|
|
in the PLT entries for MIPS R6.
|
|
|
|
@end table
|
|
|
|
@c man end
|
|
@end ifset
|
|
|
|
|
|
@ifset PDP11
|
|
@subsection Options specific to PDP11 targets
|
|
|
|
@c man begin OPTIONS
|
|
|
|
For the pdp11-aout target, three variants of the output format can be
|
|
produced as selected by the following options. The default variant
|
|
for pdp11-aout is the @samp{--omagic} option, whereas for other
|
|
targets @samp{--nmagic} is the default. The @samp{--imagic} option is
|
|
defined only for the pdp11-aout target, while the others are described
|
|
here as they apply to the pdp11-aout target.
|
|
|
|
@table @gcctabopt
|
|
|
|
@kindex -N
|
|
@item -N
|
|
@kindex --omagic
|
|
@itemx --omagic
|
|
|
|
Mark the output as @code{OMAGIC} (0407) in the @file{a.out} header to
|
|
indicate that the text segment is not to be write-protected and
|
|
shared. Since the text and data sections are both readable and
|
|
writable, the data section is allocated immediately contiguous after
|
|
the text segment. This is the oldest format for PDP11 executable
|
|
programs and is the default for @command{ld} on PDP11 Unix systems
|
|
from the beginning through 2.11BSD.
|
|
|
|
@kindex -n
|
|
@item -n
|
|
@kindex --nmagic
|
|
@itemx --nmagic
|
|
|
|
Mark the output as @code{NMAGIC} (0410) in the @file{a.out} header to
|
|
indicate that when the output file is executed, the text portion will
|
|
be read-only and shareable among all processes executing the same
|
|
file. This involves moving the data areas up to the first possible 8K
|
|
byte page boundary following the end of the text. This option creates
|
|
a @emph{pure executable} format.
|
|
|
|
@kindex -z
|
|
@item -z
|
|
@kindex --imagic
|
|
@itemx --imagic
|
|
|
|
Mark the output as @code{IMAGIC} (0411) in the @file{a.out} header to
|
|
indicate that when the output file is executed, the program text and
|
|
data areas will be loaded into separate address spaces using the split
|
|
instruction and data space feature of the memory management unit in
|
|
larger models of the PDP11. This doubles the address space available
|
|
to the program. The text segment is again pure, write-protected, and
|
|
shareable. The only difference in the output format between this
|
|
option and the others, besides the magic number, is that both the text
|
|
and data sections start at location 0. The @samp{-z} option selected
|
|
this format in 2.11BSD. This option creates a @emph{separate
|
|
executable} format.
|
|
|
|
@kindex --no-omagic
|
|
@item --no-omagic
|
|
|
|
Equivalent to @samp{--nmagic} for pdp11-aout.
|
|
|
|
@end table
|
|
|
|
@c man end
|
|
@end ifset
|
|
|
|
@ifset UsesEnvVars
|
|
@node Environment
|
|
@section Environment Variables
|
|
|
|
@c man begin ENVIRONMENT
|
|
|
|
You can change the behaviour of @command{ld} with the environment variables
|
|
@ifclear SingleFormat
|
|
@code{GNUTARGET},
|
|
@end ifclear
|
|
@code{LDEMULATION} and @code{COLLECT_NO_DEMANGLE}.
|
|
|
|
@ifclear SingleFormat
|
|
@kindex GNUTARGET
|
|
@cindex default input format
|
|
@code{GNUTARGET} determines the input-file object format if you don't
|
|
use @samp{-b} (or its synonym @samp{--format}). Its value should be one
|
|
of the BFD names for an input format (@pxref{BFD}). If there is no
|
|
@code{GNUTARGET} in the environment, @command{ld} uses the natural format
|
|
of the target. If @code{GNUTARGET} is set to @code{default} then BFD
|
|
attempts to discover the input format by examining binary input files;
|
|
this method often succeeds, but there are potential ambiguities, since
|
|
there is no method of ensuring that the magic number used to specify
|
|
object-file formats is unique. However, the configuration procedure for
|
|
BFD on each system places the conventional format for that system first
|
|
in the search-list, so ambiguities are resolved in favor of convention.
|
|
@end ifclear
|
|
|
|
@kindex LDEMULATION
|
|
@cindex default emulation
|
|
@cindex emulation, default
|
|
@code{LDEMULATION} determines the default emulation if you don't use the
|
|
@samp{-m} option. The emulation can affect various aspects of linker
|
|
behaviour, particularly the default linker script. You can list the
|
|
available emulations with the @samp{--verbose} or @samp{-V} options. If
|
|
the @samp{-m} option is not used, and the @code{LDEMULATION} environment
|
|
variable is not defined, the default emulation depends upon how the
|
|
linker was configured.
|
|
|
|
@kindex COLLECT_NO_DEMANGLE
|
|
@cindex demangling, default
|
|
Normally, the linker will default to demangling symbols. However, if
|
|
@code{COLLECT_NO_DEMANGLE} is set in the environment, then it will
|
|
default to not demangling symbols. This environment variable is used in
|
|
a similar fashion by the @code{gcc} linker wrapper program. The default
|
|
may be overridden by the @samp{--demangle} and @samp{--no-demangle}
|
|
options.
|
|
|
|
@c man end
|
|
@end ifset
|
|
|
|
@node Scripts
|
|
@chapter Linker Scripts
|
|
|
|
@cindex scripts
|
|
@cindex linker scripts
|
|
@cindex command files
|
|
Every link is controlled by a @dfn{linker script}. This script is
|
|
written in the linker command language.
|
|
|
|
The main purpose of the linker script is to describe how the sections in
|
|
the input files should be mapped into the output file, and to control
|
|
the memory layout of the output file. Most linker scripts do nothing
|
|
more than this. However, when necessary, the linker script can also
|
|
direct the linker to perform many other operations, using the commands
|
|
described below.
|
|
|
|
The linker always uses a linker script. If you do not supply one
|
|
yourself, the linker will use a default script that is compiled into the
|
|
linker executable. You can use the @samp{--verbose} command-line option
|
|
to display the default linker script. Certain command-line options,
|
|
such as @samp{-r} or @samp{-N}, will affect the default linker script.
|
|
|
|
You may supply your own linker script by using the @samp{-T} command
|
|
line option. When you do this, your linker script will replace the
|
|
default linker script.
|
|
|
|
You may also use linker scripts implicitly by naming them as input files
|
|
to the linker, as though they were files to be linked. @xref{Implicit
|
|
Linker Scripts}.
|
|
|
|
@menu
|
|
* Basic Script Concepts:: Basic Linker Script Concepts
|
|
* Script Format:: Linker Script Format
|
|
* Simple Example:: Simple Linker Script Example
|
|
* Simple Commands:: Simple Linker Script Commands
|
|
* Assignments:: Assigning Values to Symbols
|
|
* SECTIONS:: SECTIONS Command
|
|
* MEMORY:: MEMORY Command
|
|
* PHDRS:: PHDRS Command
|
|
* VERSION:: VERSION Command
|
|
* Expressions:: Expressions in Linker Scripts
|
|
* Implicit Linker Scripts:: Implicit Linker Scripts
|
|
@end menu
|
|
|
|
@node Basic Script Concepts
|
|
@section Basic Linker Script Concepts
|
|
@cindex linker script concepts
|
|
We need to define some basic concepts and vocabulary in order to
|
|
describe the linker script language.
|
|
|
|
The linker combines input files into a single output file. The output
|
|
file and each input file are in a special data format known as an
|
|
@dfn{object file format}. Each file is called an @dfn{object file}.
|
|
The output file is often called an @dfn{executable}, but for our
|
|
purposes we will also call it an object file. Each object file has,
|
|
among other things, a list of @dfn{sections}. We sometimes refer to a
|
|
section in an input file as an @dfn{input section}; similarly, a section
|
|
in the output file is an @dfn{output section}.
|
|
|
|
Each section in an object file has a name and a size. Most sections
|
|
also have an associated block of data, known as the @dfn{section
|
|
contents}. A section may be marked as @dfn{loadable}, which means that
|
|
the contents should be loaded into memory when the output file is run.
|
|
A section with no contents may be @dfn{allocatable}, which means that an
|
|
area in memory should be set aside, but nothing in particular should be
|
|
loaded there (in some cases this memory must be zeroed out). A section
|
|
which is neither loadable nor allocatable typically contains some sort
|
|
of debugging information.
|
|
|
|
Every loadable or allocatable output section has two addresses. The
|
|
first is the @dfn{VMA}, or virtual memory address. This is the address
|
|
the section will have when the output file is run. The second is the
|
|
@dfn{LMA}, or load memory address. This is the address at which the
|
|
section will be loaded. In most cases the two addresses will be the
|
|
same. An example of when they might be different is when a data section
|
|
is loaded into ROM, and then copied into RAM when the program starts up
|
|
(this technique is often used to initialize global variables in a ROM
|
|
based system). In this case the ROM address would be the LMA, and the
|
|
RAM address would be the VMA.
|
|
|
|
You can see the sections in an object file by using the @code{objdump}
|
|
program with the @samp{-h} option.
|
|
|
|
Every object file also has a list of @dfn{symbols}, known as the
|
|
@dfn{symbol table}. A symbol may be defined or undefined. Each symbol
|
|
has a name, and each defined symbol has an address, among other
|
|
information. If you compile a C or C++ program into an object file, you
|
|
will get a defined symbol for every defined function and global or
|
|
static variable. Every undefined function or global variable which is
|
|
referenced in the input file will become an undefined symbol.
|
|
|
|
You can see the symbols in an object file by using the @code{nm}
|
|
program, or by using the @code{objdump} program with the @samp{-t}
|
|
option.
|
|
|
|
@node Script Format
|
|
@section Linker Script Format
|
|
@cindex linker script format
|
|
Linker scripts are text files.
|
|
|
|
You write a linker script as a series of commands. Each command is
|
|
either a keyword, possibly followed by arguments, or an assignment to a
|
|
symbol. You may separate commands using semicolons. Whitespace is
|
|
generally ignored.
|
|
|
|
Strings such as file or format names can normally be entered directly.
|
|
If the file name contains a character such as a comma which would
|
|
otherwise serve to separate file names, you may put the file name in
|
|
double quotes. There is no way to use a double quote character in a
|
|
file name.
|
|
|
|
You may include comments in linker scripts just as in C, delimited by
|
|
@samp{/*} and @samp{*/}. As in C, comments are syntactically equivalent
|
|
to whitespace.
|
|
|
|
@node Simple Example
|
|
@section Simple Linker Script Example
|
|
@cindex linker script example
|
|
@cindex example of linker script
|
|
Many linker scripts are fairly simple.
|
|
|
|
The simplest possible linker script has just one command:
|
|
@samp{SECTIONS}. You use the @samp{SECTIONS} command to describe the
|
|
memory layout of the output file.
|
|
|
|
The @samp{SECTIONS} command is a powerful command. Here we will
|
|
describe a simple use of it. Let's assume your program consists only of
|
|
code, initialized data, and uninitialized data. These will be in the
|
|
@samp{.text}, @samp{.data}, and @samp{.bss} sections, respectively.
|
|
Let's assume further that these are the only sections which appear in
|
|
your input files.
|
|
|
|
For this example, let's say that the code should be loaded at address
|
|
0x10000, and that the data should start at address 0x8000000. Here is a
|
|
linker script which will do that:
|
|
@smallexample
|
|
SECTIONS
|
|
@{
|
|
. = 0x10000;
|
|
.text : @{ *(.text) @}
|
|
. = 0x8000000;
|
|
.data : @{ *(.data) @}
|
|
.bss : @{ *(.bss) @}
|
|
@}
|
|
@end smallexample
|
|
|
|
You write the @samp{SECTIONS} command as the keyword @samp{SECTIONS},
|
|
followed by a series of symbol assignments and output section
|
|
descriptions enclosed in curly braces.
|
|
|
|
The first line inside the @samp{SECTIONS} command of the above example
|
|
sets the value of the special symbol @samp{.}, which is the location
|
|
counter. If you do not specify the address of an output section in some
|
|
other way (other ways are described later), the address is set from the
|
|
current value of the location counter. The location counter is then
|
|
incremented by the size of the output section. At the start of the
|
|
@samp{SECTIONS} command, the location counter has the value @samp{0}.
|
|
|
|
The second line defines an output section, @samp{.text}. The colon is
|
|
required syntax which may be ignored for now. Within the curly braces
|
|
after the output section name, you list the names of the input sections
|
|
which should be placed into this output section. The @samp{*} is a
|
|
wildcard which matches any file name. The expression @samp{*(.text)}
|
|
means all @samp{.text} input sections in all input files.
|
|
|
|
Since the location counter is @samp{0x10000} when the output section
|
|
@samp{.text} is defined, the linker will set the address of the
|
|
@samp{.text} section in the output file to be @samp{0x10000}.
|
|
|
|
The remaining lines define the @samp{.data} and @samp{.bss} sections in
|
|
the output file. The linker will place the @samp{.data} output section
|
|
at address @samp{0x8000000}. After the linker places the @samp{.data}
|
|
output section, the value of the location counter will be
|
|
@samp{0x8000000} plus the size of the @samp{.data} output section. The
|
|
effect is that the linker will place the @samp{.bss} output section
|
|
immediately after the @samp{.data} output section in memory.
|
|
|
|
The linker will ensure that each output section has the required
|
|
alignment, by increasing the location counter if necessary. In this
|
|
example, the specified addresses for the @samp{.text} and @samp{.data}
|
|
sections will probably satisfy any alignment constraints, but the linker
|
|
may have to create a small gap between the @samp{.data} and @samp{.bss}
|
|
sections.
|
|
|
|
That's it! That's a simple and complete linker script.
|
|
|
|
@node Simple Commands
|
|
@section Simple Linker Script Commands
|
|
@cindex linker script simple commands
|
|
In this section we describe the simple linker script commands.
|
|
|
|
@menu
|
|
* Entry Point:: Setting the entry point
|
|
* File Commands:: Commands dealing with files
|
|
@ifclear SingleFormat
|
|
* Format Commands:: Commands dealing with object file formats
|
|
@end ifclear
|
|
|
|
* REGION_ALIAS:: Assign alias names to memory regions
|
|
* Miscellaneous Commands:: Other linker script commands
|
|
@end menu
|
|
|
|
@node Entry Point
|
|
@subsection Setting the Entry Point
|
|
@kindex ENTRY(@var{symbol})
|
|
@cindex start of execution
|
|
@cindex first instruction
|
|
@cindex entry point
|
|
The first instruction to execute in a program is called the @dfn{entry
|
|
point}. You can use the @code{ENTRY} linker script command to set the
|
|
entry point. The argument is a symbol name:
|
|
@smallexample
|
|
ENTRY(@var{symbol})
|
|
@end smallexample
|
|
|
|
There are several ways to set the entry point. The linker will set the
|
|
entry point by trying each of the following methods in order, and
|
|
stopping when one of them succeeds:
|
|
@itemize @bullet
|
|
@item
|
|
the @samp{-e} @var{entry} command-line option;
|
|
@item
|
|
the @code{ENTRY(@var{symbol})} command in a linker script;
|
|
@item
|
|
the value of a target-specific symbol, if it is defined; For many
|
|
targets this is @code{start}, but PE- and BeOS-based systems for example
|
|
check a list of possible entry symbols, matching the first one found.
|
|
@item
|
|
the address of the first byte of the @samp{.text} section, if present;
|
|
@item
|
|
The address @code{0}.
|
|
@end itemize
|
|
|
|
@node File Commands
|
|
@subsection Commands Dealing with Files
|
|
@cindex linker script file commands
|
|
Several linker script commands deal with files.
|
|
|
|
@table @code
|
|
@item INCLUDE @var{filename}
|
|
@kindex INCLUDE @var{filename}
|
|
@cindex including a linker script
|
|
Include the linker script @var{filename} at this point. The file will
|
|
be searched for in the current directory, and in any directory specified
|
|
with the @option{-L} option. You can nest calls to @code{INCLUDE} up to
|
|
10 levels deep.
|
|
|
|
You can place @code{INCLUDE} directives at the top level, in @code{MEMORY} or
|
|
@code{SECTIONS} commands, or in output section descriptions.
|
|
|
|
@item INPUT(@var{file}, @var{file}, @dots{})
|
|
@itemx INPUT(@var{file} @var{file} @dots{})
|
|
@kindex INPUT(@var{files})
|
|
@cindex input files in linker scripts
|
|
@cindex input object files in linker scripts
|
|
@cindex linker script input object files
|
|
The @code{INPUT} command directs the linker to include the named files
|
|
in the link, as though they were named on the command line.
|
|
|
|
For example, if you always want to include @file{subr.o} any time you do
|
|
a link, but you can't be bothered to put it on every link command line,
|
|
then you can put @samp{INPUT (subr.o)} in your linker script.
|
|
|
|
In fact, if you like, you can list all of your input files in the linker
|
|
script, and then invoke the linker with nothing but a @samp{-T} option.
|
|
|
|
In case a @dfn{sysroot prefix} is configured, and the filename starts
|
|
with the @samp{/} character, and the script being processed was
|
|
located inside the @dfn{sysroot prefix}, the filename will be looked
|
|
for in the @dfn{sysroot prefix}. The @dfn{sysroot prefix} can also be forced by specifying
|
|
@code{=} as the first character in the filename path, or prefixing the
|
|
filename path with @code{$SYSROOT}. See also the description of
|
|
@samp{-L} in @ref{Options,,Command-line Options}.
|
|
|
|
If a @dfn{sysroot prefix} is not used then the linker will try to open
|
|
the file in the directory containing the linker script. If it is not
|
|
found the linker will then search the current directory. If it is still
|
|
not found the linker will search through the archive library search
|
|
path.
|
|
|
|
If you use @samp{INPUT (-l@var{file})}, @command{ld} will transform the
|
|
name to @code{lib@var{file}.a}, as with the command-line argument
|
|
@samp{-l}.
|
|
|
|
When you use the @code{INPUT} command in an implicit linker script, the
|
|
files will be included in the link at the point at which the linker
|
|
script file is included. This can affect archive searching.
|
|
|
|
@item GROUP(@var{file}, @var{file}, @dots{})
|
|
@itemx GROUP(@var{file} @var{file} @dots{})
|
|
@kindex GROUP(@var{files})
|
|
@cindex grouping input files
|
|
The @code{GROUP} command is like @code{INPUT}, except that the named
|
|
files should all be archives, and they are searched repeatedly until no
|
|
new undefined references are created. See the description of @samp{-(}
|
|
in @ref{Options,,Command-line Options}.
|
|
|
|
@item AS_NEEDED(@var{file}, @var{file}, @dots{})
|
|
@itemx AS_NEEDED(@var{file} @var{file} @dots{})
|
|
@kindex AS_NEEDED(@var{files})
|
|
This construct can appear only inside of the @code{INPUT} or @code{GROUP}
|
|
commands, among other filenames. The files listed will be handled
|
|
as if they appear directly in the @code{INPUT} or @code{GROUP} commands,
|
|
with the exception of ELF shared libraries, that will be added only
|
|
when they are actually needed. This construct essentially enables
|
|
@option{--as-needed} option for all the files listed inside of it
|
|
and restores previous @option{--as-needed} resp. @option{--no-as-needed}
|
|
setting afterwards.
|
|
|
|
@item OUTPUT(@var{filename})
|
|
@kindex OUTPUT(@var{filename})
|
|
@cindex output file name in linker script
|
|
The @code{OUTPUT} command names the output file. Using
|
|
@code{OUTPUT(@var{filename})} in the linker script is exactly like using
|
|
@samp{-o @var{filename}} on the command line (@pxref{Options,,Command
|
|
Line Options}). If both are used, the command-line option takes
|
|
precedence.
|
|
|
|
You can use the @code{OUTPUT} command to define a default name for the
|
|
output file other than the usual default of @file{a.out}.
|
|
|
|
@item SEARCH_DIR(@var{path})
|
|
@kindex SEARCH_DIR(@var{path})
|
|
@cindex library search path in linker script
|
|
@cindex archive search path in linker script
|
|
@cindex search path in linker script
|
|
The @code{SEARCH_DIR} command adds @var{path} to the list of paths where
|
|
@command{ld} looks for archive libraries. Using
|
|
@code{SEARCH_DIR(@var{path})} is exactly like using @samp{-L @var{path}}
|
|
on the command line (@pxref{Options,,Command-line Options}). If both
|
|
are used, then the linker will search both paths. Paths specified using
|
|
the command-line option are searched first.
|
|
|
|
@item STARTUP(@var{filename})
|
|
@kindex STARTUP(@var{filename})
|
|
@cindex first input file
|
|
The @code{STARTUP} command is just like the @code{INPUT} command, except
|
|
that @var{filename} will become the first input file to be linked, as
|
|
though it were specified first on the command line. This may be useful
|
|
when using a system in which the entry point is always the start of the
|
|
first file.
|
|
@end table
|
|
|
|
@ifclear SingleFormat
|
|
@node Format Commands
|
|
@subsection Commands Dealing with Object File Formats
|
|
A couple of linker script commands deal with object file formats.
|
|
|
|
@table @code
|
|
@item OUTPUT_FORMAT(@var{bfdname})
|
|
@itemx OUTPUT_FORMAT(@var{default}, @var{big}, @var{little})
|
|
@kindex OUTPUT_FORMAT(@var{bfdname})
|
|
@cindex output file format in linker script
|
|
The @code{OUTPUT_FORMAT} command names the BFD format to use for the
|
|
output file (@pxref{BFD}). Using @code{OUTPUT_FORMAT(@var{bfdname})} is
|
|
exactly like using @samp{--oformat @var{bfdname}} on the command line
|
|
(@pxref{Options,,Command-line Options}). If both are used, the command
|
|
line option takes precedence.
|
|
|
|
You can use @code{OUTPUT_FORMAT} with three arguments to use different
|
|
formats based on the @samp{-EB} and @samp{-EL} command-line options.
|
|
This permits the linker script to set the output format based on the
|
|
desired endianness.
|
|
|
|
If neither @samp{-EB} nor @samp{-EL} are used, then the output format
|
|
will be the first argument, @var{default}. If @samp{-EB} is used, the
|
|
output format will be the second argument, @var{big}. If @samp{-EL} is
|
|
used, the output format will be the third argument, @var{little}.
|
|
|
|
For example, the default linker script for the MIPS ELF target uses this
|
|
command:
|
|
@smallexample
|
|
OUTPUT_FORMAT(elf32-bigmips, elf32-bigmips, elf32-littlemips)
|
|
@end smallexample
|
|
This says that the default format for the output file is
|
|
@samp{elf32-bigmips}, but if the user uses the @samp{-EL} command-line
|
|
option, the output file will be created in the @samp{elf32-littlemips}
|
|
format.
|
|
|
|
@item TARGET(@var{bfdname})
|
|
@kindex TARGET(@var{bfdname})
|
|
@cindex input file format in linker script
|
|
The @code{TARGET} command names the BFD format to use when reading input
|
|
files. It affects subsequent @code{INPUT} and @code{GROUP} commands.
|
|
This command is like using @samp{-b @var{bfdname}} on the command line
|
|
(@pxref{Options,,Command-line Options}). If the @code{TARGET} command
|
|
is used but @code{OUTPUT_FORMAT} is not, then the last @code{TARGET}
|
|
command is also used to set the format for the output file. @xref{BFD}.
|
|
@end table
|
|
@end ifclear
|
|
|
|
@node REGION_ALIAS
|
|
@subsection Assign alias names to memory regions
|
|
@kindex REGION_ALIAS(@var{alias}, @var{region})
|
|
@cindex region alias
|
|
@cindex region names
|
|
|
|
Alias names can be added to existing memory regions created with the
|
|
@ref{MEMORY} command. Each name corresponds to at most one memory region.
|
|
|
|
@smallexample
|
|
REGION_ALIAS(@var{alias}, @var{region})
|
|
@end smallexample
|
|
|
|
The @code{REGION_ALIAS} function creates an alias name @var{alias} for the
|
|
memory region @var{region}. This allows a flexible mapping of output sections
|
|
to memory regions. An example follows.
|
|
|
|
Suppose we have an application for embedded systems which come with various
|
|
memory storage devices. All have a general purpose, volatile memory @code{RAM}
|
|
that allows code execution or data storage. Some may have a read-only,
|
|
non-volatile memory @code{ROM} that allows code execution and read-only data
|
|
access. The last variant is a read-only, non-volatile memory @code{ROM2} with
|
|
read-only data access and no code execution capability. We have four output
|
|
sections:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
@code{.text} program code;
|
|
@item
|
|
@code{.rodata} read-only data;
|
|
@item
|
|
@code{.data} read-write initialized data;
|
|
@item
|
|
@code{.bss} read-write zero initialized data.
|
|
@end itemize
|
|
|
|
The goal is to provide a linker command file that contains a system independent
|
|
part defining the output sections and a system dependent part mapping the
|
|
output sections to the memory regions available on the system. Our embedded
|
|
systems come with three different memory setups @code{A}, @code{B} and
|
|
@code{C}:
|
|
@multitable @columnfractions .25 .25 .25 .25
|
|
@item Section @tab Variant A @tab Variant B @tab Variant C
|
|
@item .text @tab RAM @tab ROM @tab ROM
|
|
@item .rodata @tab RAM @tab ROM @tab ROM2
|
|
@item .data @tab RAM @tab RAM/ROM @tab RAM/ROM2
|
|
@item .bss @tab RAM @tab RAM @tab RAM
|
|
@end multitable
|
|
The notation @code{RAM/ROM} or @code{RAM/ROM2} means that this section is
|
|
loaded into region @code{ROM} or @code{ROM2} respectively. Please note that
|
|
the load address of the @code{.data} section starts in all three variants at
|
|
the end of the @code{.rodata} section.
|
|
|
|
The base linker script that deals with the output sections follows. It
|
|
includes the system dependent @code{linkcmds.memory} file that describes the
|
|
memory layout:
|
|
@smallexample
|
|
INCLUDE linkcmds.memory
|
|
|
|
SECTIONS
|
|
@{
|
|
.text :
|
|
@{
|
|
*(.text)
|
|
@} > REGION_TEXT
|
|
.rodata :
|
|
@{
|
|
*(.rodata)
|
|
rodata_end = .;
|
|
@} > REGION_RODATA
|
|
.data : AT (rodata_end)
|
|
@{
|
|
data_start = .;
|
|
*(.data)
|
|
@} > REGION_DATA
|
|
data_size = SIZEOF(.data);
|
|
data_load_start = LOADADDR(.data);
|
|
.bss :
|
|
@{
|
|
*(.bss)
|
|
@} > REGION_BSS
|
|
@}
|
|
@end smallexample
|
|
|
|
Now we need three different @code{linkcmds.memory} files to define memory
|
|
regions and alias names. The content of @code{linkcmds.memory} for the three
|
|
variants @code{A}, @code{B} and @code{C}:
|
|
@table @code
|
|
@item A
|
|
Here everything goes into the @code{RAM}.
|
|
@smallexample
|
|
MEMORY
|
|
@{
|
|
RAM : ORIGIN = 0, LENGTH = 4M
|
|
@}
|
|
|
|
REGION_ALIAS("REGION_TEXT", RAM);
|
|
REGION_ALIAS("REGION_RODATA", RAM);
|
|
REGION_ALIAS("REGION_DATA", RAM);
|
|
REGION_ALIAS("REGION_BSS", RAM);
|
|
@end smallexample
|
|
@item B
|
|
Program code and read-only data go into the @code{ROM}. Read-write data goes
|
|
into the @code{RAM}. An image of the initialized data is loaded into the
|
|
@code{ROM} and will be copied during system start into the @code{RAM}.
|
|
@smallexample
|
|
MEMORY
|
|
@{
|
|
ROM : ORIGIN = 0, LENGTH = 3M
|
|
RAM : ORIGIN = 0x10000000, LENGTH = 1M
|
|
@}
|
|
|
|
REGION_ALIAS("REGION_TEXT", ROM);
|
|
REGION_ALIAS("REGION_RODATA", ROM);
|
|
REGION_ALIAS("REGION_DATA", RAM);
|
|
REGION_ALIAS("REGION_BSS", RAM);
|
|
@end smallexample
|
|
@item C
|
|
Program code goes into the @code{ROM}. Read-only data goes into the
|
|
@code{ROM2}. Read-write data goes into the @code{RAM}. An image of the
|
|
initialized data is loaded into the @code{ROM2} and will be copied during
|
|
system start into the @code{RAM}.
|
|
@smallexample
|
|
MEMORY
|
|
@{
|
|
ROM : ORIGIN = 0, LENGTH = 2M
|
|
ROM2 : ORIGIN = 0x10000000, LENGTH = 1M
|
|
RAM : ORIGIN = 0x20000000, LENGTH = 1M
|
|
@}
|
|
|
|
REGION_ALIAS("REGION_TEXT", ROM);
|
|
REGION_ALIAS("REGION_RODATA", ROM2);
|
|
REGION_ALIAS("REGION_DATA", RAM);
|
|
REGION_ALIAS("REGION_BSS", RAM);
|
|
@end smallexample
|
|
@end table
|
|
|
|
It is possible to write a common system initialization routine to copy the
|
|
@code{.data} section from @code{ROM} or @code{ROM2} into the @code{RAM} if
|
|
necessary:
|
|
@smallexample
|
|
#include <string.h>
|
|
|
|
extern char data_start [];
|
|
extern char data_size [];
|
|
extern char data_load_start [];
|
|
|
|
void copy_data(void)
|
|
@{
|
|
if (data_start != data_load_start)
|
|
@{
|
|
memcpy(data_start, data_load_start, (size_t) data_size);
|
|
@}
|
|
@}
|
|
@end smallexample
|
|
|
|
@node Miscellaneous Commands
|
|
@subsection Other Linker Script Commands
|
|
There are a few other linker scripts commands.
|
|
|
|
@table @code
|
|
@item ASSERT(@var{exp}, @var{message})
|
|
@kindex ASSERT
|
|
@cindex assertion in linker script
|
|
Ensure that @var{exp} is non-zero. If it is zero, then exit the linker
|
|
with an error code, and print @var{message}.
|
|
|
|
Note that assertions are checked before the final stages of linking
|
|
take place. This means that expressions involving symbols PROVIDEd
|
|
inside section definitions will fail if the user has not set values
|
|
for those symbols. The only exception to this rule is PROVIDEd
|
|
symbols that just reference dot. Thus an assertion like this:
|
|
|
|
@smallexample
|
|
.stack :
|
|
@{
|
|
PROVIDE (__stack = .);
|
|
PROVIDE (__stack_size = 0x100);
|
|
ASSERT ((__stack > (_end + __stack_size)), "Error: No room left for the stack");
|
|
@}
|
|
@end smallexample
|
|
|
|
will fail if @code{__stack_size} is not defined elsewhere. Symbols
|
|
PROVIDEd outside of section definitions are evaluated earlier, so they
|
|
can be used inside ASSERTions. Thus:
|
|
|
|
@smallexample
|
|
PROVIDE (__stack_size = 0x100);
|
|
.stack :
|
|
@{
|
|
PROVIDE (__stack = .);
|
|
ASSERT ((__stack > (_end + __stack_size)), "Error: No room left for the stack");
|
|
@}
|
|
@end smallexample
|
|
|
|
will work.
|
|
|
|
@item EXTERN(@var{symbol} @var{symbol} @dots{})
|
|
@kindex EXTERN
|
|
@cindex undefined symbol in linker script
|
|
Force @var{symbol} to be entered in the output file as an undefined
|
|
symbol. Doing this may, for example, trigger linking of additional
|
|
modules from standard libraries. You may list several @var{symbol}s for
|
|
each @code{EXTERN}, and you may use @code{EXTERN} multiple times. This
|
|
command has the same effect as the @samp{-u} command-line option.
|
|
|
|
@item FORCE_COMMON_ALLOCATION
|
|
@kindex FORCE_COMMON_ALLOCATION
|
|
@cindex common allocation in linker script
|
|
This command has the same effect as the @samp{-d} command-line option:
|
|
to make @command{ld} assign space to common symbols even if a relocatable
|
|
output file is specified (@samp{-r}).
|
|
|
|
@item INHIBIT_COMMON_ALLOCATION
|
|
@kindex INHIBIT_COMMON_ALLOCATION
|
|
@cindex common allocation in linker script
|
|
This command has the same effect as the @samp{--no-define-common}
|
|
command-line option: to make @code{ld} omit the assignment of addresses
|
|
to common symbols even for a non-relocatable output file.
|
|
|
|
@item FORCE_GROUP_ALLOCATION
|
|
@kindex FORCE_GROUP_ALLOCATION
|
|
@cindex group allocation in linker script
|
|
@cindex section groups
|
|
@cindex COMDAT
|
|
This command has the same effect as the
|
|
@samp{--force-group-allocation} command-line option: to make
|
|
@command{ld} place section group members like normal input sections,
|
|
and to delete the section groups even if a relocatable output file is
|
|
specified (@samp{-r}).
|
|
|
|
@item INSERT [ AFTER | BEFORE ] @var{output_section}
|
|
@kindex INSERT
|
|
@cindex insert user script into default script
|
|
This command is typically used in a script specified by @samp{-T} to
|
|
augment the default @code{SECTIONS} with, for example, overlays. It
|
|
inserts all prior linker script statements after (or before)
|
|
@var{output_section}, and also causes @samp{-T} to not override the
|
|
default linker script. The exact insertion point is as for orphan
|
|
sections. @xref{Location Counter}. The insertion happens after the
|
|
linker has mapped input sections to output sections. Prior to the
|
|
insertion, since @samp{-T} scripts are parsed before the default
|
|
linker script, statements in the @samp{-T} script occur before the
|
|
default linker script statements in the internal linker representation
|
|
of the script. In particular, input section assignments will be made
|
|
to @samp{-T} output sections before those in the default script. Here
|
|
is an example of how a @samp{-T} script using @code{INSERT} might look:
|
|
|
|
@smallexample
|
|
SECTIONS
|
|
@{
|
|
OVERLAY :
|
|
@{
|
|
.ov1 @{ ov1*(.text) @}
|
|
.ov2 @{ ov2*(.text) @}
|
|
@}
|
|
@}
|
|
INSERT AFTER .text;
|
|
@end smallexample
|
|
|
|
@item NOCROSSREFS(@var{section} @var{section} @dots{})
|
|
@kindex NOCROSSREFS(@var{sections})
|
|
@cindex cross references
|
|
This command may be used to tell @command{ld} to issue an error about any
|
|
references among certain output sections.
|
|
|
|
In certain types of programs, particularly on embedded systems when
|
|
using overlays, when one section is loaded into memory, another section
|
|
will not be. Any direct references between the two sections would be
|
|
errors. For example, it would be an error if code in one section called
|
|
a function defined in the other section.
|
|
|
|
The @code{NOCROSSREFS} command takes a list of output section names. If
|
|
@command{ld} detects any cross references between the sections, it reports
|
|
an error and returns a non-zero exit status. Note that the
|
|
@code{NOCROSSREFS} command uses output section names, not input section
|
|
names.
|
|
|
|
@item NOCROSSREFS_TO(@var{tosection} @var{fromsection} @dots{})
|
|
@kindex NOCROSSREFS_TO(@var{tosection} @var{fromsections})
|
|
@cindex cross references
|
|
This command may be used to tell @command{ld} to issue an error about any
|
|
references to one section from a list of other sections.
|
|
|
|
The @code{NOCROSSREFS} command is useful when ensuring that two or more
|
|
output sections are entirely independent but there are situations where
|
|
a one-way dependency is needed. For example, in a multi-core application
|
|
there may be shared code that can be called from each core but for safety
|
|
must never call back.
|
|
|
|
The @code{NOCROSSREFS_TO} command takes a list of output section names.
|
|
The first section can not be referenced from any of the other sections.
|
|
If @command{ld} detects any references to the first section from any of
|
|
the other sections, it reports an error and returns a non-zero exit
|
|
status. Note that the @code{NOCROSSREFS_TO} command uses output section
|
|
names, not input section names.
|
|
|
|
@ifclear SingleFormat
|
|
@item OUTPUT_ARCH(@var{bfdarch})
|
|
@kindex OUTPUT_ARCH(@var{bfdarch})
|
|
@cindex machine architecture
|
|
@cindex architecture
|
|
Specify a particular output machine architecture. The argument is one
|
|
of the names used by the BFD library (@pxref{BFD}). You can see the
|
|
architecture of an object file by using the @code{objdump} program with
|
|
the @samp{-f} option.
|
|
@end ifclear
|
|
|
|
@item LD_FEATURE(@var{string})
|
|
@kindex LD_FEATURE(@var{string})
|
|
This command may be used to modify @command{ld} behavior. If
|
|
@var{string} is @code{"SANE_EXPR"} then absolute symbols and numbers
|
|
in a script are simply treated as numbers everywhere.
|
|
@xref{Expression Section}.
|
|
@end table
|
|
|
|
@node Assignments
|
|
@section Assigning Values to Symbols
|
|
@cindex assignment in scripts
|
|
@cindex symbol definition, scripts
|
|
@cindex variables, defining
|
|
You may assign a value to a symbol in a linker script. This will define
|
|
the symbol and place it into the symbol table with a global scope.
|
|
|
|
@menu
|
|
* Simple Assignments:: Simple Assignments
|
|
* HIDDEN:: HIDDEN
|
|
* PROVIDE:: PROVIDE
|
|
* PROVIDE_HIDDEN:: PROVIDE_HIDDEN
|
|
* Source Code Reference:: How to use a linker script defined symbol in source code
|
|
@end menu
|
|
|
|
@node Simple Assignments
|
|
@subsection Simple Assignments
|
|
|
|
You may assign to a symbol using any of the C assignment operators:
|
|
|
|
@table @code
|
|
@item @var{symbol} = @var{expression} ;
|
|
@itemx @var{symbol} += @var{expression} ;
|
|
@itemx @var{symbol} -= @var{expression} ;
|
|
@itemx @var{symbol} *= @var{expression} ;
|
|
@itemx @var{symbol} /= @var{expression} ;
|
|
@itemx @var{symbol} <<= @var{expression} ;
|
|
@itemx @var{symbol} >>= @var{expression} ;
|
|
@itemx @var{symbol} &= @var{expression} ;
|
|
@itemx @var{symbol} |= @var{expression} ;
|
|
@end table
|
|
|
|
The first case will define @var{symbol} to the value of
|
|
@var{expression}. In the other cases, @var{symbol} must already be
|
|
defined, and the value will be adjusted accordingly.
|
|
|
|
The special symbol name @samp{.} indicates the location counter. You
|
|
may only use this within a @code{SECTIONS} command. @xref{Location Counter}.
|
|
|
|
The semicolon after @var{expression} is required.
|
|
|
|
Expressions are defined below; see @ref{Expressions}.
|
|
|
|
You may write symbol assignments as commands in their own right, or as
|
|
statements within a @code{SECTIONS} command, or as part of an output
|
|
section description in a @code{SECTIONS} command.
|
|
|
|
The section of the symbol will be set from the section of the
|
|
expression; for more information, see @ref{Expression Section}.
|
|
|
|
Here is an example showing the three different places that symbol
|
|
assignments may be used:
|
|
|
|
@smallexample
|
|
floating_point = 0;
|
|
SECTIONS
|
|
@{
|
|
.text :
|
|
@{
|
|
*(.text)
|
|
_etext = .;
|
|
@}
|
|
_bdata = (. + 3) & ~ 3;
|
|
.data : @{ *(.data) @}
|
|
@}
|
|
@end smallexample
|
|
@noindent
|
|
In this example, the symbol @samp{floating_point} will be defined as
|
|
zero. The symbol @samp{_etext} will be defined as the address following
|
|
the last @samp{.text} input section. The symbol @samp{_bdata} will be
|
|
defined as the address following the @samp{.text} output section aligned
|
|
upward to a 4 byte boundary.
|
|
|
|
@node HIDDEN
|
|
@subsection HIDDEN
|
|
@cindex HIDDEN
|
|
For ELF targeted ports, define a symbol that will be hidden and won't be
|
|
exported. The syntax is @code{HIDDEN(@var{symbol} = @var{expression})}.
|
|
|
|
Here is the example from @ref{Simple Assignments}, rewritten to use
|
|
@code{HIDDEN}:
|
|
|
|
@smallexample
|
|
HIDDEN(floating_point = 0);
|
|
SECTIONS
|
|
@{
|
|
.text :
|
|
@{
|
|
*(.text)
|
|
HIDDEN(_etext = .);
|
|
@}
|
|
HIDDEN(_bdata = (. + 3) & ~ 3);
|
|
.data : @{ *(.data) @}
|
|
@}
|
|
@end smallexample
|
|
@noindent
|
|
In this case none of the three symbols will be visible outside this module.
|
|
|
|
@node PROVIDE
|
|
@subsection PROVIDE
|
|
@cindex PROVIDE
|
|
In some cases, it is desirable for a linker script to define a symbol
|
|
only if it is referenced and is not defined by any object included in
|
|
the link. For example, traditional linkers defined the symbol
|
|
@samp{etext}. However, ANSI C requires that the user be able to use
|
|
@samp{etext} as a function name without encountering an error. The
|
|
@code{PROVIDE} keyword may be used to define a symbol, such as
|
|
@samp{etext}, only if it is referenced but not defined. The syntax is
|
|
@code{PROVIDE(@var{symbol} = @var{expression})}.
|
|
|
|
Here is an example of using @code{PROVIDE} to define @samp{etext}:
|
|
@smallexample
|
|
SECTIONS
|
|
@{
|
|
.text :
|
|
@{
|
|
*(.text)
|
|
_etext = .;
|
|
PROVIDE(etext = .);
|
|
@}
|
|
@}
|
|
@end smallexample
|
|
|
|
In this example, if the program defines @samp{_etext} (with a leading
|
|
underscore), the linker will give a multiple definition error. If, on
|
|
the other hand, the program defines @samp{etext} (with no leading
|
|
underscore), the linker will silently use the definition in the program.
|
|
If the program references @samp{etext} but does not define it, the
|
|
linker will use the definition in the linker script.
|
|
|
|
Note - the @code{PROVIDE} directive considers a common symbol to be
|
|
defined, even though such a symbol could be combined with the symbol
|
|
that the @code{PROVIDE} would create. This is particularly important
|
|
when considering constructor and destructor list symbols such as
|
|
@samp{__CTOR_LIST__} as these are often defined as common symbols.
|
|
|
|
@node PROVIDE_HIDDEN
|
|
@subsection PROVIDE_HIDDEN
|
|
@cindex PROVIDE_HIDDEN
|
|
Similar to @code{PROVIDE}. For ELF targeted ports, the symbol will be
|
|
hidden and won't be exported.
|
|
|
|
@node Source Code Reference
|
|
@subsection Source Code Reference
|
|
|
|
Accessing a linker script defined variable from source code is not
|
|
intuitive. In particular a linker script symbol is not equivalent to
|
|
a variable declaration in a high level language, it is instead a
|
|
symbol that does not have a value.
|
|
|
|
Before going further, it is important to note that compilers often
|
|
transform names in the source code into different names when they are
|
|
stored in the symbol table. For example, Fortran compilers commonly
|
|
prepend or append an underscore, and C++ performs extensive @samp{name
|
|
mangling}. Therefore there might be a discrepancy between the name
|
|
of a variable as it is used in source code and the name of the same
|
|
variable as it is defined in a linker script. For example in C a
|
|
linker script variable might be referred to as:
|
|
|
|
@smallexample
|
|
extern int foo;
|
|
@end smallexample
|
|
|
|
But in the linker script it might be defined as:
|
|
|
|
@smallexample
|
|
_foo = 1000;
|
|
@end smallexample
|
|
|
|
In the remaining examples however it is assumed that no name
|
|
transformation has taken place.
|
|
|
|
When a symbol is declared in a high level language such as C, two
|
|
things happen. The first is that the compiler reserves enough space
|
|
in the program's memory to hold the @emph{value} of the symbol. The
|
|
second is that the compiler creates an entry in the program's symbol
|
|
table which holds the symbol's @emph{address}. ie the symbol table
|
|
contains the address of the block of memory holding the symbol's
|
|
value. So for example the following C declaration, at file scope:
|
|
|
|
@smallexample
|
|
int foo = 1000;
|
|
@end smallexample
|
|
|
|
creates an entry called @samp{foo} in the symbol table. This entry
|
|
holds the address of an @samp{int} sized block of memory where the
|
|
number 1000 is initially stored.
|
|
|
|
When a program references a symbol the compiler generates code that
|
|
first accesses the symbol table to find the address of the symbol's
|
|
memory block and then code to read the value from that memory block.
|
|
So:
|
|
|
|
@smallexample
|
|
foo = 1;
|
|
@end smallexample
|
|
|
|
looks up the symbol @samp{foo} in the symbol table, gets the address
|
|
associated with this symbol and then writes the value 1 into that
|
|
address. Whereas:
|
|
|
|
@smallexample
|
|
int * a = & foo;
|
|
@end smallexample
|
|
|
|
looks up the symbol @samp{foo} in the symbol table, gets its address
|
|
and then copies this address into the block of memory associated with
|
|
the variable @samp{a}.
|
|
|
|
Linker scripts symbol declarations, by contrast, create an entry in
|
|
the symbol table but do not assign any memory to them. Thus they are
|
|
an address without a value. So for example the linker script definition:
|
|
|
|
@smallexample
|
|
foo = 1000;
|
|
@end smallexample
|
|
|
|
creates an entry in the symbol table called @samp{foo} which holds
|
|
the address of memory location 1000, but nothing special is stored at
|
|
address 1000. This means that you cannot access the @emph{value} of a
|
|
linker script defined symbol - it has no value - all you can do is
|
|
access the @emph{address} of a linker script defined symbol.
|
|
|
|
Hence when you are using a linker script defined symbol in source code
|
|
you should always take the address of the symbol, and never attempt to
|
|
use its value. For example suppose you want to copy the contents of a
|
|
section of memory called .ROM into a section called .FLASH and the
|
|
linker script contains these declarations:
|
|
|
|
@smallexample
|
|
@group
|
|
start_of_ROM = .ROM;
|
|
end_of_ROM = .ROM + sizeof (.ROM);
|
|
start_of_FLASH = .FLASH;
|
|
@end group
|
|
@end smallexample
|
|
|
|
Then the C source code to perform the copy would be:
|
|
|
|
@smallexample
|
|
@group
|
|
extern char start_of_ROM, end_of_ROM, start_of_FLASH;
|
|
|
|
memcpy (& start_of_FLASH, & start_of_ROM, & end_of_ROM - & start_of_ROM);
|
|
@end group
|
|
@end smallexample
|
|
|
|
Note the use of the @samp{&} operators. These are correct.
|
|
Alternatively the symbols can be treated as the names of vectors or
|
|
arrays and then the code will again work as expected:
|
|
|
|
@smallexample
|
|
@group
|
|
extern char start_of_ROM[], end_of_ROM[], start_of_FLASH[];
|
|
|
|
memcpy (start_of_FLASH, start_of_ROM, end_of_ROM - start_of_ROM);
|
|
@end group
|
|
@end smallexample
|
|
|
|
Note how using this method does not require the use of @samp{&}
|
|
operators.
|
|
|
|
@node SECTIONS
|
|
@section SECTIONS Command
|
|
@kindex SECTIONS
|
|
The @code{SECTIONS} command tells the linker how to map input sections
|
|
into output sections, and how to place the output sections in memory.
|
|
|
|
The format of the @code{SECTIONS} command is:
|
|
@smallexample
|
|
SECTIONS
|
|
@{
|
|
@var{sections-command}
|
|
@var{sections-command}
|
|
@dots{}
|
|
@}
|
|
@end smallexample
|
|
|
|
Each @var{sections-command} may of be one of the following:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
an @code{ENTRY} command (@pxref{Entry Point,,Entry command})
|
|
@item
|
|
a symbol assignment (@pxref{Assignments})
|
|
@item
|
|
an output section description
|
|
@item
|
|
an overlay description
|
|
@end itemize
|
|
|
|
The @code{ENTRY} command and symbol assignments are permitted inside the
|
|
@code{SECTIONS} command for convenience in using the location counter in
|
|
those commands. This can also make the linker script easier to
|
|
understand because you can use those commands at meaningful points in
|
|
the layout of the output file.
|
|
|
|
Output section descriptions and overlay descriptions are described
|
|
below.
|
|
|
|
If you do not use a @code{SECTIONS} command in your linker script, the
|
|
linker will place each input section into an identically named output
|
|
section in the order that the sections are first encountered in the
|
|
input files. If all input sections are present in the first file, for
|
|
example, the order of sections in the output file will match the order
|
|
in the first input file. The first section will be at address zero.
|
|
|
|
@menu
|
|
* Output Section Description:: Output section description
|
|
* Output Section Name:: Output section name
|
|
* Output Section Address:: Output section address
|
|
* Input Section:: Input section description
|
|
* Output Section Data:: Output section data
|
|
* Output Section Keywords:: Output section keywords
|
|
* Output Section Discarding:: Output section discarding
|
|
* Output Section Attributes:: Output section attributes
|
|
* Overlay Description:: Overlay description
|
|
@end menu
|
|
|
|
@node Output Section Description
|
|
@subsection Output Section Description
|
|
The full description of an output section looks like this:
|
|
@smallexample
|
|
@group
|
|
@var{section} [@var{address}] [(@var{type})] :
|
|
[AT(@var{lma})]
|
|
[ALIGN(@var{section_align}) | ALIGN_WITH_INPUT]
|
|
[SUBALIGN(@var{subsection_align})]
|
|
[@var{constraint}]
|
|
@{
|
|
@var{output-section-command}
|
|
@var{output-section-command}
|
|
@dots{}
|
|
@} [>@var{region}] [AT>@var{lma_region}] [:@var{phdr} :@var{phdr} @dots{}] [=@var{fillexp}] [,]
|
|
@end group
|
|
@end smallexample
|
|
|
|
Most output sections do not use most of the optional section attributes.
|
|
|
|
The whitespace around @var{section} is required, so that the section
|
|
name is unambiguous. The colon and the curly braces are also required.
|
|
The comma at the end may be required if a @var{fillexp} is used and
|
|
the next @var{sections-command} looks like a continuation of the expression.
|
|
The line breaks and other white space are optional.
|
|
|
|
Each @var{output-section-command} may be one of the following:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
a symbol assignment (@pxref{Assignments})
|
|
@item
|
|
an input section description (@pxref{Input Section})
|
|
@item
|
|
data values to include directly (@pxref{Output Section Data})
|
|
@item
|
|
a special output section keyword (@pxref{Output Section Keywords})
|
|
@end itemize
|
|
|
|
@node Output Section Name
|
|
@subsection Output Section Name
|
|
@cindex name, section
|
|
@cindex section name
|
|
The name of the output section is @var{section}. @var{section} must
|
|
meet the constraints of your output format. In formats which only
|
|
support a limited number of sections, such as @code{a.out}, the name
|
|
must be one of the names supported by the format (@code{a.out}, for
|
|
example, allows only @samp{.text}, @samp{.data} or @samp{.bss}). If the
|
|
output format supports any number of sections, but with numbers and not
|
|
names (as is the case for Oasys), the name should be supplied as a
|
|
quoted numeric string. A section name may consist of any sequence of
|
|
characters, but a name which contains any unusual characters such as
|
|
commas must be quoted.
|
|
|
|
The output section name @samp{/DISCARD/} is special; @ref{Output Section
|
|
Discarding}.
|
|
|
|
@node Output Section Address
|
|
@subsection Output Section Address
|
|
@cindex address, section
|
|
@cindex section address
|
|
The @var{address} is an expression for the VMA (the virtual memory
|
|
address) of the output section. This address is optional, but if it
|
|
is provided then the output address will be set exactly as specified.
|
|
|
|
If the output address is not specified then one will be chosen for the
|
|
section, based on the heuristic below. This address will be adjusted
|
|
to fit the alignment requirement of the output section. The
|
|
alignment requirement is the strictest alignment of any input section
|
|
contained within the output section.
|
|
|
|
The output section address heuristic is as follows:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
If an output memory @var{region} is set for the section then it
|
|
is added to this region and its address will be the next free address
|
|
in that region.
|
|
|
|
@item
|
|
If the MEMORY command has been used to create a list of memory
|
|
regions then the first region which has attributes compatible with the
|
|
section is selected to contain it. The section's output address will
|
|
be the next free address in that region; @ref{MEMORY}.
|
|
|
|
@item
|
|
If no memory regions were specified, or none match the section then
|
|
the output address will be based on the current value of the location
|
|
counter.
|
|
@end itemize
|
|
|
|
@noindent
|
|
For example:
|
|
|
|
@smallexample
|
|
.text . : @{ *(.text) @}
|
|
@end smallexample
|
|
|
|
@noindent
|
|
and
|
|
|
|
@smallexample
|
|
.text : @{ *(.text) @}
|
|
@end smallexample
|
|
|
|
@noindent
|
|
are subtly different. The first will set the address of the
|
|
@samp{.text} output section to the current value of the location
|
|
counter. The second will set it to the current value of the location
|
|
counter aligned to the strictest alignment of any of the @samp{.text}
|
|
input sections.
|
|
|
|
The @var{address} may be an arbitrary expression; @ref{Expressions}.
|
|
For example, if you want to align the section on a 0x10 byte boundary,
|
|
so that the lowest four bits of the section address are zero, you could
|
|
do something like this:
|
|
@smallexample
|
|
.text ALIGN(0x10) : @{ *(.text) @}
|
|
@end smallexample
|
|
@noindent
|
|
This works because @code{ALIGN} returns the current location counter
|
|
aligned upward to the specified value.
|
|
|
|
Specifying @var{address} for a section will change the value of the
|
|
location counter, provided that the section is non-empty. (Empty
|
|
sections are ignored).
|
|
|
|
@node Input Section
|
|
@subsection Input Section Description
|
|
@cindex input sections
|
|
@cindex mapping input sections to output sections
|
|
The most common output section command is an input section description.
|
|
|
|
The input section description is the most basic linker script operation.
|
|
You use output sections to tell the linker how to lay out your program
|
|
in memory. You use input section descriptions to tell the linker how to
|
|
map the input files into your memory layout.
|
|
|
|
@menu
|
|
* Input Section Basics:: Input section basics
|
|
* Input Section Wildcards:: Input section wildcard patterns
|
|
* Input Section Common:: Input section for common symbols
|
|
* Input Section Keep:: Input section and garbage collection
|
|
* Input Section Example:: Input section example
|
|
@end menu
|
|
|
|
@node Input Section Basics
|
|
@subsubsection Input Section Basics
|
|
@cindex input section basics
|
|
An input section description consists of a file name optionally followed
|
|
by a list of section names in parentheses.
|
|
|
|
The file name and the section name may be wildcard patterns, which we
|
|
describe further below (@pxref{Input Section Wildcards}).
|
|
|
|
The most common input section description is to include all input
|
|
sections with a particular name in the output section. For example, to
|
|
include all input @samp{.text} sections, you would write:
|
|
@smallexample
|
|
*(.text)
|
|
@end smallexample
|
|
@noindent
|
|
Here the @samp{*} is a wildcard which matches any file name. To exclude a list
|
|
@cindex EXCLUDE_FILE
|
|
of files from matching the file name wildcard, EXCLUDE_FILE may be used to
|
|
match all files except the ones specified in the EXCLUDE_FILE list. For
|
|
example:
|
|
@smallexample
|
|
EXCLUDE_FILE (*crtend.o *otherfile.o) *(.ctors)
|
|
@end smallexample
|
|
@noindent
|
|
will cause all .ctors sections from all files except @file{crtend.o}
|
|
and @file{otherfile.o} to be included. The EXCLUDE_FILE can also be
|
|
placed inside the section list, for example:
|
|
@smallexample
|
|
*(EXCLUDE_FILE (*crtend.o *otherfile.o) .ctors)
|
|
@end smallexample
|
|
@noindent
|
|
The result of this is identically to the previous example. Supporting
|
|
two syntaxes for EXCLUDE_FILE is useful if the section list contains
|
|
more than one section, as described below.
|
|
|
|
There are two ways to include more than one section:
|
|
@smallexample
|
|
*(.text .rdata)
|
|
*(.text) *(.rdata)
|
|
@end smallexample
|
|
@noindent
|
|
The difference between these is the order in which the @samp{.text} and
|
|
@samp{.rdata} input sections will appear in the output section. In the
|
|
first example, they will be intermingled, appearing in the same order as
|
|
they are found in the linker input. In the second example, all
|
|
@samp{.text} input sections will appear first, followed by all
|
|
@samp{.rdata} input sections.
|
|
|
|
When using EXCLUDE_FILE with more than one section, if the exclusion
|
|
is within the section list then the exclusion only applies to the
|
|
immediately following section, for example:
|
|
@smallexample
|
|
*(EXCLUDE_FILE (*somefile.o) .text .rdata)
|
|
@end smallexample
|
|
@noindent
|
|
will cause all @samp{.text} sections from all files except
|
|
@file{somefile.o} to be included, while all @samp{.rdata} sections
|
|
from all files, including @file{somefile.o}, will be included. To
|
|
exclude the @samp{.rdata} sections from @file{somefile.o} the example
|
|
could be modified to:
|
|
@smallexample
|
|
*(EXCLUDE_FILE (*somefile.o) .text EXCLUDE_FILE (*somefile.o) .rdata)
|
|
@end smallexample
|
|
@noindent
|
|
Alternatively, placing the EXCLUDE_FILE outside of the section list,
|
|
before the input file selection, will cause the exclusion to apply for
|
|
all sections. Thus the previous example can be rewritten as:
|
|
@smallexample
|
|
EXCLUDE_FILE (*somefile.o) *(.text .rdata)
|
|
@end smallexample
|
|
|
|
You can specify a file name to include sections from a particular file.
|
|
You would do this if one or more of your files contain special data that
|
|
needs to be at a particular location in memory. For example:
|
|
@smallexample
|
|
data.o(.data)
|
|
@end smallexample
|
|
|
|
To refine the sections that are included based on the section flags
|
|
of an input section, INPUT_SECTION_FLAGS may be used.
|
|
|
|
Here is a simple example for using Section header flags for ELF sections:
|
|
|
|
@smallexample
|
|
@group
|
|
SECTIONS @{
|
|
.text : @{ INPUT_SECTION_FLAGS (SHF_MERGE & SHF_STRINGS) *(.text) @}
|
|
.text2 : @{ INPUT_SECTION_FLAGS (!SHF_WRITE) *(.text) @}
|
|
@}
|
|
@end group
|
|
@end smallexample
|
|
|
|
In this example, the output section @samp{.text} will be comprised of any
|
|
input section matching the name *(.text) whose section header flags
|
|
@code{SHF_MERGE} and @code{SHF_STRINGS} are set. The output section
|
|
@samp{.text2} will be comprised of any input section matching the name *(.text)
|
|
whose section header flag @code{SHF_WRITE} is clear.
|
|
|
|
You can also specify files within archives by writing a pattern
|
|
matching the archive, a colon, then the pattern matching the file,
|
|
with no whitespace around the colon.
|
|
|
|
@table @samp
|
|
@item archive:file
|
|
matches file within archive
|
|
@item archive:
|
|
matches the whole archive
|
|
@item :file
|
|
matches file but not one in an archive
|
|
@end table
|
|
|
|
Either one or both of @samp{archive} and @samp{file} can contain shell
|
|
wildcards. On DOS based file systems, the linker will assume that a
|
|
single letter followed by a colon is a drive specifier, so
|
|
@samp{c:myfile.o} is a simple file specification, not @samp{myfile.o}
|
|
within an archive called @samp{c}. @samp{archive:file} filespecs may
|
|
also be used within an @code{EXCLUDE_FILE} list, but may not appear in
|
|
other linker script contexts. For instance, you cannot extract a file
|
|
from an archive by using @samp{archive:file} in an @code{INPUT}
|
|
command.
|
|
|
|
If you use a file name without a list of sections, then all sections in
|
|
the input file will be included in the output section. This is not
|
|
commonly done, but it may by useful on occasion. For example:
|
|
@smallexample
|
|
data.o
|
|
@end smallexample
|
|
|
|
When you use a file name which is not an @samp{archive:file} specifier
|
|
and does not contain any wild card
|
|
characters, the linker will first see if you also specified the file
|
|
name on the linker command line or in an @code{INPUT} command. If you
|
|
did not, the linker will attempt to open the file as an input file, as
|
|
though it appeared on the command line. Note that this differs from an
|
|
@code{INPUT} command, because the linker will not search for the file in
|
|
the archive search path.
|
|
|
|
@node Input Section Wildcards
|
|
@subsubsection Input Section Wildcard Patterns
|
|
@cindex input section wildcards
|
|
@cindex wildcard file name patterns
|
|
@cindex file name wildcard patterns
|
|
@cindex section name wildcard patterns
|
|
In an input section description, either the file name or the section
|
|
name or both may be wildcard patterns.
|
|
|
|
The file name of @samp{*} seen in many examples is a simple wildcard
|
|
pattern for the file name.
|
|
|
|
The wildcard patterns are like those used by the Unix shell.
|
|
|
|
@table @samp
|
|
@item *
|
|
matches any number of characters
|
|
@item ?
|
|
matches any single character
|
|
@item [@var{chars}]
|
|
matches a single instance of any of the @var{chars}; the @samp{-}
|
|
character may be used to specify a range of characters, as in
|
|
@samp{[a-z]} to match any lower case letter
|
|
@item \
|
|
quotes the following character
|
|
@end table
|
|
|
|
When a file name is matched with a wildcard, the wildcard characters
|
|
will not match a @samp{/} character (used to separate directory names on
|
|
Unix). A pattern consisting of a single @samp{*} character is an
|
|
exception; it will always match any file name, whether it contains a
|
|
@samp{/} or not. In a section name, the wildcard characters will match
|
|
a @samp{/} character.
|
|
|
|
File name wildcard patterns only match files which are explicitly
|
|
specified on the command line or in an @code{INPUT} command. The linker
|
|
does not search directories to expand wildcards.
|
|
|
|
If a file name matches more than one wildcard pattern, or if a file name
|
|
appears explicitly and is also matched by a wildcard pattern, the linker
|
|
will use the first match in the linker script. For example, this
|
|
sequence of input section descriptions is probably in error, because the
|
|
@file{data.o} rule will not be used:
|
|
@smallexample
|
|
.data : @{ *(.data) @}
|
|
.data1 : @{ data.o(.data) @}
|
|
@end smallexample
|
|
|
|
@cindex SORT_BY_NAME
|
|
Normally, the linker will place files and sections matched by wildcards
|
|
in the order in which they are seen during the link. You can change
|
|
this by using the @code{SORT_BY_NAME} keyword, which appears before a wildcard
|
|
pattern in parentheses (e.g., @code{SORT_BY_NAME(.text*)}). When the
|
|
@code{SORT_BY_NAME} keyword is used, the linker will sort the files or sections
|
|
into ascending order by name before placing them in the output file.
|
|
|
|
@cindex SORT_BY_ALIGNMENT
|
|
@code{SORT_BY_ALIGNMENT} is similar to @code{SORT_BY_NAME}.
|
|
@code{SORT_BY_ALIGNMENT} will sort sections into descending order of
|
|
alignment before placing them in the output file. Placing larger
|
|
alignments before smaller alignments can reduce the amount of padding
|
|
needed.
|
|
|
|
@cindex SORT_BY_INIT_PRIORITY
|
|
@code{SORT_BY_INIT_PRIORITY} is also similar to @code{SORT_BY_NAME}.
|
|
@code{SORT_BY_INIT_PRIORITY} will sort sections into ascending
|
|
numerical order of the GCC init_priority attribute encoded in the
|
|
section name before placing them in the output file. In
|
|
@code{.init_array.NNNNN} and @code{.fini_array.NNNNN}, @code{NNNNN} is
|
|
the init_priority. In @code{.ctors.NNNNN} and @code{.dtors.NNNNN},
|
|
@code{NNNNN} is 65535 minus the init_priority.
|
|
|
|
@cindex SORT
|
|
@code{SORT} is an alias for @code{SORT_BY_NAME}.
|
|
|
|
When there are nested section sorting commands in linker script, there
|
|
can be at most 1 level of nesting for section sorting commands.
|
|
|
|
@enumerate
|
|
@item
|
|
@code{SORT_BY_NAME} (@code{SORT_BY_ALIGNMENT} (wildcard section pattern)).
|
|
It will sort the input sections by name first, then by alignment if two
|
|
sections have the same name.
|
|
@item
|
|
@code{SORT_BY_ALIGNMENT} (@code{SORT_BY_NAME} (wildcard section pattern)).
|
|
It will sort the input sections by alignment first, then by name if two
|
|
sections have the same alignment.
|
|
@item
|
|
@code{SORT_BY_NAME} (@code{SORT_BY_NAME} (wildcard section pattern)) is
|
|
treated the same as @code{SORT_BY_NAME} (wildcard section pattern).
|
|
@item
|
|
@code{SORT_BY_ALIGNMENT} (@code{SORT_BY_ALIGNMENT} (wildcard section pattern))
|
|
is treated the same as @code{SORT_BY_ALIGNMENT} (wildcard section pattern).
|
|
@item
|
|
All other nested section sorting commands are invalid.
|
|
@end enumerate
|
|
|
|
When both command-line section sorting option and linker script
|
|
section sorting command are used, section sorting command always
|
|
takes precedence over the command-line option.
|
|
|
|
If the section sorting command in linker script isn't nested, the
|
|
command-line option will make the section sorting command to be
|
|
treated as nested sorting command.
|
|
|
|
@enumerate
|
|
@item
|
|
@code{SORT_BY_NAME} (wildcard section pattern ) with
|
|
@option{--sort-sections alignment} is equivalent to
|
|
@code{SORT_BY_NAME} (@code{SORT_BY_ALIGNMENT} (wildcard section pattern)).
|
|
@item
|
|
@code{SORT_BY_ALIGNMENT} (wildcard section pattern) with
|
|
@option{--sort-section name} is equivalent to
|
|
@code{SORT_BY_ALIGNMENT} (@code{SORT_BY_NAME} (wildcard section pattern)).
|
|
@end enumerate
|
|
|
|
If the section sorting command in linker script is nested, the
|
|
command-line option will be ignored.
|
|
|
|
@cindex SORT_NONE
|
|
@code{SORT_NONE} disables section sorting by ignoring the command-line
|
|
section sorting option.
|
|
|
|
If you ever get confused about where input sections are going, use the
|
|
@samp{-M} linker option to generate a map file. The map file shows
|
|
precisely how input sections are mapped to output sections.
|
|
|
|
This example shows how wildcard patterns might be used to partition
|
|
files. This linker script directs the linker to place all @samp{.text}
|
|
sections in @samp{.text} and all @samp{.bss} sections in @samp{.bss}.
|
|
The linker will place the @samp{.data} section from all files beginning
|
|
with an upper case character in @samp{.DATA}; for all other files, the
|
|
linker will place the @samp{.data} section in @samp{.data}.
|
|
@smallexample
|
|
@group
|
|
SECTIONS @{
|
|
.text : @{ *(.text) @}
|
|
.DATA : @{ [A-Z]*(.data) @}
|
|
.data : @{ *(.data) @}
|
|
.bss : @{ *(.bss) @}
|
|
@}
|
|
@end group
|
|
@end smallexample
|
|
|
|
@node Input Section Common
|
|
@subsubsection Input Section for Common Symbols
|
|
@cindex common symbol placement
|
|
@cindex uninitialized data placement
|
|
A special notation is needed for common symbols, because in many object
|
|
file formats common symbols do not have a particular input section. The
|
|
linker treats common symbols as though they are in an input section
|
|
named @samp{COMMON}.
|
|
|
|
You may use file names with the @samp{COMMON} section just as with any
|
|
other input sections. You can use this to place common symbols from a
|
|
particular input file in one section while common symbols from other
|
|
input files are placed in another section.
|
|
|
|
In most cases, common symbols in input files will be placed in the
|
|
@samp{.bss} section in the output file. For example:
|
|
@smallexample
|
|
.bss @{ *(.bss) *(COMMON) @}
|
|
@end smallexample
|
|
|
|
@cindex scommon section
|
|
@cindex small common symbols
|
|
Some object file formats have more than one type of common symbol. For
|
|
example, the MIPS ELF object file format distinguishes standard common
|
|
symbols and small common symbols. In this case, the linker will use a
|
|
different special section name for other types of common symbols. In
|
|
the case of MIPS ELF, the linker uses @samp{COMMON} for standard common
|
|
symbols and @samp{.scommon} for small common symbols. This permits you
|
|
to map the different types of common symbols into memory at different
|
|
locations.
|
|
|
|
@cindex [COMMON]
|
|
You will sometimes see @samp{[COMMON]} in old linker scripts. This
|
|
notation is now considered obsolete. It is equivalent to
|
|
@samp{*(COMMON)}.
|
|
|
|
@node Input Section Keep
|
|
@subsubsection Input Section and Garbage Collection
|
|
@cindex KEEP
|
|
@cindex garbage collection
|
|
When link-time garbage collection is in use (@samp{--gc-sections}),
|
|
it is often useful to mark sections that should not be eliminated.
|
|
This is accomplished by surrounding an input section's wildcard entry
|
|
with @code{KEEP()}, as in @code{KEEP(*(.init))} or
|
|
@code{KEEP(SORT_BY_NAME(*)(.ctors))}.
|
|
|
|
@node Input Section Example
|
|
@subsubsection Input Section Example
|
|
The following example is a complete linker script. It tells the linker
|
|
to read all of the sections from file @file{all.o} and place them at the
|
|
start of output section @samp{outputa} which starts at location
|
|
@samp{0x10000}. All of section @samp{.input1} from file @file{foo.o}
|
|
follows immediately, in the same output section. All of section
|
|
@samp{.input2} from @file{foo.o} goes into output section
|
|
@samp{outputb}, followed by section @samp{.input1} from @file{foo1.o}.
|
|
All of the remaining @samp{.input1} and @samp{.input2} sections from any
|
|
files are written to output section @samp{outputc}.
|
|
|
|
@smallexample
|
|
@group
|
|
SECTIONS @{
|
|
outputa 0x10000 :
|
|
@{
|
|
all.o
|
|
foo.o (.input1)
|
|
@}
|
|
@end group
|
|
@group
|
|
outputb :
|
|
@{
|
|
foo.o (.input2)
|
|
foo1.o (.input1)
|
|
@}
|
|
@end group
|
|
@group
|
|
outputc :
|
|
@{
|
|
*(.input1)
|
|
*(.input2)
|
|
@}
|
|
@}
|
|
@end group
|
|
@end smallexample
|
|
|
|
If an output section's name is the same as the input section's name
|
|
and is representable as a C identifier, then the linker will
|
|
automatically @pxref{PROVIDE} two symbols: __start_SECNAME and
|
|
__stop_SECNAME, where SECNAME is the name of the section. These
|
|
indicate the start address and end address of the output section
|
|
respectively. Note: most section names are not representable as
|
|
C identifiers because they contain a @samp{.} character.
|
|
|
|
@node Output Section Data
|
|
@subsection Output Section Data
|
|
@cindex data
|
|
@cindex section data
|
|
@cindex output section data
|
|
@kindex BYTE(@var{expression})
|
|
@kindex SHORT(@var{expression})
|
|
@kindex LONG(@var{expression})
|
|
@kindex QUAD(@var{expression})
|
|
@kindex SQUAD(@var{expression})
|
|
You can include explicit bytes of data in an output section by using
|
|
@code{BYTE}, @code{SHORT}, @code{LONG}, @code{QUAD}, or @code{SQUAD} as
|
|
an output section command. Each keyword is followed by an expression in
|
|
parentheses providing the value to store (@pxref{Expressions}). The
|
|
value of the expression is stored at the current value of the location
|
|
counter.
|
|
|
|
The @code{BYTE}, @code{SHORT}, @code{LONG}, and @code{QUAD} commands
|
|
store one, two, four, and eight bytes (respectively). After storing the
|
|
bytes, the location counter is incremented by the number of bytes
|
|
stored.
|
|
|
|
For example, this will store the byte 1 followed by the four byte value
|
|
of the symbol @samp{addr}:
|
|
@smallexample
|
|
BYTE(1)
|
|
LONG(addr)
|
|
@end smallexample
|
|
|
|
When using a 64 bit host or target, @code{QUAD} and @code{SQUAD} are the
|
|
same; they both store an 8 byte, or 64 bit, value. When both host and
|
|
target are 32 bits, an expression is computed as 32 bits. In this case
|
|
@code{QUAD} stores a 32 bit value zero extended to 64 bits, and
|
|
@code{SQUAD} stores a 32 bit value sign extended to 64 bits.
|
|
|
|
If the object file format of the output file has an explicit endianness,
|
|
which is the normal case, the value will be stored in that endianness.
|
|
When the object file format does not have an explicit endianness, as is
|
|
true of, for example, S-records, the value will be stored in the
|
|
endianness of the first input object file.
|
|
|
|
Note---these commands only work inside a section description and not
|
|
between them, so the following will produce an error from the linker:
|
|
@smallexample
|
|
SECTIONS @{@ .text : @{@ *(.text) @}@ LONG(1) .data : @{@ *(.data) @}@ @}@
|
|
@end smallexample
|
|
whereas this will work:
|
|
@smallexample
|
|
SECTIONS @{@ .text : @{@ *(.text) ; LONG(1) @}@ .data : @{@ *(.data) @}@ @}@
|
|
@end smallexample
|
|
|
|
@kindex FILL(@var{expression})
|
|
@cindex holes, filling
|
|
@cindex unspecified memory
|
|
You may use the @code{FILL} command to set the fill pattern for the
|
|
current section. It is followed by an expression in parentheses. Any
|
|
otherwise unspecified regions of memory within the section (for example,
|
|
gaps left due to the required alignment of input sections) are filled
|
|
with the value of the expression, repeated as
|
|
necessary. A @code{FILL} statement covers memory locations after the
|
|
point at which it occurs in the section definition; by including more
|
|
than one @code{FILL} statement, you can have different fill patterns in
|
|
different parts of an output section.
|
|
|
|
This example shows how to fill unspecified regions of memory with the
|
|
value @samp{0x90}:
|
|
@smallexample
|
|
FILL(0x90909090)
|
|
@end smallexample
|
|
|
|
The @code{FILL} command is similar to the @samp{=@var{fillexp}} output
|
|
section attribute, but it only affects the
|
|
part of the section following the @code{FILL} command, rather than the
|
|
entire section. If both are used, the @code{FILL} command takes
|
|
precedence. @xref{Output Section Fill}, for details on the fill
|
|
expression.
|
|
|
|
@node Output Section Keywords
|
|
@subsection Output Section Keywords
|
|
There are a couple of keywords which can appear as output section
|
|
commands.
|
|
|
|
@table @code
|
|
@kindex CREATE_OBJECT_SYMBOLS
|
|
@cindex input filename symbols
|
|
@cindex filename symbols
|
|
@item CREATE_OBJECT_SYMBOLS
|
|
The command tells the linker to create a symbol for each input file.
|
|
The name of each symbol will be the name of the corresponding input
|
|
file. The section of each symbol will be the output section in which
|
|
the @code{CREATE_OBJECT_SYMBOLS} command appears.
|
|
|
|
This is conventional for the a.out object file format. It is not
|
|
normally used for any other object file format.
|
|
|
|
@kindex CONSTRUCTORS
|
|
@cindex C++ constructors, arranging in link
|
|
@cindex constructors, arranging in link
|
|
@item CONSTRUCTORS
|
|
When linking using the a.out object file format, the linker uses an
|
|
unusual set construct to support C++ global constructors and
|
|
destructors. When linking object file formats which do not support
|
|
arbitrary sections, such as ECOFF and XCOFF, the linker will
|
|
automatically recognize C++ global constructors and destructors by name.
|
|
For these object file formats, the @code{CONSTRUCTORS} command tells the
|
|
linker to place constructor information in the output section where the
|
|
@code{CONSTRUCTORS} command appears. The @code{CONSTRUCTORS} command is
|
|
ignored for other object file formats.
|
|
|
|
The symbol @w{@code{__CTOR_LIST__}} marks the start of the global
|
|
constructors, and the symbol @w{@code{__CTOR_END__}} marks the end.
|
|
Similarly, @w{@code{__DTOR_LIST__}} and @w{@code{__DTOR_END__}} mark
|
|
the start and end of the global destructors. The
|
|
first word in the list is the number of entries, followed by the address
|
|
of each constructor or destructor, followed by a zero word. The
|
|
compiler must arrange to actually run the code. For these object file
|
|
formats @sc{gnu} C++ normally calls constructors from a subroutine
|
|
@code{__main}; a call to @code{__main} is automatically inserted into
|
|
the startup code for @code{main}. @sc{gnu} C++ normally runs
|
|
destructors either by using @code{atexit}, or directly from the function
|
|
@code{exit}.
|
|
|
|
For object file formats such as @code{COFF} or @code{ELF} which support
|
|
arbitrary section names, @sc{gnu} C++ will normally arrange to put the
|
|
addresses of global constructors and destructors into the @code{.ctors}
|
|
and @code{.dtors} sections. Placing the following sequence into your
|
|
linker script will build the sort of table which the @sc{gnu} C++
|
|
runtime code expects to see.
|
|
|
|
@smallexample
|
|
__CTOR_LIST__ = .;
|
|
LONG((__CTOR_END__ - __CTOR_LIST__) / 4 - 2)
|
|
*(.ctors)
|
|
LONG(0)
|
|
__CTOR_END__ = .;
|
|
__DTOR_LIST__ = .;
|
|
LONG((__DTOR_END__ - __DTOR_LIST__) / 4 - 2)
|
|
*(.dtors)
|
|
LONG(0)
|
|
__DTOR_END__ = .;
|
|
@end smallexample
|
|
|
|
If you are using the @sc{gnu} C++ support for initialization priority,
|
|
which provides some control over the order in which global constructors
|
|
are run, you must sort the constructors at link time to ensure that they
|
|
are executed in the correct order. When using the @code{CONSTRUCTORS}
|
|
command, use @samp{SORT_BY_NAME(CONSTRUCTORS)} instead. When using the
|
|
@code{.ctors} and @code{.dtors} sections, use @samp{*(SORT_BY_NAME(.ctors))} and
|
|
@samp{*(SORT_BY_NAME(.dtors))} instead of just @samp{*(.ctors)} and
|
|
@samp{*(.dtors)}.
|
|
|
|
Normally the compiler and linker will handle these issues automatically,
|
|
and you will not need to concern yourself with them. However, you may
|
|
need to consider this if you are using C++ and writing your own linker
|
|
scripts.
|
|
|
|
@end table
|
|
|
|
@node Output Section Discarding
|
|
@subsection Output Section Discarding
|
|
@cindex discarding sections
|
|
@cindex sections, discarding
|
|
@cindex removing sections
|
|
The linker will not normally create output sections with no contents.
|
|
This is for convenience when referring to input sections that may or
|
|
may not be present in any of the input files. For example:
|
|
@smallexample
|
|
.foo : @{ *(.foo) @}
|
|
@end smallexample
|
|
@noindent
|
|
will only create a @samp{.foo} section in the output file if there is a
|
|
@samp{.foo} section in at least one input file, and if the input
|
|
sections are not all empty. Other link script directives that allocate
|
|
space in an output section will also create the output section. So
|
|
too will assignments to dot even if the assignment does not create
|
|
space, except for @samp{. = 0}, @samp{. = . + 0}, @samp{. = sym},
|
|
@samp{. = . + sym} and @samp{. = ALIGN (. != 0, expr, 1)} when
|
|
@samp{sym} is an absolute symbol of value 0 defined in the script.
|
|
This allows you to force output of an empty section with @samp{. = .}.
|
|
|
|
The linker will ignore address assignments (@pxref{Output Section Address})
|
|
on discarded output sections, except when the linker script defines
|
|
symbols in the output section. In that case the linker will obey
|
|
the address assignments, possibly advancing dot even though the
|
|
section is discarded.
|
|
|
|
@cindex /DISCARD/
|
|
The special output section name @samp{/DISCARD/} may be used to discard
|
|
input sections. Any input sections which are assigned to an output
|
|
section named @samp{/DISCARD/} are not included in the output file.
|
|
|
|
Note, sections that match the @samp{/DISCARD/} output section will be
|
|
discarded even if they are in an ELF section group which has other
|
|
members which are not being discarded. This is deliberate.
|
|
Discarding takes precedence over grouping.
|
|
|
|
@node Output Section Attributes
|
|
@subsection Output Section Attributes
|
|
@cindex output section attributes
|
|
We showed above that the full description of an output section looked
|
|
like this:
|
|
|
|
@smallexample
|
|
@group
|
|
@var{section} [@var{address}] [(@var{type})] :
|
|
[AT(@var{lma})]
|
|
[ALIGN(@var{section_align}) | ALIGN_WITH_INPUT]
|
|
[SUBALIGN(@var{subsection_align})]
|
|
[@var{constraint}]
|
|
@{
|
|
@var{output-section-command}
|
|
@var{output-section-command}
|
|
@dots{}
|
|
@} [>@var{region}] [AT>@var{lma_region}] [:@var{phdr} :@var{phdr} @dots{}] [=@var{fillexp}]
|
|
@end group
|
|
@end smallexample
|
|
|
|
We've already described @var{section}, @var{address}, and
|
|
@var{output-section-command}. In this section we will describe the
|
|
remaining section attributes.
|
|
|
|
@menu
|
|
* Output Section Type:: Output section type
|
|
* Output Section LMA:: Output section LMA
|
|
* Forced Output Alignment:: Forced Output Alignment
|
|
* Forced Input Alignment:: Forced Input Alignment
|
|
* Output Section Constraint:: Output section constraint
|
|
* Output Section Region:: Output section region
|
|
* Output Section Phdr:: Output section phdr
|
|
* Output Section Fill:: Output section fill
|
|
@end menu
|
|
|
|
@node Output Section Type
|
|
@subsubsection Output Section Type
|
|
Each output section may have a type. The type is a keyword in
|
|
parentheses. The following types are defined:
|
|
|
|
@table @code
|
|
@item NOLOAD
|
|
The section should be marked as not loadable, so that it will not be
|
|
loaded into memory when the program is run.
|
|
@item DSECT
|
|
@itemx COPY
|
|
@itemx INFO
|
|
@itemx OVERLAY
|
|
These type names are supported for backward compatibility, and are
|
|
rarely used. They all have the same effect: the section should be
|
|
marked as not allocatable, so that no memory is allocated for the
|
|
section when the program is run.
|
|
@end table
|
|
|
|
@kindex NOLOAD
|
|
@cindex prevent unnecessary loading
|
|
@cindex loading, preventing
|
|
The linker normally sets the attributes of an output section based on
|
|
the input sections which map into it. You can override this by using
|
|
the section type. For example, in the script sample below, the
|
|
@samp{ROM} section is addressed at memory location @samp{0} and does not
|
|
need to be loaded when the program is run.
|
|
@smallexample
|
|
@group
|
|
SECTIONS @{
|
|
ROM 0 (NOLOAD) : @{ @dots{} @}
|
|
@dots{}
|
|
@}
|
|
@end group
|
|
@end smallexample
|
|
|
|
@node Output Section LMA
|
|
@subsubsection Output Section LMA
|
|
@kindex AT>@var{lma_region}
|
|
@kindex AT(@var{lma})
|
|
@cindex load address
|
|
@cindex section load address
|
|
Every section has a virtual address (VMA) and a load address (LMA); see
|
|
@ref{Basic Script Concepts}. The virtual address is specified by the
|
|
@pxref{Output Section Address} described earlier. The load address is
|
|
specified by the @code{AT} or @code{AT>} keywords. Specifying a load
|
|
address is optional.
|
|
|
|
The @code{AT} keyword takes an expression as an argument. This
|
|
specifies the exact load address of the section. The @code{AT>} keyword
|
|
takes the name of a memory region as an argument. @xref{MEMORY}. The
|
|
load address of the section is set to the next free address in the
|
|
region, aligned to the section's alignment requirements.
|
|
|
|
If neither @code{AT} nor @code{AT>} is specified for an allocatable
|
|
section, the linker will use the following heuristic to determine the
|
|
load address:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
If the section has a specific VMA address, then this is used as
|
|
the LMA address as well.
|
|
|
|
@item
|
|
If the section is not allocatable then its LMA is set to its VMA.
|
|
|
|
@item
|
|
Otherwise if a memory region can be found that is compatible
|
|
with the current section, and this region contains at least one
|
|
section, then the LMA is set so the difference between the
|
|
VMA and LMA is the same as the difference between the VMA and LMA of
|
|
the last section in the located region.
|
|
|
|
@item
|
|
If no memory regions have been declared then a default region
|
|
that covers the entire address space is used in the previous step.
|
|
|
|
@item
|
|
If no suitable region could be found, or there was no previous
|
|
section then the LMA is set equal to the VMA.
|
|
@end itemize
|
|
|
|
@cindex ROM initialized data
|
|
@cindex initialized data in ROM
|
|
This feature is designed to make it easy to build a ROM image. For
|
|
example, the following linker script creates three output sections: one
|
|
called @samp{.text}, which starts at @code{0x1000}, one called
|
|
@samp{.mdata}, which is loaded at the end of the @samp{.text} section
|
|
even though its VMA is @code{0x2000}, and one called @samp{.bss} to hold
|
|
uninitialized data at address @code{0x3000}. The symbol @code{_data} is
|
|
defined with the value @code{0x2000}, which shows that the location
|
|
counter holds the VMA value, not the LMA value.
|
|
|
|
@smallexample
|
|
@group
|
|
SECTIONS
|
|
@{
|
|
.text 0x1000 : @{ *(.text) _etext = . ; @}
|
|
.mdata 0x2000 :
|
|
AT ( ADDR (.text) + SIZEOF (.text) )
|
|
@{ _data = . ; *(.data); _edata = . ; @}
|
|
.bss 0x3000 :
|
|
@{ _bstart = . ; *(.bss) *(COMMON) ; _bend = . ;@}
|
|
@}
|
|
@end group
|
|
@end smallexample
|
|
|
|
The run-time initialization code for use with a program generated with
|
|
this linker script would include something like the following, to copy
|
|
the initialized data from the ROM image to its runtime address. Notice
|
|
how this code takes advantage of the symbols defined by the linker
|
|
script.
|
|
|
|
@smallexample
|
|
@group
|
|
extern char _etext, _data, _edata, _bstart, _bend;
|
|
char *src = &_etext;
|
|
char *dst = &_data;
|
|
|
|
/* ROM has data at end of text; copy it. */
|
|
while (dst < &_edata)
|
|
*dst++ = *src++;
|
|
|
|
/* Zero bss. */
|
|
for (dst = &_bstart; dst< &_bend; dst++)
|
|
*dst = 0;
|
|
@end group
|
|
@end smallexample
|
|
|
|
@node Forced Output Alignment
|
|
@subsubsection Forced Output Alignment
|
|
@kindex ALIGN(@var{section_align})
|
|
@cindex forcing output section alignment
|
|
@cindex output section alignment
|
|
You can increase an output section's alignment by using ALIGN. As an
|
|
alternative you can enforce that the difference between the VMA and LMA remains
|
|
intact throughout this output section with the ALIGN_WITH_INPUT attribute.
|
|
|
|
@node Forced Input Alignment
|
|
@subsubsection Forced Input Alignment
|
|
@kindex SUBALIGN(@var{subsection_align})
|
|
@cindex forcing input section alignment
|
|
@cindex input section alignment
|
|
You can force input section alignment within an output section by using
|
|
SUBALIGN. The value specified overrides any alignment given by input
|
|
sections, whether larger or smaller.
|
|
|
|
@node Output Section Constraint
|
|
@subsubsection Output Section Constraint
|
|
@kindex ONLY_IF_RO
|
|
@kindex ONLY_IF_RW
|
|
@cindex constraints on output sections
|
|
You can specify that an output section should only be created if all
|
|
of its input sections are read-only or all of its input sections are
|
|
read-write by using the keyword @code{ONLY_IF_RO} and
|
|
@code{ONLY_IF_RW} respectively.
|
|
|
|
@node Output Section Region
|
|
@subsubsection Output Section Region
|
|
@kindex >@var{region}
|
|
@cindex section, assigning to memory region
|
|
@cindex memory regions and sections
|
|
You can assign a section to a previously defined region of memory by
|
|
using @samp{>@var{region}}. @xref{MEMORY}.
|
|
|
|
Here is a simple example:
|
|
@smallexample
|
|
@group
|
|
MEMORY @{ rom : ORIGIN = 0x1000, LENGTH = 0x1000 @}
|
|
SECTIONS @{ ROM : @{ *(.text) @} >rom @}
|
|
@end group
|
|
@end smallexample
|
|
|
|
@node Output Section Phdr
|
|
@subsubsection Output Section Phdr
|
|
@kindex :@var{phdr}
|
|
@cindex section, assigning to program header
|
|
@cindex program headers and sections
|
|
You can assign a section to a previously defined program segment by
|
|
using @samp{:@var{phdr}}. @xref{PHDRS}. If a section is assigned to
|
|
one or more segments, then all subsequent allocated sections will be
|
|
assigned to those segments as well, unless they use an explicitly
|
|
@code{:@var{phdr}} modifier. You can use @code{:NONE} to tell the
|
|
linker to not put the section in any segment at all.
|
|
|
|
Here is a simple example:
|
|
@smallexample
|
|
@group
|
|
PHDRS @{ text PT_LOAD ; @}
|
|
SECTIONS @{ .text : @{ *(.text) @} :text @}
|
|
@end group
|
|
@end smallexample
|
|
|
|
@node Output Section Fill
|
|
@subsubsection Output Section Fill
|
|
@kindex =@var{fillexp}
|
|
@cindex section fill pattern
|
|
@cindex fill pattern, entire section
|
|
You can set the fill pattern for an entire section by using
|
|
@samp{=@var{fillexp}}. @var{fillexp} is an expression
|
|
(@pxref{Expressions}). Any otherwise unspecified regions of memory
|
|
within the output section (for example, gaps left due to the required
|
|
alignment of input sections) will be filled with the value, repeated as
|
|
necessary. If the fill expression is a simple hex number, ie. a string
|
|
of hex digit starting with @samp{0x} and without a trailing @samp{k} or @samp{M}, then
|
|
an arbitrarily long sequence of hex digits can be used to specify the
|
|
fill pattern; Leading zeros become part of the pattern too. For all
|
|
other cases, including extra parentheses or a unary @code{+}, the fill
|
|
pattern is the four least significant bytes of the value of the
|
|
expression. In all cases, the number is big-endian.
|
|
|
|
You can also change the fill value with a @code{FILL} command in the
|
|
output section commands; (@pxref{Output Section Data}).
|
|
|
|
Here is a simple example:
|
|
@smallexample
|
|
@group
|
|
SECTIONS @{ .text : @{ *(.text) @} =0x90909090 @}
|
|
@end group
|
|
@end smallexample
|
|
|
|
@node Overlay Description
|
|
@subsection Overlay Description
|
|
@kindex OVERLAY
|
|
@cindex overlays
|
|
An overlay description provides an easy way to describe sections which
|
|
are to be loaded as part of a single memory image but are to be run at
|
|
the same memory address. At run time, some sort of overlay manager will
|
|
copy the overlaid sections in and out of the runtime memory address as
|
|
required, perhaps by simply manipulating addressing bits. This approach
|
|
can be useful, for example, when a certain region of memory is faster
|
|
than another.
|
|
|
|
Overlays are described using the @code{OVERLAY} command. The
|
|
@code{OVERLAY} command is used within a @code{SECTIONS} command, like an
|
|
output section description. The full syntax of the @code{OVERLAY}
|
|
command is as follows:
|
|
@smallexample
|
|
@group
|
|
OVERLAY [@var{start}] : [NOCROSSREFS] [AT ( @var{ldaddr} )]
|
|
@{
|
|
@var{secname1}
|
|
@{
|
|
@var{output-section-command}
|
|
@var{output-section-command}
|
|
@dots{}
|
|
@} [:@var{phdr}@dots{}] [=@var{fill}]
|
|
@var{secname2}
|
|
@{
|
|
@var{output-section-command}
|
|
@var{output-section-command}
|
|
@dots{}
|
|
@} [:@var{phdr}@dots{}] [=@var{fill}]
|
|
@dots{}
|
|
@} [>@var{region}] [:@var{phdr}@dots{}] [=@var{fill}] [,]
|
|
@end group
|
|
@end smallexample
|
|
|
|
Everything is optional except @code{OVERLAY} (a keyword), and each
|
|
section must have a name (@var{secname1} and @var{secname2} above). The
|
|
section definitions within the @code{OVERLAY} construct are identical to
|
|
those within the general @code{SECTIONS} construct (@pxref{SECTIONS}),
|
|
except that no addresses and no memory regions may be defined for
|
|
sections within an @code{OVERLAY}.
|
|
|
|
The comma at the end may be required if a @var{fill} is used and
|
|
the next @var{sections-command} looks like a continuation of the expression.
|
|
|
|
The sections are all defined with the same starting address. The load
|
|
addresses of the sections are arranged such that they are consecutive in
|
|
memory starting at the load address used for the @code{OVERLAY} as a
|
|
whole (as with normal section definitions, the load address is optional,
|
|
and defaults to the start address; the start address is also optional,
|
|
and defaults to the current value of the location counter).
|
|
|
|
If the @code{NOCROSSREFS} keyword is used, and there are any
|
|
references among the sections, the linker will report an error. Since
|
|
the sections all run at the same address, it normally does not make
|
|
sense for one section to refer directly to another.
|
|
@xref{Miscellaneous Commands, NOCROSSREFS}.
|
|
|
|
For each section within the @code{OVERLAY}, the linker automatically
|
|
provides two symbols. The symbol @code{__load_start_@var{secname}} is
|
|
defined as the starting load address of the section. The symbol
|
|
@code{__load_stop_@var{secname}} is defined as the final load address of
|
|
the section. Any characters within @var{secname} which are not legal
|
|
within C identifiers are removed. C (or assembler) code may use these
|
|
symbols to move the overlaid sections around as necessary.
|
|
|
|
At the end of the overlay, the value of the location counter is set to
|
|
the start address of the overlay plus the size of the largest section.
|
|
|
|
Here is an example. Remember that this would appear inside a
|
|
@code{SECTIONS} construct.
|
|
@smallexample
|
|
@group
|
|
OVERLAY 0x1000 : AT (0x4000)
|
|
@{
|
|
.text0 @{ o1/*.o(.text) @}
|
|
.text1 @{ o2/*.o(.text) @}
|
|
@}
|
|
@end group
|
|
@end smallexample
|
|
@noindent
|
|
This will define both @samp{.text0} and @samp{.text1} to start at
|
|
address 0x1000. @samp{.text0} will be loaded at address 0x4000, and
|
|
@samp{.text1} will be loaded immediately after @samp{.text0}. The
|
|
following symbols will be defined if referenced: @code{__load_start_text0},
|
|
@code{__load_stop_text0}, @code{__load_start_text1},
|
|
@code{__load_stop_text1}.
|
|
|
|
C code to copy overlay @code{.text1} into the overlay area might look
|
|
like the following.
|
|
|
|
@smallexample
|
|
@group
|
|
extern char __load_start_text1, __load_stop_text1;
|
|
memcpy ((char *) 0x1000, &__load_start_text1,
|
|
&__load_stop_text1 - &__load_start_text1);
|
|
@end group
|
|
@end smallexample
|
|
|
|
Note that the @code{OVERLAY} command is just syntactic sugar, since
|
|
everything it does can be done using the more basic commands. The above
|
|
example could have been written identically as follows.
|
|
|
|
@smallexample
|
|
@group
|
|
.text0 0x1000 : AT (0x4000) @{ o1/*.o(.text) @}
|
|
PROVIDE (__load_start_text0 = LOADADDR (.text0));
|
|
PROVIDE (__load_stop_text0 = LOADADDR (.text0) + SIZEOF (.text0));
|
|
.text1 0x1000 : AT (0x4000 + SIZEOF (.text0)) @{ o2/*.o(.text) @}
|
|
PROVIDE (__load_start_text1 = LOADADDR (.text1));
|
|
PROVIDE (__load_stop_text1 = LOADADDR (.text1) + SIZEOF (.text1));
|
|
. = 0x1000 + MAX (SIZEOF (.text0), SIZEOF (.text1));
|
|
@end group
|
|
@end smallexample
|
|
|
|
@node MEMORY
|
|
@section MEMORY Command
|
|
@kindex MEMORY
|
|
@cindex memory regions
|
|
@cindex regions of memory
|
|
@cindex allocating memory
|
|
@cindex discontinuous memory
|
|
The linker's default configuration permits allocation of all available
|
|
memory. You can override this by using the @code{MEMORY} command.
|
|
|
|
The @code{MEMORY} command describes the location and size of blocks of
|
|
memory in the target. You can use it to describe which memory regions
|
|
may be used by the linker, and which memory regions it must avoid. You
|
|
can then assign sections to particular memory regions. The linker will
|
|
set section addresses based on the memory regions, and will warn about
|
|
regions that become too full. The linker will not shuffle sections
|
|
around to fit into the available regions.
|
|
|
|
A linker script may contain many uses of the @code{MEMORY} command,
|
|
however, all memory blocks defined are treated as if they were
|
|
specified inside a single @code{MEMORY} command. The syntax for
|
|
@code{MEMORY} is:
|
|
@smallexample
|
|
@group
|
|
MEMORY
|
|
@{
|
|
@var{name} [(@var{attr})] : ORIGIN = @var{origin}, LENGTH = @var{len}
|
|
@dots{}
|
|
@}
|
|
@end group
|
|
@end smallexample
|
|
|
|
The @var{name} is a name used in the linker script to refer to the
|
|
region. The region name has no meaning outside of the linker script.
|
|
Region names are stored in a separate name space, and will not conflict
|
|
with symbol names, file names, or section names. Each memory region
|
|
must have a distinct name within the @code{MEMORY} command. However you can
|
|
add later alias names to existing memory regions with the @ref{REGION_ALIAS}
|
|
command.
|
|
|
|
@cindex memory region attributes
|
|
The @var{attr} string is an optional list of attributes that specify
|
|
whether to use a particular memory region for an input section which is
|
|
not explicitly mapped in the linker script. As described in
|
|
@ref{SECTIONS}, if you do not specify an output section for some input
|
|
section, the linker will create an output section with the same name as
|
|
the input section. If you define region attributes, the linker will use
|
|
them to select the memory region for the output section that it creates.
|
|
|
|
The @var{attr} string must consist only of the following characters:
|
|
@table @samp
|
|
@item R
|
|
Read-only section
|
|
@item W
|
|
Read/write section
|
|
@item X
|
|
Executable section
|
|
@item A
|
|
Allocatable section
|
|
@item I
|
|
Initialized section
|
|
@item L
|
|
Same as @samp{I}
|
|
@item !
|
|
Invert the sense of any of the attributes that follow
|
|
@end table
|
|
|
|
If an unmapped section matches any of the listed attributes other than
|
|
@samp{!}, it will be placed in the memory region. The @samp{!}
|
|
attribute reverses the test for the characters that follow, so that an
|
|
unmapped section will be placed in the memory region only if it does
|
|
not match any of the attributes listed afterwards. Thus an attribute
|
|
string of @samp{RW!X} will match any unmapped section that has either
|
|
or both of the @samp{R} and @samp{W} attributes, but only as long as
|
|
the section does not also have the @samp{X} attribute.
|
|
|
|
@kindex ORIGIN =
|
|
@kindex o =
|
|
@kindex org =
|
|
The @var{origin} is an numerical expression for the start address of
|
|
the memory region. The expression must evaluate to a constant and it
|
|
cannot involve any symbols. The keyword @code{ORIGIN} may be
|
|
abbreviated to @code{org} or @code{o} (but not, for example,
|
|
@code{ORG}).
|
|
|
|
@kindex LENGTH =
|
|
@kindex len =
|
|
@kindex l =
|
|
The @var{len} is an expression for the size in bytes of the memory
|
|
region. As with the @var{origin} expression, the expression must
|
|
be numerical only and must evaluate to a constant. The keyword
|
|
@code{LENGTH} may be abbreviated to @code{len} or @code{l}.
|
|
|
|
In the following example, we specify that there are two memory regions
|
|
available for allocation: one starting at @samp{0} for 256 kilobytes,
|
|
and the other starting at @samp{0x40000000} for four megabytes. The
|
|
linker will place into the @samp{rom} memory region every section which
|
|
is not explicitly mapped into a memory region, and is either read-only
|
|
or executable. The linker will place other sections which are not
|
|
explicitly mapped into a memory region into the @samp{ram} memory
|
|
region.
|
|
|
|
@smallexample
|
|
@group
|
|
MEMORY
|
|
@{
|
|
rom (rx) : ORIGIN = 0, LENGTH = 256K
|
|
ram (!rx) : org = 0x40000000, l = 4M
|
|
@}
|
|
@end group
|
|
@end smallexample
|
|
|
|
Once you define a memory region, you can direct the linker to place
|
|
specific output sections into that memory region by using the
|
|
@samp{>@var{region}} output section attribute. For example, if you have
|
|
a memory region named @samp{mem}, you would use @samp{>mem} in the
|
|
output section definition. @xref{Output Section Region}. If no address
|
|
was specified for the output section, the linker will set the address to
|
|
the next available address within the memory region. If the combined
|
|
output sections directed to a memory region are too large for the
|
|
region, the linker will issue an error message.
|
|
|
|
It is possible to access the origin and length of a memory in an
|
|
expression via the @code{ORIGIN(@var{memory})} and
|
|
@code{LENGTH(@var{memory})} functions:
|
|
|
|
@smallexample
|
|
@group
|
|
_fstack = ORIGIN(ram) + LENGTH(ram) - 4;
|
|
@end group
|
|
@end smallexample
|
|
|
|
@node PHDRS
|
|
@section PHDRS Command
|
|
@kindex PHDRS
|
|
@cindex program headers
|
|
@cindex ELF program headers
|
|
@cindex program segments
|
|
@cindex segments, ELF
|
|
The ELF object file format uses @dfn{program headers}, also knows as
|
|
@dfn{segments}. The program headers describe how the program should be
|
|
loaded into memory. You can print them out by using the @code{objdump}
|
|
program with the @samp{-p} option.
|
|
|
|
When you run an ELF program on a native ELF system, the system loader
|
|
reads the program headers in order to figure out how to load the
|
|
program. This will only work if the program headers are set correctly.
|
|
This manual does not describe the details of how the system loader
|
|
interprets program headers; for more information, see the ELF ABI.
|
|
|
|
The linker will create reasonable program headers by default. However,
|
|
in some cases, you may need to specify the program headers more
|
|
precisely. You may use the @code{PHDRS} command for this purpose. When
|
|
the linker sees the @code{PHDRS} command in the linker script, it will
|
|
not create any program headers other than the ones specified.
|
|
|
|
The linker only pays attention to the @code{PHDRS} command when
|
|
generating an ELF output file. In other cases, the linker will simply
|
|
ignore @code{PHDRS}.
|
|
|
|
This is the syntax of the @code{PHDRS} command. The words @code{PHDRS},
|
|
@code{FILEHDR}, @code{AT}, and @code{FLAGS} are keywords.
|
|
|
|
@smallexample
|
|
@group
|
|
PHDRS
|
|
@{
|
|
@var{name} @var{type} [ FILEHDR ] [ PHDRS ] [ AT ( @var{address} ) ]
|
|
[ FLAGS ( @var{flags} ) ] ;
|
|
@}
|
|
@end group
|
|
@end smallexample
|
|
|
|
The @var{name} is used only for reference in the @code{SECTIONS} command
|
|
of the linker script. It is not put into the output file. Program
|
|
header names are stored in a separate name space, and will not conflict
|
|
with symbol names, file names, or section names. Each program header
|
|
must have a distinct name. The headers are processed in order and it
|
|
is usual for them to map to sections in ascending load address order.
|
|
|
|
Certain program header types describe segments of memory which the
|
|
system loader will load from the file. In the linker script, you
|
|
specify the contents of these segments by placing allocatable output
|
|
sections in the segments. You use the @samp{:@var{phdr}} output section
|
|
attribute to place a section in a particular segment. @xref{Output
|
|
Section Phdr}.
|
|
|
|
It is normal to put certain sections in more than one segment. This
|
|
merely implies that one segment of memory contains another. You may
|
|
repeat @samp{:@var{phdr}}, using it once for each segment which should
|
|
contain the section.
|
|
|
|
If you place a section in one or more segments using @samp{:@var{phdr}},
|
|
then the linker will place all subsequent allocatable sections which do
|
|
not specify @samp{:@var{phdr}} in the same segments. This is for
|
|
convenience, since generally a whole set of contiguous sections will be
|
|
placed in a single segment. You can use @code{:NONE} to override the
|
|
default segment and tell the linker to not put the section in any
|
|
segment at all.
|
|
|
|
@kindex FILEHDR
|
|
@kindex PHDRS
|
|
You may use the @code{FILEHDR} and @code{PHDRS} keywords after
|
|
the program header type to further describe the contents of the segment.
|
|
The @code{FILEHDR} keyword means that the segment should include the ELF
|
|
file header. The @code{PHDRS} keyword means that the segment should
|
|
include the ELF program headers themselves. If applied to a loadable
|
|
segment (@code{PT_LOAD}), all prior loadable segments must have one of
|
|
these keywords.
|
|
|
|
The @var{type} may be one of the following. The numbers indicate the
|
|
value of the keyword.
|
|
|
|
@table @asis
|
|
@item @code{PT_NULL} (0)
|
|
Indicates an unused program header.
|
|
|
|
@item @code{PT_LOAD} (1)
|
|
Indicates that this program header describes a segment to be loaded from
|
|
the file.
|
|
|
|
@item @code{PT_DYNAMIC} (2)
|
|
Indicates a segment where dynamic linking information can be found.
|
|
|
|
@item @code{PT_INTERP} (3)
|
|
Indicates a segment where the name of the program interpreter may be
|
|
found.
|
|
|
|
@item @code{PT_NOTE} (4)
|
|
Indicates a segment holding note information.
|
|
|
|
@item @code{PT_SHLIB} (5)
|
|
A reserved program header type, defined but not specified by the ELF
|
|
ABI.
|
|
|
|
@item @code{PT_PHDR} (6)
|
|
Indicates a segment where the program headers may be found.
|
|
|
|
@item @code{PT_TLS} (7)
|
|
Indicates a segment containing thread local storage.
|
|
|
|
@item @var{expression}
|
|
An expression giving the numeric type of the program header. This may
|
|
be used for types not defined above.
|
|
@end table
|
|
|
|
You can specify that a segment should be loaded at a particular address
|
|
in memory by using an @code{AT} expression. This is identical to the
|
|
@code{AT} command used as an output section attribute (@pxref{Output
|
|
Section LMA}). The @code{AT} command for a program header overrides the
|
|
output section attribute.
|
|
|
|
The linker will normally set the segment flags based on the sections
|
|
which comprise the segment. You may use the @code{FLAGS} keyword to
|
|
explicitly specify the segment flags. The value of @var{flags} must be
|
|
an integer. It is used to set the @code{p_flags} field of the program
|
|
header.
|
|
|
|
Here is an example of @code{PHDRS}. This shows a typical set of program
|
|
headers used on a native ELF system.
|
|
|
|
@example
|
|
@group
|
|
PHDRS
|
|
@{
|
|
headers PT_PHDR PHDRS ;
|
|
interp PT_INTERP ;
|
|
text PT_LOAD FILEHDR PHDRS ;
|
|
data PT_LOAD ;
|
|
dynamic PT_DYNAMIC ;
|
|
@}
|
|
|
|
SECTIONS
|
|
@{
|
|
. = SIZEOF_HEADERS;
|
|
.interp : @{ *(.interp) @} :text :interp
|
|
.text : @{ *(.text) @} :text
|
|
.rodata : @{ *(.rodata) @} /* defaults to :text */
|
|
@dots{}
|
|
. = . + 0x1000; /* move to a new page in memory */
|
|
.data : @{ *(.data) @} :data
|
|
.dynamic : @{ *(.dynamic) @} :data :dynamic
|
|
@dots{}
|
|
@}
|
|
@end group
|
|
@end example
|
|
|
|
@node VERSION
|
|
@section VERSION Command
|
|
@kindex VERSION @{script text@}
|
|
@cindex symbol versions
|
|
@cindex version script
|
|
@cindex versions of symbols
|
|
The linker supports symbol versions when using ELF. Symbol versions are
|
|
only useful when using shared libraries. The dynamic linker can use
|
|
symbol versions to select a specific version of a function when it runs
|
|
a program that may have been linked against an earlier version of the
|
|
shared library.
|
|
|
|
You can include a version script directly in the main linker script, or
|
|
you can supply the version script as an implicit linker script. You can
|
|
also use the @samp{--version-script} linker option.
|
|
|
|
The syntax of the @code{VERSION} command is simply
|
|
@smallexample
|
|
VERSION @{ version-script-commands @}
|
|
@end smallexample
|
|
|
|
The format of the version script commands is identical to that used by
|
|
Sun's linker in Solaris 2.5. The version script defines a tree of
|
|
version nodes. You specify the node names and interdependencies in the
|
|
version script. You can specify which symbols are bound to which
|
|
version nodes, and you can reduce a specified set of symbols to local
|
|
scope so that they are not globally visible outside of the shared
|
|
library.
|
|
|
|
The easiest way to demonstrate the version script language is with a few
|
|
examples.
|
|
|
|
@smallexample
|
|
VERS_1.1 @{
|
|
global:
|
|
foo1;
|
|
local:
|
|
old*;
|
|
original*;
|
|
new*;
|
|
@};
|
|
|
|
VERS_1.2 @{
|
|
foo2;
|
|
@} VERS_1.1;
|
|
|
|
VERS_2.0 @{
|
|
bar1; bar2;
|
|
extern "C++" @{
|
|
ns::*;
|
|
"f(int, double)";
|
|
@};
|
|
@} VERS_1.2;
|
|
@end smallexample
|
|
|
|
This example version script defines three version nodes. The first
|
|
version node defined is @samp{VERS_1.1}; it has no other dependencies.
|
|
The script binds the symbol @samp{foo1} to @samp{VERS_1.1}. It reduces
|
|
a number of symbols to local scope so that they are not visible outside
|
|
of the shared library; this is done using wildcard patterns, so that any
|
|
symbol whose name begins with @samp{old}, @samp{original}, or @samp{new}
|
|
is matched. The wildcard patterns available are the same as those used
|
|
in the shell when matching filenames (also known as ``globbing'').
|
|
However, if you specify the symbol name inside double quotes, then the
|
|
name is treated as literal, rather than as a glob pattern.
|
|
|
|
Next, the version script defines node @samp{VERS_1.2}. This node
|
|
depends upon @samp{VERS_1.1}. The script binds the symbol @samp{foo2}
|
|
to the version node @samp{VERS_1.2}.
|
|
|
|
Finally, the version script defines node @samp{VERS_2.0}. This node
|
|
depends upon @samp{VERS_1.2}. The scripts binds the symbols @samp{bar1}
|
|
and @samp{bar2} are bound to the version node @samp{VERS_2.0}.
|
|
|
|
When the linker finds a symbol defined in a library which is not
|
|
specifically bound to a version node, it will effectively bind it to an
|
|
unspecified base version of the library. You can bind all otherwise
|
|
unspecified symbols to a given version node by using @samp{global: *;}
|
|
somewhere in the version script. Note that it's slightly crazy to use
|
|
wildcards in a global spec except on the last version node. Global
|
|
wildcards elsewhere run the risk of accidentally adding symbols to the
|
|
set exported for an old version. That's wrong since older versions
|
|
ought to have a fixed set of symbols.
|
|
|
|
The names of the version nodes have no specific meaning other than what
|
|
they might suggest to the person reading them. The @samp{2.0} version
|
|
could just as well have appeared in between @samp{1.1} and @samp{1.2}.
|
|
However, this would be a confusing way to write a version script.
|
|
|
|
Node name can be omitted, provided it is the only version node
|
|
in the version script. Such version script doesn't assign any versions to
|
|
symbols, only selects which symbols will be globally visible out and which
|
|
won't.
|
|
|
|
@smallexample
|
|
@{ global: foo; bar; local: *; @};
|
|
@end smallexample
|
|
|
|
When you link an application against a shared library that has versioned
|
|
symbols, the application itself knows which version of each symbol it
|
|
requires, and it also knows which version nodes it needs from each
|
|
shared library it is linked against. Thus at runtime, the dynamic
|
|
loader can make a quick check to make sure that the libraries you have
|
|
linked against do in fact supply all of the version nodes that the
|
|
application will need to resolve all of the dynamic symbols. In this
|
|
way it is possible for the dynamic linker to know with certainty that
|
|
all external symbols that it needs will be resolvable without having to
|
|
search for each symbol reference.
|
|
|
|
The symbol versioning is in effect a much more sophisticated way of
|
|
doing minor version checking that SunOS does. The fundamental problem
|
|
that is being addressed here is that typically references to external
|
|
functions are bound on an as-needed basis, and are not all bound when
|
|
the application starts up. If a shared library is out of date, a
|
|
required interface may be missing; when the application tries to use
|
|
that interface, it may suddenly and unexpectedly fail. With symbol
|
|
versioning, the user will get a warning when they start their program if
|
|
the libraries being used with the application are too old.
|
|
|
|
There are several GNU extensions to Sun's versioning approach. The
|
|
first of these is the ability to bind a symbol to a version node in the
|
|
source file where the symbol is defined instead of in the versioning
|
|
script. This was done mainly to reduce the burden on the library
|
|
maintainer. You can do this by putting something like:
|
|
@smallexample
|
|
__asm__(".symver original_foo,foo@@VERS_1.1");
|
|
@end smallexample
|
|
@noindent
|
|
in the C source file. This renames the function @samp{original_foo} to
|
|
be an alias for @samp{foo} bound to the version node @samp{VERS_1.1}.
|
|
The @samp{local:} directive can be used to prevent the symbol
|
|
@samp{original_foo} from being exported. A @samp{.symver} directive
|
|
takes precedence over a version script.
|
|
|
|
The second GNU extension is to allow multiple versions of the same
|
|
function to appear in a given shared library. In this way you can make
|
|
an incompatible change to an interface without increasing the major
|
|
version number of the shared library, while still allowing applications
|
|
linked against the old interface to continue to function.
|
|
|
|
To do this, you must use multiple @samp{.symver} directives in the
|
|
source file. Here is an example:
|
|
|
|
@smallexample
|
|
__asm__(".symver original_foo,foo@@");
|
|
__asm__(".symver old_foo,foo@@VERS_1.1");
|
|
__asm__(".symver old_foo1,foo@@VERS_1.2");
|
|
__asm__(".symver new_foo,foo@@@@VERS_2.0");
|
|
@end smallexample
|
|
|
|
In this example, @samp{foo@@} represents the symbol @samp{foo} bound to the
|
|
unspecified base version of the symbol. The source file that contains this
|
|
example would define 4 C functions: @samp{original_foo}, @samp{old_foo},
|
|
@samp{old_foo1}, and @samp{new_foo}.
|
|
|
|
When you have multiple definitions of a given symbol, there needs to be
|
|
some way to specify a default version to which external references to
|
|
this symbol will be bound. You can do this with the
|
|
@samp{foo@@@@VERS_2.0} type of @samp{.symver} directive. You can only
|
|
declare one version of a symbol as the default in this manner; otherwise
|
|
you would effectively have multiple definitions of the same symbol.
|
|
|
|
If you wish to bind a reference to a specific version of the symbol
|
|
within the shared library, you can use the aliases of convenience
|
|
(i.e., @samp{old_foo}), or you can use the @samp{.symver} directive to
|
|
specifically bind to an external version of the function in question.
|
|
|
|
You can also specify the language in the version script:
|
|
|
|
@smallexample
|
|
VERSION extern "lang" @{ version-script-commands @}
|
|
@end smallexample
|
|
|
|
The supported @samp{lang}s are @samp{C}, @samp{C++}, and @samp{Java}.
|
|
The linker will iterate over the list of symbols at the link time and
|
|
demangle them according to @samp{lang} before matching them to the
|
|
patterns specified in @samp{version-script-commands}. The default
|
|
@samp{lang} is @samp{C}.
|
|
|
|
Demangled names may contains spaces and other special characters. As
|
|
described above, you can use a glob pattern to match demangled names,
|
|
or you can use a double-quoted string to match the string exactly. In
|
|
the latter case, be aware that minor differences (such as differing
|
|
whitespace) between the version script and the demangler output will
|
|
cause a mismatch. As the exact string generated by the demangler
|
|
might change in the future, even if the mangled name does not, you
|
|
should check that all of your version directives are behaving as you
|
|
expect when you upgrade.
|
|
|
|
@node Expressions
|
|
@section Expressions in Linker Scripts
|
|
@cindex expressions
|
|
@cindex arithmetic
|
|
The syntax for expressions in the linker script language is identical to
|
|
that of C expressions. All expressions are evaluated as integers. All
|
|
expressions are evaluated in the same size, which is 32 bits if both the
|
|
host and target are 32 bits, and is otherwise 64 bits.
|
|
|
|
You can use and set symbol values in expressions.
|
|
|
|
The linker defines several special purpose builtin functions for use in
|
|
expressions.
|
|
|
|
@menu
|
|
* Constants:: Constants
|
|
* Symbolic Constants:: Symbolic constants
|
|
* Symbols:: Symbol Names
|
|
* Orphan Sections:: Orphan Sections
|
|
* Location Counter:: The Location Counter
|
|
* Operators:: Operators
|
|
* Evaluation:: Evaluation
|
|
* Expression Section:: The Section of an Expression
|
|
* Builtin Functions:: Builtin Functions
|
|
@end menu
|
|
|
|
@node Constants
|
|
@subsection Constants
|
|
@cindex integer notation
|
|
@cindex constants in linker scripts
|
|
All constants are integers.
|
|
|
|
As in C, the linker considers an integer beginning with @samp{0} to be
|
|
octal, and an integer beginning with @samp{0x} or @samp{0X} to be
|
|
hexadecimal. Alternatively the linker accepts suffixes of @samp{h} or
|
|
@samp{H} for hexadecimal, @samp{o} or @samp{O} for octal, @samp{b} or
|
|
@samp{B} for binary and @samp{d} or @samp{D} for decimal. Any integer
|
|
value without a prefix or a suffix is considered to be decimal.
|
|
|
|
@cindex scaled integers
|
|
@cindex K and M integer suffixes
|
|
@cindex M and K integer suffixes
|
|
@cindex suffixes for integers
|
|
@cindex integer suffixes
|
|
In addition, you can use the suffixes @code{K} and @code{M} to scale a
|
|
constant by
|
|
@c TEXI2ROFF-KILL
|
|
@ifnottex
|
|
@c END TEXI2ROFF-KILL
|
|
@code{1024} or @code{1024*1024}
|
|
@c TEXI2ROFF-KILL
|
|
@end ifnottex
|
|
@tex
|
|
${\rm 1024}$ or ${\rm 1024}^2$
|
|
@end tex
|
|
@c END TEXI2ROFF-KILL
|
|
respectively. For example, the following
|
|
all refer to the same quantity:
|
|
|
|
@smallexample
|
|
_fourk_1 = 4K;
|
|
_fourk_2 = 4096;
|
|
_fourk_3 = 0x1000;
|
|
_fourk_4 = 10000o;
|
|
@end smallexample
|
|
|
|
Note - the @code{K} and @code{M} suffixes cannot be used in
|
|
conjunction with the base suffixes mentioned above.
|
|
|
|
@node Symbolic Constants
|
|
@subsection Symbolic Constants
|
|
@cindex symbolic constants
|
|
@kindex CONSTANT
|
|
It is possible to refer to target-specific constants via the use of
|
|
the @code{CONSTANT(@var{name})} operator, where @var{name} is one of:
|
|
|
|
@table @code
|
|
@item MAXPAGESIZE
|
|
@kindex MAXPAGESIZE
|
|
The target's maximum page size.
|
|
|
|
@item COMMONPAGESIZE
|
|
@kindex COMMONPAGESIZE
|
|
The target's default page size.
|
|
@end table
|
|
|
|
So for example:
|
|
|
|
@smallexample
|
|
.text ALIGN (CONSTANT (MAXPAGESIZE)) : @{ *(.text) @}
|
|
@end smallexample
|
|
|
|
will create a text section aligned to the largest page boundary
|
|
supported by the target.
|
|
|
|
@node Symbols
|
|
@subsection Symbol Names
|
|
@cindex symbol names
|
|
@cindex names
|
|
@cindex quoted symbol names
|
|
@kindex "
|
|
Unless quoted, symbol names start with a letter, underscore, or period
|
|
and may include letters, digits, underscores, periods, and hyphens.
|
|
Unquoted symbol names must not conflict with any keywords. You can
|
|
specify a symbol which contains odd characters or has the same name as a
|
|
keyword by surrounding the symbol name in double quotes:
|
|
@smallexample
|
|
"SECTION" = 9;
|
|
"with a space" = "also with a space" + 10;
|
|
@end smallexample
|
|
|
|
Since symbols can contain many non-alphabetic characters, it is safest
|
|
to delimit symbols with spaces. For example, @samp{A-B} is one symbol,
|
|
whereas @samp{A - B} is an expression involving subtraction.
|
|
|
|
@node Orphan Sections
|
|
@subsection Orphan Sections
|
|
@cindex orphan
|
|
Orphan sections are sections present in the input files which
|
|
are not explicitly placed into the output file by the linker
|
|
script. The linker will still copy these sections into the
|
|
output file by either finding, or creating a suitable output section
|
|
in which to place the orphaned input section.
|
|
|
|
If the name of an orphaned input section exactly matches the name of
|
|
an existing output section, then the orphaned input section will be
|
|
placed at the end of that output section.
|
|
|
|
If there is no output section with a matching name then new output
|
|
sections will be created. Each new output section will have the same
|
|
name as the orphan section placed within it. If there are multiple
|
|
orphan sections with the same name, these will all be combined into
|
|
one new output section.
|
|
|
|
If new output sections are created to hold orphaned input sections,
|
|
then the linker must decide where to place these new output sections
|
|
in relation to existing output sections. On most modern targets, the
|
|
linker attempts to place orphan sections after sections of the same
|
|
attribute, such as code vs data, loadable vs non-loadable, etc. If no
|
|
sections with matching attributes are found, or your target lacks this
|
|
support, the orphan section is placed at the end of the file.
|
|
|
|
The command-line options @samp{--orphan-handling} and @samp{--unique}
|
|
(@pxref{Options,,Command-line Options}) can be used to control which
|
|
output sections an orphan is placed in.
|
|
|
|
@node Location Counter
|
|
@subsection The Location Counter
|
|
@kindex .
|
|
@cindex dot
|
|
@cindex location counter
|
|
@cindex current output location
|
|
The special linker variable @dfn{dot} @samp{.} always contains the
|
|
current output location counter. Since the @code{.} always refers to a
|
|
location in an output section, it may only appear in an expression
|
|
within a @code{SECTIONS} command. The @code{.} symbol may appear
|
|
anywhere that an ordinary symbol is allowed in an expression.
|
|
|
|
@cindex holes
|
|
Assigning a value to @code{.} will cause the location counter to be
|
|
moved. This may be used to create holes in the output section. The
|
|
location counter may not be moved backwards inside an output section,
|
|
and may not be moved backwards outside of an output section if so
|
|
doing creates areas with overlapping LMAs.
|
|
|
|
@smallexample
|
|
SECTIONS
|
|
@{
|
|
output :
|
|
@{
|
|
file1(.text)
|
|
. = . + 1000;
|
|
file2(.text)
|
|
. += 1000;
|
|
file3(.text)
|
|
@} = 0x12345678;
|
|
@}
|
|
@end smallexample
|
|
@noindent
|
|
In the previous example, the @samp{.text} section from @file{file1} is
|
|
located at the beginning of the output section @samp{output}. It is
|
|
followed by a 1000 byte gap. Then the @samp{.text} section from
|
|
@file{file2} appears, also with a 1000 byte gap following before the
|
|
@samp{.text} section from @file{file3}. The notation @samp{= 0x12345678}
|
|
specifies what data to write in the gaps (@pxref{Output Section Fill}).
|
|
|
|
@cindex dot inside sections
|
|
Note: @code{.} actually refers to the byte offset from the start of the
|
|
current containing object. Normally this is the @code{SECTIONS}
|
|
statement, whose start address is 0, hence @code{.} can be used as an
|
|
absolute address. If @code{.} is used inside a section description
|
|
however, it refers to the byte offset from the start of that section,
|
|
not an absolute address. Thus in a script like this:
|
|
|
|
@smallexample
|
|
SECTIONS
|
|
@{
|
|
. = 0x100
|
|
.text: @{
|
|
*(.text)
|
|
. = 0x200
|
|
@}
|
|
. = 0x500
|
|
.data: @{
|
|
*(.data)
|
|
. += 0x600
|
|
@}
|
|
@}
|
|
@end smallexample
|
|
|
|
The @samp{.text} section will be assigned a starting address of 0x100
|
|
and a size of exactly 0x200 bytes, even if there is not enough data in
|
|
the @samp{.text} input sections to fill this area. (If there is too
|
|
much data, an error will be produced because this would be an attempt to
|
|
move @code{.} backwards). The @samp{.data} section will start at 0x500
|
|
and it will have an extra 0x600 bytes worth of space after the end of
|
|
the values from the @samp{.data} input sections and before the end of
|
|
the @samp{.data} output section itself.
|
|
|
|
@cindex dot outside sections
|
|
Setting symbols to the value of the location counter outside of an
|
|
output section statement can result in unexpected values if the linker
|
|
needs to place orphan sections. For example, given the following:
|
|
|
|
@smallexample
|
|
SECTIONS
|
|
@{
|
|
start_of_text = . ;
|
|
.text: @{ *(.text) @}
|
|
end_of_text = . ;
|
|
|
|
start_of_data = . ;
|
|
.data: @{ *(.data) @}
|
|
end_of_data = . ;
|
|
@}
|
|
@end smallexample
|
|
|
|
If the linker needs to place some input section, e.g. @code{.rodata},
|
|
not mentioned in the script, it might choose to place that section
|
|
between @code{.text} and @code{.data}. You might think the linker
|
|
should place @code{.rodata} on the blank line in the above script, but
|
|
blank lines are of no particular significance to the linker. As well,
|
|
the linker doesn't associate the above symbol names with their
|
|
sections. Instead, it assumes that all assignments or other
|
|
statements belong to the previous output section, except for the
|
|
special case of an assignment to @code{.}. I.e., the linker will
|
|
place the orphan @code{.rodata} section as if the script was written
|
|
as follows:
|
|
|
|
@smallexample
|
|
SECTIONS
|
|
@{
|
|
start_of_text = . ;
|
|
.text: @{ *(.text) @}
|
|
end_of_text = . ;
|
|
|
|
start_of_data = . ;
|
|
.rodata: @{ *(.rodata) @}
|
|
.data: @{ *(.data) @}
|
|
end_of_data = . ;
|
|
@}
|
|
@end smallexample
|
|
|
|
This may or may not be the script author's intention for the value of
|
|
@code{start_of_data}. One way to influence the orphan section
|
|
placement is to assign the location counter to itself, as the linker
|
|
assumes that an assignment to @code{.} is setting the start address of
|
|
a following output section and thus should be grouped with that
|
|
section. So you could write:
|
|
|
|
@smallexample
|
|
SECTIONS
|
|
@{
|
|
start_of_text = . ;
|
|
.text: @{ *(.text) @}
|
|
end_of_text = . ;
|
|
|
|
. = . ;
|
|
start_of_data = . ;
|
|
.data: @{ *(.data) @}
|
|
end_of_data = . ;
|
|
@}
|
|
@end smallexample
|
|
|
|
Now, the orphan @code{.rodata} section will be placed between
|
|
@code{end_of_text} and @code{start_of_data}.
|
|
|
|
@need 2000
|
|
@node Operators
|
|
@subsection Operators
|
|
@cindex operators for arithmetic
|
|
@cindex arithmetic operators
|
|
@cindex precedence in expressions
|
|
The linker recognizes the standard C set of arithmetic operators, with
|
|
the standard bindings and precedence levels:
|
|
@c TEXI2ROFF-KILL
|
|
@ifnottex
|
|
@c END TEXI2ROFF-KILL
|
|
@smallexample
|
|
precedence associativity Operators Notes
|
|
(highest)
|
|
1 left ! - ~ (1)
|
|
2 left * / %
|
|
3 left + -
|
|
4 left >> <<
|
|
5 left == != > < <= >=
|
|
6 left &
|
|
7 left |
|
|
8 left &&
|
|
9 left ||
|
|
10 right ? :
|
|
11 right &= += -= *= /= (2)
|
|
(lowest)
|
|
@end smallexample
|
|
Notes:
|
|
(1) Prefix operators
|
|
(2) @xref{Assignments}.
|
|
@c TEXI2ROFF-KILL
|
|
@end ifnottex
|
|
@tex
|
|
\vskip \baselineskip
|
|
%"lispnarrowing" is the extra indent used generally for smallexample
|
|
\hskip\lispnarrowing\vbox{\offinterlineskip
|
|
\hrule
|
|
\halign
|
|
{\vrule#&\strut\hfil\ #\ \hfil&\vrule#&\strut\hfil\ #\ \hfil&\vrule#&\strut\hfil\ {\tt #}\ \hfil&\vrule#\cr
|
|
height2pt&\omit&&\omit&&\omit&\cr
|
|
&Precedence&& Associativity &&{\rm Operators}&\cr
|
|
height2pt&\omit&&\omit&&\omit&\cr
|
|
\noalign{\hrule}
|
|
height2pt&\omit&&\omit&&\omit&\cr
|
|
&highest&&&&&\cr
|
|
% '176 is tilde, '~' in tt font
|
|
&1&&left&&\qquad- \char'176\ !\qquad\dag&\cr
|
|
&2&&left&&* / \%&\cr
|
|
&3&&left&&+ -&\cr
|
|
&4&&left&&>> <<&\cr
|
|
&5&&left&&== != > < <= >=&\cr
|
|
&6&&left&&\&&\cr
|
|
&7&&left&&|&\cr
|
|
&8&&left&&{\&\&}&\cr
|
|
&9&&left&&||&\cr
|
|
&10&&right&&? :&\cr
|
|
&11&&right&&\qquad\&= += -= *= /=\qquad\ddag&\cr
|
|
&lowest&&&&&\cr
|
|
height2pt&\omit&&\omit&&\omit&\cr}
|
|
\hrule}
|
|
@end tex
|
|
@iftex
|
|
{
|
|
@obeylines@parskip=0pt@parindent=0pt
|
|
@dag@quad Prefix operators.
|
|
@ddag@quad @xref{Assignments}.
|
|
}
|
|
@end iftex
|
|
@c END TEXI2ROFF-KILL
|
|
|
|
@node Evaluation
|
|
@subsection Evaluation
|
|
@cindex lazy evaluation
|
|
@cindex expression evaluation order
|
|
The linker evaluates expressions lazily. It only computes the value of
|
|
an expression when absolutely necessary.
|
|
|
|
The linker needs some information, such as the value of the start
|
|
address of the first section, and the origins and lengths of memory
|
|
regions, in order to do any linking at all. These values are computed
|
|
as soon as possible when the linker reads in the linker script.
|
|
|
|
However, other values (such as symbol values) are not known or needed
|
|
until after storage allocation. Such values are evaluated later, when
|
|
other information (such as the sizes of output sections) is available
|
|
for use in the symbol assignment expression.
|
|
|
|
The sizes of sections cannot be known until after allocation, so
|
|
assignments dependent upon these are not performed until after
|
|
allocation.
|
|
|
|
Some expressions, such as those depending upon the location counter
|
|
@samp{.}, must be evaluated during section allocation.
|
|
|
|
If the result of an expression is required, but the value is not
|
|
available, then an error results. For example, a script like the
|
|
following
|
|
@smallexample
|
|
@group
|
|
SECTIONS
|
|
@{
|
|
.text 9+this_isnt_constant :
|
|
@{ *(.text) @}
|
|
@}
|
|
@end group
|
|
@end smallexample
|
|
@noindent
|
|
will cause the error message @samp{non constant expression for initial
|
|
address}.
|
|
|
|
@node Expression Section
|
|
@subsection The Section of an Expression
|
|
@cindex expression sections
|
|
@cindex absolute expressions
|
|
@cindex relative expressions
|
|
@cindex absolute and relocatable symbols
|
|
@cindex relocatable and absolute symbols
|
|
@cindex symbols, relocatable and absolute
|
|
Addresses and symbols may be section relative, or absolute. A section
|
|
relative symbol is relocatable. If you request relocatable output
|
|
using the @samp{-r} option, a further link operation may change the
|
|
value of a section relative symbol. On the other hand, an absolute
|
|
symbol will retain the same value throughout any further link
|
|
operations.
|
|
|
|
Some terms in linker expressions are addresses. This is true of
|
|
section relative symbols and for builtin functions that return an
|
|
address, such as @code{ADDR}, @code{LOADADDR}, @code{ORIGIN} and
|
|
@code{SEGMENT_START}. Other terms are simply numbers, or are builtin
|
|
functions that return a non-address value, such as @code{LENGTH}.
|
|
One complication is that unless you set @code{LD_FEATURE ("SANE_EXPR")}
|
|
(@pxref{Miscellaneous Commands}), numbers and absolute symbols are treated
|
|
differently depending on their location, for compatibility with older
|
|
versions of @code{ld}. Expressions appearing outside an output
|
|
section definition treat all numbers as absolute addresses.
|
|
Expressions appearing inside an output section definition treat
|
|
absolute symbols as numbers. If @code{LD_FEATURE ("SANE_EXPR")} is
|
|
given, then absolute symbols and numbers are simply treated as numbers
|
|
everywhere.
|
|
|
|
In the following simple example,
|
|
|
|
@smallexample
|
|
@group
|
|
SECTIONS
|
|
@{
|
|
. = 0x100;
|
|
__executable_start = 0x100;
|
|
.data :
|
|
@{
|
|
. = 0x10;
|
|
__data_start = 0x10;
|
|
*(.data)
|
|
@}
|
|
@dots{}
|
|
@}
|
|
@end group
|
|
@end smallexample
|
|
|
|
both @code{.} and @code{__executable_start} are set to the absolute
|
|
address 0x100 in the first two assignments, then both @code{.} and
|
|
@code{__data_start} are set to 0x10 relative to the @code{.data}
|
|
section in the second two assignments.
|
|
|
|
For expressions involving numbers, relative addresses and absolute
|
|
addresses, ld follows these rules to evaluate terms:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
Unary operations on an absolute address or number, and binary
|
|
operations on two absolute addresses or two numbers, or between one
|
|
absolute address and a number, apply the operator to the value(s).
|
|
@item
|
|
Unary operations on a relative address, and binary operations on two
|
|
relative addresses in the same section or between one relative address
|
|
and a number, apply the operator to the offset part of the address(es).
|
|
@item
|
|
Other binary operations, that is, between two relative addresses not
|
|
in the same section, or between a relative address and an absolute
|
|
address, first convert any non-absolute term to an absolute address
|
|
before applying the operator.
|
|
@end itemize
|
|
|
|
The result section of each sub-expression is as follows:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
An operation involving only numbers results in a number.
|
|
@item
|
|
The result of comparisons, @samp{&&} and @samp{||} is also a number.
|
|
@item
|
|
The result of other binary arithmetic and logical operations on two
|
|
relative addresses in the same section or two absolute addresses
|
|
(after above conversions) is also a number when
|
|
@code{LD_FEATURE ("SANE_EXPR")} or inside an output section definition
|
|
but an absolute address otherwise.
|
|
@item
|
|
The result of other operations on relative addresses or one
|
|
relative address and a number, is a relative address in the same
|
|
section as the relative operand(s).
|
|
@item
|
|
The result of other operations on absolute addresses (after above
|
|
conversions) is an absolute address.
|
|
@end itemize
|
|
|
|
You can use the builtin function @code{ABSOLUTE} to force an expression
|
|
to be absolute when it would otherwise be relative. For example, to
|
|
create an absolute symbol set to the address of the end of the output
|
|
section @samp{.data}:
|
|
@smallexample
|
|
SECTIONS
|
|
@{
|
|
.data : @{ *(.data) _edata = ABSOLUTE(.); @}
|
|
@}
|
|
@end smallexample
|
|
@noindent
|
|
If @samp{ABSOLUTE} were not used, @samp{_edata} would be relative to the
|
|
@samp{.data} section.
|
|
|
|
Using @code{LOADADDR} also forces an expression absolute, since this
|
|
particular builtin function returns an absolute address.
|
|
|
|
@node Builtin Functions
|
|
@subsection Builtin Functions
|
|
@cindex functions in expressions
|
|
The linker script language includes a number of builtin functions for
|
|
use in linker script expressions.
|
|
|
|
@table @code
|
|
@item ABSOLUTE(@var{exp})
|
|
@kindex ABSOLUTE(@var{exp})
|
|
@cindex expression, absolute
|
|
Return the absolute (non-relocatable, as opposed to non-negative) value
|
|
of the expression @var{exp}. Primarily useful to assign an absolute
|
|
value to a symbol within a section definition, where symbol values are
|
|
normally section relative. @xref{Expression Section}.
|
|
|
|
@item ADDR(@var{section})
|
|
@kindex ADDR(@var{section})
|
|
@cindex section address in expression
|
|
Return the address (VMA) of the named @var{section}. Your
|
|
script must previously have defined the location of that section. In
|
|
the following example, @code{start_of_output_1}, @code{symbol_1} and
|
|
@code{symbol_2} are assigned equivalent values, except that
|
|
@code{symbol_1} will be relative to the @code{.output1} section while
|
|
the other two will be absolute:
|
|
@smallexample
|
|
@group
|
|
SECTIONS @{ @dots{}
|
|
.output1 :
|
|
@{
|
|
start_of_output_1 = ABSOLUTE(.);
|
|
@dots{}
|
|
@}
|
|
.output :
|
|
@{
|
|
symbol_1 = ADDR(.output1);
|
|
symbol_2 = start_of_output_1;
|
|
@}
|
|
@dots{} @}
|
|
@end group
|
|
@end smallexample
|
|
|
|
@item ALIGN(@var{align})
|
|
@itemx ALIGN(@var{exp},@var{align})
|
|
@kindex ALIGN(@var{align})
|
|
@kindex ALIGN(@var{exp},@var{align})
|
|
@cindex round up location counter
|
|
@cindex align location counter
|
|
@cindex round up expression
|
|
@cindex align expression
|
|
Return the location counter (@code{.}) or arbitrary expression aligned
|
|
to the next @var{align} boundary. The single operand @code{ALIGN}
|
|
doesn't change the value of the location counter---it just does
|
|
arithmetic on it. The two operand @code{ALIGN} allows an arbitrary
|
|
expression to be aligned upwards (@code{ALIGN(@var{align})} is
|
|
equivalent to @code{ALIGN(ABSOLUTE(.), @var{align})}).
|
|
|
|
Here is an example which aligns the output @code{.data} section to the
|
|
next @code{0x2000} byte boundary after the preceding section and sets a
|
|
variable within the section to the next @code{0x8000} boundary after the
|
|
input sections:
|
|
@smallexample
|
|
@group
|
|
SECTIONS @{ @dots{}
|
|
.data ALIGN(0x2000): @{
|
|
*(.data)
|
|
variable = ALIGN(0x8000);
|
|
@}
|
|
@dots{} @}
|
|
@end group
|
|
@end smallexample
|
|
@noindent
|
|
The first use of @code{ALIGN} in this example specifies the location of
|
|
a section because it is used as the optional @var{address} attribute of
|
|
a section definition (@pxref{Output Section Address}). The second use
|
|
of @code{ALIGN} is used to defines the value of a symbol.
|
|
|
|
The builtin function @code{NEXT} is closely related to @code{ALIGN}.
|
|
|
|
@item ALIGNOF(@var{section})
|
|
@kindex ALIGNOF(@var{section})
|
|
@cindex section alignment
|
|
Return the alignment in bytes of the named @var{section}, if that section has
|
|
been allocated. If the section has not been allocated when this is
|
|
evaluated, the linker will report an error. In the following example,
|
|
the alignment of the @code{.output} section is stored as the first
|
|
value in that section.
|
|
@smallexample
|
|
@group
|
|
SECTIONS@{ @dots{}
|
|
.output @{
|
|
LONG (ALIGNOF (.output))
|
|
@dots{}
|
|
@}
|
|
@dots{} @}
|
|
@end group
|
|
@end smallexample
|
|
|
|
@item BLOCK(@var{exp})
|
|
@kindex BLOCK(@var{exp})
|
|
This is a synonym for @code{ALIGN}, for compatibility with older linker
|
|
scripts. It is most often seen when setting the address of an output
|
|
section.
|
|
|
|
@item DATA_SEGMENT_ALIGN(@var{maxpagesize}, @var{commonpagesize})
|
|
@kindex DATA_SEGMENT_ALIGN(@var{maxpagesize}, @var{commonpagesize})
|
|
This is equivalent to either
|
|
@smallexample
|
|
(ALIGN(@var{maxpagesize}) + (. & (@var{maxpagesize} - 1)))
|
|
@end smallexample
|
|
or
|
|
@smallexample
|
|
(ALIGN(@var{maxpagesize})
|
|
+ ((. + @var{commonpagesize} - 1) & (@var{maxpagesize} - @var{commonpagesize})))
|
|
@end smallexample
|
|
@noindent
|
|
depending on whether the latter uses fewer @var{commonpagesize} sized pages
|
|
for the data segment (area between the result of this expression and
|
|
@code{DATA_SEGMENT_END}) than the former or not.
|
|
If the latter form is used, it means @var{commonpagesize} bytes of runtime
|
|
memory will be saved at the expense of up to @var{commonpagesize} wasted
|
|
bytes in the on-disk file.
|
|
|
|
This expression can only be used directly in @code{SECTIONS} commands, not in
|
|
any output section descriptions and only once in the linker script.
|
|
@var{commonpagesize} should be less or equal to @var{maxpagesize} and should
|
|
be the system page size the object wants to be optimized for while still
|
|
running on system page sizes up to @var{maxpagesize}. Note however
|
|
that @samp{-z relro} protection will not be effective if the system
|
|
page size is larger than @var{commonpagesize}.
|
|
|
|
@noindent
|
|
Example:
|
|
@smallexample
|
|
. = DATA_SEGMENT_ALIGN(0x10000, 0x2000);
|
|
@end smallexample
|
|
|
|
@item DATA_SEGMENT_END(@var{exp})
|
|
@kindex DATA_SEGMENT_END(@var{exp})
|
|
This defines the end of data segment for @code{DATA_SEGMENT_ALIGN}
|
|
evaluation purposes.
|
|
|
|
@smallexample
|
|
. = DATA_SEGMENT_END(.);
|
|
@end smallexample
|
|
|
|
@item DATA_SEGMENT_RELRO_END(@var{offset}, @var{exp})
|
|
@kindex DATA_SEGMENT_RELRO_END(@var{offset}, @var{exp})
|
|
This defines the end of the @code{PT_GNU_RELRO} segment when
|
|
@samp{-z relro} option is used.
|
|
When @samp{-z relro} option is not present, @code{DATA_SEGMENT_RELRO_END}
|
|
does nothing, otherwise @code{DATA_SEGMENT_ALIGN} is padded so that
|
|
@var{exp} + @var{offset} is aligned to the @var{commonpagesize}
|
|
argument given to @code{DATA_SEGMENT_ALIGN}. If present in the linker
|
|
script, it must be placed between @code{DATA_SEGMENT_ALIGN} and
|
|
@code{DATA_SEGMENT_END}. Evaluates to the second argument plus any
|
|
padding needed at the end of the @code{PT_GNU_RELRO} segment due to
|
|
section alignment.
|
|
|
|
@smallexample
|
|
. = DATA_SEGMENT_RELRO_END(24, .);
|
|
@end smallexample
|
|
|
|
@item DEFINED(@var{symbol})
|
|
@kindex DEFINED(@var{symbol})
|
|
@cindex symbol defaults
|
|
Return 1 if @var{symbol} is in the linker global symbol table and is
|
|
defined before the statement using DEFINED in the script, otherwise
|
|
return 0. You can use this function to provide
|
|
default values for symbols. For example, the following script fragment
|
|
shows how to set a global symbol @samp{begin} to the first location in
|
|
the @samp{.text} section---but if a symbol called @samp{begin} already
|
|
existed, its value is preserved:
|
|
|
|
@smallexample
|
|
@group
|
|
SECTIONS @{ @dots{}
|
|
.text : @{
|
|
begin = DEFINED(begin) ? begin : . ;
|
|
@dots{}
|
|
@}
|
|
@dots{}
|
|
@}
|
|
@end group
|
|
@end smallexample
|
|
|
|
@item LENGTH(@var{memory})
|
|
@kindex LENGTH(@var{memory})
|
|
Return the length of the memory region named @var{memory}.
|
|
|
|
@item LOADADDR(@var{section})
|
|
@kindex LOADADDR(@var{section})
|
|
@cindex section load address in expression
|
|
Return the absolute LMA of the named @var{section}. (@pxref{Output
|
|
Section LMA}).
|
|
|
|
@item LOG2CEIL(@var{exp})
|
|
@kindex LOG2CEIL(@var{exp})
|
|
Return the binary logarithm of @var{exp} rounded towards infinity.
|
|
@code{LOG2CEIL(0)} returns 0.
|
|
|
|
@kindex MAX
|
|
@item MAX(@var{exp1}, @var{exp2})
|
|
Returns the maximum of @var{exp1} and @var{exp2}.
|
|
|
|
@kindex MIN
|
|
@item MIN(@var{exp1}, @var{exp2})
|
|
Returns the minimum of @var{exp1} and @var{exp2}.
|
|
|
|
@item NEXT(@var{exp})
|
|
@kindex NEXT(@var{exp})
|
|
@cindex unallocated address, next
|
|
Return the next unallocated address that is a multiple of @var{exp}.
|
|
This function is closely related to @code{ALIGN(@var{exp})}; unless you
|
|
use the @code{MEMORY} command to define discontinuous memory for the
|
|
output file, the two functions are equivalent.
|
|
|
|
@item ORIGIN(@var{memory})
|
|
@kindex ORIGIN(@var{memory})
|
|
Return the origin of the memory region named @var{memory}.
|
|
|
|
@item SEGMENT_START(@var{segment}, @var{default})
|
|
@kindex SEGMENT_START(@var{segment}, @var{default})
|
|
Return the base address of the named @var{segment}. If an explicit
|
|
value has already been given for this segment (with a command-line
|
|
@samp{-T} option) then that value will be returned otherwise the value
|
|
will be @var{default}. At present, the @samp{-T} command-line option
|
|
can only be used to set the base address for the ``text'', ``data'', and
|
|
``bss'' sections, but you can use @code{SEGMENT_START} with any segment
|
|
name.
|
|
|
|
@item SIZEOF(@var{section})
|
|
@kindex SIZEOF(@var{section})
|
|
@cindex section size
|
|
Return the size in bytes of the named @var{section}, if that section has
|
|
been allocated. If the section has not been allocated when this is
|
|
evaluated, the linker will report an error. In the following example,
|
|
@code{symbol_1} and @code{symbol_2} are assigned identical values:
|
|
@smallexample
|
|
@group
|
|
SECTIONS@{ @dots{}
|
|
.output @{
|
|
.start = . ;
|
|
@dots{}
|
|
.end = . ;
|
|
@}
|
|
symbol_1 = .end - .start ;
|
|
symbol_2 = SIZEOF(.output);
|
|
@dots{} @}
|
|
@end group
|
|
@end smallexample
|
|
|
|
@item SIZEOF_HEADERS
|
|
@itemx sizeof_headers
|
|
@kindex SIZEOF_HEADERS
|
|
@cindex header size
|
|
Return the size in bytes of the output file's headers. This is
|
|
information which appears at the start of the output file. You can use
|
|
this number when setting the start address of the first section, if you
|
|
choose, to facilitate paging.
|
|
|
|
@cindex not enough room for program headers
|
|
@cindex program headers, not enough room
|
|
When producing an ELF output file, if the linker script uses the
|
|
@code{SIZEOF_HEADERS} builtin function, the linker must compute the
|
|
number of program headers before it has determined all the section
|
|
addresses and sizes. If the linker later discovers that it needs
|
|
additional program headers, it will report an error @samp{not enough
|
|
room for program headers}. To avoid this error, you must avoid using
|
|
the @code{SIZEOF_HEADERS} function, or you must rework your linker
|
|
script to avoid forcing the linker to use additional program headers, or
|
|
you must define the program headers yourself using the @code{PHDRS}
|
|
command (@pxref{PHDRS}).
|
|
@end table
|
|
|
|
@node Implicit Linker Scripts
|
|
@section Implicit Linker Scripts
|
|
@cindex implicit linker scripts
|
|
If you specify a linker input file which the linker can not recognize as
|
|
an object file or an archive file, it will try to read the file as a
|
|
linker script. If the file can not be parsed as a linker script, the
|
|
linker will report an error.
|
|
|
|
An implicit linker script will not replace the default linker script.
|
|
|
|
Typically an implicit linker script would contain only symbol
|
|
assignments, or the @code{INPUT}, @code{GROUP}, or @code{VERSION}
|
|
commands.
|
|
|
|
Any input files read because of an implicit linker script will be read
|
|
at the position in the command line where the implicit linker script was
|
|
read. This can affect archive searching.
|
|
|
|
@ifset GENERIC
|
|
@node Machine Dependent
|
|
@chapter Machine Dependent Features
|
|
|
|
@cindex machine dependencies
|
|
@command{ld} has additional features on some platforms; the following
|
|
sections describe them. Machines where @command{ld} has no additional
|
|
functionality are not listed.
|
|
|
|
@menu
|
|
@ifset H8300
|
|
* H8/300:: @command{ld} and the H8/300
|
|
@end ifset
|
|
@ifset M68HC11
|
|
* M68HC11/68HC12:: @code{ld} and the Motorola 68HC11 and 68HC12 families
|
|
@end ifset
|
|
@ifset ARM
|
|
* ARM:: @command{ld} and the ARM family
|
|
@end ifset
|
|
@ifset HPPA
|
|
* HPPA ELF32:: @command{ld} and HPPA 32-bit ELF
|
|
@end ifset
|
|
@ifset M68K
|
|
* M68K:: @command{ld} and the Motorola 68K family
|
|
@end ifset
|
|
@ifset MIPS
|
|
* MIPS:: @command{ld} and the MIPS family
|
|
@end ifset
|
|
@ifset MMIX
|
|
* MMIX:: @command{ld} and MMIX
|
|
@end ifset
|
|
@ifset MSP430
|
|
* MSP430:: @command{ld} and MSP430
|
|
@end ifset
|
|
@ifset NDS32
|
|
* NDS32:: @command{ld} and NDS32
|
|
@end ifset
|
|
@ifset NIOSII
|
|
* Nios II:: @command{ld} and the Altera Nios II
|
|
@end ifset
|
|
@ifset POWERPC
|
|
* PowerPC ELF32:: @command{ld} and PowerPC 32-bit ELF Support
|
|
@end ifset
|
|
@ifset POWERPC64
|
|
* PowerPC64 ELF64:: @command{ld} and PowerPC64 64-bit ELF Support
|
|
@end ifset
|
|
@ifset S/390
|
|
* S/390 ELF:: @command{ld} and S/390 ELF Support
|
|
@end ifset
|
|
@ifset SPU
|
|
* SPU ELF:: @command{ld} and SPU ELF Support
|
|
@end ifset
|
|
@ifset TICOFF
|
|
* TI COFF:: @command{ld} and TI COFF
|
|
@end ifset
|
|
@ifset WIN32
|
|
* WIN32:: @command{ld} and WIN32 (cygwin/mingw)
|
|
@end ifset
|
|
@ifset XTENSA
|
|
* Xtensa:: @command{ld} and Xtensa Processors
|
|
@end ifset
|
|
@end menu
|
|
@end ifset
|
|
|
|
@ifset H8300
|
|
@ifclear GENERIC
|
|
@raisesections
|
|
@end ifclear
|
|
|
|
@node H8/300
|
|
@section @command{ld} and the H8/300
|
|
|
|
@cindex H8/300 support
|
|
For the H8/300, @command{ld} can perform these global optimizations when
|
|
you specify the @samp{--relax} command-line option.
|
|
|
|
@table @emph
|
|
@cindex relaxing on H8/300
|
|
@item relaxing address modes
|
|
@command{ld} finds all @code{jsr} and @code{jmp} instructions whose
|
|
targets are within eight bits, and turns them into eight-bit
|
|
program-counter relative @code{bsr} and @code{bra} instructions,
|
|
respectively.
|
|
|
|
@cindex synthesizing on H8/300
|
|
@item synthesizing instructions
|
|
@c FIXME: specifically mov.b, or any mov instructions really? -> mov.b only, at least on H8, H8H, H8S
|
|
@command{ld} finds all @code{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 @samp{mov.b @code{@@}@var{aa}:16} into
|
|
@samp{mov.b @code{@@}@var{aa}:8} whenever the address @var{aa} is in the
|
|
top page of memory).
|
|
|
|
@command{ld} finds all @code{mov} instructions which use the register
|
|
indirect with 32-bit displacement addressing mode, but use a small
|
|
displacement inside 16-bit displacement range, and changes them to use
|
|
the 16-bit displacement form. (That is: the linker turns @samp{mov.b
|
|
@code{@@}@var{d}:32,ERx} into @samp{mov.b @code{@@}@var{d}:16,ERx}
|
|
whenever the displacement @var{d} is in the 16 bit signed integer
|
|
range. Only implemented in ELF-format ld).
|
|
|
|
@item bit manipulation instructions
|
|
@command{ld} finds all bit manipulation instructions like @code{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 @samp{bset #xx:3,@code{@@}@var{aa}:32} into
|
|
@samp{bset #xx:3,@code{@@}@var{aa}:8} whenever the address @var{aa} is in
|
|
the top page of memory).
|
|
|
|
@item system control instructions
|
|
@command{ld} finds all @code{ldc.w, stc.w} instructions 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 @samp{ldc.w @code{@@}@var{aa}:32,ccr} into
|
|
@samp{ldc.w @code{@@}@var{aa}:16,ccr} whenever the address @var{aa} is in
|
|
the top page of memory).
|
|
@end table
|
|
|
|
@ifclear GENERIC
|
|
@lowersections
|
|
@end ifclear
|
|
@end ifset
|
|
|
|
@ifclear GENERIC
|
|
@ifset Renesas
|
|
@c This stuff is pointless to say unless you're especially concerned
|
|
@c with Renesas chips; don't enable it for generic case, please.
|
|
@node Renesas
|
|
@chapter @command{ld} and Other Renesas Chips
|
|
|
|
@command{ld} also supports the Renesas (formerly Hitachi) H8/300H,
|
|
H8/500, and SH chips. No special features, commands, or command-line
|
|
options are required for these chips.
|
|
@end ifset
|
|
@end ifclear
|
|
|
|
@ifset ARM
|
|
@ifclear GENERIC
|
|
@raisesections
|
|
@end ifclear
|
|
|
|
@ifset M68HC11
|
|
@ifclear GENERIC
|
|
@raisesections
|
|
@end ifclear
|
|
|
|
@node M68HC11/68HC12
|
|
@section @command{ld} and the Motorola 68HC11 and 68HC12 families
|
|
|
|
@cindex M68HC11 and 68HC12 support
|
|
|
|
@subsection Linker Relaxation
|
|
|
|
For the Motorola 68HC11, @command{ld} can perform these global
|
|
optimizations when you specify the @samp{--relax} command-line option.
|
|
|
|
@table @emph
|
|
@cindex relaxing on M68HC11
|
|
@item relaxing address modes
|
|
@command{ld} finds all @code{jsr} and @code{jmp} instructions whose
|
|
targets are within eight bits, and turns them into eight-bit
|
|
program-counter relative @code{bsr} and @code{bra} instructions,
|
|
respectively.
|
|
|
|
@command{ld} also looks at all 16-bit extended addressing modes and
|
|
transforms them in a direct addressing mode when the address is in
|
|
page 0 (between 0 and 0x0ff).
|
|
|
|
@item relaxing gcc instruction group
|
|
When @command{gcc} is called with @option{-mrelax}, it can emit group
|
|
of instructions that the linker can optimize to use a 68HC11 direct
|
|
addressing mode. These instructions consists of @code{bclr} or
|
|
@code{bset} instructions.
|
|
|
|
@end table
|
|
|
|
@subsection Trampoline Generation
|
|
|
|
@cindex trampoline generation on M68HC11
|
|
@cindex trampoline generation on M68HC12
|
|
For 68HC11 and 68HC12, @command{ld} can generate trampoline code to
|
|
call a far function using a normal @code{jsr} instruction. The linker
|
|
will also change the relocation to some far function to use the
|
|
trampoline address instead of the function address. This is typically the
|
|
case when a pointer to a function is taken. The pointer will in fact
|
|
point to the function trampoline.
|
|
|
|
@ifclear GENERIC
|
|
@lowersections
|
|
@end ifclear
|
|
@end ifset
|
|
|
|
@node ARM
|
|
@section @command{ld} and the ARM family
|
|
|
|
@cindex ARM interworking support
|
|
@kindex --support-old-code
|
|
For the ARM, @command{ld} will generate code stubs to allow functions calls
|
|
between ARM and Thumb code. These stubs only work with code that has
|
|
been compiled and assembled with the @samp{-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 @samp{--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.
|
|
|
|
@cindex thumb entry point
|
|
@cindex entry point, thumb
|
|
@kindex --thumb-entry=@var{entry}
|
|
The @samp{--thumb-entry} switch is a duplicate of the generic
|
|
@samp{--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.
|
|
|
|
@cindex PE import table prefixing
|
|
@kindex --use-nul-prefixed-import-tables
|
|
The @samp{--use-nul-prefixed-import-tables} switch is specifying, that
|
|
the import tables idata4 and idata5 have to be generated with a zero
|
|
element prefix for import libraries. This is the old style to generate
|
|
import tables. By default this option is turned off.
|
|
|
|
@cindex BE8
|
|
@kindex --be8
|
|
The @samp{--be8} switch instructs @command{ld} to generate BE8 format
|
|
executables. This option is only valid when linking big-endian
|
|
objects - ie ones which have been assembled with the @option{-EB}
|
|
option. The resulting image will contain big-endian data and
|
|
little-endian code.
|
|
|
|
@cindex TARGET1
|
|
@kindex --target1-rel
|
|
@kindex --target1-abs
|
|
The @samp{R_ARM_TARGET1} relocation is typically used for entries in the
|
|
@samp{.init_array} section. It is interpreted as either @samp{R_ARM_REL32}
|
|
or @samp{R_ARM_ABS32}, depending on the target. The @samp{--target1-rel}
|
|
and @samp{--target1-abs} switches override the default.
|
|
|
|
@cindex TARGET2
|
|
@kindex --target2=@var{type}
|
|
The @samp{--target2=type} switch overrides the default definition of the
|
|
@samp{R_ARM_TARGET2} relocation. Valid values for @samp{type}, their
|
|
meanings, and target defaults are as follows:
|
|
@table @samp
|
|
@item rel
|
|
@samp{R_ARM_REL32} (arm*-*-elf, arm*-*-eabi)
|
|
@item abs
|
|
@samp{R_ARM_ABS32} (arm*-*-symbianelf)
|
|
@item got-rel
|
|
@samp{R_ARM_GOT_PREL} (arm*-*-linux, arm*-*-*bsd)
|
|
@end table
|
|
|
|
@cindex FIX_V4BX
|
|
@kindex --fix-v4bx
|
|
The @samp{R_ARM_V4BX} relocation (defined by the ARM AAELF
|
|
specification) enables objects compiled for the ARMv4 architecture to be
|
|
interworking-safe when linked with other objects compiled for ARMv4t, but
|
|
also allows pure ARMv4 binaries to be built from the same ARMv4 objects.
|
|
|
|
In the latter case, the switch @option{--fix-v4bx} must be passed to the
|
|
linker, which causes v4t @code{BX rM} instructions to be rewritten as
|
|
@code{MOV PC,rM}, since v4 processors do not have a @code{BX} instruction.
|
|
|
|
In the former case, the switch should not be used, and @samp{R_ARM_V4BX}
|
|
relocations are ignored.
|
|
|
|
@cindex FIX_V4BX_INTERWORKING
|
|
@kindex --fix-v4bx-interworking
|
|
Replace @code{BX rM} instructions identified by @samp{R_ARM_V4BX}
|
|
relocations with a branch to the following veneer:
|
|
|
|
@smallexample
|
|
TST rM, #1
|
|
MOVEQ PC, rM
|
|
BX Rn
|
|
@end smallexample
|
|
|
|
This allows generation of libraries/applications that work on ARMv4 cores
|
|
and are still interworking safe. Note that the above veneer clobbers the
|
|
condition flags, so may cause incorrect program behavior in rare cases.
|
|
|
|
@cindex USE_BLX
|
|
@kindex --use-blx
|
|
The @samp{--use-blx} switch enables the linker to use ARM/Thumb
|
|
BLX instructions (available on ARMv5t and above) in various
|
|
situations. Currently it is used to perform calls via the PLT from Thumb
|
|
code using BLX rather than using BX and a mode-switching stub before
|
|
each PLT entry. This should lead to such calls executing slightly faster.
|
|
|
|
This option is enabled implicitly for SymbianOS, so there is no need to
|
|
specify it if you are using that target.
|
|
|
|
@cindex VFP11_DENORM_FIX
|
|
@kindex --vfp11-denorm-fix
|
|
The @samp{--vfp11-denorm-fix} switch enables a link-time workaround for a
|
|
bug in certain VFP11 coprocessor hardware, which sometimes allows
|
|
instructions with denorm operands (which must be handled by support code)
|
|
to have those operands overwritten by subsequent instructions before
|
|
the support code can read the intended values.
|
|
|
|
The bug may be avoided in scalar mode if you allow at least one
|
|
intervening instruction between a VFP11 instruction which uses a register
|
|
and another instruction which writes to the same register, or at least two
|
|
intervening instructions if vector mode is in use. The bug only affects
|
|
full-compliance floating-point mode: you do not need this workaround if
|
|
you are using "runfast" mode. Please contact ARM for further details.
|
|
|
|
If you know you are using buggy VFP11 hardware, you can
|
|
enable this workaround by specifying the linker option
|
|
@samp{--vfp-denorm-fix=scalar} if you are using the VFP11 scalar
|
|
mode only, or @samp{--vfp-denorm-fix=vector} if you are using
|
|
vector mode (the latter also works for scalar code). The default is
|
|
@samp{--vfp-denorm-fix=none}.
|
|
|
|
If the workaround is enabled, instructions are scanned for
|
|
potentially-troublesome sequences, and a veneer is created for each
|
|
such sequence which may trigger the erratum. The veneer consists of the
|
|
first instruction of the sequence and a branch back to the subsequent
|
|
instruction. The original instruction is then replaced with a branch to
|
|
the veneer. The extra cycles required to call and return from the veneer
|
|
are sufficient to avoid the erratum in both the scalar and vector cases.
|
|
|
|
@cindex ARM1176 erratum workaround
|
|
@kindex --fix-arm1176
|
|
@kindex --no-fix-arm1176
|
|
The @samp{--fix-arm1176} switch enables a link-time workaround for an erratum
|
|
in certain ARM1176 processors. The workaround is enabled by default if you
|
|
are targeting ARM v6 (excluding ARM v6T2) or earlier. It can be disabled
|
|
unconditionally by specifying @samp{--no-fix-arm1176}.
|
|
|
|
Further information is available in the ``ARM1176JZ-S and ARM1176JZF-S
|
|
Programmer Advice Notice'' available on the ARM documentation website at:
|
|
http://infocenter.arm.com/.
|
|
|
|
@cindex STM32L4xx erratum workaround
|
|
@kindex --fix-stm32l4xx-629360
|
|
|
|
The @samp{--fix-stm32l4xx-629360} switch enables a link-time
|
|
workaround for a bug in the bus matrix / memory controller for some of
|
|
the STM32 Cortex-M4 based products (STM32L4xx). When accessing
|
|
off-chip memory via the affected bus for bus reads of 9 words or more,
|
|
the bus can generate corrupt data and/or abort. These are only
|
|
core-initiated accesses (not DMA), and might affect any access:
|
|
integer loads such as LDM, POP and floating-point loads such as VLDM,
|
|
VPOP. Stores are not affected.
|
|
|
|
The bug can be avoided by splitting memory accesses into the
|
|
necessary chunks to keep bus reads below 8 words.
|
|
|
|
The workaround is not enabled by default, this is equivalent to use
|
|
@samp{--fix-stm32l4xx-629360=none}. If you know you are using buggy
|
|
STM32L4xx hardware, you can enable the workaround by specifying the
|
|
linker option @samp{--fix-stm32l4xx-629360}, or the equivalent
|
|
@samp{--fix-stm32l4xx-629360=default}.
|
|
|
|
If the workaround is enabled, instructions are scanned for
|
|
potentially-troublesome sequences, and a veneer is created for each
|
|
such sequence which may trigger the erratum. The veneer consists in a
|
|
replacement sequence emulating the behaviour of the original one and a
|
|
branch back to the subsequent instruction. The original instruction is
|
|
then replaced with a branch to the veneer.
|
|
|
|
The workaround does not always preserve the memory access order for
|
|
the LDMDB instruction, when the instruction loads the PC.
|
|
|
|
The workaround is not able to handle problematic instructions when
|
|
they are in the middle of an IT block, since a branch is not allowed
|
|
there. In that case, the linker reports a warning and no replacement
|
|
occurs.
|
|
|
|
The workaround is not able to replace problematic instructions with a
|
|
PC-relative branch instruction if the @samp{.text} section is too
|
|
large. In that case, when the branch that replaces the original code
|
|
cannot be encoded, the linker reports a warning and no replacement
|
|
occurs.
|
|
|
|
@cindex NO_ENUM_SIZE_WARNING
|
|
@kindex --no-enum-size-warning
|
|
The @option{--no-enum-size-warning} switch prevents the linker from
|
|
warning when linking object files that specify incompatible EABI
|
|
enumeration size attributes. For example, with this switch enabled,
|
|
linking of an object file using 32-bit enumeration values with another
|
|
using enumeration values fitted into the smallest possible space will
|
|
not be diagnosed.
|
|
|
|
@cindex NO_WCHAR_SIZE_WARNING
|
|
@kindex --no-wchar-size-warning
|
|
The @option{--no-wchar-size-warning} switch prevents the linker from
|
|
warning when linking object files that specify incompatible EABI
|
|
@code{wchar_t} size attributes. For example, with this switch enabled,
|
|
linking of an object file using 32-bit @code{wchar_t} values with another
|
|
using 16-bit @code{wchar_t} values will not be diagnosed.
|
|
|
|
@cindex PIC_VENEER
|
|
@kindex --pic-veneer
|
|
The @samp{--pic-veneer} switch makes the linker use PIC sequences for
|
|
ARM/Thumb interworking veneers, even if the rest of the binary
|
|
is not PIC. This avoids problems on uClinux targets where
|
|
@samp{--emit-relocs} is used to generate relocatable binaries.
|
|
|
|
@cindex STUB_GROUP_SIZE
|
|
@kindex --stub-group-size=@var{N}
|
|
The linker will automatically generate and insert small sequences of
|
|
code into a linked ARM ELF executable whenever an attempt is made to
|
|
perform a function call to a symbol that is too far away. The
|
|
placement of these sequences of instructions - called stubs - is
|
|
controlled by the command-line option @option{--stub-group-size=N}.
|
|
The placement is important because a poor choice can create a need for
|
|
duplicate stubs, increasing the code size. The linker will try to
|
|
group stubs together in order to reduce interruptions to the flow of
|
|
code, but it needs guidance as to how big these groups should be and
|
|
where they should be placed.
|
|
|
|
The value of @samp{N}, the parameter to the
|
|
@option{--stub-group-size=} option controls where the stub groups are
|
|
placed. If it is negative then all stubs are placed after the first
|
|
branch that needs them. If it is positive then the stubs can be
|
|
placed either before or after the branches that need them. If the
|
|
value of @samp{N} is 1 (either +1 or -1) then the linker will choose
|
|
exactly where to place groups of stubs, using its built in heuristics.
|
|
A value of @samp{N} greater than 1 (or smaller than -1) tells the
|
|
linker that a single group of stubs can service at most @samp{N} bytes
|
|
from the input sections.
|
|
|
|
The default, if @option{--stub-group-size=} is not specified, is
|
|
@samp{N = +1}.
|
|
|
|
Farcalls stubs insertion is fully supported for the ARM-EABI target
|
|
only, because it relies on object files properties not present
|
|
otherwise.
|
|
|
|
@cindex Cortex-A8 erratum workaround
|
|
@kindex --fix-cortex-a8
|
|
@kindex --no-fix-cortex-a8
|
|
The @samp{--fix-cortex-a8} switch enables a link-time workaround for an erratum in certain Cortex-A8 processors. The workaround is enabled by default if you are targeting the ARM v7-A architecture profile. It can be enabled otherwise by specifying @samp{--fix-cortex-a8}, or disabled unconditionally by specifying @samp{--no-fix-cortex-a8}.
|
|
|
|
The erratum only affects Thumb-2 code. Please contact ARM for further details.
|
|
|
|
@cindex Cortex-A53 erratum 835769 workaround
|
|
@kindex --fix-cortex-a53-835769
|
|
@kindex --no-fix-cortex-a53-835769
|
|
The @samp{--fix-cortex-a53-835769} switch enables a link-time workaround for erratum 835769 present on certain early revisions of Cortex-A53 processors. The workaround is disabled by default. It can be enabled by specifying @samp{--fix-cortex-a53-835769}, or disabled unconditionally by specifying @samp{--no-fix-cortex-a53-835769}.
|
|
|
|
Please contact ARM for further details.
|
|
|
|
@kindex --merge-exidx-entries
|
|
@kindex --no-merge-exidx-entries
|
|
@cindex Merging exidx entries
|
|
The @samp{--no-merge-exidx-entries} switch disables the merging of adjacent exidx entries in debuginfo.
|
|
|
|
@kindex --long-plt
|
|
@cindex 32-bit PLT entries
|
|
The @samp{--long-plt} option enables the use of 16 byte PLT entries
|
|
which support up to 4Gb of code. The default is to use 12 byte PLT
|
|
entries which only support 512Mb of code.
|
|
|
|
@kindex --no-apply-dynamic-relocs
|
|
@cindex AArch64 rela addend
|
|
The @samp{--no-apply-dynamic-relocs} option makes AArch64 linker do not apply
|
|
link-time values for dynamic relocations.
|
|
|
|
@cindex Placement of SG veneers
|
|
All SG veneers are placed in the special output section @code{.gnu.sgstubs}.
|
|
Its start address must be set, either with the command-line option
|
|
@samp{--section-start} or in a linker script, to indicate where to place these
|
|
veneers in memory.
|
|
|
|
@kindex --cmse-implib
|
|
@cindex Secure gateway import library
|
|
The @samp{--cmse-implib} option requests that the import libraries
|
|
specified by the @samp{--out-implib} and @samp{--in-implib} options are
|
|
secure gateway import libraries, suitable for linking a non-secure
|
|
executable against secure code as per ARMv8-M Security Extensions.
|
|
|
|
@kindex --in-implib=@var{file}
|
|
@cindex Input import library
|
|
The @samp{--in-implib=file} specifies an input import library whose symbols
|
|
must keep the same address in the executable being produced. A warning is
|
|
given if no @samp{--out-implib} is given but new symbols have been introduced
|
|
in the executable that should be listed in its import library. Otherwise, if
|
|
@samp{--out-implib} is specified, the symbols are added to the output import
|
|
library. A warning is also given if some symbols present in the input import
|
|
library have disappeared from the executable. This option is only effective
|
|
for Secure Gateway import libraries, ie. when @samp{--cmse-implib} is
|
|
specified.
|
|
|
|
@ifclear GENERIC
|
|
@lowersections
|
|
@end ifclear
|
|
@end ifset
|
|
|
|
@ifset HPPA
|
|
@ifclear GENERIC
|
|
@raisesections
|
|
@end ifclear
|
|
|
|
@node HPPA ELF32
|
|
@section @command{ld} and HPPA 32-bit ELF Support
|
|
@cindex HPPA multiple sub-space stubs
|
|
@kindex --multi-subspace
|
|
When generating a shared library, @command{ld} will by default generate
|
|
import stubs suitable for use with a single sub-space application.
|
|
The @samp{--multi-subspace} switch causes @command{ld} to generate export
|
|
stubs, and different (larger) import stubs suitable for use with
|
|
multiple sub-spaces.
|
|
|
|
@cindex HPPA stub grouping
|
|
@kindex --stub-group-size=@var{N}
|
|
Long branch stubs and import/export stubs are placed by @command{ld} in
|
|
stub sections located between groups of input sections.
|
|
@samp{--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 @samp{N} chooses this scheme, ensuring that
|
|
branches to stubs always use a negative offset. Two special values of
|
|
@samp{N} are recognized, @samp{1} and @samp{-1}. These both instruct
|
|
@command{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 @samp{N} respectively.
|
|
|
|
Note that @samp{--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.
|
|
|
|
@ifclear GENERIC
|
|
@lowersections
|
|
@end ifclear
|
|
@end ifset
|
|
|
|
@ifset M68K
|
|
@ifclear GENERIC
|
|
@raisesections
|
|
@end ifclear
|
|
|
|
@node M68K
|
|
@section @command{ld} and the Motorola 68K family
|
|
|
|
@cindex Motorola 68K GOT generation
|
|
@kindex --got=@var{type}
|
|
The @samp{--got=@var{type}} option lets you choose the GOT generation scheme.
|
|
The choices are @samp{single}, @samp{negative}, @samp{multigot} and
|
|
@samp{target}. When @samp{target} is selected the linker chooses
|
|
the default GOT generation scheme for the current target.
|
|
@samp{single} tells the linker to generate a single GOT with
|
|
entries only at non-negative offsets.
|
|
@samp{negative} instructs the linker to generate a single GOT with
|
|
entries at both negative and positive offsets. Not all environments
|
|
support such GOTs.
|
|
@samp{multigot} allows the linker to generate several GOTs in the
|
|
output file. All GOT references from a single input object
|
|
file access the same GOT, but references from different input object
|
|
files might access different GOTs. Not all environments support such GOTs.
|
|
|
|
@ifclear GENERIC
|
|
@lowersections
|
|
@end ifclear
|
|
@end ifset
|
|
|
|
@ifset MIPS
|
|
@ifclear GENERIC
|
|
@raisesections
|
|
@end ifclear
|
|
|
|
@node MIPS
|
|
@section @command{ld} and the MIPS family
|
|
|
|
@cindex MIPS microMIPS instruction choice selection
|
|
@kindex --insn32
|
|
@kindex --no-insn32
|
|
The @samp{--insn32} and @samp{--no-insn32} options control the choice of
|
|
microMIPS instructions used in code generated by the linker, such as that
|
|
in the PLT or lazy binding stubs, or in relaxation. If @samp{--insn32} is
|
|
used, then the linker only uses 32-bit instruction encodings. By default
|
|
or if @samp{--no-insn32} is used, all instruction encodings are used,
|
|
including 16-bit ones where possible.
|
|
|
|
@cindex MIPS branch relocation check control
|
|
@kindex --ignore-branch-isa
|
|
@kindex --no-ignore-branch-isa
|
|
The @samp{--ignore-branch-isa} and @samp{--no-ignore-branch-isa} options
|
|
control branch relocation checks for invalid ISA mode transitions. If
|
|
@samp{--ignore-branch-isa} is used, then the linker accepts any branch
|
|
relocations and any ISA mode transition required is lost in relocation
|
|
calculation, except for some cases of @code{BAL} instructions which meet
|
|
relaxation conditions and are converted to equivalent @code{JALX}
|
|
instructions as the associated relocation is calculated. By default
|
|
or if @samp{--no-ignore-branch-isa} is used a check is made causing
|
|
the loss of an ISA mode transition to produce an error.
|
|
|
|
@ifclear GENERIC
|
|
@lowersections
|
|
@end ifclear
|
|
@end ifset
|
|
|
|
@ifset MMIX
|
|
@ifclear GENERIC
|
|
@raisesections
|
|
@end ifclear
|
|
|
|
@node MMIX
|
|
@section @code{ld} and MMIX
|
|
For MMIX, there is a choice of generating @code{ELF} object files or
|
|
@code{mmo} object files when linking. The simulator @code{mmix}
|
|
understands the @code{mmo} format. The binutils @code{objcopy} utility
|
|
can translate between the two formats.
|
|
|
|
There is one special section, the @samp{.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
|
|
@samp{.MMIX.reg_contents} section corresponds to the first allocated
|
|
global register multiplied by 8. Register @code{$255} is not included in
|
|
this section; it is always set to the program entry, which is at the
|
|
symbol @code{Main} for @code{mmo} files.
|
|
|
|
Global symbols with the prefix @code{__.MMIX.start.}, for example
|
|
@code{__.MMIX.start..text} and @code{__.MMIX.start..data} are special.
|
|
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.
|
|
|
|
@ifclear GENERIC
|
|
@lowersections
|
|
@end ifclear
|
|
@end ifset
|
|
|
|
@ifset MSP430
|
|
@ifclear GENERIC
|
|
@raisesections
|
|
@end ifclear
|
|
|
|
@node MSP430
|
|
@section @code{ld} and MSP430
|
|
For the MSP430 it is possible to select the MPU architecture. The flag @samp{-m [mpu type]}
|
|
will select an appropriate linker script for selected MPU type. (To get a list of known MPUs
|
|
just pass @samp{-m help} option to the linker).
|
|
|
|
@cindex MSP430 extra sections
|
|
The linker will recognize some extra sections which are MSP430 specific:
|
|
|
|
@table @code
|
|
@item @samp{.vectors}
|
|
Defines a portion of ROM where interrupt vectors located.
|
|
|
|
@item @samp{.bootloader}
|
|
Defines the bootloader portion of the ROM (if applicable). Any code
|
|
in this section will be uploaded to the MPU.
|
|
|
|
@item @samp{.infomem}
|
|
Defines an information memory section (if applicable). Any code in
|
|
this section will be uploaded to the MPU.
|
|
|
|
@item @samp{.infomemnobits}
|
|
This is the same as the @samp{.infomem} section except that any code
|
|
in this section will not be uploaded to the MPU.
|
|
|
|
@item @samp{.noinit}
|
|
Denotes a portion of RAM located above @samp{.bss} section.
|
|
|
|
The last two sections are used by gcc.
|
|
@end table
|
|
|
|
@table @option
|
|
@cindex MSP430 Options
|
|
@kindex --code-region
|
|
@item --code-region=[either,lower,upper,none]
|
|
This will transform .text* sections to [either,lower,upper].text* sections. The
|
|
argument passed to GCC for -mcode-region is propagated to the linker
|
|
using this option.
|
|
|
|
@kindex --data-region
|
|
@item --data-region=[either,lower,upper,none]
|
|
This will transform .data*, .bss* and .rodata* sections to
|
|
[either,lower,upper].[data,bss,rodata]* sections. The argument passed to GCC
|
|
for -mdata-region is propagated to the linker using this option.
|
|
|
|
@kindex --disable-sec-transformation
|
|
@item --disable-sec-transformation
|
|
Prevent the transformation of sections as specified by the @code{--code-region}
|
|
and @code{--data-region} options.
|
|
This is useful if you are compiling and linking using a single call to the GCC
|
|
wrapper, and want to compile the source files using -m[code,data]-region but
|
|
not transform the sections for prebuilt libraries and objects.
|
|
@end table
|
|
|
|
@ifclear GENERIC
|
|
@lowersections
|
|
@end ifclear
|
|
@end ifset
|
|
|
|
@ifset NDS32
|
|
@ifclear GENERIC
|
|
@raisesections
|
|
@end ifclear
|
|
|
|
@node NDS32
|
|
@section @code{ld} and NDS32
|
|
@kindex relaxing on NDS32
|
|
For NDS32, there are some options to select relaxation behavior. The linker
|
|
relaxes objects according to these options.
|
|
|
|
@table @code
|
|
@item @samp{--m[no-]fp-as-gp}
|
|
Disable/enable fp-as-gp relaxation.
|
|
|
|
@item @samp{--mexport-symbols=FILE}
|
|
Exporting symbols and their address into FILE as linker script.
|
|
|
|
@item @samp{--m[no-]ex9}
|
|
Disable/enable link-time EX9 relaxation.
|
|
|
|
@item @samp{--mexport-ex9=FILE}
|
|
Export the EX9 table after linking.
|
|
|
|
@item @samp{--mimport-ex9=FILE}
|
|
Import the Ex9 table for EX9 relaxation.
|
|
|
|
@item @samp{--mupdate-ex9}
|
|
Update the existing EX9 table.
|
|
|
|
@item @samp{--mex9-limit=NUM}
|
|
Maximum number of entries in the ex9 table.
|
|
|
|
@item @samp{--mex9-loop-aware}
|
|
Avoid generating the EX9 instruction inside the loop.
|
|
|
|
@item @samp{--m[no-]ifc}
|
|
Disable/enable the link-time IFC optimization.
|
|
|
|
@item @samp{--mifc-loop-aware}
|
|
Avoid generating the IFC instruction inside the loop.
|
|
@end table
|
|
|
|
@ifclear GENERIC
|
|
@lowersections
|
|
@end ifclear
|
|
@end ifset
|
|
|
|
@ifset NIOSII
|
|
@ifclear GENERIC
|
|
@raisesections
|
|
@end ifclear
|
|
|
|
@node Nios II
|
|
@section @command{ld} and the Altera Nios II
|
|
@cindex Nios II call relaxation
|
|
@kindex --relax on Nios II
|
|
|
|
Call and immediate jump instructions on Nios II processors are limited to
|
|
transferring control to addresses in the same 256MB memory segment,
|
|
which may result in @command{ld} giving
|
|
@samp{relocation truncated to fit} errors with very large programs.
|
|
The command-line option @option{--relax} enables the generation of
|
|
trampolines that can access the entire 32-bit address space for calls
|
|
outside the normal @code{call} and @code{jmpi} address range. These
|
|
trampolines are inserted at section boundaries, so may not themselves
|
|
be reachable if an input section and its associated call trampolines are
|
|
larger than 256MB.
|
|
|
|
The @option{--relax} option is enabled by default unless @option{-r}
|
|
is also specified. You can disable trampoline generation by using the
|
|
@option{--no-relax} linker option. You can also disable this optimization
|
|
locally by using the @samp{set .noat} directive in assembly-language
|
|
source files, as the linker-inserted trampolines use the @code{at}
|
|
register as a temporary.
|
|
|
|
Note that the linker @option{--relax} option is independent of assembler
|
|
relaxation options, and that using the GNU assembler's @option{-relax-all}
|
|
option interferes with the linker's more selective call instruction relaxation.
|
|
|
|
@ifclear GENERIC
|
|
@lowersections
|
|
@end ifclear
|
|
@end ifset
|
|
|
|
@ifset POWERPC
|
|
@ifclear GENERIC
|
|
@raisesections
|
|
@end ifclear
|
|
|
|
@node PowerPC ELF32
|
|
@section @command{ld} and PowerPC 32-bit ELF Support
|
|
@cindex PowerPC long branches
|
|
@kindex --relax on PowerPC
|
|
Branches on PowerPC processors are limited to a signed 26-bit
|
|
displacement, which may result in @command{ld} giving
|
|
@samp{relocation truncated to fit} errors with very large programs.
|
|
@samp{--relax} enables the generation of trampolines that can access
|
|
the entire 32-bit address space. These trampolines are inserted at
|
|
section boundaries, so may not themselves be reachable if an input
|
|
section exceeds 33M in size. You may combine @samp{-r} and
|
|
@samp{--relax} to add trampolines in a partial link. In that case
|
|
both branches to undefined symbols and inter-section branches are also
|
|
considered potentially out of range, and trampolines inserted.
|
|
|
|
@cindex PowerPC ELF32 options
|
|
@table @option
|
|
@cindex PowerPC PLT
|
|
@kindex --bss-plt
|
|
@item --bss-plt
|
|
Current PowerPC GCC accepts a @samp{-msecure-plt} option that
|
|
generates code capable of using a newer PLT and GOT layout that has
|
|
the security advantage of no executable section ever needing to be
|
|
writable and no writable section ever being executable. PowerPC
|
|
@command{ld} will generate this layout, including stubs to access the
|
|
PLT, if all input files (including startup and static libraries) were
|
|
compiled with @samp{-msecure-plt}. @samp{--bss-plt} forces the old
|
|
BSS PLT (and GOT layout) which can give slightly better performance.
|
|
|
|
@kindex --secure-plt
|
|
@item --secure-plt
|
|
@command{ld} will use the new PLT and GOT layout if it is linking new
|
|
@samp{-fpic} or @samp{-fPIC} code, but does not do so automatically
|
|
when linking non-PIC code. This option requests the new PLT and GOT
|
|
layout. A warning will be given if some object file requires the old
|
|
style BSS PLT.
|
|
|
|
@cindex PowerPC GOT
|
|
@kindex --sdata-got
|
|
@item --sdata-got
|
|
The new secure PLT and GOT are placed differently relative to other
|
|
sections compared to older BSS PLT and GOT placement. The location of
|
|
@code{.plt} must change because the new secure PLT is an initialized
|
|
section while the old PLT is uninitialized. The reason for the
|
|
@code{.got} change is more subtle: The new placement allows
|
|
@code{.got} to be read-only in applications linked with
|
|
@samp{-z relro -z now}. However, this placement means that
|
|
@code{.sdata} cannot always be used in shared libraries, because the
|
|
PowerPC ABI accesses @code{.sdata} in shared libraries from the GOT
|
|
pointer. @samp{--sdata-got} forces the old GOT placement. PowerPC
|
|
GCC doesn't use @code{.sdata} in shared libraries, so this option is
|
|
really only useful for other compilers that may do so.
|
|
|
|
@cindex PowerPC stub symbols
|
|
@kindex --emit-stub-syms
|
|
@item --emit-stub-syms
|
|
This option causes @command{ld} to label linker stubs with a local
|
|
symbol that encodes the stub type and destination.
|
|
|
|
@cindex PowerPC TLS optimization
|
|
@kindex --no-tls-optimize
|
|
@item --no-tls-optimize
|
|
PowerPC @command{ld} normally performs some optimization of code
|
|
sequences used to access Thread-Local Storage. Use this option to
|
|
disable the optimization.
|
|
@end table
|
|
|
|
@ifclear GENERIC
|
|
@lowersections
|
|
@end ifclear
|
|
@end ifset
|
|
|
|
@ifset POWERPC64
|
|
@ifclear GENERIC
|
|
@raisesections
|
|
@end ifclear
|
|
|
|
@node PowerPC64 ELF64
|
|
@section @command{ld} and PowerPC64 64-bit ELF Support
|
|
|
|
@cindex PowerPC64 ELF64 options
|
|
@table @option
|
|
@cindex PowerPC64 stub grouping
|
|
@kindex --stub-group-size
|
|
@item --stub-group-size
|
|
Long branch stubs, PLT call stubs and TOC adjusting stubs are placed
|
|
by @command{ld} in stub sections located between groups of input sections.
|
|
@samp{--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 @samp{N} chooses this scheme, ensuring that
|
|
branches to stubs always use a negative offset. Two special values of
|
|
@samp{N} are recognized, @samp{1} and @samp{-1}. These both instruct
|
|
@command{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 @samp{N} respectively.
|
|
|
|
Note that @samp{--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.
|
|
|
|
@cindex PowerPC64 stub symbols
|
|
@kindex --emit-stub-syms
|
|
@item --emit-stub-syms
|
|
This option causes @command{ld} to label linker stubs with a local
|
|
symbol that encodes the stub type and destination.
|
|
|
|
@cindex PowerPC64 dot symbols
|
|
@kindex --dotsyms
|
|
@kindex --no-dotsyms
|
|
@item --dotsyms
|
|
@itemx --no-dotsyms
|
|
These two options control how @command{ld} interprets version patterns
|
|
in a version script. Older PowerPC64 compilers emitted both a
|
|
function descriptor symbol with the same name as the function, and a
|
|
code entry symbol with the name prefixed by a dot (@samp{.}). To
|
|
properly version a function @samp{foo}, the version script thus needs
|
|
to control both @samp{foo} and @samp{.foo}. The option
|
|
@samp{--dotsyms}, on by default, automatically adds the required
|
|
dot-prefixed patterns. Use @samp{--no-dotsyms} to disable this
|
|
feature.
|
|
|
|
@cindex PowerPC64 register save/restore functions
|
|
@kindex --save-restore-funcs
|
|
@kindex --no-save-restore-funcs
|
|
@item --save-restore-funcs
|
|
@itemx --no-save-restore-funcs
|
|
These two options control whether PowerPC64 @command{ld} automatically
|
|
provides out-of-line register save and restore functions used by
|
|
@samp{-Os} code. The default is to provide any such referenced
|
|
function for a normal final link, and to not do so for a relocatable
|
|
link.
|
|
|
|
@cindex PowerPC64 TLS optimization
|
|
@kindex --no-tls-optimize
|
|
@item --no-tls-optimize
|
|
PowerPC64 @command{ld} normally performs some optimization of code
|
|
sequences used to access Thread-Local Storage. Use this option to
|
|
disable the optimization.
|
|
|
|
@cindex PowerPC64 __tls_get_addr optimization
|
|
@kindex --tls-get-addr-optimize
|
|
@kindex --no-tls-get-addr-optimize
|
|
@kindex --tls-get-addr-regsave
|
|
@kindex --no-tls-get-addr-regsave
|
|
@item --tls-get-addr-optimize
|
|
@itemx --no-tls-get-addr-optimize
|
|
These options control how PowerPC64 @command{ld} uses a special
|
|
stub to call __tls_get_addr. PowerPC64 glibc 2.22 and later support
|
|
an optimization that allows the second and subsequent calls to
|
|
@code{__tls_get_addr} for a given symbol to be resolved by the special
|
|
stub without calling in to glibc. By default the linker enables
|
|
generation of the stub when glibc advertises the availability of
|
|
__tls_get_addr_opt.
|
|
Using @option{--tls-get-addr-optimize} with an older glibc won't do
|
|
much besides slow down your applications, but may be useful if linking
|
|
an application against an older glibc with the expectation that it
|
|
will normally be used on systems having a newer glibc.
|
|
@option{--tls-get-addr-regsave} forces generation of a stub that saves
|
|
and restores volatile registers around the call into glibc. Normally,
|
|
this is done when the linker detects a call to __tls_get_addr_desc.
|
|
Such calls then go via the register saving stub to __tls_get_addr_opt.
|
|
@option{--no-tls-get-addr-regsave} disables generation of the
|
|
register saves.
|
|
|
|
@cindex PowerPC64 OPD optimization
|
|
@kindex --no-opd-optimize
|
|
@item --no-opd-optimize
|
|
PowerPC64 @command{ld} normally removes @code{.opd} section entries
|
|
corresponding to deleted link-once functions, or functions removed by
|
|
the action of @samp{--gc-sections} or linker script @code{/DISCARD/}.
|
|
Use this option to disable @code{.opd} optimization.
|
|
|
|
@cindex PowerPC64 OPD spacing
|
|
@kindex --non-overlapping-opd
|
|
@item --non-overlapping-opd
|
|
Some PowerPC64 compilers have an option to generate compressed
|
|
@code{.opd} entries spaced 16 bytes apart, overlapping the third word,
|
|
the static chain pointer (unused in C) with the first word of the next
|
|
entry. This option expands such entries to the full 24 bytes.
|
|
|
|
@cindex PowerPC64 TOC optimization
|
|
@kindex --no-toc-optimize
|
|
@item --no-toc-optimize
|
|
PowerPC64 @command{ld} normally removes unused @code{.toc} section
|
|
entries. Such entries are detected by examining relocations that
|
|
reference the TOC in code sections. A reloc in a deleted code section
|
|
marks a TOC word as unneeded, while a reloc in a kept code section
|
|
marks a TOC word as needed. Since the TOC may reference itself, TOC
|
|
relocs are also examined. TOC words marked as both needed and
|
|
unneeded will of course be kept. TOC words without any referencing
|
|
reloc are assumed to be part of a multi-word entry, and are kept or
|
|
discarded as per the nearest marked preceding word. This works
|
|
reliably for compiler generated code, but may be incorrect if assembly
|
|
code is used to insert TOC entries. Use this option to disable the
|
|
optimization.
|
|
|
|
@cindex PowerPC64 multi-TOC
|
|
@kindex --no-multi-toc
|
|
@item --no-multi-toc
|
|
If given any toc option besides @code{-mcmodel=medium} or
|
|
@code{-mcmodel=large}, PowerPC64 GCC generates code for a TOC model
|
|
where TOC
|
|
entries are accessed with a 16-bit offset from r2. This limits the
|
|
total TOC size to 64K. PowerPC64 @command{ld} extends this limit by
|
|
grouping code sections such that each group uses less than 64K for its
|
|
TOC entries, then inserts r2 adjusting stubs between inter-group
|
|
calls. @command{ld} does not split apart input sections, so cannot
|
|
help if a single input file has a @code{.toc} section that exceeds
|
|
64K, most likely from linking multiple files with @command{ld -r}.
|
|
Use this option to turn off this feature.
|
|
|
|
@cindex PowerPC64 TOC sorting
|
|
@kindex --no-toc-sort
|
|
@item --no-toc-sort
|
|
By default, @command{ld} sorts TOC sections so that those whose file
|
|
happens to have a section called @code{.init} or @code{.fini} are
|
|
placed first, followed by TOC sections referenced by code generated
|
|
with PowerPC64 gcc's @code{-mcmodel=small}, and lastly TOC sections
|
|
referenced only by code generated with PowerPC64 gcc's
|
|
@code{-mcmodel=medium} or @code{-mcmodel=large} options. Doing this
|
|
results in better TOC grouping for multi-TOC. Use this option to turn
|
|
off this feature.
|
|
|
|
@cindex PowerPC64 PLT stub alignment
|
|
@kindex --plt-align
|
|
@kindex --no-plt-align
|
|
@item --plt-align
|
|
@itemx --no-plt-align
|
|
Use these options to control whether individual PLT call stubs are
|
|
aligned to a 32-byte boundary, or to the specified power of two
|
|
boundary when using @code{--plt-align=}. A negative value may be
|
|
specified to pad PLT call stubs so that they do not cross the
|
|
specified power of two boundary (or the minimum number of boundaries
|
|
if a PLT stub is so large that it must cross a boundary). By default
|
|
PLT call stubs are aligned to 32-byte boundaries.
|
|
|
|
@cindex PowerPC64 PLT call stub static chain
|
|
@kindex --plt-static-chain
|
|
@kindex --no-plt-static-chain
|
|
@item --plt-static-chain
|
|
@itemx --no-plt-static-chain
|
|
Use these options to control whether PLT call stubs load the static
|
|
chain pointer (r11). @code{ld} defaults to not loading the static
|
|
chain since there is never any need to do so on a PLT call.
|
|
|
|
@cindex PowerPC64 PLT call stub thread safety
|
|
@kindex --plt-thread-safe
|
|
@kindex --no-plt-thread-safe
|
|
@item --plt-thread-safe
|
|
@itemx --no-plt-thread-safe
|
|
With power7's weakly ordered memory model, it is possible when using
|
|
lazy binding for ld.so to update a plt entry in one thread and have
|
|
another thread see the individual plt entry words update in the wrong
|
|
order, despite ld.so carefully writing in the correct order and using
|
|
memory write barriers. To avoid this we need some sort of read
|
|
barrier in the call stub, or use LD_BIND_NOW=1. By default, @code{ld}
|
|
looks for calls to commonly used functions that create threads, and if
|
|
seen, adds the necessary barriers. Use these options to change the
|
|
default behaviour.
|
|
|
|
@cindex PowerPC64 ELFv2 PLT localentry optimization
|
|
@kindex --plt-localentry
|
|
@kindex --no-plt-localentry
|
|
@item --plt-localentry
|
|
@itemx --no-localentry
|
|
ELFv2 functions with localentry:0 are those with a single entry point,
|
|
ie. global entry == local entry, and that have no requirement on r2
|
|
(the TOC/GOT pointer) or r12, and guarantee r2 is unchanged on return.
|
|
Such an external function can be called via the PLT without saving r2
|
|
or restoring it on return, avoiding a common load-hit-store for small
|
|
functions. The optimization is attractive, with up to 40% reduction
|
|
in execution time for a small function, but can result in symbol
|
|
interposition failures. Also, minor changes in a shared library,
|
|
including system libraries, can cause a function that was localentry:0
|
|
to become localentry:8. This will result in a dynamic loader
|
|
complaint and failure to run. The option is experimental, use with
|
|
care. @option{--no-plt-localentry} is the default.
|
|
@end table
|
|
|
|
@ifclear GENERIC
|
|
@lowersections
|
|
@end ifclear
|
|
@end ifset
|
|
|
|
@ifset S/390
|
|
@ifclear GENERIC
|
|
@raisesections
|
|
@end ifclear
|
|
|
|
@node S/390 ELF
|
|
@section @command{ld} and S/390 ELF Support
|
|
|
|
@cindex S/390 ELF options
|
|
@table @option
|
|
|
|
@cindex S/390
|
|
@kindex --s390-pgste
|
|
@item --s390-pgste
|
|
This option marks the result file with a @code{PT_S390_PGSTE}
|
|
segment. The Linux kernel is supposed to allocate 4k page tables for
|
|
binaries marked that way.
|
|
@end table
|
|
|
|
@ifclear GENERIC
|
|
@lowersections
|
|
@end ifclear
|
|
@end ifset
|
|
|
|
@ifset SPU
|
|
@ifclear GENERIC
|
|
@raisesections
|
|
@end ifclear
|
|
|
|
@node SPU ELF
|
|
@section @command{ld} and SPU ELF Support
|
|
|
|
@cindex SPU ELF options
|
|
@table @option
|
|
|
|
@cindex SPU plugins
|
|
@kindex --plugin
|
|
@item --plugin
|
|
This option marks an executable as a PIC plugin module.
|
|
|
|
@cindex SPU overlays
|
|
@kindex --no-overlays
|
|
@item --no-overlays
|
|
Normally, @command{ld} recognizes calls to functions within overlay
|
|
regions, and redirects such calls to an overlay manager via a stub.
|
|
@command{ld} also provides a built-in overlay manager. This option
|
|
turns off all this special overlay handling.
|
|
|
|
@cindex SPU overlay stub symbols
|
|
@kindex --emit-stub-syms
|
|
@item --emit-stub-syms
|
|
This option causes @command{ld} to label overlay stubs with a local
|
|
symbol that encodes the stub type and destination.
|
|
|
|
@cindex SPU extra overlay stubs
|
|
@kindex --extra-overlay-stubs
|
|
@item --extra-overlay-stubs
|
|
This option causes @command{ld} to add overlay call stubs on all
|
|
function calls out of overlay regions. Normally stubs are not added
|
|
on calls to non-overlay regions.
|
|
|
|
@cindex SPU local store size
|
|
@kindex --local-store=lo:hi
|
|
@item --local-store=lo:hi
|
|
@command{ld} usually checks that a final executable for SPU fits in
|
|
the address range 0 to 256k. This option may be used to change the
|
|
range. Disable the check entirely with @option{--local-store=0:0}.
|
|
|
|
@cindex SPU
|
|
@kindex --stack-analysis
|
|
@item --stack-analysis
|
|
SPU local store space is limited. Over-allocation of stack space
|
|
unnecessarily limits space available for code and data, while
|
|
under-allocation results in runtime failures. If given this option,
|
|
@command{ld} will provide an estimate of maximum stack usage.
|
|
@command{ld} does this by examining symbols in code sections to
|
|
determine the extents of functions, and looking at function prologues
|
|
for stack adjusting instructions. A call-graph is created by looking
|
|
for relocations on branch instructions. The graph is then searched
|
|
for the maximum stack usage path. Note that this analysis does not
|
|
find calls made via function pointers, and does not handle recursion
|
|
and other cycles in the call graph. Stack usage may be
|
|
under-estimated if your code makes such calls. Also, stack usage for
|
|
dynamic allocation, e.g. alloca, will not be detected. If a link map
|
|
is requested, detailed information about each function's stack usage
|
|
and calls will be given.
|
|
|
|
@cindex SPU
|
|
@kindex --emit-stack-syms
|
|
@item --emit-stack-syms
|
|
This option, if given along with @option{--stack-analysis} will result
|
|
in @command{ld} emitting stack sizing symbols for each function.
|
|
These take the form @code{__stack_<function_name>} for global
|
|
functions, and @code{__stack_<number>_<function_name>} for static
|
|
functions. @code{<number>} is the section id in hex. The value of
|
|
such symbols is the stack requirement for the corresponding function.
|
|
The symbol size will be zero, type @code{STT_NOTYPE}, binding
|
|
@code{STB_LOCAL}, and section @code{SHN_ABS}.
|
|
@end table
|
|
|
|
@ifclear GENERIC
|
|
@lowersections
|
|
@end ifclear
|
|
@end ifset
|
|
|
|
@ifset TICOFF
|
|
@ifclear GENERIC
|
|
@raisesections
|
|
@end ifclear
|
|
|
|
@node TI COFF
|
|
@section @command{ld}'s Support for Various TI COFF Versions
|
|
@cindex TI COFF versions
|
|
@kindex --format=@var{version}
|
|
The @samp{--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; @command{ld} will read any version or byte order, but the output
|
|
header format depends on the default specified by the specific target.
|
|
|
|
@ifclear GENERIC
|
|
@lowersections
|
|
@end ifclear
|
|
@end ifset
|
|
|
|
@ifset WIN32
|
|
@ifclear GENERIC
|
|
@raisesections
|
|
@end ifclear
|
|
|
|
@node WIN32
|
|
@section @command{ld} and WIN32 (cygwin/mingw)
|
|
|
|
This section describes some of the win32 specific @command{ld} issues.
|
|
See @ref{Options,,Command-line Options} for detailed description of the
|
|
command-line options mentioned here.
|
|
|
|
@table @emph
|
|
@cindex import libraries
|
|
@item 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 @command{ld} have specific
|
|
support for creating such libraries provided with the
|
|
@samp{--out-implib} command-line option.
|
|
|
|
@item exporting DLL symbols
|
|
@cindex exporting DLL symbols
|
|
The cygwin/mingw @command{ld} has several ways to export symbols for dll's.
|
|
|
|
@table @emph
|
|
@item using auto-export functionality
|
|
@cindex using auto-export functionality
|
|
By default @command{ld} exports symbols with the auto-export functionality,
|
|
which is controlled by the following command-line options:
|
|
|
|
@itemize
|
|
@item --export-all-symbols [This is the default]
|
|
@item --exclude-symbols
|
|
@item --exclude-libs
|
|
@item --exclude-modules-for-implib
|
|
@item --version-script
|
|
@end itemize
|
|
|
|
When auto-export is in operation, @command{ld} will export all the non-local
|
|
(global and common) symbols it finds in a DLL, with the exception of a few
|
|
symbols known to belong to the system's runtime and libraries. As it will
|
|
often not be desirable to export all of a DLL's symbols, which may include
|
|
private functions that are not part of any public interface, the command-line
|
|
options listed above may be used to filter symbols out from the list for
|
|
exporting. The @samp{--output-def} option can be used in order to see the
|
|
final list of exported symbols with all exclusions taken into effect.
|
|
|
|
If @samp{--export-all-symbols} is not given explicitly on the
|
|
command line, then the default auto-export behavior will be @emph{disabled}
|
|
if either of the following are true:
|
|
|
|
@itemize
|
|
@item A DEF file is used.
|
|
@item Any symbol in any object file was marked with the __declspec(dllexport) attribute.
|
|
@end itemize
|
|
|
|
@item using a DEF file
|
|
@cindex 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 @samp{<dll
|
|
name>.def} and is added as any other object file to the linker's
|
|
command line. The file's name must end in @samp{.def} or @samp{.DEF}.
|
|
|
|
@example
|
|
gcc -o <output> <objectfiles> <dll name>.def
|
|
@end example
|
|
|
|
Using a DEF file turns off the normal auto-export behavior, unless the
|
|
@samp{--export-all-symbols} option is also used.
|
|
|
|
Here is an example of a DEF file for a shared library called @samp{xyz.dll}:
|
|
|
|
@example
|
|
LIBRARY "xyz.dll" BASE=0x20000000
|
|
|
|
EXPORTS
|
|
foo
|
|
bar
|
|
_bar = bar
|
|
another_foo = abc.dll.afoo
|
|
var1 DATA
|
|
doo = foo == foo2
|
|
eoo DATA == var1
|
|
@end example
|
|
|
|
This example defines a DLL with a non-default base address and seven
|
|
symbols in the export table. The third exported symbol @code{_bar} is an
|
|
alias for the second. The fourth symbol, @code{another_foo} is resolved
|
|
by "forwarding" to another module and treating it as an alias for
|
|
@code{afoo} exported from the DLL @samp{abc.dll}. The final symbol
|
|
@code{var1} is declared to be a data object. The @samp{doo} symbol in
|
|
export library is an alias of @samp{foo}, which gets the string name
|
|
in export table @samp{foo2}. The @samp{eoo} symbol is an data export
|
|
symbol, which gets in export table the name @samp{var1}.
|
|
|
|
The optional @code{LIBRARY <name>} command indicates the @emph{internal}
|
|
name of the output DLL. If @samp{<name>} does not include a suffix,
|
|
the default library suffix, @samp{.DLL} is appended.
|
|
|
|
When the .DEF file is used to build an application, rather than a
|
|
library, the @code{NAME <name>} command should be used instead of
|
|
@code{LIBRARY}. If @samp{<name>} does not include a suffix, the default
|
|
executable suffix, @samp{.EXE} is appended.
|
|
|
|
With either @code{LIBRARY <name>} or @code{NAME <name>} the optional
|
|
specification @code{BASE = <number>} may be used to specify a
|
|
non-default base address for the image.
|
|
|
|
If neither @code{LIBRARY <name>} nor @code{NAME <name>} is specified,
|
|
or they specify an empty string, the internal name is the same as the
|
|
filename specified on the command line.
|
|
|
|
The complete specification of an export symbol is:
|
|
|
|
@example
|
|
EXPORTS
|
|
( ( ( <name1> [ = <name2> ] )
|
|
| ( <name1> = <module-name> . <external-name>))
|
|
[ @@ <integer> ] [NONAME] [DATA] [CONSTANT] [PRIVATE] [== <name3>] ) *
|
|
@end example
|
|
|
|
Declares @samp{<name1>} as an exported symbol from the DLL, or declares
|
|
@samp{<name1>} as an exported alias for @samp{<name2>}; or declares
|
|
@samp{<name1>} as a "forward" alias for the symbol
|
|
@samp{<external-name>} in the DLL @samp{<module-name>}.
|
|
Optionally, the symbol may be exported by the specified ordinal
|
|
@samp{<integer>} alias. The optional @samp{<name3>} is the to be used
|
|
string in import/export table for the symbol.
|
|
|
|
The optional keywords that follow the declaration indicate:
|
|
|
|
@code{NONAME}: Do not put the symbol name in the DLL's export table. It
|
|
will still be exported by its ordinal alias (either the value specified
|
|
by the .def specification or, otherwise, the value assigned by the
|
|
linker). The symbol name, however, does remain visible in the import
|
|
library (if any), unless @code{PRIVATE} is also specified.
|
|
|
|
@code{DATA}: The symbol is a variable or object, rather than a function.
|
|
The import lib will export only an indirect reference to @code{foo} as
|
|
the symbol @code{_imp__foo} (ie, @code{foo} must be resolved as
|
|
@code{*_imp__foo}).
|
|
|
|
@code{CONSTANT}: Like @code{DATA}, but put the undecorated @code{foo} as
|
|
well as @code{_imp__foo} into the import library. Both refer to the
|
|
read-only import address table's pointer to the variable, not to the
|
|
variable itself. This can be dangerous. If the user code fails to add
|
|
the @code{dllimport} attribute and also fails to explicitly add the
|
|
extra indirection that the use of the attribute enforces, the
|
|
application will behave unexpectedly.
|
|
|
|
@code{PRIVATE}: Put the symbol in the DLL's export table, but do not put
|
|
it into the static import library used to resolve imports at link time. The
|
|
symbol can still be imported using the @code{LoadLibrary/GetProcAddress}
|
|
API at runtime or by using the GNU ld extension of linking directly to
|
|
the DLL without an import library.
|
|
|
|
See ld/deffilep.y in the binutils sources for the full specification of
|
|
other DEF file statements
|
|
|
|
@cindex creating a DEF file
|
|
While linking a shared dll, @command{ld} is able to create a DEF file
|
|
with the @samp{--output-def <file>} command-line option.
|
|
|
|
@item Using decorations
|
|
@cindex 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:
|
|
|
|
@example
|
|
__declspec(dllexport) int a_variable
|
|
__declspec(dllexport) void a_function(int with_args)
|
|
@end example
|
|
|
|
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 @samp{--export-all-symbols} option is also used.
|
|
|
|
Note that object files that wish to access these symbols must @emph{not}
|
|
decorate them with dllexport. Instead, they should use dllimport,
|
|
instead:
|
|
|
|
@example
|
|
__declspec(dllimport) int a_variable
|
|
__declspec(dllimport) void a_function(int with_args)
|
|
@end example
|
|
|
|
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
|
|
@samp{--enable-auto-import} and @samp{automatic data imports} for more
|
|
information.
|
|
@end table
|
|
|
|
@cindex automatic data imports
|
|
@item 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 achieve a behavior that conforms to that on POSIX/Un*x
|
|
platforms. This feature is enabled with the @samp{--enable-auto-import}
|
|
command-line option, although it is enabled by default on cygwin/mingw.
|
|
The @samp{--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 @code{--enable-auto-import} for details."
|
|
|
|
The @samp{--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 @emph{runtime pseudo-relocs} feature, described
|
|
below.
|
|
|
|
@cindex runtime pseudo-relocation
|
|
For complex variables imported from DLLs (such as structs or classes),
|
|
object files typically contain a base address for the variable and an
|
|
offset (@emph{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 @samp{--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.
|
|
|
|
@samp{--enable-runtime-pseudo-relocs} is not the default; it must be explicitly
|
|
enabled as needed.
|
|
|
|
@cindex direct linking to a dll
|
|
@item direct linking to a dll
|
|
The cygwin/mingw ports of @command{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, especially when linking large
|
|
libraries or applications. When @command{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
|
|
@samp{-L} and @samp{-l}, because @command{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 @samp{-lxxx} it will attempt
|
|
to find, in the first directory of its search path,
|
|
|
|
@example
|
|
libxxx.dll.a
|
|
xxx.dll.a
|
|
libxxx.a
|
|
xxx.lib
|
|
libxxx.lib
|
|
cygxxx.dll (*)
|
|
libxxx.dll
|
|
xxx.dll
|
|
@end example
|
|
|
|
before moving on to the next directory in the search path.
|
|
|
|
(*) Actually, this is not @samp{cygxxx.dll} but in fact is @samp{<prefix>xxx.dll},
|
|
where @samp{<prefix>} is set by the @command{ld} option
|
|
@samp{--dll-search-prefix=<prefix>}. In the case of cygwin, the standard gcc spec
|
|
file includes @samp{--dll-search-prefix=cyg}, so in effect we actually search for
|
|
@samp{cygxxx.dll}.
|
|
|
|
Other win32-based unix environments, such as mingw or pw32, may use other
|
|
@samp{<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 @samp{bin} directory for
|
|
applications and dll's and a @samp{lib} directory for the import
|
|
libraries (using cygwin nomenclature):
|
|
|
|
@example
|
|
bin/
|
|
cygxxx.dll
|
|
lib/
|
|
libxxx.dll.a (in case of dll's)
|
|
libxxx.a (in case of static archive)
|
|
@end example
|
|
|
|
Linking directly to a dll without using the import library can be
|
|
done two ways:
|
|
|
|
1. Use the dll directly by adding the @samp{bin} path to the link line
|
|
@example
|
|
gcc -Wl,-verbose -o a.exe -L../bin/ -lxxx
|
|
@end example
|
|
|
|
However, as the dll's often have version numbers appended to their names
|
|
(@samp{cygncurses-5.dll}) this will often fail, unless one specifies
|
|
@samp{-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 @samp{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.
|
|
|
|
@example
|
|
ln -s bin/cygxxx.dll lib/[cyg|lib|]xxx.dll[.a]
|
|
@end example
|
|
|
|
Then you can link without any make environment changes.
|
|
|
|
@example
|
|
gcc -Wl,-verbose -o a.exe -L../lib/ -lxxx
|
|
@end example
|
|
|
|
This technique also avoids the version number problems, because the following is
|
|
perfectly legal
|
|
|
|
@example
|
|
bin/
|
|
cygxxx-5.dll
|
|
lib/
|
|
libxxx.dll.a -> ../bin/cygxxx-5.dll
|
|
@end example
|
|
|
|
Linking directly to a dll without using an import lib will work
|
|
even when auto-import features are exercised, and even when
|
|
@samp{--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 three reasons:
|
|
|
|
1. Until recently, the link-directly-to-dll functionality did @emph{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.
|
|
|
|
3. Symbol aliases can only be resolved using an import lib. This is
|
|
critical when linking against OS-supplied dll's (eg, the win32 API)
|
|
in which symbols are usually exported as undecorated aliases of their
|
|
stdcall-decorated assembly names.
|
|
|
|
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 many 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.
|
|
|
|
@item symbol aliasing
|
|
@table @emph
|
|
@item adding additional names
|
|
Sometimes, it is useful to export symbols with additional names.
|
|
A symbol @samp{foo} will be exported as @samp{foo}, but it can also be
|
|
exported as @samp{_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:
|
|
|
|
@example
|
|
LIBRARY "xyz.dll" BASE=0x61000000
|
|
|
|
EXPORTS
|
|
foo
|
|
_foo = foo
|
|
@end example
|
|
|
|
The line @samp{_foo = foo} maps the symbol @samp{foo} to @samp{_foo}.
|
|
|
|
Another method for creating a symbol alias is to create it in the
|
|
source code using the "weak" attribute:
|
|
|
|
@example
|
|
void foo () @{ /* Do something. */; @}
|
|
void _foo () __attribute__ ((weak, alias ("foo")));
|
|
@end example
|
|
|
|
See the gcc manual for more information about attributes and weak
|
|
symbols.
|
|
|
|
@item renaming symbols
|
|
Sometimes it is useful to rename exports. For instance, the cygwin
|
|
kernel does this regularly. A symbol @samp{_foo} can be exported as
|
|
@samp{foo} but not as @samp{_foo} by using special directives in the
|
|
DEF file. (This will also affect the import library, if it is
|
|
created). In the following example:
|
|
|
|
@example
|
|
LIBRARY "xyz.dll" BASE=0x61000000
|
|
|
|
EXPORTS
|
|
_foo = foo
|
|
@end example
|
|
|
|
The line @samp{_foo = foo} maps the exported symbol @samp{foo} to
|
|
@samp{_foo}.
|
|
@end table
|
|
|
|
Note: using a DEF file disables the default auto-export behavior,
|
|
unless the @samp{--export-all-symbols} command-line option is used.
|
|
If, however, you are trying to rename symbols, then you should list
|
|
@emph{all} desired exports in the DEF file, including the symbols
|
|
that are not being renamed, and do @emph{not} use the
|
|
@samp{--export-all-symbols} option. If you list only the
|
|
renamed symbols in the DEF file, and use @samp{--export-all-symbols}
|
|
to handle the other symbols, then the both the new names @emph{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.
|
|
|
|
@cindex weak externals
|
|
@item 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:
|
|
@itemize
|
|
@item Definition is searched for in objects and libraries, historically
|
|
called lazy externals.
|
|
@item Definition is searched for only in other objects, not in libraries.
|
|
This form is not presently implemented.
|
|
@item No search; the symbol is an alias. This form is not presently
|
|
implemented.
|
|
@end itemize
|
|
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.
|
|
|
|
@cindex aligned common symbols
|
|
@item aligned common symbols
|
|
As a GNU extension to the PE file format, it is possible to specify the
|
|
desired alignment for a common symbol. This information is conveyed from
|
|
the assembler or compiler to the linker by means of GNU-specific commands
|
|
carried in the object file's @samp{.drectve} section, which are recognized
|
|
by @command{ld} and respected when laying out the common symbols. Native
|
|
tools will be able to process object files employing this GNU extension,
|
|
but will fail to respect the alignment instructions, and may issue noisy
|
|
warnings about unknown linker directives.
|
|
|
|
@end table
|
|
|
|
@ifclear GENERIC
|
|
@lowersections
|
|
@end ifclear
|
|
@end ifset
|
|
|
|
@ifset XTENSA
|
|
@ifclear GENERIC
|
|
@raisesections
|
|
@end ifclear
|
|
|
|
@node Xtensa
|
|
@section @code{ld} and Xtensa Processors
|
|
|
|
@cindex Xtensa processors
|
|
The default @command{ld} behavior for Xtensa processors is to interpret
|
|
@code{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:
|
|
|
|
@smallexample
|
|
SECTIONS
|
|
@{
|
|
.text : @{
|
|
*(.literal .text)
|
|
@}
|
|
@}
|
|
@end smallexample
|
|
|
|
@noindent
|
|
@command{ld} may interleave some of the @code{.literal}
|
|
and @code{.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 @code{.literal} sections from an initial
|
|
group of files followed by the @code{.text} sections of that group of
|
|
files. Then, the @code{.literal} sections from the rest of the files
|
|
and the @code{.text} sections from the rest of the files would follow.
|
|
|
|
@cindex @option{--relax} on Xtensa
|
|
@cindex relaxing on Xtensa
|
|
Relaxation is enabled by default for the Xtensa version of @command{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 @code{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 @code{L32R} instructions. The second optimization is to remove
|
|
unnecessary overhead from assembler-generated ``longcall'' sequences of
|
|
@code{L32R}/@code{CALLX@var{n}} when the target functions are within
|
|
range of direct @code{CALL@var{n}} instructions.
|
|
|
|
For each of these cases where an indirect call sequence can be optimized
|
|
to a direct call, the linker will change the @code{CALLX@var{n}}
|
|
instruction to a @code{CALL@var{n}} instruction, remove the @code{L32R}
|
|
instruction, and remove the literal referenced by the @code{L32R}
|
|
instruction if it is not used for anything else. Removing the
|
|
@code{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 @code{L32R}
|
|
instruction that was removed. If code size is more important than
|
|
performance, the @option{--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:
|
|
|
|
@cindex Xtensa options
|
|
@table @option
|
|
@item --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.
|
|
|
|
@item --abi-windowed
|
|
@itemx --abi-call0
|
|
Choose ABI for the output object and for the generated PLT code.
|
|
PLT code inserted by the linker must match ABI of the output object
|
|
because windowed and call0 ABI use incompatible function call
|
|
conventions.
|
|
Default ABI is chosen by the ABI tag in the @code{.xtensa.info} section
|
|
of the first input object.
|
|
A warning is issued if ABI tags of input objects do not match each other
|
|
or the chosen output object ABI.
|
|
@end table
|
|
|
|
@ifclear GENERIC
|
|
@lowersections
|
|
@end ifclear
|
|
@end ifset
|
|
|
|
@ifclear SingleFormat
|
|
@node BFD
|
|
@chapter BFD
|
|
|
|
@cindex back end
|
|
@cindex object file management
|
|
@cindex object formats available
|
|
@kindex objdump -i
|
|
The linker accesses object and archive files using the BFD libraries.
|
|
These libraries allow the linker to use the same routines to operate on
|
|
object files whatever the object file format. A different object file
|
|
format can be supported simply by creating a new BFD back end and adding
|
|
it to the library. To conserve runtime memory, however, the linker and
|
|
associated tools are usually configured to support only a subset of the
|
|
object file formats available. You can use @code{objdump -i}
|
|
(@pxref{objdump,,objdump,binutils.info,The GNU Binary Utilities}) to
|
|
list all the formats available for your configuration.
|
|
|
|
@cindex BFD requirements
|
|
@cindex requirements for BFD
|
|
As with most implementations, BFD is a compromise between
|
|
several conflicting requirements. The major factor influencing
|
|
BFD design was efficiency: any time used converting between
|
|
formats is time which would not have been spent had BFD not
|
|
been involved. This is partly offset by abstraction payback; since
|
|
BFD simplifies applications and back ends, more time and care
|
|
may be spent optimizing algorithms for a greater speed.
|
|
|
|
One minor artifact of the BFD solution which you should bear in
|
|
mind is the potential for information loss. There are two places where
|
|
useful information can be lost using the BFD mechanism: during
|
|
conversion and during output. @xref{BFD information loss}.
|
|
|
|
@menu
|
|
* BFD outline:: How it works: an outline of BFD
|
|
@end menu
|
|
|
|
@node BFD outline
|
|
@section How It Works: An Outline of BFD
|
|
@cindex opening object files
|
|
@include bfdsumm.texi
|
|
@end ifclear
|
|
|
|
@node Reporting Bugs
|
|
@chapter Reporting Bugs
|
|
@cindex bugs in @command{ld}
|
|
@cindex reporting bugs in @command{ld}
|
|
|
|
Your bug reports play an essential role in making @command{ld} reliable.
|
|
|
|
Reporting a bug may help you by bringing a solution to your problem, or
|
|
it may not. But in any case the principal function of a bug report is
|
|
to help the entire community by making the next version of @command{ld}
|
|
work better. Bug reports are your contribution to the maintenance of
|
|
@command{ld}.
|
|
|
|
In order for a bug report to serve its purpose, you must include the
|
|
information that enables us to fix the bug.
|
|
|
|
@menu
|
|
* Bug Criteria:: Have you found a bug?
|
|
* Bug Reporting:: How to report bugs
|
|
@end menu
|
|
|
|
@node Bug Criteria
|
|
@section Have You Found a Bug?
|
|
@cindex bug criteria
|
|
|
|
If you are not sure whether you have found a bug, here are some guidelines:
|
|
|
|
@itemize @bullet
|
|
@cindex fatal signal
|
|
@cindex linker crash
|
|
@cindex crash of linker
|
|
@item
|
|
If the linker gets a fatal signal, for any input whatever, that is a
|
|
@command{ld} bug. Reliable linkers never crash.
|
|
|
|
@cindex error on valid input
|
|
@item
|
|
If @command{ld} produces an error message for valid input, that is a bug.
|
|
|
|
@cindex invalid input
|
|
@item
|
|
If @command{ld} does not produce an error message for invalid input, that
|
|
may be a bug. In the general case, the linker can not verify that
|
|
object files are correct.
|
|
|
|
@item
|
|
If you are an experienced user of linkers, your suggestions for
|
|
improvement of @command{ld} are welcome in any case.
|
|
@end itemize
|
|
|
|
@node Bug Reporting
|
|
@section How to Report Bugs
|
|
@cindex bug reports
|
|
@cindex @command{ld} bugs, reporting
|
|
|
|
A number of companies and individuals offer support for @sc{gnu}
|
|
products. If you obtained @command{ld} from a support organization, we
|
|
recommend you contact that organization first.
|
|
|
|
You can find contact information for many support companies and
|
|
individuals in the file @file{etc/SERVICE} in the @sc{gnu} Emacs
|
|
distribution.
|
|
|
|
@ifset BUGURL
|
|
Otherwise, send bug reports for @command{ld} to
|
|
@value{BUGURL}.
|
|
@end ifset
|
|
|
|
The fundamental principle of reporting bugs usefully is this:
|
|
@strong{report all the facts}. If you are not sure whether to state a
|
|
fact or leave it out, state it!
|
|
|
|
Often people omit facts because they think they know what causes the
|
|
problem and assume that some details do not matter. Thus, you might
|
|
assume that the name of a symbol you use in an example does not
|
|
matter. Well, probably it does not, but one cannot be sure. Perhaps
|
|
the bug is a stray memory reference which happens to fetch from the
|
|
location where that name is stored in memory; perhaps, if the name
|
|
were different, the contents of that location would fool the linker
|
|
into doing the right thing despite the bug. Play it safe and give a
|
|
specific, complete example. That is the easiest thing for you to do,
|
|
and the most helpful.
|
|
|
|
Keep in mind that the purpose of a bug report is to enable us to fix
|
|
the bug if it is new to us. Therefore, always write your bug reports
|
|
on the assumption that the bug has not been reported previously.
|
|
|
|
Sometimes people give a few sketchy facts and ask, ``Does this ring a
|
|
bell?'' This cannot help us fix a bug, so it is basically useless. We
|
|
respond by asking for enough details to enable us to investigate.
|
|
You might as well expedite matters by sending them to begin with.
|
|
|
|
To enable us to fix the bug, you should include all these things:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
The version of @command{ld}. @command{ld} announces it if you start it with
|
|
the @samp{--version} argument.
|
|
|
|
Without this, we will not know whether there is any point in looking for
|
|
the bug in the current version of @command{ld}.
|
|
|
|
@item
|
|
Any patches you may have applied to the @command{ld} source, including any
|
|
patches made to the @code{BFD} library.
|
|
|
|
@item
|
|
The type of machine you are using, and the operating system name and
|
|
version number.
|
|
|
|
@item
|
|
What compiler (and its version) was used to compile @command{ld}---e.g.
|
|
``@code{gcc-2.7}''.
|
|
|
|
@item
|
|
The command arguments you gave the linker to link your example and
|
|
observe the bug. To guarantee you will not omit something important,
|
|
list them all. A copy of the Makefile (or the output from make) is
|
|
sufficient.
|
|
|
|
If we were to try to guess the arguments, we would probably guess wrong
|
|
and then we might not encounter the bug.
|
|
|
|
@item
|
|
A complete input file, or set of input files, that will reproduce the
|
|
bug. It is generally most helpful to send the actual object files
|
|
provided that they are reasonably small. Say no more than 10K. For
|
|
bigger files you can either make them available by FTP or HTTP or else
|
|
state that you are willing to send the object file(s) to whomever
|
|
requests them. (Note - your email will be going to a mailing list, so
|
|
we do not want to clog it up with large attachments). But small
|
|
attachments are best.
|
|
|
|
If the source files were assembled using @code{gas} or compiled using
|
|
@code{gcc}, then it may be OK to send the source files rather than the
|
|
object files. In this case, be sure to say exactly what version of
|
|
@code{gas} or @code{gcc} was used to produce the object files. Also say
|
|
how @code{gas} or @code{gcc} were configured.
|
|
|
|
@item
|
|
A description of what behavior you observe that you believe is
|
|
incorrect. For example, ``It gets a fatal signal.''
|
|
|
|
Of course, if the bug is that @command{ld} gets a fatal signal, then we
|
|
will certainly notice it. But if the bug is incorrect output, we might
|
|
not notice unless it is glaringly wrong. You might as well not give us
|
|
a chance to make a mistake.
|
|
|
|
Even if the problem you experience is a fatal signal, you should still
|
|
say so explicitly. Suppose something strange is going on, such as, your
|
|
copy of @command{ld} is out of sync, or you have encountered a bug in the
|
|
C library on your system. (This has happened!) Your copy might crash
|
|
and ours would not. If you told us to expect a crash, then when ours
|
|
fails to crash, we would know that the bug was not happening for us. If
|
|
you had not told us to expect a crash, then we would not be able to draw
|
|
any conclusion from our observations.
|
|
|
|
@item
|
|
If you wish to suggest changes to the @command{ld} source, send us context
|
|
diffs, as generated by @code{diff} with the @samp{-u}, @samp{-c}, or
|
|
@samp{-p} option. Always send diffs from the old file to the new file.
|
|
If you even discuss something in the @command{ld} source, refer to it by
|
|
context, not by line number.
|
|
|
|
The line numbers in our development sources will not match those in your
|
|
sources. Your line numbers would convey no useful information to us.
|
|
@end itemize
|
|
|
|
Here are some things that are not necessary:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
A description of the envelope of the bug.
|
|
|
|
Often people who encounter a bug spend a lot of time investigating
|
|
which changes to the input file will make the bug go away and which
|
|
changes will not affect it.
|
|
|
|
This is often time consuming and not very useful, because the way we
|
|
will find the bug is by running a single example under the debugger
|
|
with breakpoints, not by pure deduction from a series of examples.
|
|
We recommend that you save your time for something else.
|
|
|
|
Of course, if you can find a simpler example to report @emph{instead}
|
|
of the original one, that is a convenience for us. Errors in the
|
|
output will be easier to spot, running under the debugger will take
|
|
less time, and so on.
|
|
|
|
However, simplification is not vital; if you do not want to do this,
|
|
report the bug anyway and send us the entire test case you used.
|
|
|
|
@item
|
|
A patch for the bug.
|
|
|
|
A patch for the bug does help us if it is a good one. But do not omit
|
|
the necessary information, such as the test case, on the assumption that
|
|
a patch is all we need. We might see problems with your patch and decide
|
|
to fix the problem another way, or we might not understand it at all.
|
|
|
|
Sometimes with a program as complicated as @command{ld} it is very hard to
|
|
construct an example that will make the program follow a certain path
|
|
through the code. If you do not send us the example, we will not be
|
|
able to construct one, so we will not be able to verify that the bug is
|
|
fixed.
|
|
|
|
And if we cannot understand what bug you are trying to fix, or why your
|
|
patch should be an improvement, we will not install it. A test case will
|
|
help us to understand.
|
|
|
|
@item
|
|
A guess about what the bug is or what it depends on.
|
|
|
|
Such guesses are usually wrong. Even we cannot guess right about such
|
|
things without first using the debugger to find the facts.
|
|
@end itemize
|
|
|
|
@node MRI
|
|
@appendix MRI Compatible Script Files
|
|
@cindex MRI compatibility
|
|
To aid users making the transition to @sc{gnu} @command{ld} from the MRI
|
|
linker, @command{ld} can use MRI compatible linker scripts as an
|
|
alternative to the more general-purpose linker scripting language
|
|
described in @ref{Scripts}. MRI compatible linker scripts have a much
|
|
simpler command set than the scripting language otherwise used with
|
|
@command{ld}. @sc{gnu} @command{ld} supports the most commonly used MRI
|
|
linker commands; these commands are described here.
|
|
|
|
In general, MRI scripts aren't of much use with the @code{a.out} object
|
|
file format, since it only has three sections and MRI scripts lack some
|
|
features to make use of them.
|
|
|
|
You can specify a file containing an MRI-compatible script using the
|
|
@samp{-c} command-line option.
|
|
|
|
Each command in an MRI-compatible script occupies its own line; each
|
|
command line starts with the keyword that identifies the command (though
|
|
blank lines are also allowed for punctuation). If a line of an
|
|
MRI-compatible script begins with an unrecognized keyword, @command{ld}
|
|
issues a warning message, but continues processing the script.
|
|
|
|
Lines beginning with @samp{*} are comments.
|
|
|
|
You can write these commands using all upper-case letters, or all
|
|
lower case; for example, @samp{chip} is the same as @samp{CHIP}.
|
|
The following list shows only the upper-case form of each command.
|
|
|
|
@table @code
|
|
@cindex @code{ABSOLUTE} (MRI)
|
|
@item ABSOLUTE @var{secname}
|
|
@itemx ABSOLUTE @var{secname}, @var{secname}, @dots{} @var{secname}
|
|
Normally, @command{ld} includes in the output file all sections from all
|
|
the input files. However, in an MRI-compatible script, you can use the
|
|
@code{ABSOLUTE} command to restrict the sections that will be present in
|
|
your output program. If the @code{ABSOLUTE} command is used at all in a
|
|
script, then only the sections named explicitly in @code{ABSOLUTE}
|
|
commands will appear in the linker output. You can still use other
|
|
input sections (whatever you select on the command line, or using
|
|
@code{LOAD}) to resolve addresses in the output file.
|
|
|
|
@cindex @code{ALIAS} (MRI)
|
|
@item ALIAS @var{out-secname}, @var{in-secname}
|
|
Use this command to place the data from input section @var{in-secname}
|
|
in a section called @var{out-secname} in the linker output file.
|
|
|
|
@var{in-secname} may be an integer.
|
|
|
|
@cindex @code{ALIGN} (MRI)
|
|
@item ALIGN @var{secname} = @var{expression}
|
|
Align the section called @var{secname} to @var{expression}. The
|
|
@var{expression} should be a power of two.
|
|
|
|
@cindex @code{BASE} (MRI)
|
|
@item BASE @var{expression}
|
|
Use the value of @var{expression} as the lowest address (other than
|
|
absolute addresses) in the output file.
|
|
|
|
@cindex @code{CHIP} (MRI)
|
|
@item CHIP @var{expression}
|
|
@itemx CHIP @var{expression}, @var{expression}
|
|
This command does nothing; it is accepted only for compatibility.
|
|
|
|
@cindex @code{END} (MRI)
|
|
@item END
|
|
This command does nothing whatever; it's only accepted for compatibility.
|
|
|
|
@cindex @code{FORMAT} (MRI)
|
|
@item FORMAT @var{output-format}
|
|
Similar to the @code{OUTPUT_FORMAT} command in the more general linker
|
|
language, but restricted to S-records, if @var{output-format} is @samp{S}
|
|
|
|
@cindex @code{LIST} (MRI)
|
|
@item LIST @var{anything}@dots{}
|
|
Print (to the standard output file) a link map, as produced by the
|
|
@command{ld} command-line option @samp{-M}.
|
|
|
|
The keyword @code{LIST} may be followed by anything on the
|
|
same line, with no change in its effect.
|
|
|
|
@cindex @code{LOAD} (MRI)
|
|
@item LOAD @var{filename}
|
|
@itemx LOAD @var{filename}, @var{filename}, @dots{} @var{filename}
|
|
Include one or more object file @var{filename} in the link; this has the
|
|
same effect as specifying @var{filename} directly on the @command{ld}
|
|
command line.
|
|
|
|
@cindex @code{NAME} (MRI)
|
|
@item NAME @var{output-name}
|
|
@var{output-name} is the name for the program produced by @command{ld}; the
|
|
MRI-compatible command @code{NAME} is equivalent to the command-line
|
|
option @samp{-o} or the general script language command @code{OUTPUT}.
|
|
|
|
@cindex @code{ORDER} (MRI)
|
|
@item ORDER @var{secname}, @var{secname}, @dots{} @var{secname}
|
|
@itemx ORDER @var{secname} @var{secname} @var{secname}
|
|
Normally, @command{ld} orders the sections in its output file in the
|
|
order in which they first appear in the input files. In an MRI-compatible
|
|
script, you can override this ordering with the @code{ORDER} command. The
|
|
sections you list with @code{ORDER} will appear first in your output
|
|
file, in the order specified.
|
|
|
|
@cindex @code{PUBLIC} (MRI)
|
|
@item PUBLIC @var{name}=@var{expression}
|
|
@itemx PUBLIC @var{name},@var{expression}
|
|
@itemx PUBLIC @var{name} @var{expression}
|
|
Supply a value (@var{expression}) for external symbol
|
|
@var{name} used in the linker input files.
|
|
|
|
@cindex @code{SECT} (MRI)
|
|
@item SECT @var{secname}, @var{expression}
|
|
@itemx SECT @var{secname}=@var{expression}
|
|
@itemx SECT @var{secname} @var{expression}
|
|
You can use any of these three forms of the @code{SECT} command to
|
|
specify the start address (@var{expression}) for section @var{secname}.
|
|
If you have more than one @code{SECT} statement for the same
|
|
@var{secname}, only the @emph{first} sets the start address.
|
|
@end table
|
|
|
|
@node GNU Free Documentation License
|
|
@appendix GNU Free Documentation License
|
|
@include fdl.texi
|
|
|
|
@node LD Index
|
|
@unnumbered LD Index
|
|
|
|
@printindex cp
|
|
|
|
@tex
|
|
% I think something like @@colophon should be in texinfo. In the
|
|
% meantime:
|
|
\long\def\colophon{\hbox to0pt{}\vfill
|
|
\centerline{The body of this manual is set in}
|
|
\centerline{\fontname\tenrm,}
|
|
\centerline{with headings in {\bf\fontname\tenbf}}
|
|
\centerline{and examples in {\tt\fontname\tentt}.}
|
|
\centerline{{\it\fontname\tenit\/} and}
|
|
\centerline{{\sl\fontname\tensl\/}}
|
|
\centerline{are used for emphasis.}\vfill}
|
|
\page\colophon
|
|
% Blame: doc@@cygnus.com, 28mar91.
|
|
@end tex
|
|
|
|
@bye
|