\input texinfo
@setfilename ld.info
@c Copyright 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000,
-@c 2001, 2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
+@c 2001, 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
@syncodeindex ky cp
@c man begin INCLUDE
@include configdoc.texi
@c (configdoc.texi is generated by the Makefile)
-@include ldver.texi
+@include bfdver.texi
@c man end
@c @smallbook
@c Configure for the generation of man pages
@set UsesEnvVars
@set GENERIC
-@set ARC
@set ARM
-@set D10V
-@set D30V
-@set H8/300
-@set H8/500
+@set H8300
@set HPPA
-@set I370
-@set I80386
-@set I860
@set I960
-@set M32R
@set M68HC11
-@set M680X0
-@set MCORE
-@set MIPS
@set MMIX
@set MSP430
-@set PDP11
-@set PJ
@set POWERPC
@set POWERPC64
-@set SH
-@set SPARC
-@set TIC54X
-@set V850
-@set VAX
+@set Renesas
+@set SPU
+@set TICOFF
@set WIN32
@set XTENSA
@end ifset
@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,
-2001, 2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
+@copying
+This file documents the @sc{gnu} linker LD
+@ifset VERSION_PACKAGE
+@value{VERSION_PACKAGE}
+@end ifset
+version @value{VERSION}.
-@ignore
+Copyright @copyright{} 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000,
+2001, 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1
with no Invariant Sections, with no Front-Cover Texts, and with no
Back-Cover Texts. A copy of the license is included in the
section entitled ``GNU Free Documentation License''.
-
-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
+@end copying
@iftex
@finalout
@setchapternewpage odd
@titlepage
@title The GNU linker
@sp 1
-@subtitle @code{ld} version 2
+@subtitle @code{ld}
+@ifset VERSION_PACKAGE
+@subtitle @value{VERSION_PACKAGE}
+@end ifset
@subtitle Version @value{VERSION}
@author Steve Chamberlain
@author Ian Lance Taylor
@vskip 0pt plus 1filll
@c man begin COPYRIGHT
Copyright @copyright{} 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000, 2001,
-2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
+2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1
@end titlepage
@end iftex
+@contents
@c FIXME: Talk about importance of *order* of args, cmds to linker!
@ifnottex
@node Top
@top LD
-This file documents the @sc{gnu} linker ld version @value{VERSION}.
+This file documents the @sc{gnu} linker ld
+@ifset VERSION_PACKAGE
+@value{VERSION_PACKAGE}
+@end ifset
+version @value{VERSION}.
This document is distributed under the terms of the GNU Free
Documentation License. A copy of the license is included in the
@ifset POWERPC64
* PowerPC64 ELF64:: ld and PowerPC64 64-bit ELF Support
@end ifset
+@ifset SPU
+* SPU ELF:: ld and SPU ELF Support
+@end ifset
@ifset TICOFF
* TI COFF:: ld and the TI COFF
@end ifset
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. @command{ld} will search its
-path-list for occurrences of @code{lib@var{archive}.a} for every
-@var{archive} specified.
+@kindex -l@var{namespec}
+@kindex --library=@var{namespec}
+@item -l@var{namespec}
+@itemx --library=@var{namespec}
+Add the archive or object file specified by @var{namespec} to the
+list of files to link. This option may be used any number of times.
+If @var{namespec} is of the form @file{:@var{filename}}, @command{ld}
+will search the library path for a file called @var{filename}, otherise it
+will search the library path for a file called @file{lib@var{namespec}.a}.
On systems which support shared libraries, @command{ld} may also search for
-libraries with extensions other than @code{.a}. Specifically, on ELF
-and SunOS systems, @command{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.
+files other than @file{lib@var{namespec}.a}. Specifically, on ELF
+and SunOS systems, @command{ld} will search a directory for a library
+called @file{lib@var{namespec}.so} before searching for one called
+@file{lib@var{namespec}.a}. (By convention, a @code{.so} extension
+indicates a shared library.) Note that this behavior does not apply
+to @file{:@var{filename}}, which always specifies a file called
+@var{filename}.
The linker will search an archive only once, at the location where it is
specified on the command line. If the archive defines a symbol which
have taken some special action that ensures that the linker errors are
inappropriate.
+@kindex --no-warn-search-mismatch
+@item --no-warn-search-mismatch
+Normally @command{ld} will give a warning if it finds an incompatible
+library during a library search. This option silences the warning.
+
@kindex --no-whole-archive
@item --no-whole-archive
Turn off the effect of the @option{--whole-archive} option for subsequent
NOCROSSREFS}.
For each section within the @code{OVERLAY}, the linker automatically
-defines two symbols. The symbol @code{__load_start_@var{secname}} is
+provides two symbols. The symbol @code{__load_start_@var{secname}} is
defined as the starting load address of the section. The symbol
@code{__load_stop_@var{secname}} is defined as the final load address of
the section. Any characters within @var{secname} which are not legal
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},
+following symbols will be defined if referenced: @code{__load_start_text0},
@code{__load_stop_text0}, @code{__load_start_text1},
@code{__load_stop_text1}.
@smallexample
@group
.text0 0x1000 : AT (0x4000) @{ o1/*.o(.text) @}
- __load_start_text0 = LOADADDR (.text0);
- __load_stop_text0 = LOADADDR (.text0) + SIZEOF (.text0);
+ PROVIDE (__load_start_text0 = LOADADDR (.text0));
+ PROVIDE (__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);
+ PROVIDE (__load_start_text1 = LOADADDR (.text1));
+ PROVIDE (__load_stop_text1 = LOADADDR (.text1) + SIZEOF (.text1));
. = 0x1000 + MAX (SIZEOF (.text0), SIZEOF (.text1));
@end group
@end smallexample
The builtin function @code{NEXT} is closely related to @code{ALIGN}.
+@item ALIGNOF(@var{section})
+@kindex ALIGNOF(@var{section})
+@cindex section alignment
+Return the alignment in bytes of the named @var{section}, if that section has
+been allocated. If the section has not been allocated when this is
+evaluated, the linker will report an error. In the following example,
+the alignment of the @code{.output} section is stored as the first
+value in that section.
+@smallexample
+@group
+SECTIONS@{ @dots{}
+ .output @{
+ LONG (ALIGNOF (.output))
+ @dots{}
+ @}
+@dots{} @}
+@end group
+@end smallexample
+
@item BLOCK(@var{exp})
@kindex BLOCK(@var{exp})
This is a synonym for @code{ALIGN}, for compatibility with older linker
@ifset POWERPC64
* PowerPC64 ELF64:: @command{ld} and PowerPC64 64-bit ELF Support
@end ifset
+@ifset SPU
+* SPU ELF:: @command{ld} and SPU ELF Support
+@end ifset
@ifset TICOFF
* TI COFF:: @command{ld} and TI COFF
@end ifset
case when a pointer to a function is taken. The pointer will in fact
point to the function trampoline.
+@cindex PIC_VENEER
+@kindex --pic-veneer
+The @samp{--pic-veneer} switch makes the linker use PIC sequences for
+ARM/Thumb interworking veneers, even if the rest of the binary
+is not PIC. This avoids problems on uClinux targets where
+@samp{--emit-relocs} is used to generate relocatable binaries.
+
@ifclear GENERIC
@lowersections
@end ifclear
This option is enabled implicitly for SymbianOS, so there is no need to
specify it if you are using that target.
+@cindex VFP11_DENORM_FIX
+@kindex --vfp11-denorm-fix
+The @samp{--vfp11-denorm-fix} switch enables a link-time workaround for a
+bug in certain VFP11 coprocessor hardware, which sometimes allows
+instructions with denorm operands (which must be handled by support code)
+to have those operands overwritten by subsequent instructions before
+the support code can read the intended values.
+
+The bug may be avoided in scalar mode if you allow at least one
+intervening instruction between a VFP11 instruction which uses a register
+and another instruction which writes to the same register, or at least two
+intervening instructions if vector mode is in use. The bug only affects
+full-compliance floating-point mode: you do not need this workaround if
+you are using "runfast" mode. Please contact ARM for further details.
+
+If you know you are using buggy VFP11 hardware, you can
+enable this workaround by specifying the linker option
+@samp{--vfp-denorm-fix=scalar} if you are using the VFP11 scalar
+mode only, or @samp{--vfp-denorm-fix=vector} if you are using
+vector mode (the latter also works for scalar code). The default is
+@samp{--vfp-denorm-fix=none}.
+
+If the workaround is enabled, instructions are scanned for
+potentially-troublesome sequences, and a veneer is created for each
+such sequence which may trigger the erratum. The veneer consists of the
+first instruction of the sequence and a branch back to the subsequent
+instruction. The original instruction is then replaced with a branch to
+the veneer. The extra cycles required to call and return from the veneer
+are sufficient to avoid the erratum in both the scalar and vector cases.
+
+@cindex NO_ENUM_SIZE_WARNING
+@kindex --no-enum-size-warning
+The @samp{--no-enum-size-warning} switch prevents the linker from
+warning when linking object files that specify incompatible EABI
+enumeration size attributes. For example, with this switch enabled,
+linking of an object file using 32-bit enumeration values with another
+using enumeration values fitted into the smallest possible space will
+not be diagnosed.
+
@ifclear GENERIC
@lowersections
@end ifclear
compiled with @samp{-msecure-plt}. @samp{--bss-plt} forces the old
BSS PLT (and GOT layout) which can give slightly better performance.
+@kindex --secure-plt
+@item --secure-plt
+@command{ld} will use the new PLT and GOT layout if it is linking new
+@samp{-fpic} or @samp{-fPIC} code, but does not do so automatically
+when linking non-PIC code. This option requests the new PLT and GOT
+layout. A warning will be given if some object file requires the old
+style BSS PLT.
+
@cindex PowerPC GOT
@kindex --sdata-got
@item --sdata-got
@end ifclear
@end ifset
+@ifset SPU
+@ifclear GENERIC
+@raisesections
+@end ifclear
+
+@node SPU ELF
+@section @command{ld} and SPU ELF Support
+
+@cindex SPU ELF options
+@table @option
+
+@cindex SPU plugins
+@kindex --plugin
+@item --plugin
+This option marks an executable as a PIC plugin module.
+
+@cindex SPU overlays
+@kindex --no-overlays
+@item --no-overlays
+Normally, @command{ld} recognizes calls to functions within overlay
+regions, and redirects such calls to an overlay manager via a stub.
+@command{ld} also provides a built-in overlay manager. This option
+turns off all this special overlay handling.
+
+@cindex SPU overlay stub symbols
+@kindex --emit-stub-syms
+@item --emit-stub-syms
+This option causes @command{ld} to label overlay stubs with a local
+symbol that encodes the stub type and destination.
+
+@cindex SPU extra overlay stubs
+@kindex --extra-overlay-stubs
+@item --extra-overlay-stubs
+This option causes @command{ld} to add overlay call stubs on all
+function calls out of overlay regions. Normally stubs are not added
+on calls to non-overlay regions.
+
+@cindex SPU local store size
+@kindex --local-store=lo:hi
+@item --local-store=lo:hi
+@command{ld} usually checks that a final executable for SPU fits in
+the address range 0 to 256k. This option may be used to change the
+range. Disable the check entirely with @option{--local-store=0:0}.
+
+@cindex SPU
+@kindex --stack-analysis
+@item --stack-analysis
+SPU local store space is limited. Over-allocation of stack space
+unnecessarily limits space available for code and data, while
+under-allocation results in runtime failures. If given this option,
+@command{ld} will provide an estimate of maximum stack usage.
+@command{ld} does this by examining symbols in code sections to
+determine the extents of functions, and looking at function prologues
+for stack adjusting instructions. A call-graph is created by looking
+for relocations on branch instructions. The graph is then searched
+for the maximum stack usage path. Note that this analysis does not
+find calls made via function pointers, and does not handle recursion
+and other cycles in the call graph. Stack usage may be
+under-estimated if your code makes such calls. Also, stack usage for
+dynamic allocation, e.g. alloca, will not be detected. If a link map
+is requested, detailed information about each function's stack usage
+and calls will be given.
+
+@cindex SPU
+@kindex --emit-stack-syms
+@item --emit-stack-syms
+This option, if given along with @option{--stack-analysis} will result
+in @command{ld} emitting stack sizing symbols for each function.
+These take the form @code{__stack_<function_name>} for global
+functions, and @code{__stack_<number>_<function_name>} for static
+functions. @code{<number>} is the section id in hex. The value of
+such symbols is the stack requirement for the corresponding function.
+The symbol size will be zero, type @code{STT_NOTYPE}, binding
+@code{STB_LOCAL}, and section @code{SHN_ABS}.
+@end table
+
+@ifclear GENERIC
+@lowersections
+@end ifclear
+@end ifset
+
@ifset TICOFF
@ifclear GENERIC
@raisesections
individuals in the file @file{etc/SERVICE} in the @sc{gnu} Emacs
distribution.
+@ifset BUGURL
Otherwise, send bug reports for @command{ld} to
-@samp{bug-binutils@@gnu.org}.
+@value{BUGURL}.
+@end ifset
The fundamental principle of reporting bugs usefully is this:
@strong{report all the facts}. If you are not sure whether to state a
% Blame: doc@cygnus.com, 28mar91.
@end tex
-
-@contents
@bye
projects / deliverable / binutils-gdb.git / blobdiff