@set V850
@set VAX
@set WIN32
+@set XTENSA
@end ifset
@c man end
@ifset H8300
* H8/300:: ld and the H8/300
@end ifset
-@ifset Hitachi
-* Hitachi:: ld and other Hitachi micros
+@ifset Renesas
+* Renesas:: ld and other Renesas micros
@end ifset
@ifset I960
* i960:: ld and the Intel 960 family
@ifset WIN32
* Win32:: ld and WIN32 (cygwin/mingw)
@end ifset
+@ifset XTENSA
+* Xtensa:: ld and Xtensa Processors
+@end ifset
@end ifclear
@ifclear SingleFormat
* BFD:: BFD
@cindex partial link
@cindex relocatable output
@kindex -r
-@kindex --relocateable
+@kindex --relocatable
@item -r
-@itemx --relocateable
+@itemx --relocatable
Generate relocatable output---i.e., generate an output file that can in
turn serve as input to @command{ld}. This is often called @dfn{partial
linking}. As a side effect, in environments that support standard Unix
this option overrides it. @xref{BFD}.
@end ifclear
+@kindex -pie
+@kindex --pic-executable
+@item -pie
+@itemx --pic-executable
+@cindex position independent executables
+Create a position independent executable. This is currently only supported on
+ELF platforms. Position independent executables are similar to shared
+libraries in that they are relocated by the dynamic linker to the virtual
+address OS chooses for them (which can varry between invocations), like
+normal dynamically linked executables they can be executed and symbols
+defined in the executable cannot be overridden by shared libraries.
+
@kindex -qmagic
@item -qmagic
This option is ignored for Linux compatibility.
@ifset I960
@xref{i960,, @command{ld} and the Intel 960 family}.
@end ifset
-
+@ifset XTENSA
+@xref{Xtensa,, @command{ld} and Xtensa Processors}.
+@end ifset
On some platforms, the @samp{--relax} option performs global
optimizations that become possible when the linker resolves addressing
@item --add-stdcall-alias
If given, symbols with a stdcall suffix (@@@var{nn}) will be exported
as-is and also with the suffix stripped.
+[This option is specific to the i386 PE targeted port of the linker]
@kindex --base-file
@item --base-file @var{file}
Use @var{file} as the name of a file in which to save the base
addresses of all the relocations needed for generating DLLs with
@file{dlltool}.
+[This is an i386 PE specific option]
@kindex --dll
@item --dll
Create a DLL instead of a regular executable. You may also use
@option{-shared} or specify a @code{LIBRARY} in a given @code{.def}
file.
+[This option is specific to the i386 PE targeted port of the linker]
@kindex --enable-stdcall-fixup
@kindex --disable-stdcall-fixup
feature is fully enabled and warnings are not printed. If you specify
@option{--disable-stdcall-fixup}, this feature is disabled and such
mismatches are considered to be errors.
+[This option is specific to the i386 PE targeted port of the linker]
@cindex DLLs, creating
@kindex --export-all-symbols
@code{_fmode}, @code{_impure_ptr}, @code{cygwin_attach_dll},
@code{cygwin_premain0}, @code{cygwin_premain1}, @code{cygwin_premain2},
@code{cygwin_premain3}, and @code{environ}.
+[This option is specific to the i386 PE targeted port of the linker]
@kindex --exclude-symbols
@item --exclude-symbols @var{symbol},@var{symbol},...
Specifies a list of symbols which should not be automatically
exported. The symbol names may be delimited by commas or colons.
+[This option is specific to the i386 PE targeted port of the linker]
@kindex --exclude-libs
@item --exclude-libs @var{lib},@var{lib},...
@code{--exclude-libs ALL} excludes symbols in all archive libraries from
automatic export. Symbols explicitly listed in a .def file are still exported,
regardless of this option.
+[This option is specific to the i386 PE targeted port of the linker]
@kindex --file-alignment
@item --file-alignment
Specify the file alignment. Sections in the file will always begin at
file offsets which are multiples of this number. This defaults to
512.
+[This option is specific to the i386 PE targeted port of the linker]
@cindex heap size
@kindex --heap
Specify the amount of memory to reserve (and optionally commit) to be
used as heap for this program. The default is 1Mb reserved, 4K
committed.
+[This option is specific to the i386 PE targeted port of the linker]
@cindex image base
@kindex --image-base
your dlls, each should have a unique base address and not overlap any
other dlls. The default is 0x400000 for executables, and 0x10000000
for dlls.
+[This option is specific to the i386 PE targeted port of the linker]
@kindex --kill-at
@item --kill-at
If given, the stdcall suffixes (@@@var{nn}) will be stripped from
symbols before they are exported.
+[This option is specific to the i386 PE targeted port of the linker]
@kindex --major-image-version
@item --major-image-version @var{value}
Sets the major number of the ``image version''. Defaults to 1.
+[This option is specific to the i386 PE targeted port of the linker]
@kindex --major-os-version
@item --major-os-version @var{value}
Sets the major number of the ``os version''. Defaults to 4.
+[This option is specific to the i386 PE targeted port of the linker]
@kindex --major-subsystem-version
@item --major-subsystem-version @var{value}
Sets the major number of the ``subsystem version''. Defaults to 4.
+[This option is specific to the i386 PE targeted port of the linker]
@kindex --minor-image-version
@item --minor-image-version @var{value}
Sets the minor number of the ``image version''. Defaults to 0.
+[This option is specific to the i386 PE targeted port of the linker]
@kindex --minor-os-version
@item --minor-os-version @var{value}
Sets the minor number of the ``os version''. Defaults to 0.
+[This option is specific to the i386 PE targeted port of the linker]
@kindex --minor-subsystem-version
@item --minor-subsystem-version @var{value}
Sets the minor number of the ``subsystem version''. Defaults to 0.
+[This option is specific to the i386 PE targeted port of the linker]
@cindex DEF files, creating
@cindex DLLs, creating
(which should be called @code{*.def}) may be used to create an import
library with @code{dlltool} or may be used as a reference to
automatically or implicitly exported symbols.
+[This option is specific to the i386 PE targeted port of the linker]
@cindex DLLs, creating
@kindex --out-implib
may be used to link clients against the generated DLL; this behavior
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
from the dllname to create unique image bases for each DLL, in-memory
collisions and relocations which can delay program execution are
avoided.
+[This option is specific to the i386 PE targeted port of the linker]
@kindex --disable-auto-image-base
@item --disable-auto-image-base
Do not automatically generate a unique image base. If there is no
user-specified image base (@code{--image-base}) then use the platform
default.
+[This option is specific to the i386 PE targeted port of the linker]
@cindex DLLs, linking to
@kindex --dll-search-prefix
between DLLs built for the various "subplatforms": native, cygwin,
uwin, pw, etc. For instance, cygwin DLLs typically use
@code{--dll-search-prefix=cyg}.
+[This option is specific to the i386 PE targeted port of the linker]
@kindex --enable-auto-import
@item --enable-auto-import
library to use a functional interface rather than a data interface
for the offending variables (e.g. set_foo() and get_foo() accessor
functions).
+[This option is specific to the i386 PE targeted port of the linker]
@kindex --disable-auto-import
@item --disable-auto-import
Do not attempt to do sophisticalted linking of @code{_symbol} to
@code{__imp__symbol} for DATA imports from DLLs.
+[This option is specific to the i386 PE targeted port of the linker]
@kindex --enable-runtime-pseudo-reloc
@item --enable-runtime-pseudo-reloc
that is, DATA imports from DLL with non-zero offset, this switch will create
a vector of 'runtime pseudo relocations' which can be used by runtime
environment to adjust references to such data in your client code.
+[This option is specific to the i386 PE targeted port of the linker]
@kindex --disable-runtime-pseudo-reloc
@item --disable-runtime-pseudo-reloc
Do not create pseudo relocations for non-zero offset DATA imports from
DLLs. This is the default.
+[This option is specific to the i386 PE targeted port of the linker]
@kindex --enable-extra-pe-debug
@item --enable-extra-pe-debug
Show additional debug info related to auto-import symbol thunking.
+[This option is specific to the i386 PE targeted port of the linker]
@kindex --section-alignment
@item --section-alignment
Sets the section alignment. Sections in memory will always begin at
addresses which are a multiple of this number. Defaults to 0x1000.
+[This option is specific to the i386 PE targeted port of the linker]
@cindex stack size
@kindex --stack
Specify the amount of memory to reserve (and optionally commit) to be
used as stack for this program. The default is 2Mb reserved, 4K
committed.
+[This option is specific to the i386 PE targeted port of the linker]
@kindex --subsystem
@item --subsystem @var{which}
legal values for @var{which} are @code{native}, @code{windows},
@code{console}, and @code{posix}. You may optionally set the
subsystem version also.
+[This option is specific to the i386 PE targeted port of the linker]
@end table
@ifset WIN32
* WIN32:: @command{ld} and WIN32 (cygwin/mingw)
@end ifset
+@ifset XTENSA
+* Xtensa:: @command{ld} and Xtensa Processors
+@end ifset
@end menu
@end ifset
@end ifset
@ifclear GENERIC
-@ifset Hitachi
+@ifset Renesas
@c This stuff is pointless to say unless you're especially concerned
-@c with Hitachi chips; don't enable it for generic case, please.
-@node Hitachi
-@chapter @command{ld} and Other Hitachi Chips
+@c with Renesas chips; don't enable it for generic case, please.
+@node Renesas
+@chapter @command{ld} and Other Renesas Chips
-@command{ld} also supports the H8/300H, the H8/500, and the Hitachi SH. No
-special features, commands, or command-line options are required for
-these chips.
+@command{ld} also supports the Renesas (formerly Hitachi) H8/300H,
+H8/500, and SH chips. No special features, commands, or command-line
+options are required for these chips.
@end ifset
@end ifclear
@end ifclear
@end ifset
+@ifset XTENSA
+@ifclear GENERIC
+@raisesections
+@end ifclear
+
+@node Xtensa
+@section @code{ld} and Xtensa Processors
+
+@cindex Xtensa processors
+The default @command{ld} behavior for Xtensa processors is to interpret
+@code{SECTIONS} commands so that lists of explicitly named sections in a
+specification with a wildcard file will be interleaved when necessary to
+keep literal pools within the range of PC-relative load offsets. For
+example, with the command:
+
+@smallexample
+SECTIONS
+@{
+ .text : @{
+ *(.literal .text)
+ @}
+@}
+@end smallexample
+
+@noindent
+@command{ld} may interleave some of the @code{.literal}
+and @code{.text} sections from different object files to ensure that the
+literal pools are within the range of PC-relative load offsets. A valid
+interleaving might place the @code{.literal} sections from an initial
+group of files followed by the @code{.text} sections of that group of
+files. Then, the @code{.literal} sections from the rest of the files
+and the @code{.text} sections from the rest of the files would follow.
+The non-interleaved order can still be specified as:
+
+@smallexample
+SECTIONS
+@{
+ .text : @{
+ *(.literal) *(.text)
+ @}
+@}
+@end smallexample
+
+@cindex @code{--relax} on Xtensa
+@cindex relaxing on Xtensa
+@kindex --no-relax
+The Xtensa version of @command{ld} enables the @option{--relax} option by
+default to attempt to reduce space in the output image by combining
+literals with identical values. It also provides the
+@option{--no-relax} option to disable this optimization. When enabled,
+the relaxation algorithm ensures that a literal will only be merged with
+another literal when the new merged literal location is within the
+offset range of all of its uses.
+
+The relaxation mechanism will also attempt to optimize
+assembler-generated ``longcall'' sequences of
+@code{L32R}/@code{CALLX@var{n}} when the target is known to fit into a
+@code{CALL@var{n}} instruction encoding. The current optimization
+converts the sequence into @code{NOP}/@code{CALL@var{n}} and removes the
+literal referenced by the @code{L32R} instruction.
+
+@ifclear GENERIC
+@lowersections
+@end ifclear
+@end ifset
+
@ifclear SingleFormat
@node BFD
@chapter BFD
projects / deliverable / binutils-gdb.git / blobdiff