diff options
Diffstat (limited to 'contrib/binutils/ld/ld.texinfo')
| -rw-r--r-- | contrib/binutils/ld/ld.texinfo | 538 |
1 files changed, 396 insertions, 142 deletions
diff --git a/contrib/binutils/ld/ld.texinfo b/contrib/binutils/ld/ld.texinfo index 07bb0c3..71273f4 100644 --- a/contrib/binutils/ld/ld.texinfo +++ b/contrib/binutils/ld/ld.texinfo @@ -1,12 +1,12 @@ \input texinfo @setfilename ld.info @c Copyright 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, -@c 2001, 2002, 2003, 2004, 2005 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 @@ -20,33 +20,18 @@ @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 @@ -60,13 +45,15 @@ 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, -2001, 2002, 2003, 2004 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 @@ -74,23 +61,18 @@ or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in the section entitled ``GNU Free Documentation License''. - -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 -@settitle Using LD, the GNU linker +@settitle The GNU linker @titlepage -@title Using ld -@subtitle The GNU linker +@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 @@ -100,7 +82,7 @@ notice identical to this one except for the removal of this paragraph {\parskip=0pt \hfill Red Hat Inc\par \hfill nickc\@credhat.com, doc\@redhat.com\par -\hfill {\it Using LD, the GNU linker}\par +\hfill {\it The GNU linker}\par \hfill Edited by Jeffrey Osier (jeffrey\@cygnus.com)\par } \global\parindent=0pt % Steve likes it this way. @@ -109,7 +91,7 @@ notice identical to this one except for the removal of this paragraph @vskip 0pt plus 1filll @c man begin COPYRIGHT Copyright @copyright{} 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000, 2001, -2002, 2003, 2004 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 @@ -121,12 +103,17 @@ section entitled ``GNU Free Documentation License''. @end titlepage @end iftex +@contents @c FIXME: Talk about importance of *order* of args, cmds to linker! @ifnottex @node Top -@top Using ld -This file documents the @sc{gnu} linker ld version @value{VERSION}. +@top LD +This file documents the @sc{gnu} linker ld +@ifset VERSION_PACKAGE +@value{VERSION_PACKAGE} +@end ifset +version @value{VERSION}. This document is distributed under the terms of the GNU Free Documentation License. A copy of the license is included in the @@ -164,6 +151,9 @@ section entitled ``GNU Free Documentation License''. @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 @@ -182,7 +172,7 @@ section entitled ``GNU Free Documentation License''. * Reporting Bugs:: Reporting Bugs * MRI:: MRI Compatible Script Files * GNU Free Documentation License:: GNU Free Documentation License -* Index:: Index +* LD Index:: LD Index @end menu @end ifnottex @@ -216,10 +206,9 @@ to provide explicit and total control over the linking process. @ifset man @c For the man only -This man page does not describe the command language; see the -@command{ld} entry in @code{info}, or the manual -ld: the GNU linker, for full details on the command language and -on other aspects of the GNU linker. +This man page does not describe the command language; see the +@command{ld} entry in @code{info} for full details on the command +language and on other aspects of the GNU linker. @end ifset @ifclear SingleFormat @@ -322,7 +311,7 @@ For options whose names are multiple letters, either one dash or two can precede the option name; for example, @samp{-trace-symbol} and @samp{--trace-symbol} are equivalent. Note---there is one exception to this rule. Multiple letter options that start with a lower case 'o' can -only be preceeded by two dashes. This is to reduce confusion with the +only be preceded by two dashes. This is to reduce confusion with the @samp{-o} option. So for example @samp{-omagic} sets the output file name to @samp{magic} whereas @samp{--omagic} sets the NMAGIC flag on the output. @@ -489,9 +478,9 @@ back to the symbols defined by the program, rather than some other dynamic object, then you will probably need to use this option when linking the program itself. -You can also use the version script to control what symbols should +You can also use the dynamic list to control what symbols should be added to the dynamic symbol table if the output format supports it. -See the description of @samp{--version-script} in @ref{VERSION}. +See the description of @samp{--dynamic-list}. @ifclear SingleFormat @cindex big-endian objects @@ -550,7 +539,7 @@ toolchain for specifying object-file format for both input and output object files. @ifclear SingleFormat The @sc{gnu} linker uses other mechanisms for this purpose: the -@option{-b}, @option{--format}, @option{--oformat} options, the +@option{-b}, @option{--format}, @option{--oformat} options, the @code{TARGET} command in linker scripts, and the @code{GNUTARGET} environment variable. @end ifclear @@ -604,21 +593,24 @@ 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. @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 @@ -773,7 +765,7 @@ should only be enabled for the final binary. @cindex retain relocations in final executable @item -q @itemx --emit-relocs -Leave relocation sections and contents in fully linked exececutables. +Leave relocation sections and contents in fully linked executables. Post link analysis and optimization tools may need this information in order to perform correct modifications of executables. This results in larger executables. @@ -858,6 +850,22 @@ the current directory, @code{ld} looks for it in the directories specified by any preceding @samp{-L} options. Multiple @samp{-T} options accumulate. +@kindex -dT @var{script} +@kindex --default-script=@var{script} +@cindex script files +@item -dT @var{scriptfile} +@itemx --default-script=@var{scriptfile} +Use @var{scriptfile} as the default linker script. @xref{Scripts}. + +This option is similar to the @option{--script} option except that +processing of the script is delayed until after the rest of the +command line has been processed. This allows options placed after the +@option{--default-script} option on the command line to affect the +behaviour of the linker script, which can be important when the linker +command line cannot be directly controlled by the user. (eg because +the command line is being constructed by another tool, such as +@samp{gcc}). + @kindex -u @var{symbol} @kindex --undefined=@var{symbol} @cindex undefined symbol @@ -911,11 +919,11 @@ 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}. +Delete all temporary local symbols. (These symbols start with +system-specific local label prefixes, typically @samp{.L} for ELF systems +or @samp{L} for traditional a.out systems.) @kindex -y @var{symbol} @kindex --trace-symbol=@var{symbol} @@ -962,6 +970,12 @@ objects. Marks the object that its symbol table interposes before all symbols but the primary executable. +@item lazy +When generating an executable or shared library, mark it to tell the +dynamic linker to defer function call resolution to the point when +the function is called (lazy binding), rather than at load time. +Lazy binding is the default. + @item loadfltr Marks the object that its filters be processed immediately at runtime. @@ -1007,9 +1021,15 @@ Marks the object may contain $ORIGIN. @item relro Create an ELF @code{PT_GNU_RELRO} segment header in the object. +@item max-page-size=@var{value} +Set the emulation maximum page size to @var{value}. + +@item common-page-size=@var{value} +Set the emulation common page size to @var{value}. + @end table -Other keywords are ignored for Solaris compatibility. +Other keywords are ignored for Solaris compatibility. @kindex -( @cindex groups of archives @@ -1110,7 +1130,7 @@ option also implies @option{--unresolved-symbols=report-all}. This option can be used with @option{-shared}. Doing so means that a shared library is being created but that all of the library's external references must be resolved by pulling in entries from static -libraries. +libraries. @kindex -Bsymbolic @item -Bsymbolic @@ -1120,6 +1140,39 @@ for a program linked against a shared library to override the definition within the shared library. This option is only meaningful on ELF platforms which support shared libraries. +@kindex -Bsymbolic-functions +@item -Bsymbolic-functions +When creating a shared library, bind references to global function +symbols to the definition within the shared library, if any. +This option is only meaningful on ELF platforms which support shared +libraries. + +@kindex --dynamic-list=@var{dynamic-list-file} +@item --dynamic-list=@var{dynamic-list-file} +Specify the name of a dynamic list file to the linker. This is +typically used when creating shared libraries to specify a list of +global symbols whose references shouldn't be bound to the definition +within the shared library, or creating dynamically linked executables +to specify a list of symbols which should be added to the symbol table +in the executable. This option is only meaningful on ELF platforms +which support shared libraries. + +The format of the dynamic list is the same as the version node without +scope and node name. See @ref{VERSION} for more information. + +@kindex --dynamic-list-data +@item --dynamic-list-data +Include all global data symbols to the dynamic list. + +@kindex --dynamic-list-cpp-new +@item --dynamic-list-cpp-new +Provide the builtin dynamic list for C++ operator new and delete. It +is mainly useful for building shared libstdc++. + +@kindex --dynamic-list-cpp-typeinfo +@item --dynamic-list-cpp-typeinfo +Provide the builtin dynamic list for C++ runtime type identification. + @kindex --check-sections @kindex --no-check-sections @item --check-sections @@ -1220,13 +1273,25 @@ it ends in a @code{.exe} suffix. @kindex --gc-sections @kindex --no-gc-sections @cindex garbage collection -@item --no-gc-sections -@itemx --gc-sections +@item --gc-sections +@itemx --no-gc-sections Enable garbage collection of unused input sections. It is ignored on targets that do not support this option. This option is not compatible -with @samp{-r}. The default behaviour (of not performing this garbage -collection) can be restored by specifying @samp{--no-gc-sections} on -the command line. +with @samp{-r} or @samp{--emit-relocs}. The default behaviour (of not +performing this garbage collection) can be restored by specifying +@samp{--no-gc-sections} on the command line. + +@kindex --print-gc-sections +@kindex --no-print-gc-sections +@cindex garbage collection +@item --print-gc-sections +@itemx --no-print-gc-sections +List all sections removed by garbage collection. The listing is +printed on stderr. This option is only effective if garbage +collection has been enabled via the @samp{--gc-sections}) option. The +default behaviour (of not listing the sections that are removed) can +be restored by specifying @samp{--no-print-gc-sections} on the command +line. @cindex help @cindex usage @@ -1260,7 +1325,7 @@ Report unresolved symbol references from regular object files. This is done even if the linker is creating a non-symbolic shared library. The switch @option{--[no-]allow-shlib-undefined} controls the behaviour for reporting unresolved references found in shared -libraries being linked in. +libraries being linked in. @kindex --allow-multiple-definition @kindex -z muldefs @@ -1285,7 +1350,7 @@ the shared library being specified at link time may not be the same as the one that is available at load time, so the symbols might actually be resolvable at load time. Plus there are some systems, (eg BeOS) where undefined symbols in shared libraries is normal. (The kernel patches -them at load time to select which function is most appropriate +them at load time to select which function is most appropriate for the current architecture. This is used for example to dynamically select an appropriate memset function). Apparently it is also normal for HPPA shared libraries to have undefined symbols. @@ -1316,6 +1381,11 @@ errors. This option should only be used with care, in cases when you have taken some special action that ensures that the linker errors are inappropriate. +@kindex --no-warn-search-mismatch +@item --no-warn-search-mismatch +Normally @command{ld} will give a warning if it finds an incompatible +library during a library search. This option silences the warning. + @kindex --no-whole-archive @item --no-whole-archive Turn off the effect of the @option{--whole-archive} option for subsequent @@ -1451,7 +1521,7 @@ SunOS, the linker will form a runtime search patch out of all the runtime search path will be formed exclusively using the @option{-rpath} options, ignoring the @option{-L} options. This can be useful when using gcc, which adds many @option{-L} options which may be on NFS mounted -filesystems. +file systems. For compatibility with other ELF linkers, if the @option{-R} option is followed by a directory name, rather than a file name, it is treated as @@ -1481,7 +1551,7 @@ 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. +libraries: @enumerate @item Any directories specified by @option{-rpath-link} options. @@ -1490,7 +1560,9 @@ Any directories specified by @option{-rpath} options. The difference between @option{-rpath} and @option{-rpath-link} is that directories specified by @option{-rpath} options are included in the executable and used at runtime, whereas the @option{-rpath-link} option is only effective -at link time. It is for the native linker only. +at link time. Searching @option{-rpath} in this way is only supported +by native linkers and cross linkers which have been configured with +the @option{--with-sysroot} option. @item On an ELF system, if the @option{-rpath} and @code{rpath-link} options were not used, search the contents of the environment variable @@ -1784,7 +1856,7 @@ the section (@pxref{SECTIONS}). @kindex --warn-shared-textrel @item --warn-shared-textrel -Warn if the linker adds a DT_TEXTREL to a shared object. +Warn if the linker adds a DT_TEXTREL to a shared object. @kindex --warn-unresolved-symbols @item --warn-unresolved-symbols @@ -1871,6 +1943,14 @@ time it takes the linker to perform its tasks, at the expense of increasing the linker's memory requirements. Similarly reducing this value can reduce the memory requirements at the expense of speed. +@kindex --hash-style=@var{style} +@item --hash-style=@var{style} +Set the type of linker's hash table(s). @var{style} can be either +@code{sysv} for classic ELF @code{.hash} section, @code{gnu} for +new style GNU @code{.gnu.hash} section or @code{both} for both +the classic ELF @code{.hash} and new style GNU @code{.gnu.hash} +hash tables. The default is @code{sysv}. + @kindex --reduce-memory-overheads @item --reduce-memory-overheads This option reduces memory requirements at ld runtime, at the expense of @@ -1958,22 +2038,22 @@ otherwise wouldn't be any exported symbols. When symbols are explicitly exported via DEF files or implicitly exported via function attributes, the default is to not export anything else unless this option is given. Note that the symbols @code{DllMain@@12}, -@code{DllEntryPoint@@0}, @code{DllMainCRTStartup@@12}, and +@code{DllEntryPoint@@0}, @code{DllMainCRTStartup@@12}, and @code{impure_ptr} will not be automatically -exported. Also, symbols imported from other DLLs will not be -re-exported, nor will symbols specifying the DLL's internal layout -such as those beginning with @code{_head_} or ending with -@code{_iname}. In addition, no symbols from @code{libgcc}, +exported. Also, symbols imported from other DLLs will not be +re-exported, nor will symbols specifying the DLL's internal layout +such as those beginning with @code{_head_} or ending with +@code{_iname}. In addition, no symbols from @code{libgcc}, @code{libstd++}, @code{libmingw32}, or @code{crtX.o} will be exported. Symbols whose names begin with @code{__rtti_} or @code{__builtin_} will not be exported, to help with C++ DLLs. Finally, there is an -extensive list of cygwin-private symbols that are not exported +extensive list of cygwin-private symbols that are not exported (obviously, this applies on when building DLLs for cygwin targets). -These cygwin-excludes are: @code{_cygwin_dll_entry@@12}, +These cygwin-excludes are: @code{_cygwin_dll_entry@@12}, @code{_cygwin_crt0_common@@8}, @code{_cygwin_noncygwin_dll_entry@@12}, -@code{_fmode}, @code{_impure_ptr}, @code{cygwin_attach_dll}, +@code{_fmode}, @code{_impure_ptr}, @code{cygwin_attach_dll}, @code{cygwin_premain0}, @code{cygwin_premain1}, @code{cygwin_premain2}, -@code{cygwin_premain3}, and @code{environ}. +@code{cygwin_premain3}, and @code{environ}. [This option is specific to the i386 PE targeted port of the linker] @kindex --exclude-symbols @@ -2017,9 +2097,9 @@ symbols before they are exported. @kindex --large-address-aware @item --large-address-aware -If given, the appropriate bit in the ``Charateristics'' field of the COFF +If given, the appropriate bit in the ``Characteristics'' field of the COFF header is set to indicate that this executable supports virtual addresses -greater than 2 gigabytes. This should be used in conjuction with the /3GB +greater than 2 gigabytes. This should be used in conjunction with the /3GB or /USERVA=@var{value} megabytes switch in the ``[operating systems]'' section of the BOOT.INI. Otherwise, this bit has no effect. [This option is specific to PE targeted ports of the linker] @@ -2096,17 +2176,17 @@ default. @kindex --dll-search-prefix @item --dll-search-prefix @var{string} When linking dynamically to a dll without an import library, -search for @code{<string><basename>.dll} in preference to +search for @code{<string><basename>.dll} in preference to @code{lib<basename>.dll}. This behaviour allows easy distinction between DLLs built for the various "subplatforms": native, cygwin, uwin, pw, etc. For instance, cygwin DLLs typically use -@code{--dll-search-prefix=cyg}. +@code{--dll-search-prefix=cyg}. [This option is specific to the i386 PE targeted port of the linker] @kindex --enable-auto-import @item --enable-auto-import -Do sophisticated linking of @code{_symbol} to @code{__imp__symbol} for -DATA imports from DLLs, and create the necessary thunking symbols when +Do sophisticated linking of @code{_symbol} to @code{__imp__symbol} for +DATA imports from DLLs, and create the necessary thunking symbols when building the import libraries with those DATA exports. Note: Use of the 'auto-import' extension will cause the text section of the image file to be made writable. This does not conform to the PE-COFF format @@ -2115,11 +2195,11 @@ specification published by Microsoft. Using 'auto-import' generally will 'just work' -- but sometimes you may see this message: -"variable '<var>' can't be auto-imported. Please read the +"variable '<var>' can't be auto-imported. Please read the documentation for ld's @code{--enable-auto-import} for details." -This message occurs when some (sub)expression accesses an address -ultimately given by the sum of two constants (Win32 import tables only +This message occurs when some (sub)expression accesses an address +ultimately given by the sum of two constants (Win32 import tables only allow one). Instances where this may occur include accesses to member fields of struct variables imported from a DLL, as well as using a constant index into an array variable imported from a DLL. Any @@ -2661,7 +2741,7 @@ setting afterwards. @item OUTPUT(@var{filename}) @kindex OUTPUT(@var{filename}) -@cindex output file name in linker scripot +@cindex output file name in linker script The @code{OUTPUT} command names the output file. Using @code{OUTPUT(@var{filename})} in the linker script is exactly like using @samp{-o @var{filename}} on the command line (@pxref{Options,,Command @@ -3635,19 +3715,23 @@ scripts. @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: +The linker will not create output sections with no contents. This is +for convenience when referring to input sections that may or may not +be present in any of the input files. For example: @smallexample -.foo @{ *(.foo) @} +.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. +@samp{.foo} section in at least one input file, and if the input +sections are not all empty. Other link script directives that allocate +space in an output section will also create the output section. -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. +The linker will ignore address assignments (@pxref{Output Section Address}) +on discarded output sections, except when the linker script defines +symbols in the output section. In that case the linker will obey +the address assignments, possibly advancing dot even though the +section is discarded. @cindex /DISCARD/ The special output section name @samp{/DISCARD/} may be used to discard @@ -3732,15 +3816,20 @@ Every section has a virtual address (VMA) and a load address (LMA); see 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. +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}. Note that if the section has not had a VMA assigned to it then the linker will use the @var{lma_region} as the VMA region as well. + +If neither @code{AT} nor @code{AT>} is specified for an allocatable +section, the linker will set the LMA such that the difference between +VMA and LMA for the section is the same as the preceding output +section in the same region. If there is no preceding output section +or the section is not allocatable, the linker will set the LMA equal +to the VMA. @xref{Output Section Region}. @cindex ROM initialized data @@ -3929,7 +4018,7 @@ 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 +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 @@ -3954,7 +4043,7 @@ Here is an example. Remember that this would appear inside a 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}. @@ -3976,11 +4065,11 @@ 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); + 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 @@ -4345,7 +4434,7 @@ they might suggest to the person reading them. The @samp{2.0} version could just as well have appeared in between @samp{1.1} and @samp{1.2}. However, this would be a confusing way to write a version script. -Node name can be omited, provided it is the only version node +Node name can be omitted, provided it is the only version node in the version script. Such version script doesn't assign any versions to symbols, only selects which symbols will be globally visible out and which won't. @@ -4554,7 +4643,9 @@ 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. +location counter may not be moved backwards inside an output section, +and may not be moved backwards outside of an output section if so +doing creates areas with overlapping LMAs. @smallexample SECTIONS @@ -4904,6 +4995,25 @@ of @code{ALIGN} is used to defines the value of a symbol. The builtin function @code{NEXT} is closely related to @code{ALIGN}. +@item ALIGNOF(@var{section}) +@kindex ALIGNOF(@var{section}) +@cindex section alignment +Return the alignment in bytes of the named @var{section}, if that section has +been allocated. If the section has not been allocated when this is +evaluated, the linker will report an error. In the following example, +the alignment of the @code{.output} section is stored as the first +value in that section. +@smallexample +@group +SECTIONS@{ @dots{} + .output @{ + LONG (ALIGNOF (.output)) + @dots{} + @} +@dots{} @} +@end group +@end smallexample + @item BLOCK(@var{exp}) @kindex BLOCK(@var{exp}) This is a synonym for @code{ALIGN}, for compatibility with older linker @@ -5128,6 +5238,9 @@ functionality are not listed. @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 @@ -5180,7 +5293,7 @@ page of memory, and changes them to use the 8 bit address form. the top page of memory). @item system control instructions -@command{ld} finds all @code{ldc.w, stc.w} instrcutions which use the +@command{ld} finds all @code{ldc.w, stc.w} instructions which use the 32 bit absolute address form, but refer to the top page of memory, and changes them to use 16 bit address form. (That is: the linker turns @samp{ldc.w @code{@@}@var{aa}:32,ccr} into @@ -5314,6 +5427,13 @@ trampoline address instead of the function address. This is typically the case when a pointer to a function is taken. The pointer will in fact point to the function trampoline. +@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 @@ -5325,7 +5445,7 @@ point to the function trampoline. @cindex ARM interworking support @kindex --support-old-code For the ARM, @command{ld} will generate code stubs to allow functions calls -betweem ARM and Thumb code. These stubs only work with code that has +between ARM and Thumb code. These stubs only work with code that has been compiled and assembled with the @samp{-mthumb-interwork} command line option. If it is necessary to link with old ARM object files or libraries, which have not been compiled with the -mthumb-interwork @@ -5397,6 +5517,45 @@ each PLT entry. This should lead to such calls executing slightly faster. This option is enabled implicitly for SymbianOS, so there is no need to specify it if you are using that target. +@cindex VFP11_DENORM_FIX +@kindex --vfp11-denorm-fix +The @samp{--vfp11-denorm-fix} switch enables a link-time workaround for a +bug in certain VFP11 coprocessor hardware, which sometimes allows +instructions with denorm operands (which must be handled by support code) +to have those operands overwritten by subsequent instructions before +the support code can read the intended values. + +The bug may be avoided in scalar mode if you allow at least one +intervening instruction between a VFP11 instruction which uses a register +and another instruction which writes to the same register, or at least two +intervening instructions if vector mode is in use. The bug only affects +full-compliance floating-point mode: you do not need this workaround if +you are using "runfast" mode. Please contact ARM for further details. + +If you know you are using buggy VFP11 hardware, you can +enable this workaround by specifying the linker option +@samp{--vfp-denorm-fix=scalar} if you are using the VFP11 scalar +mode only, or @samp{--vfp-denorm-fix=vector} if you are using +vector mode (the latter also works for scalar code). The default is +@samp{--vfp-denorm-fix=none}. + +If the workaround is enabled, instructions are scanned for +potentially-troublesome sequences, and a veneer is created for each +such sequence which may trigger the erratum. The veneer consists of the +first instruction of the sequence and a branch back to the subsequent +instruction. The original instruction is then replaced with a branch to +the veneer. The extra cycles required to call and return from the veneer +are sufficient to avoid the erratum in both the scalar and vector cases. + +@cindex 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 @@ -5550,6 +5709,14 @@ PLT, if all input files (including startup and static libraries) were compiled with @samp{-msecure-plt}. @samp{--bss-plt} forces the old BSS PLT (and GOT layout) which can give slightly better performance. +@kindex --secure-plt +@item --secure-plt +@command{ld} will use the new PLT and GOT layout if it is linking new +@samp{-fpic} or @samp{-fPIC} code, but does not do so automatically +when linking non-PIC code. This option requests the new PLT and GOT +layout. A warning will be given if some object file requires the old +style BSS PLT. + @cindex PowerPC GOT @kindex --sdata-got @item --sdata-got @@ -5696,6 +5863,87 @@ Use this option to turn off this feature. @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 @@ -5725,7 +5973,7 @@ header format depends on the default specified by the specific target. @section @command{ld} and WIN32 (cygwin/mingw) This section describes some of the win32 specific @command{ld} issues. -See @ref{Options,,Command Line Options} for detailed decription of the +See @ref{Options,,Command Line Options} for detailed description of the command line options mentioned here. @table @emph @@ -5802,8 +6050,8 @@ The optional @code{LIBRARY <name>} command indicates the @emph{internal} name of the output DLL. If @samp{<name>} does not include a suffix, the default library suffix, @samp{.DLL} is appended. -When the .DEF file is used to build an application. rather than a -library, the @code{NAME <name>} command shoud be used instead of +When the .DEF file is used to build an application, rather than a +library, the @code{NAME <name>} command should be used instead of @code{LIBRARY}. If @samp{<name>} does not include a suffix, the default executable suffix, @samp{.EXE} is appended. @@ -5897,7 +6145,7 @@ code the header must declare them as dllimport. There are a number of idioms that are typically used to do this; often client code can omit the __declspec() declaration completely. See @samp{--enable-auto-import} and @samp{automatic data imports} for more -imformation. +information. @end table @cindex automatic data imports @@ -5909,7 +6157,7 @@ issue. This increases the effort necessary to port existing Un*x code to these platforms, especially for large c++ libraries and applications. The auto-import feature, which was initially provided by Paul Sokolovsky, allows one to omit the -decorations to archieve a behavior that conforms to that on POSIX/Un*x +decorations to achieve a behavior that conforms to that on POSIX/Un*x platforms. This feature is enabled with the @samp{--enable-auto-import} command-line option, although it is enabled by default on cygwin/mingw. The @samp{--enable-auto-import} option itself now serves mainly to @@ -5953,7 +6201,7 @@ enabled as needed. The cygwin/mingw ports of @command{ld} support the direct linking, including data symbols, to a dll without the usage of any import libraries. This is much faster and uses much less memory than does the -traditional import library method, expecially when linking large +traditional import library method, especially when linking large libraries or applications. When @command{ld} creates an import lib, each function or variable exported from the dll is stored in its own bfd, even though a single bfd could contain many exports. The overhead involved in @@ -5972,12 +6220,13 @@ For instance, when ld is called with the argument @samp{-lxxx} it will attempt to find, in the first directory of its search path, @example -libxxx.dll.a -xxx.dll.a -libxxx.a +libxxx.dll.a +xxx.dll.a +libxxx.a +xxx.lib cygxxx.dll (*) -libxxx.dll -xxx.dll +libxxx.dll +xxx.dll @end example before moving on to the next directory in the search path. @@ -6049,7 +6298,7 @@ even when auto-import features are exercised, and even when @samp{--enable-runtime-pseudo-relocs} is used. Given the improvements in speed and memory usage, one might justifiably -wonder why import libraries are used at all. There are two reasons: +wonder why import libraries are used at all. There are three reasons: 1. Until recently, the link-directly-to-dll functionality did @emph{not} work with auto-imported data. @@ -6060,9 +6309,14 @@ symbols that point to the exports of a dll). Again, the import lib for the cygwin kernel makes use of this ability, and it is not possible to do this without an import lib. +3. Symbol aliases can only be resolved using an import lib. This is +critical when linking against OS-supplied dll's (eg, the win32 API) +in which symbols are usually exported as undecorated aliases of their +stdcall-decorated assembly names. + So, import libs are not going away. But the ability to replace true import libs with a simple symbolic link to (or a copy of) -a dll, in most cases, is a useful addition to the suite of tools +a dll, in many cases, is a useful addition to the suite of tools binutils makes available to the win32 developer. Given the massive improvements in memory requirements during linking, storage requirements, and linking speed, we expect that many developers @@ -6343,8 +6597,10 @@ You can find contact information for many support companies and individuals in the file @file{etc/SERVICE} in the @sc{gnu} Emacs distribution. +@ifset BUGURL Otherwise, send bug reports for @command{ld} to -@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 @@ -6428,7 +6684,7 @@ a chance to make a mistake. Even if the problem you experience is a fatal signal, you should still say so explicitly. Suppose something strange is going on, such as, your -copy of @command{ld} is out of synch, or you have encountered a bug in the +copy of @command{ld} is out of sync, or you have encountered a bug in the C library on your system. (This has happened!) Your copy might crash and ours would not. If you told us to expect a crash, then when ours fails to crash, we would know that the bug was not happening for us. If @@ -6629,8 +6885,8 @@ If you have more than one @code{SECT} statement for the same @include fdl.texi -@node Index -@unnumbered Index +@node LD Index +@unnumbered LD Index @printindex cp @@ -6649,6 +6905,4 @@ If you have more than one @code{SECT} statement for the same % Blame: doc@cygnus.com, 28mar91. @end tex - -@contents @bye |
