4514 lines
169 KiB
Plaintext
4514 lines
169 KiB
Plaintext
\input texinfo
|
|
@setfilename ld.info
|
|
@syncodeindex ky cp
|
|
@include configdoc.texi
|
|
@c (configdoc.texi is generated by the Makefile)
|
|
@include ldver.texi
|
|
|
|
@c @smallbook
|
|
|
|
@ifinfo
|
|
@format
|
|
START-INFO-DIR-ENTRY
|
|
* Ld: (ld). The GNU linker.
|
|
END-INFO-DIR-ENTRY
|
|
@end format
|
|
@end ifinfo
|
|
|
|
@ifinfo
|
|
This file documents the @sc{gnu} linker LD version @value{VERSION}.
|
|
|
|
Copyright (C) 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000 Free Software Foundation, Inc.
|
|
|
|
Permission is granted to make and distribute verbatim copies of
|
|
this manual provided the copyright notice and this permission notice
|
|
are preserved on all copies.
|
|
|
|
Permission is granted to copy and distribute modified versions of this
|
|
manual under the conditions for verbatim copying, provided also that
|
|
the entire resulting derived work is distributed under the terms of a
|
|
permission notice identical to this one.
|
|
|
|
Permission is granted to copy and distribute translations of this manual
|
|
into another language, under the above conditions for modified versions.
|
|
|
|
@ignore
|
|
Permission is granted to process this file through Tex and print the
|
|
results, provided the printed document carries copying permission
|
|
notice identical to this one except for the removal of this paragraph
|
|
(this paragraph not being relevant to the printed manual).
|
|
|
|
@end ignore
|
|
@end ifinfo
|
|
@iftex
|
|
@finalout
|
|
@setchapternewpage odd
|
|
@settitle Using LD, the GNU linker
|
|
@titlepage
|
|
@title Using ld
|
|
@subtitle The GNU linker
|
|
@sp 1
|
|
@subtitle @code{ld} version 2
|
|
@subtitle Version @value{VERSION}
|
|
@author Steve Chamberlain
|
|
@author Ian Lance Taylor
|
|
@author Cygnus Solutions
|
|
@page
|
|
|
|
@tex
|
|
{\parskip=0pt
|
|
\hfill Cygnus Solutions\par
|
|
\hfill ian\@cygnus.com, doc\@cygnus.com\par
|
|
\hfill {\it Using LD, 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
|
|
Copyright @copyright{} 1991, 92, 93, 94, 95, 96, 97, 98, 1999 Free Software Foundation, Inc.
|
|
|
|
Permission is granted to make and distribute verbatim copies of
|
|
this manual provided the copyright notice and this permission notice
|
|
are preserved on all copies.
|
|
|
|
Permission is granted to copy and distribute modified versions of this
|
|
manual under the conditions for verbatim copying, provided also that
|
|
the entire resulting derived work is distributed under the terms of a
|
|
permission notice identical to this one.
|
|
|
|
Permission is granted to copy and distribute translations of this manual
|
|
into another language, under the above conditions for modified versions.
|
|
@end titlepage
|
|
@end iftex
|
|
@c FIXME: Talk about importance of *order* of args, cmds to linker!
|
|
|
|
@ifinfo
|
|
@node Top
|
|
@top Using ld
|
|
This file documents the @sc{gnu} linker ld version @value{VERSION}.
|
|
|
|
@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 Hitachi
|
|
* Hitachi:: ld and other Hitachi micros
|
|
@end ifset
|
|
@ifset I960
|
|
* i960:: ld and the Intel 960 family
|
|
@end ifset
|
|
@ifset TICOFF
|
|
* TI COFF:: ld and the TI COFF
|
|
@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
|
|
* Index:: Index
|
|
@end menu
|
|
@end ifinfo
|
|
|
|
@node Overview
|
|
@chapter Overview
|
|
|
|
@cindex @sc{gnu} linker
|
|
@cindex what is this?
|
|
@code{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 @code{ld}.
|
|
|
|
@code{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.
|
|
|
|
@ifclear SingleFormat
|
|
This version of @code{ld} uses the general purpose BFD libraries
|
|
to operate on object files. This allows @code{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,
|
|
@code{ld} continues executing, allowing you to identify other errors
|
|
(or, in some cases, to get an output file in spite of the error).
|
|
|
|
@node Invocation
|
|
@chapter Invocation
|
|
|
|
The @sc{gnu} linker @code{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.
|
|
|
|
@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
|
|
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 @code{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 @code{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 @code{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 can not 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. Note that
|
|
specifying a script in this way should only be used to augment the main
|
|
linker script; if you want to use some command that logically can only
|
|
appear once, such as the @code{SECTIONS} or @code{MEMORY} command, you
|
|
must replace the default linker script using the @samp{-T} option.
|
|
@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{--oformat} and
|
|
@samp{--oformat} are equivalent. 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{--oformat srec} and
|
|
@samp{--oformat=srec} 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
|
|
(eg @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,--startgroup foo.o bar.o -Wl,--endgroup
|
|
@end smallexample
|
|
|
|
This is important, because otherwise the compiler driver program may
|
|
silently drop the linker options, resulting in a bad link.
|
|
|
|
Here is a table of the generic command line switches accepted by the GNU
|
|
linker:
|
|
|
|
@table @code
|
|
@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.
|
|
|
|
@ifset I960
|
|
@cindex architectures
|
|
@kindex -A@var{arch}
|
|
@item -A@var{architecture}
|
|
@kindex --architecture=@var{arch}
|
|
@itemx --architecture=@var{architecture}
|
|
In the current release of @code{ld}, this option is useful only for the
|
|
Intel 960 family of architectures. In that @code{ld} configuration, the
|
|
@var{architecture} argument identifies the particular architecture in
|
|
the 960 family, enabling some safeguards and modifying the
|
|
archive-library search path. @xref{i960,,@code{ld} and the Intel 960
|
|
family}, for details.
|
|
|
|
Future releases of @code{ld} may support similar functionality for
|
|
other architecture families.
|
|
@end ifset
|
|
|
|
@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}
|
|
@code{ld} may be configured to support more than one kind of object
|
|
file. If your @code{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 @code{ld} is
|
|
configured to support alternative object formats, you don't usually need
|
|
to specify this, as @code{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}; see @ref{Format Commands}.
|
|
@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, @code{ld} accepts script
|
|
files written in an alternate, restricted command language, described in
|
|
@ref{MRI,,MRI Compatible Script Files}. Introduce MRI script files with
|
|
the option @samp{-c}; use the @samp{-T} option to run linker
|
|
scripts written in the general-purpose @code{ld} scripting language.
|
|
If @var{MRI-cmdfile} does not exist, @code{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}.
|
|
|
|
@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.
|
|
|
|
@cindex dynamic symbol table
|
|
@kindex -E
|
|
@kindex --export-dynamic
|
|
@item -E
|
|
@itemx --export-dynamic
|
|
When creating a dynamically linked executable, 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 this option, 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.
|
|
|
|
@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.
|
|
|
|
@kindex -f
|
|
@kindex --auxiliary
|
|
@item -f
|
|
@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
|
|
@kindex --filter
|
|
@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 @code{-F} option throughout a compilation
|
|
toolchain for specifying object-file format for both input and output
|
|
object files. The @sc{gnu} linker uses other mechanisms for this
|
|
purpose: the @code{-b}, @code{--format}, @code{--oformat} options, the
|
|
@code{TARGET} command in linker scripts, and the @code{GNUTARGET}
|
|
environment variable. The @sc{gnu} linker will ignore the @code{-F}
|
|
option when not creating an ELF shared object.
|
|
|
|
@cindex finalization function
|
|
@kindex -fini
|
|
@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
|
|
@kindex --gpsize
|
|
@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 ECOFF which supports 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
|
|
@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{archive}
|
|
@kindex --library=@var{archive}
|
|
@item -l@var{archive}
|
|
@itemx --library=@var{archive}
|
|
Add archive file @var{archive} to the list of files to link. This
|
|
option may be used any number of times. @code{ld} will search its
|
|
path-list for occurrences of @code{lib@var{archive}.a} for every
|
|
@var{archive} specified.
|
|
|
|
On systems which support shared libraries, @code{ld} may also search for
|
|
libraries with extensions other than @code{.a}. Specifically, on ELF
|
|
and SunOS systems, @code{ld} will search a directory for a library with
|
|
an extension of @code{.so} before searching for one with an extension of
|
|
@code{.a}. By convention, a @code{.so} extension indicates a shared
|
|
library.
|
|
|
|
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 @code{-(} 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 @code{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 @code{ld} will search
|
|
for archive libraries and @code{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
|
|
@code{-L} options apply to all @code{-l} options, regardless of the
|
|
order in which the options appear.
|
|
|
|
@ifset UsesEnvVars
|
|
The default set of paths searched (without being specified with
|
|
@samp{-L}) depends on which emulation mode @code{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 and symbols 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.
|
|
@end itemize
|
|
|
|
@kindex -n
|
|
@cindex read-only text
|
|
@cindex NMAGIC
|
|
@kindex --nmagic
|
|
@item -n
|
|
@itemx --nmagic
|
|
Turn off page alignment of sections, and mark the output as
|
|
@code{NMAGIC} if possible.
|
|
|
|
@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. If the output format supports Unix
|
|
style magic numbers, mark the output as @code{OMAGIC}.
|
|
|
|
@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 @code{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 -O @var{level}
|
|
@cindex generating optimized output
|
|
@item -O @var{level}
|
|
If @var{level} is a numeric values greater than zero @code{ld} optimizes
|
|
the output. This might take significantly longer and therefore probably
|
|
should only be enabled for the final binary.
|
|
|
|
@kindex -q
|
|
@kindex --emit-relocs
|
|
@cindex retain relocations in final executable
|
|
@item -q
|
|
@itemx --emit-relocs
|
|
Leave relocation sections and contents in fully linked exececutables.
|
|
Post link analysis and optimization tools may need this information in
|
|
order to perform correct modifications of executables. This results
|
|
in larger executables.
|
|
|
|
@cindex partial link
|
|
@cindex relocatable output
|
|
@kindex -r
|
|
@kindex --relocateable
|
|
@item -r
|
|
@itemx --relocateable
|
|
Generate relocatable output---i.e., generate an output file that can in
|
|
turn serve as input to @code{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 @code{-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}.
|
|
|
|
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 @code{-R} option is
|
|
followed by a directory name, rather than a file name, it is treated as
|
|
the @code{-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 -t
|
|
@kindex --trace
|
|
@cindex input files, displaying
|
|
@item -t
|
|
@itemx --trace
|
|
Print the names of the input files as @code{ld} processes them.
|
|
|
|
@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
|
|
@code{ld}'s default linker script (rather than adding to it), so
|
|
@var{commandfile} must specify everything necessary to describe the
|
|
output file. You must use this option if you want to use a command
|
|
which can only appear once in a linker script, such as the
|
|
@code{SECTIONS} or @code{MEMORY} command. @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 -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.
|
|
|
|
@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 @code{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 --unique
|
|
@item --unique
|
|
Creates a separate output section for every orphan input section. This
|
|
option prevents the normal merging of orphan input sections with the same
|
|
name. An orphan section is one not specifically mentioned in a linker
|
|
script, so this option along with a custom linker script allows any
|
|
selection of input sections to be merged while others are kept separate.
|
|
|
|
@kindex -v
|
|
@kindex -V
|
|
@kindex --version
|
|
@cindex version
|
|
@item -v
|
|
@itemx --version
|
|
@itemx -V
|
|
Display the version number for @code{ld}. The @code{-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
|
|
@cindex L, deleting symbols beginning
|
|
@item -X
|
|
@itemx --discard-locals
|
|
Delete all temporary local symbols. For most targets, this is all local
|
|
symbols whose names begin with @samp{L}.
|
|
|
|
@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 @code{initfirst}, @code{interpose},
|
|
@code{loadfltr}, @code{nodefaultlib}, @code{nodelete}, @code{nodlopen},
|
|
@code{nodump}, @code{now} and @code{origin}. The other keywords are
|
|
ignored for Solaris compatibility. @code{initfirst} marks the object
|
|
to be initialized first at runtime before any other objects.
|
|
@code{interpose} marks the object that its symbol table interposes
|
|
before all symbols but the primary executable. @code{loadfltr} marks
|
|
the object that its filtees be processed immediately at runtime.
|
|
@code{nodefaultlib} marks the object that the search for dependencies
|
|
of this object will ignore any default library search paths.
|
|
@code{nodelete} marks the object shouldn't be unloaded at runtime.
|
|
@code{nodlopen} marks the object not available to @code{dlopen}.
|
|
@code{nodump} marks the object can not be dumped by @code{dldump}.
|
|
@code{now} marks the object with the non-lazy runtime binding.
|
|
@code{origin} marks the object may contain $ORIGIN.
|
|
|
|
@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 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 -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
|
|
@code{-l} options which follow it.
|
|
|
|
@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 @code{-l} options which follow it.
|
|
|
|
@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 --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 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 @samp{--check-sections}.
|
|
|
|
@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. The remaining files contain references to the symbol.
|
|
|
|
@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,,
|
|
Assignment: Symbol Definitions}). @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 --dynamic-linker @var{file}
|
|
@item --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.
|
|
|
|
@cindex MIPS embedded PIC code
|
|
@kindex --embedded-relocs
|
|
@item --embedded-relocs
|
|
This option is only meaningful when linking MIPS embedded PIC code,
|
|
generated by the -membedded-pic option to the @sc{gnu} compiler and
|
|
assembler. It causes the linker to create a table which may be used at
|
|
runtime to relocate any data which was statically initialized to pointer
|
|
values. See the code in testsuite/ld-empic for details.
|
|
|
|
@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 --no-gc-sections
|
|
@itemx --gc-sections
|
|
Enable garbage collection of unused input sections. It is ignored on
|
|
targets that do not support this option. This option is not compatible
|
|
with @samp{-r}, nor should it be used with dynamic linking. The default
|
|
behaviour (of not performing this garbage collection) can be restored by
|
|
specifying @samp{--no-gc-sections} on the command line.
|
|
|
|
@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
|
|
@item -Map @var{mapfile}
|
|
Print a link map to the file @var{mapfile}. See the description of the
|
|
@samp{-M} option, above.
|
|
|
|
@cindex memory usage
|
|
@kindex --no-keep-memory
|
|
@item --no-keep-memory
|
|
@code{ld} normally optimizes for speed over memory usage by caching the
|
|
symbol tables of input files in memory. This option tells @code{ld} to
|
|
instead optimize for memory usage, by rereading the symbol tables as
|
|
necessary. This may be required if @code{ld} runs out of memory space
|
|
while linking a large executable.
|
|
|
|
@kindex --no-undefined
|
|
@item --no-undefined
|
|
Normally when creating a non-symbolic shared library, undefined symbols
|
|
are allowed and left to be resolved by the runtime loader. This option
|
|
disallows such undefined symbols.
|
|
|
|
@kindex --no-warn-mismatch
|
|
@item --no-warn-mismatch
|
|
Normally @code{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 @code{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-whole-archive
|
|
@item --no-whole-archive
|
|
Turn off the effect of the @code{--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.
|
|
|
|
@ifclear SingleFormat
|
|
@kindex --oformat
|
|
@item --oformat @var{output-format}
|
|
@code{ld} may be configured to support more than one kind of object
|
|
file. If your @code{ld} is configured this way, you can use the
|
|
@samp{--oformat} option to specify the binary format for the output
|
|
object file. Even when @code{ld} is configured to support alternative
|
|
object formats, you don't usually need to specify this, as @code{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 -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
|
|
@item --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,,@code{ld} and the H8/300}.
|
|
@end ifset
|
|
@ifset I960
|
|
@xref{i960,, @code{ld} and the Intel 960 family}.
|
|
@end ifset
|
|
|
|
|
|
On some platforms, the @samp{--relax} option performs global
|
|
optimizations that become possible when the linker resolves addressing
|
|
in the program, such as relaxing address modes and synthesizing new
|
|
instructions in the output object file.
|
|
|
|
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
|
|
|
|
@cindex retaining specified symbols
|
|
@cindex stripping all but some symbols
|
|
@cindex symbols, retaining selectively
|
|
@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
|
|
Add a directory to the runtime library search path. This is used when
|
|
linking an ELF executable with shared objects. All @code{-rpath}
|
|
arguments are concatenated and passed to the runtime linker, which uses
|
|
them to locate shared objects at runtime. The @code{-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
|
|
@code{-rpath-link} option. If @code{-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 @code{-rpath} option may also be used on SunOS. By default, on
|
|
SunOS, the linker will form a runtime search patch out of all the
|
|
@code{-L} options it is given. If a @code{-rpath} option is used, the
|
|
runtime search path will be formed exclusively using the @code{-rpath}
|
|
options, ignoring the @code{-L} options. This can be useful when using
|
|
gcc, which adds many @code{-L} options which may be on NFS mounted
|
|
filesystems.
|
|
|
|
For compatibility with other ELF linkers, if the @code{-R} option is
|
|
followed by a directory name, rather than a file name, it is treated as
|
|
the @code{-rpath} option.
|
|
@end ifset
|
|
|
|
@ifset GENERIC
|
|
@cindex link-time runtime library search path
|
|
@kindex -rpath-link
|
|
@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 @code{-rpath-link} option
|
|
specifies the first set of directories to search. The
|
|
@code{-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.
|
|
|
|
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 @code{-rpath-link} options.
|
|
@item
|
|
Any directories specified by @code{-rpath} options. The difference
|
|
between @code{-rpath} and @code{-rpath-link} is that directories
|
|
specified by @code{-rpath} options are included in the executable and
|
|
used at runtime, whereas the @code{-rpath-link} option is only effective
|
|
at link time. It is for the native linker only.
|
|
@item
|
|
On an ELF system, if the @code{-rpath} and @code{rpath-link} options
|
|
were not used, search the contents of the environment variable
|
|
@code{LD_RUN_PATH}. It is for the native linker only.
|
|
@item
|
|
On SunOS, if the @code{-rpath} option was not used, search any
|
|
directories specified using @code{-L} options.
|
|
@item
|
|
For a native linker, 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 native linker on an ELF system, if the file @file{/etc/ld.so.conf}
|
|
exists, the list of directories found in that file.
|
|
@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 @code{-e} option is not used and there are
|
|
undefined symbols in the link.
|
|
|
|
@item --sort-common
|
|
@kindex --sort-common
|
|
This option tells @code{ld} to sort the common symbols by size when it
|
|
places them in the appropriate output sections. First come all the one
|
|
byte symbols, then all the two bytes, then all the four bytes, and then
|
|
everything else. This is to prevent gaps between symbols due to
|
|
alignment constraints.
|
|
|
|
@kindex --split-by-file
|
|
@item --split-by-file [@var{size}]
|
|
Similar to @code{--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 --traditional-format
|
|
@cindex traditional format
|
|
@item --traditional-format
|
|
For some targets, the output of @code{ld} is different in some ways from
|
|
the output of some existing linker. This switch requests @code{ld} to
|
|
use the traditional format instead.
|
|
|
|
@cindex dbx
|
|
For example, on SunOS, @code{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 @code{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}
|
|
Use @var{org} as the starting address for---respectively---the
|
|
@code{bss}, @code{data}, or the @code{text} segment of the output file.
|
|
@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.
|
|
|
|
@kindex --verbose
|
|
@cindex verbose
|
|
@item --dll-verbose
|
|
@itemx --verbose
|
|
Display the version number for @code{ld} and list the linker emulations
|
|
supported. Display which input files can and cannot be opened. Display
|
|
the linker script if using a default builtin script.
|
|
|
|
@kindex --version-script=@var{version-scriptfile}
|
|
@cindex version script, symbol versions
|
|
@itemx --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 heirarchy for the library being created. This option
|
|
is only meaningful on ELF platforms which support shared libraries.
|
|
@xref{VERSION}.
|
|
|
|
@kindex --warn-comon
|
|
@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 --whole-archive
|
|
@cindex including an entire archive
|
|
@item --whole-archive
|
|
For each archive mentioned on the command line after the
|
|
@code{--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.
|
|
|
|
@kindex --wrap
|
|
@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 (int c)
|
|
@{
|
|
printf ("malloc called with %ld\n", c);
|
|
return __real_malloc (c);
|
|
@}
|
|
@end smallexample
|
|
|
|
If you link other code with this file using @code{--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 @code{--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}.
|
|
|
|
@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
|
|
@code{--enable-new-dtags}, the dynamic tags will be created as needed.
|
|
If you specify @code{--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.
|
|
|
|
@end table
|
|
|
|
@subsection Options specific to i386 PE targets
|
|
|
|
The i386 PE linker supports the @code{-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 @code
|
|
|
|
@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.
|
|
|
|
@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}.
|
|
|
|
@kindex --dll
|
|
@item --dll
|
|
Create a DLL instead of a regular executable. You may also use
|
|
@code{-shared} or specify a @code{LIBRARY} in a given @code{.def}
|
|
file.
|
|
|
|
@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 @code{--enable-stdcall-fixup}, this
|
|
feature is fully enabled and warnings are not printed. If you specify
|
|
@code{--disable-stdcall-fixup}, this feature is disabled and such
|
|
mismatches are considered to be errors.
|
|
|
|
@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}, and @code{impure_ptr} will not be automatically
|
|
exported.
|
|
|
|
@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.
|
|
|
|
@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.
|
|
|
|
@cindex heap size
|
|
@kindex --heap
|
|
@item --heap @var{reserve}
|
|
@itemx --heap @var{reserve},@var{commit}
|
|
Specify the amount of memory to reserve (and optionally commit) to be
|
|
used as heap for this program. The default is 1Mb reserved, 4K
|
|
committed.
|
|
|
|
@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.
|
|
|
|
@kindex --kill-at
|
|
@item --kill-at
|
|
If given, the stdcall suffixes (@@@var{nn}) will be stripped from
|
|
symbols before they are exported.
|
|
|
|
@kindex --major-image-version
|
|
@item --major-image-version @var{value}
|
|
Sets the major number of the "image version". Defaults to 1.
|
|
|
|
@kindex --major-os-version
|
|
@item --major-os-version @var{value}
|
|
Sets the major number of the "os version". Defaults to 4.
|
|
|
|
@kindex --major-subsystem-version
|
|
@item --major-subsystem-version @var{value}
|
|
Sets the major number of the "subsystem version". Defaults to 4.
|
|
|
|
@kindex --minor-image-version
|
|
@item --minor-image-version @var{value}
|
|
Sets the minor number of the "image version". Defaults to 0.
|
|
|
|
@kindex --minor-os-version
|
|
@item --minor-os-version @var{value}
|
|
Sets the minor number of the "os version". Defaults to 0.
|
|
|
|
@kindex --minor-subsystem-version
|
|
@item --minor-subsystem-version @var{value}
|
|
Sets the minor number of the "subsystem version". Defaults to 0.
|
|
|
|
@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.
|
|
|
|
@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.
|
|
|
|
@cindex stack size
|
|
@kindex --stack
|
|
@item --stack @var{reserve}
|
|
@itemx --stack @var{reserve},@var{commit}
|
|
Specify the amount of memory to reserve (and optionally commit) to be
|
|
used as stack for this program. The default is 32Mb reserved, 4K
|
|
committed.
|
|
|
|
@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}, and @code{posix}. You may optionally set the
|
|
subsystem version also.
|
|
|
|
@end table
|
|
|
|
@ifset UsesEnvVars
|
|
@node Environment
|
|
@section Environment Variables
|
|
|
|
You can change the behavior of @code{ld} with the environment variables
|
|
@code{GNUTARGET}, @code{LDEMULATION}, and @code{COLLECT_NO_DEMANGLE}.
|
|
|
|
@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, @code{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.
|
|
|
|
@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.
|
|
@end ifset
|
|
|
|
@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.
|
|
|
|
@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 mean 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
|
|
|
|
* 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 the symbol @code{start}, if defined;
|
|
@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 @code{-L} option. You can nest calls to @code{INCLUDE} up to
|
|
10 levels deep.
|
|
|
|
@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.
|
|
|
|
The linker will first try to open the file in the current directory. If
|
|
it is not found, the linker will search through the archive library
|
|
search path. See the description of @samp{-L} in @ref{Options,,Command
|
|
Line Options}.
|
|
|
|
If you use @samp{INPUT (-l@var{file})}, @code{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 OUTPUT(@var{filename})
|
|
@kindex OUTPUT(@var{filename})
|
|
@cindex output file name in linker scripot
|
|
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
|
|
@code{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 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}.
|
|
|
|
@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 @code{ld} assign space to common symbols even if a relocatable
|
|
output file is specified (@samp{-r}).
|
|
|
|
@item NOCROSSREFS(@var{section} @var{section} @dots{})
|
|
@kindex NOCROSSREFS(@var{sections})
|
|
@cindex cross references
|
|
This command may be used to tell @code{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
|
|
@code{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.
|
|
|
|
@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
|
|
@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 as a global symbol.
|
|
|
|
@menu
|
|
* Simple Assignments:: Simple Assignments
|
|
* PROVIDE:: PROVIDE
|
|
@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.
|
|
|
|
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) & ~ 4;
|
|
.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 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.
|
|
|
|
@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})]
|
|
@{
|
|
@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 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. If you do not provide @var{address},
|
|
the linker will set it based on @var{region} if present, or otherwise
|
|
based on the current value of the location counter.
|
|
|
|
If you provide @var{address}, the address of the output section will be
|
|
set to precisely that. If you provide neither @var{address} nor
|
|
@var{region}, then the address of the output section will be set to the
|
|
current value of the location counter aligned to the alignment
|
|
requirements of the output section. The alignment requirement of the
|
|
output section is the strictest alignment of any input section contained
|
|
within the output section.
|
|
|
|
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 a @samp{.text} input
|
|
section.
|
|
|
|
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.
|
|
|
|
@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
|
|
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
|
|
will cause all .ctors sections from all files except @file{crtend.o} and
|
|
@file{otherfile.o} to be included.
|
|
|
|
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. In the second example, all
|
|
@samp{.text} input sections will appear first, followed by all
|
|
@samp{.rdata} input sections.
|
|
|
|
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
|
|
|
|
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 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
|
|
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} keyword, which appears before a wildcard
|
|
pattern in parentheses (e.g., @code{SORT(.text*)}). When the
|
|
@code{SORT} keyword is used, the linker will sort the files or sections
|
|
into ascending order by name before placing them in the output file.
|
|
|
|
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(*)(.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)
|
|
@}
|
|
outputb :
|
|
@{
|
|
foo.o (.input2)
|
|
foo1.o (.input1)
|
|
@}
|
|
outputc :
|
|
@{
|
|
*(.input1)
|
|
*(.input2)
|
|
@}
|
|
@}
|
|
@end group
|
|
@end smallexample
|
|
|
|
@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 two least significant bytes 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{0x9090}:
|
|
@smallexample
|
|
FILL(0x9090)
|
|
@end smallexample
|
|
|
|
The @code{FILL} command is similar to the @samp{=@var{fillexp}} output
|
|
section attribute (@pxref{Output Section Fill}), 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.
|
|
|
|
@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{__DTOR_LIST}} marks the end. 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(CONSTRUCTORS)} instead. When using the
|
|
@code{.ctors} and @code{.dtors} sections, use @samp{*(SORT(.ctors))} and
|
|
@samp{*(SORT(.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 create output section which do not have any
|
|
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.
|
|
|
|
If you use anything other than an input section description as an output
|
|
section command, such as a symbol assignment, then the output section
|
|
will always be created, even if there are no matching input sections.
|
|
|
|
@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.
|
|
|
|
@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})]
|
|
@{
|
|
@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
|
|
* 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. The contents of the
|
|
@samp{ROM} section will appear in the linker output file as usual.
|
|
@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 address expression which may appear in
|
|
an output section description sets the VMA (@pxref{Output Section
|
|
Address}).
|
|
|
|
The linker will normally set the LMA equal to the VMA. You can change
|
|
that by using the @code{AT} keyword. The expression @var{lma} that
|
|
follows the @code{AT} keyword specifies the load address of the
|
|
section. Alternatively, with @samp{AT>@var{lma_region}} expression,
|
|
you may specify a memory region for the section's load address. @xref{MEMORY}.
|
|
|
|
@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 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 two least
|
|
significant bytes of the value, repeated as necessary.
|
|
|
|
You can also change the fill value with a @code{FILL} command in the
|
|
output section commands; see @ref{Output Section Data}.
|
|
|
|
Here is a simple example:
|
|
@smallexample
|
|
@group
|
|
SECTIONS @{ .text : @{ *(.text) @} =0x9090 @}
|
|
@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} contruct (@pxref{SECTIONS}),
|
|
except that no addresses and no memory regions may be defined for
|
|
sections within an @code{OVERLAY}.
|
|
|
|
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 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
|
|
defines 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: @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) @}
|
|
__load_start_text0 = LOADADDR (.text0);
|
|
__load_stop_text0 = LOADADDR (.text0) + SIZEOF (.text0);
|
|
.text1 0x1000 : AT (0x4000 + SIZEOF (.text0)) @{ o2/*.o(.text) @}
|
|
__load_start_text1 = LOADADDR (.text1);
|
|
__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 at most one use of the @code{MEMORY}
|
|
command. However, you can define as many blocks of memory within it as
|
|
you wish. The syntax 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.
|
|
|
|
@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 preceding attributes
|
|
@end table
|
|
|
|
If a unmapped section matches any of the listed attributes other than
|
|
@samp{!}, it will be placed in the memory region. The @samp{!}
|
|
attribute reverses this test, so that an unmapped section will be placed
|
|
in the memory region only if it does not match any of the listed
|
|
attributes.
|
|
|
|
@kindex ORIGIN =
|
|
@kindex o =
|
|
@kindex org =
|
|
The @var{origin} is an expression for the start address of the memory
|
|
region. The expression must evaluate to a constant before memory
|
|
allocation is performed, which means that you may not use any section
|
|
relative 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
|
|
evaluate to a constant before memory allocation is performed. 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.
|
|
|
|
@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.
|
|
|
|
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 appear 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.
|
|
|
|
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 @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;
|
|
@} 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.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
@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
|
|
* Symbols:: Symbol Names
|
|
* 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. The linker considers other integers 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
|
|
@ifinfo
|
|
@c END TEXI2ROFF-KILL
|
|
@code{1024} or @code{1024*1024}
|
|
@c TEXI2ROFF-KILL
|
|
@end ifinfo
|
|
@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;
|
|
@end smallexample
|
|
|
|
@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 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 never be moved backwards.
|
|
|
|
@smallexample
|
|
SECTIONS
|
|
@{
|
|
output :
|
|
@{
|
|
file1(.text)
|
|
. = . + 1000;
|
|
file2(.text)
|
|
. += 1000;
|
|
file3(.text)
|
|
@} = 0x1234;
|
|
@}
|
|
@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{= 0x1234}
|
|
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, whoes 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.
|
|
|
|
@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
|
|
@ifinfo
|
|
@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 ifinfo
|
|
@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
|
|
When the linker evaluates an expression, the result is either absolute
|
|
or relative to some section. A relative expression is expressed as a
|
|
fixed offset from the base of a section.
|
|
|
|
The position of the expression within the linker script determines
|
|
whether it is absolute or relative. An expression which appears within
|
|
an output section definition is relative to the base of the output
|
|
section. An expression which appears elsewhere will be absolute.
|
|
|
|
A symbol set to a relative expression will be relocatable if you request
|
|
relocatable output using the @samp{-r} option. That means that a
|
|
further link operation may change the value of the symbol. The symbol's
|
|
section will be the section of the relative expression.
|
|
|
|
A symbol set to an absolute expression will retain the same value
|
|
through any further link operation. The symbol will be absolute, and
|
|
will not have any particular associated section.
|
|
|
|
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.
|
|
|
|
@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 absolute address (the VMA) of the named @var{section}. Your
|
|
script must previously have defined the location of that section. In
|
|
the following example, @code{symbol_1} and @code{symbol_2} are assigned
|
|
identical values:
|
|
@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{exp})
|
|
@kindex ALIGN(@var{exp})
|
|
@cindex round up location counter
|
|
@cindex align location counter
|
|
Return the location counter (@code{.}) aligned to the next @var{exp}
|
|
boundary. @var{exp} must be an expression whose value is a power of
|
|
two. This is equivalent to
|
|
@smallexample
|
|
(. + @var{exp} - 1) & ~(@var{exp} - 1)
|
|
@end smallexample
|
|
|
|
@code{ALIGN} doesn't change the value of the location counter---it just
|
|
does arithmetic on it. 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 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 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, 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 LOADADDR(@var{section})
|
|
@kindex LOADADDR(@var{section})
|
|
@cindex section load address in expression
|
|
Return the absolute LMA of the named @var{section}. This is normally
|
|
the same as @code{ADDR}, but it may be different if the @code{AT}
|
|
attribute is used in the output section definition (@pxref{Output
|
|
Section LMA}).
|
|
|
|
@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 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
|
|
@code{ld} has additional features on some platforms; the following
|
|
sections describe them. Machines where @code{ld} has no additional
|
|
functionality are not listed.
|
|
|
|
@menu
|
|
* H8/300:: @code{ld} and the H8/300
|
|
* i960:: @code{ld} and the Intel 960 family
|
|
* ARM:: @code{ld} and the ARM family
|
|
* HPPA ELF32:: @code{ld} and HPPA 32-bit ELF
|
|
@ifset TICOFF
|
|
* TI COFF:: @code{ld} and TI COFF
|
|
@end ifset
|
|
@end menu
|
|
@end ifset
|
|
|
|
@c FIXME! This could use @raisesections/@lowersections, but there seems to be a conflict
|
|
@c between those and node-defaulting.
|
|
@ifset H8300
|
|
@ifclear GENERIC
|
|
@raisesections
|
|
@end ifclear
|
|
|
|
@node H8/300
|
|
@section @code{ld} and the H8/300
|
|
|
|
@cindex H8/300 support
|
|
For the H8/300, @code{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
|
|
@code{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?
|
|
@code{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).
|
|
@end table
|
|
|
|
@ifclear GENERIC
|
|
@lowersections
|
|
@end ifclear
|
|
@end ifset
|
|
|
|
@ifclear GENERIC
|
|
@ifset Hitachi
|
|
@c This stuff is pointless to say unless you're especially concerned
|
|
@c with Hitachi chips; don't enable it for generic case, please.
|
|
@node Hitachi
|
|
@chapter @code{ld} and other Hitachi chips
|
|
|
|
@code{ld} also supports the H8/300H, the H8/500, and the Hitachi SH. No
|
|
special features, commands, or command-line options are required for
|
|
these chips.
|
|
@end ifset
|
|
@end ifclear
|
|
|
|
@ifset I960
|
|
@ifclear GENERIC
|
|
@raisesections
|
|
@end ifclear
|
|
|
|
@node i960
|
|
@section @code{ld} and the Intel 960 family
|
|
|
|
@cindex i960 support
|
|
|
|
You can use the @samp{-A@var{architecture}} command line option to
|
|
specify one of the two-letter names identifying members of the 960
|
|
family; the option specifies the desired output target, and warns of any
|
|
incompatible instructions in the input files. It also modifies the
|
|
linker's search strategy for archive libraries, to support the use of
|
|
libraries specific to each particular architecture, by including in the
|
|
search loop names suffixed with the string identifying the architecture.
|
|
|
|
For example, if your @code{ld} command line included @w{@samp{-ACA}} as
|
|
well as @w{@samp{-ltry}}, the linker would look (in its built-in search
|
|
paths, and in any paths you specify with @samp{-L}) for a library with
|
|
the names
|
|
|
|
@smallexample
|
|
@group
|
|
try
|
|
libtry.a
|
|
tryca
|
|
libtryca.a
|
|
@end group
|
|
@end smallexample
|
|
|
|
@noindent
|
|
The first two possibilities would be considered in any event; the last
|
|
two are due to the use of @w{@samp{-ACA}}.
|
|
|
|
You can meaningfully use @samp{-A} more than once on a command line, since
|
|
the 960 architecture family allows combination of target architectures; each
|
|
use will add another pair of name variants to search for when @w{@samp{-l}}
|
|
specifies a library.
|
|
|
|
@cindex @code{--relax} on i960
|
|
@cindex relaxing on i960
|
|
@code{ld} supports the @samp{--relax} option for the i960 family. If
|
|
you specify @samp{--relax}, @code{ld} finds all @code{balx} and
|
|
@code{calx} instructions whose targets are within 24 bits, and turns
|
|
them into 24-bit program-counter relative @code{bal} and @code{cal}
|
|
instructions, respectively. @code{ld} also turns @code{cal}
|
|
instructions into @code{bal} instructions when it determines that the
|
|
target subroutine is a leaf routine (that is, the target subroutine does
|
|
not itself call any subroutines).
|
|
|
|
@ifclear GENERIC
|
|
@lowersections
|
|
@end ifclear
|
|
@end ifset
|
|
|
|
@ifclear GENERIC
|
|
@raisesections
|
|
@end ifclear
|
|
|
|
@node ARM
|
|
@section @code{ld}'s support for interworking between ARM and Thumb code
|
|
|
|
@cindex ARM interworking support
|
|
@kindex --support-old-code
|
|
For the ARM, @code{ld} will generate code stubs to allow functions calls
|
|
betweem ARM and Thumb code. These stubs only work with code that has
|
|
been compiled and assembled with the @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.
|
|
|
|
@node HPPA ELF32
|
|
@section @code{ld} and HPPA 32-bit ELF support
|
|
@cindex HPPA multiple sub-space stubs
|
|
@kindex --multi-subspace
|
|
When generating a shared library, @code{ld} will by default generate
|
|
import stubs suitable for use with a single sub-space application.
|
|
The @samp{--multi-subspace} switch causes @code{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 @code{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
|
|
@code{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.
|
|
|
|
@ifset TICOFF
|
|
@node TI COFF
|
|
@section @code{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; @code{ld} will read any version or byte order, but the output
|
|
header format depends on the default specified by the specific target.
|
|
@end ifset
|
|
|
|
@ifclear GENERIC
|
|
@lowersections
|
|
@end ifclear
|
|
|
|
@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 @code{ld}
|
|
@cindex reporting bugs in @code{ld}
|
|
|
|
Your bug reports play an essential role in making @code{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 @code{ld}
|
|
work better. Bug reports are your contribution to the maintenance of
|
|
@code{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
|
|
@code{ld} bug. Reliable linkers never crash.
|
|
|
|
@cindex error on valid input
|
|
@item
|
|
If @code{ld} produces an error message for valid input, that is a bug.
|
|
|
|
@cindex invalid input
|
|
@item
|
|
If @code{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 @code{ld} are welcome in any case.
|
|
@end itemize
|
|
|
|
@node Bug Reporting
|
|
@section How to report bugs
|
|
@cindex bug reports
|
|
@cindex @code{ld} bugs, reporting
|
|
|
|
A number of companies and individuals offer support for @sc{gnu}
|
|
products. If you obtained @code{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.
|
|
|
|
Otherwise, send bug reports for @code{ld} to
|
|
@samp{bug-gnu-utils@@gnu.org}.
|
|
|
|
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?'' Those bug reports are useless, and we urge everyone to
|
|
@emph{refuse to respond to them} except to chide the sender to report
|
|
bugs properly.
|
|
|
|
To enable us to fix the bug, you should include all these things:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
The version of @code{ld}. @code{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 @code{ld}.
|
|
|
|
@item
|
|
Any patches you may have applied to the @code{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 @code{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,
|
|
uuencoded if necessary to get them through the mail system. Making them
|
|
available for anonymous FTP is not as good, but may be the only
|
|
reasonable choice for large object files.
|
|
|
|
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 @code{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 @code{ld} is out of synch, 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 @code{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 @code{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 @code{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} @code{ld} from the MRI
|
|
linker, @code{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
|
|
@code{ld}. @sc{gnu} @code{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, @code{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, @code{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 one of these output formats:
|
|
|
|
@enumerate
|
|
@item
|
|
S-records, if @var{output-format} is @samp{S}
|
|
|
|
@item
|
|
IEEE, if @var{output-format} is @samp{IEEE}
|
|
|
|
@item
|
|
COFF (the @samp{coff-m68k} variant in BFD), if @var{output-format} is
|
|
@samp{COFF}
|
|
@end enumerate
|
|
|
|
@cindex @code{LIST} (MRI)
|
|
@item LIST @var{anything}@dots{}
|
|
Print (to the standard output file) a link map, as produced by the
|
|
@code{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 @code{ld}
|
|
command line.
|
|
|
|
@cindex @code{NAME} (MRI)
|
|
@item NAME @var{output-name}
|
|
@var{output-name} is the name for the program produced by @code{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, @code{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 Index
|
|
@unnumbered 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
|
|
|
|
|
|
@contents
|
|
@bye
|
|
|
|
|