\input texinfo
@setfilename ld.info
-@c Copyright 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000,
-@c 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011,
-@c 2012, 2013
-@c Free Software Foundation, Inc.
+@c Copyright 1991-2013 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 POWERPC
@end ifset
version @value{VERSION}.
-Copyright @copyright{} 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000,
-2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2012, 2013
-Free Software Foundation, Inc.
+Copyright @copyright{} 1991-2013 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, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
-1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009,
-2012, 2013 Free Software Foundation, Inc.
+Copyright @copyright{} 1991-2013 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
@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
the linker will add a DT_NEEDED tag for each dynamic library mentioned
on the command line, regardless of whether the library is actually
needed or not. @option{--as-needed} causes a DT_NEEDED tag to only be
-emitted for a library that satisfies an undefined symbol reference
-from a regular object file or, if the library is not found in the
-DT_NEEDED lists of other libraries linked up to that point, an
-undefined symbol reference from another dynamic library.
-@option{--no-as-needed} restores the default behaviour.
+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.
+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
+from archives. @option{--no-as-needed} restores the default behaviour.
@kindex --add-needed
@kindex --no-add-needed
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
On SunOS, if the @option{-rpath} option was not used, search any
directories specified using @option{-L} options.
@item
-For a native linker, the search the contents of the environment
+For a native linker, search the contents of the environment
variable @code{LD_LIBRARY_PATH}.
@item
For a native ELF linker, the directories in @code{DT_RUNPATH} or
@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.
+DLLs.
[This option is specific to the i386 PE targeted port of the linker]
@kindex --enable-extra-pe-debug
@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
Each section in an object file has a name and a size. Most sections
also have an associated block of data, known as the @dfn{section
-contents}. A section may be marked as @dfn{loadable}, which mean that
+contents}. A section may be marked as @dfn{loadable}, which means that
the contents should be loaded into memory when the output file is run.
A section with no contents may be @dfn{allocatable}, which means that an
area in memory should be set aside, but nothing in particular should be
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}.
@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
and defaults to the start address; the start address is also optional,
and defaults to the current value of the location counter).
-If the @code{NOCROSSREFS} keyword is used, and there any references
-among the sections, the linker will report an error. Since the sections
-all run at the same address, it normally does not make sense for one
-section to refer directly to another. @xref{Miscellaneous Commands,
-NOCROSSREFS}.
+If the @code{NOCROSSREFS} keyword is used, and there are any
+references among the sections, the linker will report an error. Since
+the sections all run at the same address, it normally does not make
+sense for one section to refer directly to another.
+@xref{Miscellaneous Commands, NOCROSSREFS}.
For each section within the @code{OVERLAY}, the linker automatically
provides two symbols. The symbol @code{__load_start_@var{secname}} is
@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
@cindex synthesizing on H8/300
@item synthesizing instructions
-@c FIXME: specifically mov.b, or any mov instructions really?
+@c FIXME: specifically mov.b, or any mov instructions really? -> mov.b only, at least on H8, H8H, H8S
@command{ld} finds all @code{mov.b} instructions which use the
sixteen-bit absolute address form, but refer to the top
page of memory, and changes them to use the eight-bit address form.
@samp{mov.b @code{@@}@var{aa}:8} whenever the address @var{aa} is in the
top page of memory).
+@command{ld} finds all @code{mov} instructions which use the register
+indirect with 32-bit displacement addressing mode, but use a small
+displacement inside 16-bit displacement range, and changes them to use
+the 16-bit displacement form. (That is: the linker turns @samp{mov.b
+@code{@@}@var{d}:32,ERx} into @samp{mov.b @code{@@}@var{d}:16,ERx}
+whenever the displacement @var{d} is in the 16 bit signed integer
+range. Only implemented in ELF-format ld).
+
@item bit manipulation instructions
@command{ld} finds all bit manipulation instructions like @code{band, bclr,
biand, bild, bior, bist, bixor, bld, bnot, bor, bset, bst, btst, bxor}
@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
projects / binutils-gdb.git / blobdiff