@set I960
@set M68HC11
@set M68K
+@set MIPS
@set MMIX
@set MSP430
+@set NDS32
+@set NIOSII
@set POWERPC
@set POWERPC64
@set Renesas
@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
@itemx --gpsize=@var{value}
Set the maximum size of objects to be optimized using the GP register to
@var{size}. This is only meaningful for object file formats such as
-MIPS ECOFF which supports putting large and small objects into different
+MIPS ELF that support putting large and small objects into different
sections. This is ignored for other object file formats.
@cindex runtime library name
easily processed by a script if necessary. The symbols are printed out,
sorted by name. For each symbol, a list of file names is given. If the
symbol is defined, the first file listed is the location of the
-definition. The remaining files contain references to the symbol.
+definition. If the symbol is defined as a common value then any files
+where this happens appear next. Finally any files that reference the
+symbol are listed.
@cindex common allocation
@kindex --no-define-common
@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
@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}
@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.
@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]
@item --tsaware
The image is Terminal Server aware.
+@kindex --insert-timestamp
+@item --insert-timestamp
+Insert a real timestamp into the image, rather than the default value
+of zero. This will result in a slightly different results with each
+invocation, which could be helpful for distributing unique images.
@end table
@c man end
@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 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.
+
+@end table
+
+@c man end
+@end ifset
+
@ifset UsesEnvVars
@node Environment
@section Environment Variables
int foo = 1000;
@end smallexample
-creates a entry called @samp{foo} in the symbol table. This entry
+creates an entry called @samp{foo} in the symbol table. This entry
holds the address of an @samp{int} sized block of memory where the
number 1000 is initially stored.
int * a = & foo;
@end smallexample
-looks up the symbol @samp{foo} in the symbol table, gets it address
+looks up the symbol @samp{foo} in the symbol table, gets its address
and then copies this address into the block of memory associated with
the variable @samp{a}.
@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}]
@{
@cindex SORT_BY_ALIGNMENT
@code{SORT_BY_ALIGNMENT} is very similar to @code{SORT_BY_NAME}. The
difference is @code{SORT_BY_ALIGNMENT} will sort sections into
-ascending order by alignment before placing them in the output file.
+descending order by alignment before placing them in the output file.
+Larger alignments are placed before smaller alignments in order to
+reduce the amount of padding necessary.
@cindex SORT_BY_INIT_PRIORITY
@code{SORT_BY_INIT_PRIORITY} is very similar to @code{SORT_BY_NAME}. The
@enumerate
@item
@code{SORT_BY_NAME} (@code{SORT_BY_ALIGNMENT} (wildcard section pattern)).
-It will sort the input sections by name first, then by alignment if 2
+It will sort the input sections by name first, then by alignment if two
sections have the same name.
@item
@code{SORT_BY_ALIGNMENT} (@code{SORT_BY_NAME} (wildcard section pattern)).
-It will sort the input sections by alignment first, then by name if 2
+It will sort the input sections by alignment first, then by name if two
sections have the same alignment.
@item
@code{SORT_BY_NAME} (@code{SORT_BY_NAME} (wildcard section pattern)) is
@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
@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}.
@item SEGMENT_START(@var{segment}, @var{default})
@kindex SEGMENT_START(@var{segment}, @var{default})
Return the base address of the named @var{segment}. If an explicit
-value has been given for this segment (with a command-line @samp{-T}
-option) that value will be returned; otherwise the value will be
-@var{default}. At present, the @samp{-T} command-line option can only
-be used to set the base address for the ``text'', ``data'', and
+value has already been given for this segment (with a command-line
+@samp{-T} option) then that value will be returned otherwise the value
+will be @var{default}. At present, the @samp{-T} command-line option
+can only be used to set the base address for the ``text'', ``data'', and
``bss'' sections, but you can use @code{SEGMENT_START} with any segment
name.
@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
@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.
+
+@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
projects / deliverable / binutils-gdb.git / blobdiff