\input texinfo
@setfilename ld.info
-@c Copyright 1991-2013 Free Software Foundation, Inc.
+@c Copyright (C) 1991-2017 Free Software Foundation, Inc.
@syncodeindex ky cp
@c man begin INCLUDE
@include configdoc.texi
@set I960
@set M68HC11
@set M68K
+@set MIPS
@set MMIX
@set MSP430
+@set NDS32
+@set NIOSII
@set POWERPC
@set POWERPC64
@set Renesas
+@set S/390
@set SPU
@set TICOFF
@set WIN32
@end ifset
version @value{VERSION}.
-Copyright @copyright{} 1991-2013 Free Software Foundation, Inc.
+Copyright @copyright{} 1991-2017 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
@vskip 0pt plus 1filll
@c man begin COPYRIGHT
-Copyright @copyright{} 1991-2013 Free Software Foundation, Inc.
+Copyright @copyright{} 1991-2017 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
@ifset M68K
* M68K:: ld and Motorola 68K family
@end ifset
+@ifset MIPS
+* MIPS:: ld and MIPS family
+@end ifset
@ifset POWERPC
* PowerPC ELF32:: ld and PowerPC 32-bit ELF Support
@end ifset
@ifset POWERPC64
* PowerPC64 ELF64:: ld and PowerPC64 64-bit ELF Support
@end ifset
+@ifset S/390
+* S/390 ELF:: ld and S/390 ELF Support
+@end ifset
@ifset SPU
* SPU ELF:: ld and SPU ELF Support
@end ifset
how @command{ld} searches for a linker script unless @option{-T}
option is specified.
-If @var{searchdir} begins with @code{=}, then the @code{=} will be replaced
-by the @dfn{sysroot prefix}, a path specified when the linker is configured.
+If @var{searchdir} begins with @code{=} or @code{$SYSROOT}, then this
+prefix will be replaced by the @dfn{sysroot prefix}, controlled by the
+@samp{--sysroot} option, or specified when the linker is configured.
@ifset UsesEnvVars
The default set of paths searched (without being specified with
no difference in the linker's behaviour for different non-zero values
of this option. Again this may change with future releases.
+@kindex -plugin @var{name}
+@item -plugin @var{name}
+Involve a plugin in the linking process. The @var{name} parameter is
+the absolute filename of the plugin. Usually this parameter is
+automatically added by the complier, when using link time
+optimization, but users can also add their own plugins if they so
+wish.
+
+Note that the location of the compiler originated plugins is different
+from the place where the @command{ar}, @command{nm} and
+@command{ranlib} programs search for their plugins. In order for
+those commands to make use of a compiler based plugin it must first be
+copied into the @file{$@{libdir@}/bfd-plugins} directory. All gcc
+based linker plugins are backward compatible, so it is sufficient to
+just copy in the newest one.
+
+@kindex --push-state
+@cindex push state governing input file handling
+@item --push-state
+The @option{--push-state} allows to preserve the current state of the
+flags which govern the input file handling so that they can all be
+restored with one corresponding @option{--pop-state} option.
+
+The option which are covered are: @option{-Bdynamic}, @option{-Bstatic},
+@option{-dn}, @option{-dy}, @option{-call_shared}, @option{-non_shared},
+@option{-static}, @option{-N}, @option{-n}, @option{--whole-archive},
+@option{--no-whole-archive}, @option{-r}, @option{-Ur},
+@option{--copy-dt-needed-entries}, @option{--no-copy-dt-needed-entries},
+@option{--as-needed}, @option{--no-as-needed}, and @option{-a}.
+
+One target for this option are specifications for @file{pkg-config}. When
+used with the @option{--libs} option all possibly needed libraries are
+listed and then possibly linked with all the time. It is better to return
+something as follows:
+
+@smallexample
+-Wl,--push-state,--as-needed -libone -libtwo -Wl,--pop-state
+@end smallexample
+
+@kindex --pop-state
+@cindex pop state governing input file handling
+@item --pop-state
+Undoes the effect of --push-state, restores the previous values of the
+flags governing input file handling.
+
@kindex -q
@kindex --emit-relocs
@cindex retain relocations in final executable
@itemx --strip-debug
Omit debugger symbol information (but not all symbols) from the output file.
+@kindex --strip-discarded
+@kindex --no-strip-discarded
+@item --strip-discarded
+@itemx --no-strip-discarded
+Omit (or do not omit) global symbols defined in discarded sections.
+Enabled by default.
+
@kindex -t
@kindex --trace
@cindex input files, displaying
different option arguments to enter additional undefined symbols. This
option is equivalent to the @code{EXTERN} linker script command.
+If this option is being used to force additional modules to be pulled
+into the link, and if it is an error for the symbol to remain
+undefined, then the option @option{--require-defined} should be used
+instead.
+
+@kindex --require-defined=@var{symbol}
+@cindex symbols, require defined
+@cindex defined symbol
+@item --require-defined=@var{symbol}
+Require that @var{symbol} is defined in the output file. This option
+is the same as option @option{--undefined} except that if @var{symbol}
+is not defined in the output file then the linker will issue an error
+and exit. The same effect can be achieved in a linker script by using
+@code{EXTERN}, @code{ASSERT} and @code{DEFINED} together. This option
+can be used multiple times to require additional symbols.
+
@kindex -Ur
@cindex constructors
@item -Ur
be added to. Use @samp{-Ur} only for the last partial link, and
@samp{-r} for the others.
+@kindex --orphan-handling=@var{MODE}
+@cindex orphan sections
+@cindex sections, orphan
+@item --orphan-handling=@var{MODE}
+Control how orphan sections are handled. An orphan section is one not
+specifically mentioned in a linker script. @xref{Orphan Sections}.
+
+@var{MODE} can have any of the following values:
+
+@table @code
+@item place
+Orphan sections are placed into a suitable output section following
+the strategy described in @ref{Orphan Sections}. The option
+@samp{--unique} also affects how sections are placed.
+
+@item discard
+All orphan sections are discarded, by placing them in the
+@samp{/DISCARD/} section (@pxref{Output Section Discarding}).
+
+@item warn
+The linker will place the orphan section as for @code{place} and also
+issue a warning.
+
+@item error
+The linker will exit with an error if any orphan section is found.
+@end table
+
+The default if @samp{--orphan-handling} is not given is @code{place}.
+
@kindex --unique[=@var{SECTION}]
@item --unique[=@var{SECTION}]
Creates a separate output section for every input section matching
Combines multiple reloc sections and sorts them to make dynamic symbol
lookup caching possible.
+@item common
+Generate common symbols with the STT_COMMON type druing a relocatable
+link.
+
@item defs
Disallows undefined symbols in object files. Undefined symbols in
shared libraries are still allowed.
@item nocombreloc
Disables multiple reloc sections combining.
+@item nocommon
+Generate common symbols with the STT_OBJECT type druing a relocatable
+link.
+
@item nocopyreloc
-Disables production of copy relocs.
+Disable linker generated .dynbss variables used in place of variables
+defined in shared libraries. May result in dynamic text relocations.
@item nodefaultlib
Marks the object that the search for dependencies of this object will
@item noexecstack
Marks the object as not requiring executable stack.
+@item text
+Treat DT_TEXTREL in shared object as error.
+
+@item notext
+Don't treat DT_TEXTREL in shared object as error.
+
+@item textoff
+Don't treat DT_TEXTREL in shared object as error.
+
@item norelro
Don't create an ELF @code{PT_GNU_RELRO} segment header in the object.
Specifying zero will override any default non-zero sized
@code{PT_GNU_STACK} segment creation.
+@item bndplt
+Always generate BND prefix in PLT entries. Supported for Linux/x86_64.
+
+@item noextern-protected-data
+Don't treat protected data symbol as external when building shared
+library. This option overrides linker backend default. It can be used
+to workaround incorrect relocations against protected data symbols
+generated by compiler. Updates on protected data symbols by another
+module aren't visible to the resulting shared library. Supported for
+i386 and x86-64.
+
+@item dynamic-undefined-weak
+Make undefined weak symbols dynamic when building a dynamic object,
+if they are referenced from a regular object file and not forced local
+by symbol visibility or versioning. Not all targets support this
+option.
+
+@item nodynamic-undefined-weak
+Do not make undefined weak symbols dynamic when building a dynamic
+object. Not all targets support this option. If neither
+@option{-z nodynamic-undefined-weak} nor @option{-z dynamic-undefined-weak}
+are given, a target may default to either option being in force, or
+make some other selection of undefined weak symbols dynamic.
+
+@item noreloc-overflow
+Disable relocation overflow check. This can be used to disable
+relocation overflow check if there will be no dynamic relocation
+overflow at run-time. Supported for x86_64.
+
+@item call-nop=prefix-addr
+@itemx call-nop=suffix-nop
+@itemx call-nop=prefix-@var{byte}
+@itemx call-nop=suffix-@var{byte}
+Specify the 1-byte @code{NOP} padding when transforming indirect call
+to a locally defined function, foo, via its GOT slot.
+@option{call-nop=prefix-addr} generates @code{0x67 call foo}.
+@option{call-nop=suffix-nop} generates @code{call foo 0x90}.
+@option{call-nop=prefix-@var{byte}} generates @code{@var{byte} call foo}.
+@option{call-nop=suffix-@var{byte}} generates @code{call foo @var{byte}}.
+Supported for i386 and x86_64.
+
+@item ibtplt
+Generate Intel Indirect Branch Tracking (IBT) enabled PLT entries.
+Supported for Linux/i386 and Linux/x86_64.
+
+@item IBT
+Generate GNU_PROPERTY_X86_FEATURE_1_IBT in .note.gnu.property section
+to indicate compatibility with IBT. This also implies @option{ibtplt}.
+Supported for Linux/i386 and Linux/x86_64.
+
+@item shstk
+Generate GNU_PROPERTY_X86_FEATURE_1_SHSTK in .note.gnu.property section
+to indicate compatibility with Intel Shadow Stack. Supported for
+Linux/i386 and Linux/x86_64.
+
@end table
Other keywords are ignored for Solaris compatibility.
needed or not. @option{--as-needed} causes a DT_NEEDED tag to only be
emitted for a library that @emph{at that point in the link} satisfies a
non-weak undefined symbol reference from a regular object file or, if
-the library is not found in the DT_NEEDED lists of other libraries, a
-non-weak undefined symbol reference from another dynamic library.
+the library is not found in the DT_NEEDED lists of other needed libraries, a
+non-weak undefined symbol reference from another needed dynamic library.
Object files or libraries appearing on the command line @emph{after}
the library in question do not affect whether the library is seen as
needed. This is similar to the rules for extraction of object files
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.
+within the shared library. This option can also be used with the
+@option{--export-dynamic} option, when creating a position independent
+executable, to bind references to global symbols to the definition within
+the executable. This option is only meaningful on ELF platforms which
+support shared libraries and position independent executables.
@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 can also be used with the @option{--export-dynamic} option,
+when creating a position independent executable, to bind references
+to global function symbols to the definition within the executable.
This option is only meaningful on ELF platforms which support shared
-libraries.
+libraries and position independent executables.
@kindex --dynamic-list=@var{dynamic-list-file}
@item --dynamic-list=@var{dynamic-list-file}
duplicate when there are many dynamic modules with specialized search
paths for runtime symbol resolution.
+@cindex group allocation in linker script
+@cindex section groups
+@cindex COMDAT
+@kindex --force-group-allocation
+@item --force-group-allocation
+This option causes the linker to place section group members like
+normal input sections, and to delete the section groups. This is the
+default behaviour for a final link but this option can be used to
+change the behaviour of a relocatable link (@samp{-r}). The script
+command @code{FORCE_GROUP_ALLOCATION} has the same
+effect. @xref{Miscellaneous Commands}.
+
@cindex symbols, from command line
@kindex --defsym=@var{symbol}=@var{exp}
@item --defsym=@var{symbol}=@var{expression}
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}.
+using the linker command language from a script (@pxref{Assignments}).
+@emph{Note:} there should be no white space between @var{symbol}, the
+equals sign (``@key{=}''), and @var{expression}.
@cindex demangling, from command line
@kindex --demangle[=@var{style}]
linker is normally correct; don't use this unless you know what you are
doing.
+@kindex --no-dynamic-linker
+@item --no-dynamic-linker
+When producing an executable file, omit the request for a dynamic
+linker to be used at load-time. This is only meaningful for ELF
+executables that contain dynamic relocations, and usually requires
+entry point code that is capable of processing these relocations.
+
+@kindex --embedded-relocs
+@item --embedded-relocs
+This option is similar to the @option{--emit-relocs} option except
+that the relocs are stored in a target specific section. This option
+is only supported by the @samp{BFIN}, @samp{CR16} and @emph{M68K}
+targets.
+
@kindex --fatal-warnings
@kindex --no-fatal-warnings
@item --fatal-warnings
Enable garbage collection of unused input sections. It is ignored on
targets that do not support this option. The default behaviour (of not
performing this garbage collection) can be restored by specifying
-@samp{--no-gc-sections} on the command line.
+@samp{--no-gc-sections} on the command line. Note that garbage
+collection for COFF and PE format targets is supported, but the
+implementation is currently considered to be experimental.
@samp{--gc-sections} decides which input sections are used by
examining symbols and relocations. The section containing the entry
be restored by specifying @samp{--no-print-gc-sections} on the command
line.
+@kindex --gc-keep-exported
+@cindex garbage collection
+@item --gc-keep-exported
+When @samp{--gc-sections} is enabled, this option prevents garbage
+collection of unused input sections that contain global symbols having
+default or protected visibility. This option is intended to be used for
+executables where unreferenced sections would otherwise be garbage
+collected regardless of the external visibility of contained symbols.
+Note that this option has no effect when linking shared objects since
+it is already the default behaviour. This option is only supported for
+ELF format targets.
+
@kindex --print-output-format
@cindex output format
@item --print-output-format
other command-line options). This is the string that would appear
in an @code{OUTPUT_FORMAT} linker script command (@pxref{File Commands}).
+@kindex --print-memory-usage
+@cindex memory usage
+@item --print-memory-usage
+Print used size, total size and used size of memory regions created with
+the @ref{MEMORY} command. This is useful on embedded targets to have a
+quick view of amount of free memory. The format of the output has one
+headline and one line per region. It is both human readable and easily
+parsable by tools. Here is an example of an output:
+
+@smallexample
+Memory region Used Size Region Size %age Used
+ ROM: 256 KB 1 MB 25.00%
+ RAM: 32 B 2 GB 0.00%
+@end smallexample
+
@cindex help
@cindex usage
@kindex --help
this option overrides it. @xref{BFD}.
@end ifclear
+@kindex --out-implib
+@item --out-implib @var{file}
+Create an import library in @var{file} corresponding to the executable
+the linker is generating (eg. a DLL or ELF program). This import
+library (which should be called @code{*.dll.a} or @code{*.a} for DLLs)
+may be used to link clients against the generated executable; this
+behaviour makes it possible to skip a separate import library creation
+step (eg. @code{dlltool} for DLLs). This option is only available for
+the i386 PE and ELF targetted ports of the linker.
+
@kindex -pie
@kindex --pic-executable
@item -pie
@ifset M68HC11
@xref{M68HC11/68HC12,,@command{ld} and the 68HC11 and 68HC12}.
@end ifset
+@ifset NIOSII
+@xref{Nios II,,@command{ld} and the Altera Nios II}.
+@end ifset
@ifset POWERPC
@xref{PowerPC ELF32,,@command{ld} and PowerPC 32-bit ELF Support}.
@end ifset
@code{LD_RUN_PATH} will be used if it is defined.
The @option{-rpath} option may also be used on SunOS. By default, on
-SunOS, the linker will form a runtime search patch out of all the
+SunOS, the linker will form a runtime search path out of all the
@option{-L} options it is given. If a @option{-rpath} option is used, the
runtime search path will be formed exclusively using the @option{-rpath}
options, ignoring the @option{-L} options. This can be useful when using
either by specifying a list of names separated by colons, or by
appearing multiple times.
+The tokens @var{$ORIGIN} and @var{$LIB} can appear in these search
+directories. They will be replaced by the full path to the directory
+containing the program or shared object in the case of @var{$ORIGIN}
+and either @samp{lib} - for 32-bit binaries - or @samp{lib64} - for
+64-bit binaries - in the case of @var{$LIB}.
+
+The alternative form of these tokens - @var{$@{ORIGIN@}} and
+@var{$@{LIB@}} can also be used. The token @var{$PLATFORM} is not
+supported.
+
This option should be used with caution as it overrides the search path
that may have been hard compiled into a shared library. In such a case it
is possible to use unintentionally a different search path than the
This option will apply @code{SORT_BY_ALIGNMENT} to all wildcard section
patterns in the linker script.
+@kindex --spare-dynamic-tags
+@item --spare-dynamic-tags=@var{count}
+This option specifies the number of empty slots to leave in the
+.dynamic section of ELF shared objects. Empty slots may be needed by
+post processing tools, such as the prelinker. The default is 5.
+
@kindex --split-by-file
@item --split-by-file[=@var{size}]
Similar to @option{--split-by-reloc} but creates a new output section for
configure-time default. This option is only supported by linkers
that were configured using @option{--with-sysroot}.
+@kindex --task-link
+@item --task-link
+This is used by COFF/PE based targets to create a task-linked object
+file where all of the global symbols have been converted to statics.
+
@kindex --traditional-format
@cindex traditional format
@item --traditional-format
@kindex -Ttext-segment=@var{org}
@item -Ttext-segment=@var{org}
@cindex text segment origin, cmd line
-When creating an ELF executable or shared object, it will set the address
-of the first byte of the text segment.
+When creating an ELF executable, it will set the address of the first
+byte of the text segment.
@kindex -Trodata-segment=@var{org}
@item -Trodata-segment=@var{org}
call before the linker has a chance to wrap it to @code{malloc}.
@kindex --eh-frame-hdr
+@kindex --no-eh-frame-hdr
@item --eh-frame-hdr
-Request creation of @code{.eh_frame_hdr} section and ELF
-@code{PT_GNU_EH_FRAME} segment header.
+@itemx --no-eh-frame-hdr
+Request (@option{--eh-frame-hdr}) or suppress
+(@option{--no-eh-frame-hdr}) the creation of @code{.eh_frame_hdr}
+section and ELF @code{PT_GNU_EH_FRAME} segment header.
@kindex --ld-generated-unwind-info
@item --no-ld-generated-unwind-info
the classic ELF @code{.hash} and new style GNU @code{.gnu.hash}
hash tables. The default is @code{sysv}.
+@kindex --compress-debug-sections=none
+@kindex --compress-debug-sections=zlib
+@kindex --compress-debug-sections=zlib-gnu
+@kindex --compress-debug-sections=zlib-gabi
+@item --compress-debug-sections=none
+@itemx --compress-debug-sections=zlib
+@itemx --compress-debug-sections=zlib-gnu
+@itemx --compress-debug-sections=zlib-gabi
+On ELF platforms, these options control how DWARF debug sections are
+compressed using zlib.
+
+@option{--compress-debug-sections=none} doesn't compress DWARF debug
+sections. @option{--compress-debug-sections=zlib-gnu} compresses
+DWARF debug sections and renames them to begin with @samp{.zdebug}
+instead of @samp{.debug}. @option{--compress-debug-sections=zlib-gabi}
+also compresses DWARF debug sections, but rather than renaming them it
+sets the SHF_COMPRESSED flag in the sections' headers.
+
+The @option{--compress-debug-sections=zlib} option is an alias for
+@option{--compress-debug-sections=zlib-gabi}.
+
+Note that this option overrides any compression in input debug
+sections, so if a binary is linked with @option{--compress-debug-sections=none}
+for example, then any compressed debug sections in input files will be
+uncompressed before they are copied into the output binary.
+
+The default compression behaviour varies depending upon the target
+involved and the configure options used to build the toolchain. The
+default can be determined by examining the output from the linker's
+@option{--help} option.
+
@kindex --reduce-memory-overheads
@item --reduce-memory-overheads
This option reduces memory requirements at ld runtime, at the expense of
@kindex --build-id=@var{style}
@item --build-id
@itemx --build-id=@var{style}
-Request creation of @code{.note.gnu.build-id} ELF note section.
-The contents of the note are unique bits identifying this linked
-file. @var{style} can be @code{uuid} to use 128 random bits,
-@code{sha1} to use a 160-bit @sc{SHA1} hash on the normative
-parts of the output contents, @code{md5} to use a 128-bit
-@sc{MD5} hash on the normative parts of the output contents, or
-@code{0x@var{hexstring}} to use a chosen bit string specified as
-an even number of hexadecimal digits (@code{-} and @code{:}
-characters between digit pairs are ignored). If @var{style} is
-omitted, @code{sha1} is used.
+Request the creation of a @code{.note.gnu.build-id} ELF note section
+or a @code{.buildid} COFF section. The contents of the note are
+unique bits identifying this linked file. @var{style} can be
+@code{uuid} to use 128 random bits, @code{sha1} to use a 160-bit
+@sc{SHA1} hash on the normative parts of the output contents,
+@code{md5} to use a 128-bit @sc{MD5} hash on the normative parts of
+the output contents, or @code{0x@var{hexstring}} to use a chosen bit
+string specified as an even number of hexadecimal digits (@code{-} and
+@code{:} characters between digit pairs are ignored). If @var{style}
+is omitted, @code{sha1} is used.
The @code{md5} and @code{sha1} styles produces an identifier
that is always the same in an identical output file, but will be
@kindex --disable-long-section-names
@item --enable-long-section-names
@itemx --disable-long-section-names
-The PE variants of the Coff object format add an extension that permits
+The PE variants of the COFF object format add an extension that permits
the use of section names longer than eight characters, the normal limit
-for Coff. By default, these names are only allowed in object files, as
-fully-linked executable images do not carry the Coff string table required
+for COFF. By default, these names are only allowed in object files, as
+fully-linked executable images do not carry the COFF string table required
to support the longer names. As a GNU extension, it is possible to
allow their use in executable images as well, or to (probably pointlessly!)
disallow it in object files, by using these two options. Executable images
@item --heap @var{reserve}
@itemx --heap @var{reserve},@var{commit}
Specify the number of bytes of memory to reserve (and optionally commit)
-to be used as heap for this program. The default is 1Mb reserved, 4K
+to be used as heap for this program. The default is 1MB reserved, 4K
committed.
[This option is specific to the i386 PE targeted port of the linker]
section of the BOOT.INI. Otherwise, this bit has no effect.
[This option is specific to PE targeted ports of the linker]
+@kindex --disable-large-address-aware
+@item --disable-large-address-aware
+Reverts the effect of a previous @samp{--large-address-aware} option.
+This is useful if @samp{--large-address-aware} is always set by the compiler
+driver (e.g. Cygwin gcc) and the executable does not support virtual
+addresses greater than 2 gigabytes.
+[This option is specific to PE targeted ports of the linker]
+
@kindex --major-image-version
@item --major-image-version @var{value}
Sets the major number of the ``image version''. Defaults to 1.
[This option is specific to the i386 PE targeted port of the linker]
@cindex DLLs, creating
-@kindex --out-implib
-@item --out-implib @var{file}
-The linker will create the file @var{file} which will contain an
-import lib corresponding to the DLL the linker is generating. This
-import lib (which should be called @code{*.dll.a} or @code{*.a}
-may be used to link clients against the generated DLL; this behaviour
-makes it possible to skip a separate @code{dlltool} import library
-creation step.
-[This option is specific to the i386 PE targeted port of the linker]
-
@kindex --enable-auto-image-base
@item --enable-auto-image-base
-Automatically choose the image base for DLLs, unless one is specified
-using the @code{--image-base} argument. By using a hash generated
-from the dllname to create unique image bases for each DLL, in-memory
-collisions and relocations which can delay program execution are
-avoided.
+@itemx --enable-auto-image-base=@var{value}
+Automatically choose the image base for DLLs, optionally starting with base
+@var{value}, unless one is specified using the @code{--image-base} argument.
+By using a hash generated from the dllname to create unique image bases
+for each DLL, in-memory collisions and relocations which can delay program
+execution are avoided.
[This option is specific to the i386 PE targeted port of the linker]
@kindex --disable-auto-image-base
@item --stack @var{reserve}
@itemx --stack @var{reserve},@var{commit}
Specify the number of bytes of memory to reserve (and optionally commit)
-to be used as stack for this program. The default is 2Mb reserved, 4K
+to be used as stack for this program. The default is 2MB reserved, 4K
committed.
[This option is specific to the i386 PE targeted port of the linker]
of the PE file header:
[These options are specific to PE targeted ports of the linker]
+@kindex --high-entropy-va
+@item --high-entropy-va
+Image is compatible with 64-bit address space layout randomization
+(ASLR).
+
@kindex --dynamicbase
@item --dynamicbase
The image base address may be relocated using address space layout
@item --tsaware
The image is Terminal Server aware.
+@kindex --insert-timestamp
+@item --insert-timestamp
+@itemx --no-insert-timestamp
+Insert a real timestamp into the image. This is the default behaviour
+as it matches legacy code and it means that the image will work with
+other, proprietary tools. The problem with this default is that it
+will result in slightly different images being produced each time the
+same sources are linked. The option @option{--no-insert-timestamp}
+can be used to insert a zero value for the timestamp, this ensuring
+that binaries produced from identical sources will compare
+identically.
@end table
@c man end
@kindex --dsbt-size
@item --dsbt-size @var{size}
-This option sets the number of entires in the DSBT of the current executable
+This option sets the number of entries in the DSBT of the current executable
or shared library to @var{size}. The default is to create a table with 64
entries.
@c man end
@end ifset
+@ifset MIPS
+@subsection Options specific to MIPS targets
+
+@c man begin OPTIONS
+
+The following options are supported to control microMIPS instruction
+generation and branch relocation checks for ISA mode transitions when
+linking for MIPS targets.
+
+@table @gcctabopt
+
+@kindex --insn32
+@item --insn32
+@kindex --no-insn32
+@itemx --no-insn32
+These options control the choice of microMIPS instructions used in code
+generated by the linker, such as that in the PLT or lazy binding stubs,
+or in relaxation. If @samp{--insn32} is used, then the linker only uses
+32-bit instruction encodings. By default or if @samp{--no-insn32} is
+used, all instruction encodings are used, including 16-bit ones where
+possible.
+
+@kindex --ignore-branch-isa
+@item --ignore-branch-isa
+@kindex --no-ignore-branch-isa
+@itemx --no-ignore-branch-isa
+These options control branch relocation checks for invalid ISA mode
+transitions. If @samp{--ignore-branch-isa} is used, then the linker
+accepts any branch relocations and any ISA mode transition required
+is lost in relocation calculation, except for some cases of @code{BAL}
+instructions which meet relaxation conditions and are converted to
+equivalent @code{JALX} instructions as the associated relocation is
+calculated. By default or if @samp{--no-ignore-branch-isa} is used
+a check is made causing the loss of an ISA mode transition to produce
+an error.
+
+@end table
+
+@c man end
+@end ifset
+
@ifset UsesEnvVars
@node Environment
@section Environment Variables
located inside the @dfn{sysroot prefix}, the filename will be looked
for in the @dfn{sysroot prefix}. Otherwise, the linker will 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}.
+linker will search through the archive library search path.
+The @dfn{sysroot prefix} can also be forced by specifying @code{=}
+as the first character in the filename path, or prefixing the filename
+path with @code{$SYSROOT}. See also the description of @samp{-L} in
+@ref{Options,,Command Line Options}.
If you use @samp{INPUT (-l@var{file})}, @command{ld} will transform the
name to @code{lib@var{file}.a}, as with the command line argument
Ensure that @var{exp} is non-zero. If it is zero, then exit the linker
with an error code, and print @var{message}.
+Note that assertions are checked before the final stages of linking
+take place. This means that expressions involving symbols PROVIDEd
+inside section definitions will fail if the user has not set values
+for those symbols. The only exception to this rule is PROVIDEd
+symbols that just reference dot. Thus an assertion like this:
+
+@smallexample
+ .stack :
+ @{
+ PROVIDE (__stack = .);
+ PROVIDE (__stack_size = 0x100);
+ ASSERT ((__stack > (_end + __stack_size)), "Error: No room left for the stack");
+ @}
+@end smallexample
+
+will fail if @code{__stack_size} is not defined elsewhere. Symbols
+PROVIDEd outside of section definitions are evaluated earlier, so they
+can be used inside ASSERTions. Thus:
+
+@smallexample
+ PROVIDE (__stack_size = 0x100);
+ .stack :
+ @{
+ PROVIDE (__stack = .);
+ ASSERT ((__stack > (_end + __stack_size)), "Error: No room left for the stack");
+ @}
+@end smallexample
+
+will work.
+
@item EXTERN(@var{symbol} @var{symbol} @dots{})
@kindex EXTERN
@cindex undefined symbol in linker script
command-line option: to make @code{ld} omit the assignment of addresses
to common symbols even for a non-relocatable output file.
+@item FORCE_GROUP_ALLOCATION
+@kindex FORCE_GROUP_ALLOCATION
+@cindex group allocation in linker script
+@cindex section groups
+@cindex COMDAT
+This command has the same effect as the
+@samp{--force-group-allocation} command-line option: to make
+@command{ld} place section group members like normal input sections,
+and to delete the section groups even if a relocatable output file is
+specified (@samp{-r}).
+
@item INSERT [ AFTER | BEFORE ] @var{output_section}
@kindex INSERT
@cindex insert user script into default script
@code{NOCROSSREFS} command uses output section names, not input section
names.
+@item NOCROSSREFS_TO(@var{tosection} @var{fromsection} @dots{})
+@kindex NOCROSSREFS_TO(@var{tosection} @var{fromsections})
+@cindex cross references
+This command may be used to tell @command{ld} to issue an error about any
+references to one section from a list of other sections.
+
+The @code{NOCROSSREFS} command is useful when ensuring that two or more
+output sections are entirely independent but there are situations where
+a one-way dependency is needed. For example, in a multi-core application
+there may be shared code that can be called from each core but for safety
+must never call back.
+
+The @code{NOCROSSREFS_TO} command takes a list of output section names.
+The first section can not be referenced from any of the other sections.
+If @command{ld} detects any references to the first section from any of
+the other sections, it reports an error and returns a non-zero exit
+status. Note that the @code{NOCROSSREFS_TO} command uses output section
+names, not input section names.
+
@ifclear SingleFormat
@item OUTPUT_ARCH(@var{bfdarch})
@kindex OUTPUT_ARCH(@var{bfdarch})
@smallexample
@group
start_of_ROM = .ROM;
- end_of_ROM = .ROM + sizeof (.ROM) - 1;
+ end_of_ROM = .ROM + sizeof (.ROM);
start_of_FLASH = .FLASH;
@end group
@end smallexample
@end smallexample
Note the use of the @samp{&} operators. These are correct.
+Alternatively the symbols can be treated as the names of vectors or
+arrays and then the code will again work as expected:
+
+@smallexample
+@group
+ extern char start_of_ROM[], end_of_ROM[], start_of_FLASH[];
+
+ memcpy (start_of_FLASH, start_of_ROM, end_of_ROM - start_of_ROM);
+@end group
+@end smallexample
+
+Note how using this method does not require the use of @samp{&}
+operators.
@node SECTIONS
@section SECTIONS Command
@group
@var{section} [@var{address}] [(@var{type})] :
[AT(@var{lma})]
- [ALIGN(@var{section_align})]
+ [ALIGN(@var{section_align}) | ALIGN_WITH_INPUT]
[SUBALIGN(@var{subsection_align})]
[@var{constraint}]
@{
@var{output-section-command}
@var{output-section-command}
@dots{}
- @} [>@var{region}] [AT>@var{lma_region}] [:@var{phdr} :@var{phdr} @dots{}] [=@var{fillexp}]
+ @} [>@var{region}] [AT>@var{lma_region}] [:@var{phdr} :@var{phdr} @dots{}] [=@var{fillexp}] [,]
@end group
@end smallexample
The whitespace around @var{section} is required, so that the section
name is unambiguous. The colon and the curly braces are also required.
+The comma at the end may be required if a @var{fillexp} is used and
+the next @var{sections-command} looks like a continuation of the expression.
The line breaks and other white space are optional.
Each @var{output-section-command} may be one of the following:
@end smallexample
@noindent
Here the @samp{*} is a wildcard which matches any file name. To exclude a list
+@cindex EXCLUDE_FILE
of files from matching the file name wildcard, EXCLUDE_FILE may be used to
match all files except the ones specified in the EXCLUDE_FILE list. For
example:
@smallexample
+EXCLUDE_FILE (*crtend.o *otherfile.o) *(.ctors)
+@end smallexample
+@noindent
+will cause all .ctors sections from all files except @file{crtend.o}
+and @file{otherfile.o} to be included. The EXCLUDE_FILE can also be
+placed inside the section list, for example:
+@smallexample
*(EXCLUDE_FILE (*crtend.o *otherfile.o) .ctors)
@end smallexample
-will cause all .ctors sections from all files except @file{crtend.o} and
-@file{otherfile.o} to be included.
+@noindent
+The result of this is identically to the previous example. Supporting
+two syntaxes for EXCLUDE_FILE is useful if the section list contains
+more than one section, as described below.
There are two ways to include more than one section:
@smallexample
@samp{.text} input sections will appear first, followed by all
@samp{.rdata} input sections.
+When using EXCLUDE_FILE with more than one section, if the exclusion
+is within the section list then the exclusion only applies to the
+immediately following section, for example:
+@smallexample
+*(EXCLUDE_FILE (*somefile.o) .text .rdata)
+@end smallexample
+@noindent
+will cause all @samp{.text} sections from all files except
+@file{somefile.o} to be included, while all @samp{.rdata} sections
+from all files, including @file{somefile.o}, will be included. To
+exclude the @samp{.rdata} sections from @file{somefile.o} the example
+could be modified to:
+@smallexample
+*(EXCLUDE_FILE (*somefile.o) .text EXCLUDE_FILE (*somefile.o) .rdata)
+@end smallexample
+@noindent
+Alternatively, placing the EXCLUDE_FILE outside of the section list,
+before the input file selection, will cause the exclusion to apply for
+all sections. Thus the previous example can be rewritten as:
+@smallexample
+EXCLUDE_FILE (*somefile.o) *(.text .rdata)
+@end smallexample
+
You can specify a file name to include sections from a particular file.
You would do this if one or more of your files contain special data that
needs to be at a particular location in memory. For example:
@end group
@end smallexample
+If an output section's name is the same as the input section's name
+and is representable as a C identifier, then the linker will
+automatically @pxref{PROVIDE} two symbols: __start_SECNAME and
+__stop_SECNAME, where SECNAME is the name of the section. These
+indicate the start address and end address of the output section
+respectively. Note: most section names are not representable as
+C identifiers because they contain a @samp{.} character.
+
@node Output Section Data
@subsection Output Section Data
@cindex data
@cindex discarding sections
@cindex sections, discarding
@cindex removing sections
-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:
+The linker will not normally create output sections with no contents.
+This is for convenience when referring to input sections that may or
+may not be present in any of the input files. For example:
@smallexample
.foo : @{ *(.foo) @}
@end smallexample
will only create a @samp{.foo} section in the output file if there is a
@samp{.foo} section in at least one input file, and if the input
sections are not all empty. Other link script directives that allocate
-space in an output section will also create the output section.
+space in an output section will also create the output section. So
+too will assignments to dot even if the assignment does not create
+space, except for @samp{. = 0}, @samp{. = . + 0}, @samp{. = sym},
+@samp{. = . + sym} and @samp{. = ALIGN (. != 0, expr, 1)} when
+@samp{sym} is an absolute symbol of value 0 defined in the script.
+This allows you to force output of an empty section with @samp{. = .}.
The linker will ignore address assignments (@pxref{Output Section Address})
on discarded output sections, except when the linker script defines
@kindex ALIGN(@var{section_align})
@cindex forcing output section alignment
@cindex output section alignment
-You can increase an output section's alignment by using ALIGN.
+You can increase an output section's alignment by using ALIGN. As an
+alternative you can enforce that the difference between the VMA and LMA remains
+intact throughout this output section with the ALIGN_WITH_INPUT attribute.
@node Forced Input Alignment
@subsubsection Forced Input Alignment
@dots{}
@} [:@var{phdr}@dots{}] [=@var{fill}]
@dots{}
- @} [>@var{region}] [:@var{phdr}@dots{}] [=@var{fill}]
+ @} [>@var{region}] [:@var{phdr}@dots{}] [=@var{fill}] [,]
@end group
@end smallexample
except that no addresses and no memory regions may be defined for
sections within an @code{OVERLAY}.
+The comma at the end may be required if a @var{fill} is used and
+the next @var{sections-command} looks like a continuation of the expression.
+
The sections are all defined with the same starting address. The load
addresses of the sections are arranged such that they are consecutive in
memory starting at the load address used for the @code{OVERLAY} as a
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:
+A linker script may contain many uses of the @code{MEMORY} command,
+however, all memory blocks defined are treated as if they were
+specified inside a single @code{MEMORY} command. The syntax for
+@code{MEMORY} is:
@smallexample
@group
MEMORY
@item @code{PT_PHDR} (6)
Indicates a segment where the program headers may be found.
+@item @code{PT_TLS} (7)
+Indicates a segment containing thread local storage.
+
@item @var{expression}
An expression giving the numeric type of the program header. This may
be used for types not defined above.
Orphan sections are sections present in the input files which
are not explicitly placed into the output file by the linker
script. The linker will still copy these sections into the
-output file, but it has to guess as to where they should be
-placed. The linker uses a simple heuristic to do this. It
-attempts to place orphan sections after non-orphan sections of the
-same attribute, such as code vs data, loadable vs non-loadable, etc.
-If there is not enough room to do this then it places
-at the end of the file.
-
-For ELF targets, the attribute of the section includes section type as
-well as section flag.
-
-If an orphaned section's name is representable as a C identifier then
-the linker will automatically @pxref{PROVIDE} two symbols:
-__start_SECNAME and __stop_SECNAME, where SECNAME is the name of the
-section. These indicate the start address and end address of the
-orphaned section respectively. Note: most section names are not
-representable as C identifiers because they contain a @samp{.}
-character.
+output file by either finding, or creating a suitable output section
+in which to place the orphaned input section.
+
+If the name of an orphaned input section exactly matches the name of
+an existing output section, then the orphaned input section will be
+placed at the end of that output section.
+
+If there is no output section with a matching name then new output
+sections will be created. Each new output section will have the same
+name as the orphan section placed within it. If there are multiple
+orphan sections with the same name, these will all be combined into
+one new output section.
+
+If new output sections are created to hold orphaned input sections,
+then the linker must decide where to place these new output sections
+in relation to existing output sections. On most modern targets, the
+linker attempts to place orphan sections after sections of the same
+attribute, such as code vs data, loadable vs non-loadable, etc. If no
+sections with matching attributes are found, or your target lacks this
+support, the orphan section is placed at the end of the file.
+
+The command line options @samp{--orphan-handling} and @samp{--unique}
+(@pxref{Options,,Command Line Options}) can be used to control which
+output sections an orphan is placed in.
@node Location Counter
@subsection The Location Counter
@item
The result of other binary arithmetic and logical operations on two
relative addresses in the same section or two absolute addresses
-(after above conversions) is also a number.
+(after above conversions) is also a number when
+@code{LD_FEATURE ("SANE_EXPR")} or inside an output section definition
+but an absolute address otherwise.
@item
The result of other operations on relative addresses or one
relative address and a number, is a relative address in the same
doesn't change the value of the location counter---it just does
arithmetic on it. The two operand @code{ALIGN} allows an arbitrary
expression to be aligned upwards (@code{ALIGN(@var{align})} is
-equivalent to @code{ALIGN(., @var{align})}).
+equivalent to @code{ALIGN(ABSOLUTE(.), @var{align})}).
Here is an example which aligns the output @code{.data} section to the
next @code{0x2000} byte boundary after the preceding section and sets a
@end smallexample
or
@smallexample
-(ALIGN(@var{maxpagesize}) + (. & (@var{maxpagesize} - @var{commonpagesize})))
+(ALIGN(@var{maxpagesize})
+ + ((. + @var{commonpagesize} - 1) & (@var{maxpagesize} - @var{commonpagesize})))
@end smallexample
@noindent
depending on whether the latter uses fewer @var{commonpagesize} sized pages
@item DATA_SEGMENT_RELRO_END(@var{offset}, @var{exp})
@kindex DATA_SEGMENT_RELRO_END(@var{offset}, @var{exp})
This defines the end of the @code{PT_GNU_RELRO} segment when
-@samp{-z relro} option is used. Second argument is returned.
+@samp{-z relro} option is used.
When @samp{-z relro} option is not present, @code{DATA_SEGMENT_RELRO_END}
does nothing, otherwise @code{DATA_SEGMENT_ALIGN} is padded so that
@var{exp} + @var{offset} is aligned to the most commonly used page
boundary for particular target. If present in the linker script,
it must always come in between @code{DATA_SEGMENT_ALIGN} and
-@code{DATA_SEGMENT_END}.
+@code{DATA_SEGMENT_END}. Evaluates to the second argument plus any
+padding needed at the end of the @code{PT_GNU_RELRO} segment due to
+section alignment.
@smallexample
. = DATA_SEGMENT_RELRO_END(24, .);
Return the absolute LMA of the named @var{section}. (@pxref{Output
Section LMA}).
+@item LOG2CEIL(@var{exp})
+@kindex LOG2CEIL(@var{exp})
+Return the binary logarithm of @var{exp} rounded towards infinity.
+@code{LOG2CEIL(0)} returns 0.
+
@kindex MAX
@item MAX(@var{exp1}, @var{exp2})
Returns the maximum of @var{exp1} and @var{exp2}.
@ifset M68K
* M68K:: @command{ld} and the Motorola 68K family
@end ifset
+@ifset MIPS
+* MIPS:: @command{ld} and the MIPS family
+@end ifset
@ifset MMIX
* MMIX:: @command{ld} and MMIX
@end ifset
@ifset MSP430
* MSP430:: @command{ld} and MSP430
@end ifset
+@ifset NDS32
+* NDS32:: @command{ld} and NDS32
+@end ifset
+@ifset NIOSII
+* Nios II:: @command{ld} and the Altera Nios II
+@end ifset
@ifset POWERPC
* PowerPC ELF32:: @command{ld} and PowerPC 32-bit ELF Support
@end ifset
@ifset POWERPC64
* PowerPC64 ELF64:: @command{ld} and PowerPC64 64-bit ELF Support
@end ifset
+@ifset S/390
+* S/390 ELF:: @command{ld} and S/390 ELF Support
+@end ifset
@ifset SPU
* SPU ELF:: @command{ld} and SPU ELF Support
@end ifset
target subroutine is a leaf routine (that is, the target subroutine does
not itself call any subroutines).
-@cindex Cortex-A8 erratum workaround
-@kindex --fix-cortex-a8
-@kindex --no-fix-cortex-a8
-The @samp{--fix-cortex-a8} switch enables a link-time workaround for an erratum in certain Cortex-A8 processors. The workaround is enabled by default if you are targeting the ARM v7-A architecture profile. It can be enabled otherwise by specifying @samp{--fix-cortex-a8}, or disabled unconditionally by specifying @samp{--no-fix-cortex-a8}.
-
-The erratum only affects Thumb-2 code. Please contact ARM for further details.
-
-@kindex --merge-exidx-entries
-@kindex --no-merge-exidx-entries
-The @samp{--no-merge-exidx-entries} switch disables the merging of adjacent exidx entries in debuginfo.
-
@ifclear GENERIC
@lowersections
@end ifclear
@cindex BE8
@kindex --be8
The @samp{--be8} switch instructs @command{ld} to generate BE8 format
-executables. This option is only valid when linking big-endian objects.
-The resulting image will contain big-endian data and little-endian code.
+executables. This option is only valid when linking big-endian
+objects - ie ones which have been assembled with the @option{-EB}
+option. The resulting image will contain big-endian data and
+little-endian code.
@cindex TARGET1
@kindex --target1-rel
Programmer Advice Notice'' available on the ARM documentation website at:
http://infocenter.arm.com/.
+@cindex STM32L4xx erratum workaround
+@kindex --fix-stm32l4xx-629360
+
+The @samp{--fix-stm32l4xx-629360} switch enables a link-time
+workaround for a bug in the bus matrix / memory controller for some of
+the STM32 Cortex-M4 based products (STM32L4xx). When accessing
+off-chip memory via the affected bus for bus reads of 9 words or more,
+the bus can generate corrupt data and/or abort. These are only
+core-initiated accesses (not DMA), and might affect any access:
+integer loads such as LDM, POP and floating-point loads such as VLDM,
+VPOP. Stores are not affected.
+
+The bug can be avoided by splitting memory accesses into the
+necessary chunks to keep bus reads below 8 words.
+
+The workaround is not enabled by default, this is equivalent to use
+@samp{--fix-stm32l4xx-629360=none}. If you know you are using buggy
+STM32L4xx hardware, you can enable the workaround by specifying the
+linker option @samp{--fix-stm32l4xx-629360}, or the equivalent
+@samp{--fix-stm32l4xx-629360=default}.
+
+If the workaround is enabled, instructions are scanned for
+potentially-troublesome sequences, and a veneer is created for each
+such sequence which may trigger the erratum. The veneer consists in a
+replacement sequence emulating the behaviour of the original one and a
+branch back to the subsequent instruction. The original instruction is
+then replaced with a branch to the veneer.
+
+The workaround does not always preserve the memory access order for
+the LDMDB instruction, when the instruction loads the PC.
+
+The workaround is not able to handle problematic instructions when
+they are in the middle of an IT block, since a branch is not allowed
+there. In that case, the linker reports a warning and no replacement
+occurs.
+
+The workaround is not able to replace problematic instructions with a
+PC-relative branch instruction if the @samp{.text} section is too
+large. In that case, when the branch that replaces the original code
+cannot be encoded, the linker reports a warning and no replacement
+occurs.
+
@cindex NO_ENUM_SIZE_WARNING
@kindex --no-enum-size-warning
The @option{--no-enum-size-warning} switch prevents the linker from
only, because it relies on object files properties not present
otherwise.
+@cindex Cortex-A8 erratum workaround
+@kindex --fix-cortex-a8
+@kindex --no-fix-cortex-a8
+The @samp{--fix-cortex-a8} switch enables a link-time workaround for an erratum in certain Cortex-A8 processors. The workaround is enabled by default if you are targeting the ARM v7-A architecture profile. It can be enabled otherwise by specifying @samp{--fix-cortex-a8}, or disabled unconditionally by specifying @samp{--no-fix-cortex-a8}.
+
+The erratum only affects Thumb-2 code. Please contact ARM for further details.
+
+@cindex Cortex-A53 erratum 835769 workaround
+@kindex --fix-cortex-a53-835769
+@kindex --no-fix-cortex-a53-835769
+The @samp{--fix-cortex-a53-835769} switch enables a link-time workaround for erratum 835769 present on certain early revisions of Cortex-A53 processors. The workaround is disabled by default. It can be enabled by specifying @samp{--fix-cortex-a53-835769}, or disabled unconditionally by specifying @samp{--no-fix-cortex-a53-835769}.
+
+Please contact ARM for further details.
+
+@kindex --merge-exidx-entries
+@kindex --no-merge-exidx-entries
+@cindex Merging exidx entries
+The @samp{--no-merge-exidx-entries} switch disables the merging of adjacent exidx entries in debuginfo.
+
+@kindex --long-plt
+@cindex 32-bit PLT entries
+The @samp{--long-plt} option enables the use of 16 byte PLT entries
+which support up to 4Gb of code. The default is to use 12 byte PLT
+entries which only support 512Mb of code.
+
+@kindex --no-apply-dynamic-relocs
+@cindex AArch64 rela addend
+The @samp{--no-apply-dynamic-relocs} option makes AArch64 linker do not apply
+link-time values for dynamic relocations.
+
+@cindex Placement of SG veneers
+All SG veneers are placed in the special output section @code{.gnu.sgstubs}.
+Its start address must be set, either with the command line option
+@samp{--section-start} or in a linker script, to indicate where to place these
+veneers in memory.
+
+@kindex --cmse-implib
+@cindex Secure gateway import library
+The @samp{--cmse-implib} option requests that the import libraries
+specified by the @samp{--out-implib} and @samp{--in-implib} options are
+secure gateway import libraries, suitable for linking a non-secure
+executable against secure code as per ARMv8-M Security Extensions.
+
+@kindex --in-implib=@var{file}
+@cindex Input import library
+The @samp{--in-implib=file} specifies an input import library whose symbols
+must keep the same address in the executable being produced. A warning is
+given if no @samp{--out-implib} is given but new symbols have been introduced
+in the executable that should be listed in its import library. Otherwise, if
+@samp{--out-implib} is specified, the symbols are added to the output import
+library. A warning is also given if some symbols present in the input import
+library have disappeared from the executable. This option is only effective
+for Secure Gateway import libraries, ie. when @samp{--cmse-implib} is
+specified.
+
@ifclear GENERIC
@lowersections
@end ifclear
@end ifclear
@end ifset
+@ifset MIPS
+@ifclear GENERIC
+@raisesections
+@end ifclear
+
+@node MIPS
+@section @command{ld} and the MIPS family
+
+@cindex MIPS microMIPS instruction choice selection
+@kindex --insn32
+@kindex --no-insn32
+The @samp{--insn32} and @samp{--no-insn32} options control the choice of
+microMIPS instructions used in code generated by the linker, such as that
+in the PLT or lazy binding stubs, or in relaxation. If @samp{--insn32} is
+used, then the linker only uses 32-bit instruction encodings. By default
+or if @samp{--no-insn32} is used, all instruction encodings are used,
+including 16-bit ones where possible.
+
+@cindex MIPS branch relocation check control
+@kindex --ignore-branch-isa
+@kindex --no-ignore-branch-isa
+The @samp{--ignore-branch-isa} and @samp{--no-ignore-branch-isa} options
+control branch relocation checks for invalid ISA mode transitions. If
+@samp{--ignore-branch-isa} is used, then the linker accepts any branch
+relocations and any ISA mode transition required is lost in relocation
+calculation, except for some cases of @code{BAL} instructions which meet
+relaxation conditions and are converted to equivalent @code{JALX}
+instructions as the associated relocation is calculated. By default
+or if @samp{--no-ignore-branch-isa} is used a check is made causing
+the loss of an ISA mode transition to produce an error.
+
+@ifclear GENERIC
+@lowersections
+@end ifclear
+@end ifset
+
@ifset MMIX
@ifclear GENERIC
@raisesections
@end ifclear
@end ifset
+@ifset NDS32
+@ifclear GENERIC
+@raisesections
+@end ifclear
+
+@node NDS32
+@section @code{ld} and NDS32
+@kindex relaxing on NDS32
+For NDS32, there are some options to select relaxation behavior. The linker
+relaxes objects according to these options.
+
+@table @code
+@item @samp{--m[no-]fp-as-gp}
+Disable/enable fp-as-gp relaxation.
+
+@item @samp{--mexport-symbols=FILE}
+Exporting symbols and their address into FILE as linker script.
+
+@item @samp{--m[no-]ex9}
+Disable/enable link-time EX9 relaxation.
+
+@item @samp{--mexport-ex9=FILE}
+Export the EX9 table after linking.
+
+@item @samp{--mimport-ex9=FILE}
+Import the Ex9 table for EX9 relaxation.
+
+@item @samp{--mupdate-ex9}
+Update the existing EX9 table.
+
+@item @samp{--mex9-limit=NUM}
+Maximum number of entries in the ex9 table.
+
+@item @samp{--mex9-loop-aware}
+Avoid generating the EX9 instruction inside the loop.
+
+@item @samp{--m[no-]ifc}
+Disable/enable the link-time IFC optimization.
+
+@item @samp{--mifc-loop-aware}
+Avoid generating the IFC instruction inside the loop.
+@end table
+
+@ifclear GENERIC
+@lowersections
+@end ifclear
+@end ifset
+
+@ifset NIOSII
+@ifclear GENERIC
+@raisesections
+@end ifclear
+
+@node Nios II
+@section @command{ld} and the Altera Nios II
+@cindex Nios II call relaxation
+@kindex --relax on Nios II
+
+Call and immediate jump instructions on Nios II processors are limited to
+transferring control to addresses in the same 256MB memory segment,
+which may result in @command{ld} giving
+@samp{relocation truncated to fit} errors with very large programs.
+The command-line option @option{--relax} enables the generation of
+trampolines that can access the entire 32-bit address space for calls
+outside the normal @code{call} and @code{jmpi} address range. These
+trampolines are inserted at section boundaries, so may not themselves
+be reachable if an input section and its associated call trampolines are
+larger than 256MB.
+
+The @option{--relax} option is enabled by default unless @option{-r}
+is also specified. You can disable trampoline generation by using the
+@option{--no-relax} linker option. You can also disable this optimization
+locally by using the @samp{set .noat} directive in assembly-language
+source files, as the linker-inserted trampolines use the @code{at}
+register as a temporary.
+
+Note that the linker @option{--relax} option is independent of assembler
+relaxation options, and that using the GNU assembler's @option{-relax-all}
+option interferes with the linker's more selective call instruction relaxation.
+
+@ifclear GENERIC
+@lowersections
+@end ifclear
+@end ifset
+
@ifset POWERPC
@ifclear GENERIC
@raisesections
@cindex PowerPC64 dot symbols
@kindex --dotsyms
@kindex --no-dotsyms
-@item --dotsyms, --no-dotsyms
+@item --dotsyms
+@itemx --no-dotsyms
These two options control how @command{ld} interprets version patterns
in a version script. Older PowerPC64 compilers emitted both a
function descriptor symbol with the same name as the function, and a
dot-prefixed patterns. Use @samp{--no-dotsyms} to disable this
feature.
+@cindex PowerPC64 register save/restore functions
+@kindex --save-restore-funcs
+@kindex --no-save-restore-funcs
+@item --save-restore-funcs
+@itemx --no-save-restore-funcs
+These two options control whether PowerPC64 @command{ld} automatically
+provides out-of-line register save and restore functions used by
+@samp{-Os} code. The default is to provide any such referenced
+function for a normal final link, and to not do so for a relocatable
+link.
+
@cindex PowerPC64 TLS optimization
@kindex --no-tls-optimize
@item --no-tls-optimize
sequences used to access Thread-Local Storage. Use this option to
disable the optimization.
+@cindex PowerPC64 __tls_get_addr optimization
+@kindex --tls-get-addr-optimize
+@kindex --no-tls-get-addr-optimize
+@item --tls-get-addr-optimize
+@itemx --no-tls-get-addr-optimize
+These options control whether PowerPC64 @command{ld} uses a special
+stub to call __tls_get_addr. PowerPC64 glibc 2.22 and later support
+an optimization that allows the second and subsequent calls to
+@code{__tls_get_addr} for a given symbol to be resolved by the special
+stub without calling in to glibc. By default the linker enables this
+option when glibc advertises the availability of __tls_get_addr_opt.
+Forcing this option on when using an older glibc won't do much besides
+slow down your applications, but may be useful if linking an
+application against an older glibc with the expectation that it will
+normally be used on systems having a newer glibc.
+
@cindex PowerPC64 OPD optimization
@kindex --no-opd-optimize
@item --no-opd-optimize
@item --plt-align
@itemx --no-plt-align
Use these options to control whether individual PLT call stubs are
-aligned to a 32-byte boundary, or to the specified power of two
-boundary when using @code{--plt-align=}. By default PLT call stubs
-are packed tightly.
+padded so that they don't cross a 32-byte boundary, or to the
+specified power of two boundary when using @code{--plt-align=}. Note
+that this isn't alignment in the usual sense. By default PLT call
+stubs are packed tightly.
@cindex PowerPC64 PLT call stub static chain
@kindex --plt-static-chain
looks for calls to commonly used functions that create threads, and if
seen, adds the necessary barriers. Use these options to change the
default behaviour.
+
+@cindex PowerPC64 ELFv2 PLT localentry optimization
+@kindex --plt-localentry
+@kindex --no-plt-localentry
+@item --plt-localentry
+@itemx --no-localentry
+ELFv2 functions with localentry:0 are those with a single entry point,
+ie. global entry == local entry, and that have no requirement on r2
+(the TOC/GOT pointer) or r12, and guarantee r2 is unchanged on return.
+Such an external function can be called via the PLT without saving r2
+or restoring it on return, avoiding a common load-hit-store for small
+functions. The optimization is attractive, with up to 40% reduction
+in execution time for a small function, but can result in symbol
+interposition failures. Also, minor changes in a shared library,
+including system libraries, can cause a function that was localentry:0
+to become localentry:8. This will result in a dynamic loader
+complaint and failure to run. The option is experimental, use with
+care. @option{--no-plt-localentry} is the default.
+@end table
+
+@ifclear GENERIC
+@lowersections
+@end ifclear
+@end ifset
+
+@ifset S/390
+@ifclear GENERIC
+@raisesections
+@end ifclear
+
+@node S/390 ELF
+@section @command{ld} and S/390 ELF Support
+
+@cindex S/390 ELF options
+@table @option
+
+@cindex S/390
+@kindex --s390-pgste
+@item --s390-pgste
+This option marks the result file with a @code{PT_S390_PGSTE}
+segment. The Linux kernel is supposed to allocate 4k page tables for
+binaries marked that way.
@end table
@ifclear GENERIC
@code{PRIVATE}: Put the symbol in the DLL's export table, but do not put
it into the static import library used to resolve imports at link time. The
symbol can still be imported using the @code{LoadLibrary/GetProcAddress}
-API at runtime or by by using the GNU ld extension of linking directly to
+API at runtime or by using the GNU ld extension of linking directly to
the DLL without an import library.
See ld/deffilep.y in the binutils sources for the full specification of
tools will be able to process object files employing this GNU extension,
but will fail to respect the alignment instructions, and may issue noisy
warnings about unknown linker directives.
+
@end table
@ifclear GENERIC
projects / deliverable / binutils-gdb.git / blobdiff