\input texinfo
|
\input texinfo
|
@setfilename ldint.info
|
@setfilename ldint.info
|
@c Copyright 1992, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001,
|
@c Copyright 1992, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001,
|
@c 2003, 2007
|
@c 2003, 2007
|
@c Free Software Foundation, Inc.
|
@c Free Software Foundation, Inc.
|
|
|
@ifinfo
|
@ifinfo
|
@format
|
@format
|
START-INFO-DIR-ENTRY
|
START-INFO-DIR-ENTRY
|
* Ld-Internals: (ldint). The GNU linker internals.
|
* Ld-Internals: (ldint). The GNU linker internals.
|
END-INFO-DIR-ENTRY
|
END-INFO-DIR-ENTRY
|
@end format
|
@end format
|
@end ifinfo
|
@end ifinfo
|
|
|
@copying
|
@copying
|
This file documents the internals of the GNU linker ld.
|
This file documents the internals of the GNU linker ld.
|
|
|
Copyright @copyright{} 1992, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2007
|
Copyright @copyright{} 1992, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2007
|
Free Software Foundation, Inc.
|
Free Software Foundation, Inc.
|
Contributed by Cygnus Support.
|
Contributed by Cygnus Support.
|
|
|
Permission is granted to copy, distribute and/or modify this document
|
Permission is granted to copy, distribute and/or modify this document
|
under the terms of the GNU Free Documentation License, Version 1.1 or
|
under the terms of the GNU Free Documentation License, Version 1.1 or
|
any later version published by the Free Software Foundation; with the
|
any later version published by the Free Software Foundation; with the
|
Invariant Sections being ``GNU General Public License'' and ``Funding
|
Invariant Sections being ``GNU General Public License'' and ``Funding
|
Free Software'', the Front-Cover texts being (a) (see below), and with
|
Free Software'', the Front-Cover texts being (a) (see below), and with
|
the Back-Cover Texts being (b) (see below). A copy of the license is
|
the Back-Cover Texts being (b) (see below). A copy of the license is
|
included in the section entitled ``GNU Free Documentation License''.
|
included in the section entitled ``GNU Free Documentation License''.
|
|
|
(a) The FSF's Front-Cover Text is:
|
(a) The FSF's Front-Cover Text is:
|
|
|
A GNU Manual
|
A GNU Manual
|
|
|
(b) The FSF's Back-Cover Text is:
|
(b) The FSF's Back-Cover Text is:
|
|
|
You have freedom to copy and modify this GNU Manual, like GNU
|
You have freedom to copy and modify this GNU Manual, like GNU
|
software. Copies published by the Free Software Foundation raise
|
software. Copies published by the Free Software Foundation raise
|
funds for GNU development.
|
funds for GNU development.
|
@end copying
|
@end copying
|
|
|
@iftex
|
@iftex
|
@finalout
|
@finalout
|
@setchapternewpage off
|
@setchapternewpage off
|
@settitle GNU Linker Internals
|
@settitle GNU Linker Internals
|
@titlepage
|
@titlepage
|
@title{A guide to the internals of the GNU linker}
|
@title{A guide to the internals of the GNU linker}
|
@author Per Bothner, Steve Chamberlain, Ian Lance Taylor, DJ Delorie
|
@author Per Bothner, Steve Chamberlain, Ian Lance Taylor, DJ Delorie
|
@author Cygnus Support
|
@author Cygnus Support
|
@page
|
@page
|
|
|
@tex
|
@tex
|
\def\$#1${{#1}} % Kluge: collect RCS revision info without $...$
|
\def\$#1${{#1}} % Kluge: collect RCS revision info without $...$
|
\xdef\manvers{2.10.91} % For use in headers, footers too
|
\xdef\manvers{2.10.91} % For use in headers, footers too
|
{\parskip=0pt
|
{\parskip=0pt
|
\hfill Cygnus Support\par
|
\hfill Cygnus Support\par
|
\hfill \manvers\par
|
\hfill \manvers\par
|
\hfill \TeX{}info \texinfoversion\par
|
\hfill \TeX{}info \texinfoversion\par
|
}
|
}
|
@end tex
|
@end tex
|
|
|
@vskip 0pt plus 1filll
|
@vskip 0pt plus 1filll
|
Copyright @copyright{} 1992, 93, 94, 95, 96, 97, 1998, 2000
|
Copyright @copyright{} 1992, 93, 94, 95, 96, 97, 1998, 2000
|
Free Software Foundation, Inc.
|
Free Software Foundation, Inc.
|
|
|
Permission is granted to copy, distribute and/or modify this document
|
Permission is granted to copy, distribute and/or modify this document
|
under the terms of the GNU Free Documentation License, Version 1.1
|
under the terms of the GNU Free Documentation License, Version 1.1
|
or any later version published by the Free Software Foundation;
|
or any later version published by the Free Software Foundation;
|
with no Invariant Sections, with no Front-Cover Texts, and with no
|
with no Invariant Sections, with no Front-Cover Texts, and with no
|
Back-Cover Texts. A copy of the license is included in the
|
Back-Cover Texts. A copy of the license is included in the
|
section entitled "GNU Free Documentation License".
|
section entitled "GNU Free Documentation License".
|
|
|
@end titlepage
|
@end titlepage
|
@end iftex
|
@end iftex
|
|
|
@node Top
|
@node Top
|
@top
|
@top
|
|
|
This file documents the internals of the GNU linker @code{ld}. It is a
|
This file documents the internals of the GNU linker @code{ld}. It is a
|
collection of miscellaneous information with little form at this point.
|
collection of miscellaneous information with little form at this point.
|
Mostly, it is a repository into which you can put information about
|
Mostly, it is a repository into which you can put information about
|
GNU @code{ld} as you discover it (or as you design changes to @code{ld}).
|
GNU @code{ld} as you discover it (or as you design changes to @code{ld}).
|
|
|
This document is distributed under the terms of the GNU Free
|
This document is distributed under the terms of the GNU Free
|
Documentation License. A copy of the license is included in the
|
Documentation License. A copy of the license is included in the
|
section entitled "GNU Free Documentation License".
|
section entitled "GNU Free Documentation License".
|
|
|
@menu
|
@menu
|
* README:: The README File
|
* README:: The README File
|
* Emulations:: How linker emulations are generated
|
* Emulations:: How linker emulations are generated
|
* Emulation Walkthrough:: A Walkthrough of a Typical Emulation
|
* Emulation Walkthrough:: A Walkthrough of a Typical Emulation
|
* Architecture Specific:: Some Architecture Specific Notes
|
* Architecture Specific:: Some Architecture Specific Notes
|
* GNU Free Documentation License:: GNU Free Documentation License
|
* GNU Free Documentation License:: GNU Free Documentation License
|
@end menu
|
@end menu
|
|
|
@node README
|
@node README
|
@chapter The @file{README} File
|
@chapter The @file{README} File
|
|
|
Check the @file{README} file; it often has useful information that does not
|
Check the @file{README} file; it often has useful information that does not
|
appear anywhere else in the directory.
|
appear anywhere else in the directory.
|
|
|
@node Emulations
|
@node Emulations
|
@chapter How linker emulations are generated
|
@chapter How linker emulations are generated
|
|
|
Each linker target has an @dfn{emulation}. The emulation includes the
|
Each linker target has an @dfn{emulation}. The emulation includes the
|
default linker script, and certain emulations also modify certain types
|
default linker script, and certain emulations also modify certain types
|
of linker behaviour.
|
of linker behaviour.
|
|
|
Emulations are created during the build process by the shell script
|
Emulations are created during the build process by the shell script
|
@file{genscripts.sh}.
|
@file{genscripts.sh}.
|
|
|
The @file{genscripts.sh} script starts by reading a file in the
|
The @file{genscripts.sh} script starts by reading a file in the
|
@file{emulparams} directory. This is a shell script which sets various
|
@file{emulparams} directory. This is a shell script which sets various
|
shell variables used by @file{genscripts.sh} and the other shell scripts
|
shell variables used by @file{genscripts.sh} and the other shell scripts
|
it invokes.
|
it invokes.
|
|
|
The @file{genscripts.sh} script will invoke a shell script in the
|
The @file{genscripts.sh} script will invoke a shell script in the
|
@file{scripttempl} directory in order to create default linker scripts
|
@file{scripttempl} directory in order to create default linker scripts
|
written in the linker command language. The @file{scripttempl} script
|
written in the linker command language. The @file{scripttempl} script
|
will be invoked 5 (or, in some cases, 6) times, with different
|
will be invoked 5 (or, in some cases, 6) times, with different
|
assignments to shell variables, to create different default scripts.
|
assignments to shell variables, to create different default scripts.
|
The choice of script is made based on the command line options.
|
The choice of script is made based on the command line options.
|
|
|
After creating the scripts, @file{genscripts.sh} will invoke yet another
|
After creating the scripts, @file{genscripts.sh} will invoke yet another
|
shell script, this time in the @file{emultempl} directory. That shell
|
shell script, this time in the @file{emultempl} directory. That shell
|
script will create the emulation source file, which contains C code.
|
script will create the emulation source file, which contains C code.
|
This C code permits the linker emulation to override various linker
|
This C code permits the linker emulation to override various linker
|
behaviours. Most targets use the generic emulation code, which is in
|
behaviours. Most targets use the generic emulation code, which is in
|
@file{emultempl/generic.em}.
|
@file{emultempl/generic.em}.
|
|
|
To summarize, @file{genscripts.sh} reads three shell scripts: an
|
To summarize, @file{genscripts.sh} reads three shell scripts: an
|
emulation parameters script in the @file{emulparams} directory, a linker
|
emulation parameters script in the @file{emulparams} directory, a linker
|
script generation script in the @file{scripttempl} directory, and an
|
script generation script in the @file{scripttempl} directory, and an
|
emulation source file generation script in the @file{emultempl}
|
emulation source file generation script in the @file{emultempl}
|
directory.
|
directory.
|
|
|
For example, the Sun 4 linker sets up variables in
|
For example, the Sun 4 linker sets up variables in
|
@file{emulparams/sun4.sh}, creates linker scripts using
|
@file{emulparams/sun4.sh}, creates linker scripts using
|
@file{scripttempl/aout.sc}, and creates the emulation code using
|
@file{scripttempl/aout.sc}, and creates the emulation code using
|
@file{emultempl/sunos.em}.
|
@file{emultempl/sunos.em}.
|
|
|
Note that the linker can support several emulations simultaneously,
|
Note that the linker can support several emulations simultaneously,
|
depending upon how it is configured. An emulation can be selected with
|
depending upon how it is configured. An emulation can be selected with
|
the @code{-m} option. The @code{-V} option will list all supported
|
the @code{-m} option. The @code{-V} option will list all supported
|
emulations.
|
emulations.
|
|
|
@menu
|
@menu
|
* emulation parameters:: @file{emulparams} scripts
|
* emulation parameters:: @file{emulparams} scripts
|
* linker scripts:: @file{scripttempl} scripts
|
* linker scripts:: @file{scripttempl} scripts
|
* linker emulations:: @file{emultempl} scripts
|
* linker emulations:: @file{emultempl} scripts
|
@end menu
|
@end menu
|
|
|
@node emulation parameters
|
@node emulation parameters
|
@section @file{emulparams} scripts
|
@section @file{emulparams} scripts
|
|
|
Each target selects a particular file in the @file{emulparams} directory
|
Each target selects a particular file in the @file{emulparams} directory
|
by setting the shell variable @code{targ_emul} in @file{configure.tgt}.
|
by setting the shell variable @code{targ_emul} in @file{configure.tgt}.
|
This shell variable is used by the @file{configure} script to control
|
This shell variable is used by the @file{configure} script to control
|
building an emulation source file.
|
building an emulation source file.
|
|
|
Certain conventions are enforced. Suppose the @code{targ_emul} variable
|
Certain conventions are enforced. Suppose the @code{targ_emul} variable
|
is set to @var{emul} in @file{configure.tgt}. The name of the emulation
|
is set to @var{emul} in @file{configure.tgt}. The name of the emulation
|
shell script will be @file{emulparams/@var{emul}.sh}. The
|
shell script will be @file{emulparams/@var{emul}.sh}. The
|
@file{Makefile} must have a target named @file{e@var{emul}.c}; this
|
@file{Makefile} must have a target named @file{e@var{emul}.c}; this
|
target must depend upon @file{emulparams/@var{emul}.sh}, as well as the
|
target must depend upon @file{emulparams/@var{emul}.sh}, as well as the
|
appropriate scripts in the @file{scripttempl} and @file{emultempl}
|
appropriate scripts in the @file{scripttempl} and @file{emultempl}
|
directories. The @file{Makefile} target must invoke @code{GENSCRIPTS}
|
directories. The @file{Makefile} target must invoke @code{GENSCRIPTS}
|
with two arguments: @var{emul}, and the value of the make variable
|
with two arguments: @var{emul}, and the value of the make variable
|
@code{tdir_@var{emul}}. The value of the latter variable will be set by
|
@code{tdir_@var{emul}}. The value of the latter variable will be set by
|
the @file{configure} script, and is used to set the default target
|
the @file{configure} script, and is used to set the default target
|
directory to search.
|
directory to search.
|
|
|
By convention, the @file{emulparams/@var{emul}.sh} shell script should
|
By convention, the @file{emulparams/@var{emul}.sh} shell script should
|
only set shell variables. It may set shell variables which are to be
|
only set shell variables. It may set shell variables which are to be
|
interpreted by the @file{scripttempl} and the @file{emultempl} scripts.
|
interpreted by the @file{scripttempl} and the @file{emultempl} scripts.
|
Certain shell variables are interpreted directly by the
|
Certain shell variables are interpreted directly by the
|
@file{genscripts.sh} script.
|
@file{genscripts.sh} script.
|
|
|
Here is a list of shell variables interpreted by @file{genscripts.sh},
|
Here is a list of shell variables interpreted by @file{genscripts.sh},
|
as well as some conventional shell variables interpreted by the
|
as well as some conventional shell variables interpreted by the
|
@file{scripttempl} and @file{emultempl} scripts.
|
@file{scripttempl} and @file{emultempl} scripts.
|
|
|
@table @code
|
@table @code
|
@item SCRIPT_NAME
|
@item SCRIPT_NAME
|
This is the name of the @file{scripttempl} script to use. If
|
This is the name of the @file{scripttempl} script to use. If
|
@code{SCRIPT_NAME} is set to @var{script}, @file{genscripts.sh} will use
|
@code{SCRIPT_NAME} is set to @var{script}, @file{genscripts.sh} will use
|
the script @file{scripttempl/@var{script}.sc}.
|
the script @file{scripttempl/@var{script}.sc}.
|
|
|
@item TEMPLATE_NAME
|
@item TEMPLATE_NAME
|
This is the name of the @file{emultempl} script to use. If
|
This is the name of the @file{emultempl} script to use. If
|
@code{TEMPLATE_NAME} is set to @var{template}, @file{genscripts.sh} will
|
@code{TEMPLATE_NAME} is set to @var{template}, @file{genscripts.sh} will
|
use the script @file{emultempl/@var{template}.em}. If this variable is
|
use the script @file{emultempl/@var{template}.em}. If this variable is
|
not set, the default value is @samp{generic}.
|
not set, the default value is @samp{generic}.
|
|
|
@item GENERATE_SHLIB_SCRIPT
|
@item GENERATE_SHLIB_SCRIPT
|
If this is set to a nonempty string, @file{genscripts.sh} will invoke
|
If this is set to a nonempty string, @file{genscripts.sh} will invoke
|
the @file{scripttempl} script an extra time to create a shared library
|
the @file{scripttempl} script an extra time to create a shared library
|
script. @ref{linker scripts}.
|
script. @ref{linker scripts}.
|
|
|
@item OUTPUT_FORMAT
|
@item OUTPUT_FORMAT
|
This is normally set to indicate the BFD output format use (e.g.,
|
This is normally set to indicate the BFD output format use (e.g.,
|
@samp{"a.out-sunos-big"}. The @file{scripttempl} script will normally
|
@samp{"a.out-sunos-big"}. The @file{scripttempl} script will normally
|
use it in an @code{OUTPUT_FORMAT} expression in the linker script.
|
use it in an @code{OUTPUT_FORMAT} expression in the linker script.
|
|
|
@item ARCH
|
@item ARCH
|
This is normally set to indicate the architecture to use (e.g.,
|
This is normally set to indicate the architecture to use (e.g.,
|
@samp{sparc}). The @file{scripttempl} script will normally use it in an
|
@samp{sparc}). The @file{scripttempl} script will normally use it in an
|
@code{OUTPUT_ARCH} expression in the linker script.
|
@code{OUTPUT_ARCH} expression in the linker script.
|
|
|
@item ENTRY
|
@item ENTRY
|
Some @file{scripttempl} scripts use this to set the entry address, in an
|
Some @file{scripttempl} scripts use this to set the entry address, in an
|
@code{ENTRY} expression in the linker script.
|
@code{ENTRY} expression in the linker script.
|
|
|
@item TEXT_START_ADDR
|
@item TEXT_START_ADDR
|
Some @file{scripttempl} scripts use this to set the start address of the
|
Some @file{scripttempl} scripts use this to set the start address of the
|
@samp{.text} section.
|
@samp{.text} section.
|
|
|
@item SEGMENT_SIZE
|
@item SEGMENT_SIZE
|
The @file{genscripts.sh} script uses this to set the default value of
|
The @file{genscripts.sh} script uses this to set the default value of
|
@code{DATA_ALIGNMENT} when running the @file{scripttempl} script.
|
@code{DATA_ALIGNMENT} when running the @file{scripttempl} script.
|
|
|
@item TARGET_PAGE_SIZE
|
@item TARGET_PAGE_SIZE
|
If @code{SEGMENT_SIZE} is not defined, the @file{genscripts.sh} script
|
If @code{SEGMENT_SIZE} is not defined, the @file{genscripts.sh} script
|
uses this to define it.
|
uses this to define it.
|
|
|
@item ALIGNMENT
|
@item ALIGNMENT
|
Some @file{scripttempl} scripts set this to a number to pass to
|
Some @file{scripttempl} scripts set this to a number to pass to
|
@code{ALIGN} to set the required alignment for the @code{end} symbol.
|
@code{ALIGN} to set the required alignment for the @code{end} symbol.
|
@end table
|
@end table
|
|
|
@node linker scripts
|
@node linker scripts
|
@section @file{scripttempl} scripts
|
@section @file{scripttempl} scripts
|
|
|
Each linker target uses a @file{scripttempl} script to generate the
|
Each linker target uses a @file{scripttempl} script to generate the
|
default linker scripts. The name of the @file{scripttempl} script is
|
default linker scripts. The name of the @file{scripttempl} script is
|
set by the @code{SCRIPT_NAME} variable in the @file{emulparams} script.
|
set by the @code{SCRIPT_NAME} variable in the @file{emulparams} script.
|
If @code{SCRIPT_NAME} is set to @var{script}, @code{genscripts.sh} will
|
If @code{SCRIPT_NAME} is set to @var{script}, @code{genscripts.sh} will
|
invoke @file{scripttempl/@var{script}.sc}.
|
invoke @file{scripttempl/@var{script}.sc}.
|
|
|
The @file{genscripts.sh} script will invoke the @file{scripttempl}
|
The @file{genscripts.sh} script will invoke the @file{scripttempl}
|
script 5 to 9 times. Each time it will set the shell variable
|
script 5 to 9 times. Each time it will set the shell variable
|
@code{LD_FLAG} to a different value. When the linker is run, the
|
@code{LD_FLAG} to a different value. When the linker is run, the
|
options used will direct it to select a particular script. (Script
|
options used will direct it to select a particular script. (Script
|
selection is controlled by the @code{get_script} emulation entry point;
|
selection is controlled by the @code{get_script} emulation entry point;
|
this describes the conventional behaviour).
|
this describes the conventional behaviour).
|
|
|
The @file{scripttempl} script should just write a linker script, written
|
The @file{scripttempl} script should just write a linker script, written
|
in the linker command language, to standard output. If the emulation
|
in the linker command language, to standard output. If the emulation
|
name--the name of the @file{emulparams} file without the @file{.sc}
|
name--the name of the @file{emulparams} file without the @file{.sc}
|
extension--is @var{emul}, then the output will be directed to
|
extension--is @var{emul}, then the output will be directed to
|
@file{ldscripts/@var{emul}.@var{extension}} in the build directory,
|
@file{ldscripts/@var{emul}.@var{extension}} in the build directory,
|
where @var{extension} changes each time the @file{scripttempl} script is
|
where @var{extension} changes each time the @file{scripttempl} script is
|
invoked.
|
invoked.
|
|
|
Here is the list of values assigned to @code{LD_FLAG}.
|
Here is the list of values assigned to @code{LD_FLAG}.
|
|
|
@table @code
|
@table @code
|
@item (empty)
|
@item (empty)
|
The script generated is used by default (when none of the following
|
The script generated is used by default (when none of the following
|
cases apply). The output has an extension of @file{.x}.
|
cases apply). The output has an extension of @file{.x}.
|
@item n
|
@item n
|
The script generated is used when the linker is invoked with the
|
The script generated is used when the linker is invoked with the
|
@code{-n} option. The output has an extension of @file{.xn}.
|
@code{-n} option. The output has an extension of @file{.xn}.
|
@item N
|
@item N
|
The script generated is used when the linker is invoked with the
|
The script generated is used when the linker is invoked with the
|
@code{-N} option. The output has an extension of @file{.xbn}.
|
@code{-N} option. The output has an extension of @file{.xbn}.
|
@item r
|
@item r
|
The script generated is used when the linker is invoked with the
|
The script generated is used when the linker is invoked with the
|
@code{-r} option. The output has an extension of @file{.xr}.
|
@code{-r} option. The output has an extension of @file{.xr}.
|
@item u
|
@item u
|
The script generated is used when the linker is invoked with the
|
The script generated is used when the linker is invoked with the
|
@code{-Ur} option. The output has an extension of @file{.xu}.
|
@code{-Ur} option. The output has an extension of @file{.xu}.
|
@item shared
|
@item shared
|
The @file{scripttempl} script is only invoked with @code{LD_FLAG} set to
|
The @file{scripttempl} script is only invoked with @code{LD_FLAG} set to
|
this value if @code{GENERATE_SHLIB_SCRIPT} is defined in the
|
this value if @code{GENERATE_SHLIB_SCRIPT} is defined in the
|
@file{emulparams} file. The @file{emultempl} script must arrange to use
|
@file{emulparams} file. The @file{emultempl} script must arrange to use
|
this script at the appropriate time, normally when the linker is invoked
|
this script at the appropriate time, normally when the linker is invoked
|
with the @code{-shared} option. The output has an extension of
|
with the @code{-shared} option. The output has an extension of
|
@file{.xs}.
|
@file{.xs}.
|
@item c
|
@item c
|
The @file{scripttempl} script is only invoked with @code{LD_FLAG} set to
|
The @file{scripttempl} script is only invoked with @code{LD_FLAG} set to
|
this value if @code{GENERATE_COMBRELOC_SCRIPT} is defined in the
|
this value if @code{GENERATE_COMBRELOC_SCRIPT} is defined in the
|
@file{emulparams} file or if @code{SCRIPT_NAME} is @code{elf}. The
|
@file{emulparams} file or if @code{SCRIPT_NAME} is @code{elf}. The
|
@file{emultempl} script must arrange to use this script at the appropriate
|
@file{emultempl} script must arrange to use this script at the appropriate
|
time, normally when the linker is invoked with the @code{-z combreloc}
|
time, normally when the linker is invoked with the @code{-z combreloc}
|
option. The output has an extension of
|
option. The output has an extension of
|
@file{.xc}.
|
@file{.xc}.
|
@item cshared
|
@item cshared
|
The @file{scripttempl} script is only invoked with @code{LD_FLAG} set to
|
The @file{scripttempl} script is only invoked with @code{LD_FLAG} set to
|
this value if @code{GENERATE_COMBRELOC_SCRIPT} is defined in the
|
this value if @code{GENERATE_COMBRELOC_SCRIPT} is defined in the
|
@file{emulparams} file or if @code{SCRIPT_NAME} is @code{elf} and
|
@file{emulparams} file or if @code{SCRIPT_NAME} is @code{elf} and
|
@code{GENERATE_SHLIB_SCRIPT} is defined in the @file{emulparams} file.
|
@code{GENERATE_SHLIB_SCRIPT} is defined in the @file{emulparams} file.
|
The @file{emultempl} script must arrange to use this script at the
|
The @file{emultempl} script must arrange to use this script at the
|
appropriate time, normally when the linker is invoked with the @code{-shared
|
appropriate time, normally when the linker is invoked with the @code{-shared
|
-z combreloc} option. The output has an extension of @file{.xsc}.
|
-z combreloc} option. The output has an extension of @file{.xsc}.
|
@item auto_import
|
@item auto_import
|
The @file{scripttempl} script is only invoked with @code{LD_FLAG} set to
|
The @file{scripttempl} script is only invoked with @code{LD_FLAG} set to
|
this value if @code{GENERATE_AUTO_IMPORT_SCRIPT} is defined in the
|
this value if @code{GENERATE_AUTO_IMPORT_SCRIPT} is defined in the
|
@file{emulparams} file. The @file{emultempl} script must arrange to
|
@file{emulparams} file. The @file{emultempl} script must arrange to
|
use this script at the appropriate time, normally when the linker is
|
use this script at the appropriate time, normally when the linker is
|
invoked with the @code{--enable-auto-import} option. The output has
|
invoked with the @code{--enable-auto-import} option. The output has
|
an extension of @file{.xa}.
|
an extension of @file{.xa}.
|
@end table
|
@end table
|
|
|
Besides the shell variables set by the @file{emulparams} script, and the
|
Besides the shell variables set by the @file{emulparams} script, and the
|
@code{LD_FLAG} variable, the @file{genscripts.sh} script will set
|
@code{LD_FLAG} variable, the @file{genscripts.sh} script will set
|
certain variables for each run of the @file{scripttempl} script.
|
certain variables for each run of the @file{scripttempl} script.
|
|
|
@table @code
|
@table @code
|
@item RELOCATING
|
@item RELOCATING
|
This will be set to a non-empty string when the linker is doing a final
|
This will be set to a non-empty string when the linker is doing a final
|
relocation (e.g., all scripts other than @code{-r} and @code{-Ur}).
|
relocation (e.g., all scripts other than @code{-r} and @code{-Ur}).
|
|
|
@item CONSTRUCTING
|
@item CONSTRUCTING
|
This will be set to a non-empty string when the linker is building
|
This will be set to a non-empty string when the linker is building
|
global constructor and destructor tables (e.g., all scripts other than
|
global constructor and destructor tables (e.g., all scripts other than
|
@code{-r}).
|
@code{-r}).
|
|
|
@item DATA_ALIGNMENT
|
@item DATA_ALIGNMENT
|
This will be set to an @code{ALIGN} expression when the output should be
|
This will be set to an @code{ALIGN} expression when the output should be
|
page aligned, or to @samp{.} when generating the @code{-N} script.
|
page aligned, or to @samp{.} when generating the @code{-N} script.
|
|
|
@item CREATE_SHLIB
|
@item CREATE_SHLIB
|
This will be set to a non-empty string when generating a @code{-shared}
|
This will be set to a non-empty string when generating a @code{-shared}
|
script.
|
script.
|
|
|
@item COMBRELOC
|
@item COMBRELOC
|
This will be set to a non-empty string when generating @code{-z combreloc}
|
This will be set to a non-empty string when generating @code{-z combreloc}
|
scripts to a temporary file name which can be used during script generation.
|
scripts to a temporary file name which can be used during script generation.
|
@end table
|
@end table
|
|
|
The conventional way to write a @file{scripttempl} script is to first
|
The conventional way to write a @file{scripttempl} script is to first
|
set a few shell variables, and then write out a linker script using
|
set a few shell variables, and then write out a linker script using
|
@code{cat} with a here document. The linker script will use variable
|
@code{cat} with a here document. The linker script will use variable
|
substitutions, based on the above variables and those set in the
|
substitutions, based on the above variables and those set in the
|
@file{emulparams} script, to control its behaviour.
|
@file{emulparams} script, to control its behaviour.
|
|
|
When there are parts of the @file{scripttempl} script which should only
|
When there are parts of the @file{scripttempl} script which should only
|
be run when doing a final relocation, they should be enclosed within a
|
be run when doing a final relocation, they should be enclosed within a
|
variable substitution based on @code{RELOCATING}. For example, on many
|
variable substitution based on @code{RELOCATING}. For example, on many
|
targets special symbols such as @code{_end} should be defined when doing
|
targets special symbols such as @code{_end} should be defined when doing
|
a final link. Naturally, those symbols should not be defined when doing
|
a final link. Naturally, those symbols should not be defined when doing
|
a relocatable link using @code{-r}. The @file{scripttempl} script
|
a relocatable link using @code{-r}. The @file{scripttempl} script
|
could use a construct like this to define those symbols:
|
could use a construct like this to define those symbols:
|
@smallexample
|
@smallexample
|
$@{RELOCATING+ _end = .;@}
|
$@{RELOCATING+ _end = .;@}
|
@end smallexample
|
@end smallexample
|
This will do the symbol assignment only if the @code{RELOCATING}
|
This will do the symbol assignment only if the @code{RELOCATING}
|
variable is defined.
|
variable is defined.
|
|
|
The basic job of the linker script is to put the sections in the correct
|
The basic job of the linker script is to put the sections in the correct
|
order, and at the correct memory addresses. For some targets, the
|
order, and at the correct memory addresses. For some targets, the
|
linker script may have to do some other operations.
|
linker script may have to do some other operations.
|
|
|
For example, on most MIPS platforms, the linker is responsible for
|
For example, on most MIPS platforms, the linker is responsible for
|
defining the special symbol @code{_gp}, used to initialize the
|
defining the special symbol @code{_gp}, used to initialize the
|
@code{$gp} register. It must be set to the start of the small data
|
@code{$gp} register. It must be set to the start of the small data
|
section plus @code{0x8000}. Naturally, it should only be defined when
|
section plus @code{0x8000}. Naturally, it should only be defined when
|
doing a final relocation. This will typically be done like this:
|
doing a final relocation. This will typically be done like this:
|
@smallexample
|
@smallexample
|
$@{RELOCATING+ _gp = ALIGN(16) + 0x8000;@}
|
$@{RELOCATING+ _gp = ALIGN(16) + 0x8000;@}
|
@end smallexample
|
@end smallexample
|
This line would appear just before the sections which compose the small
|
This line would appear just before the sections which compose the small
|
data section (@samp{.sdata}, @samp{.sbss}). All those sections would be
|
data section (@samp{.sdata}, @samp{.sbss}). All those sections would be
|
contiguous in memory.
|
contiguous in memory.
|
|
|
Many COFF systems build constructor tables in the linker script. The
|
Many COFF systems build constructor tables in the linker script. The
|
compiler will arrange to output the address of each global constructor
|
compiler will arrange to output the address of each global constructor
|
in a @samp{.ctor} section, and the address of each global destructor in
|
in a @samp{.ctor} section, and the address of each global destructor in
|
a @samp{.dtor} section (this is done by defining
|
a @samp{.dtor} section (this is done by defining
|
@code{ASM_OUTPUT_CONSTRUCTOR} and @code{ASM_OUTPUT_DESTRUCTOR} in the
|
@code{ASM_OUTPUT_CONSTRUCTOR} and @code{ASM_OUTPUT_DESTRUCTOR} in the
|
@code{gcc} configuration files). The @code{gcc} runtime support
|
@code{gcc} configuration files). The @code{gcc} runtime support
|
routines expect the constructor table to be named @code{__CTOR_LIST__}.
|
routines expect the constructor table to be named @code{__CTOR_LIST__}.
|
They expect it to be a list of words, with the first word being the
|
They expect it to be a list of words, with the first word being the
|
count of the number of entries. There should be a trailing zero word.
|
count of the number of entries. There should be a trailing zero word.
|
(Actually, the count may be -1 if the trailing word is present, and the
|
(Actually, the count may be -1 if the trailing word is present, and the
|
trailing word may be omitted if the count is correct, but, as the
|
trailing word may be omitted if the count is correct, but, as the
|
@code{gcc} behaviour has changed slightly over the years, it is safest
|
@code{gcc} behaviour has changed slightly over the years, it is safest
|
to provide both). Here is a typical way that might be handled in a
|
to provide both). Here is a typical way that might be handled in a
|
@file{scripttempl} file.
|
@file{scripttempl} file.
|
@smallexample
|
@smallexample
|
$@{CONSTRUCTING+ __CTOR_LIST__ = .;@}
|
$@{CONSTRUCTING+ __CTOR_LIST__ = .;@}
|
$@{CONSTRUCTING+ LONG((__CTOR_END__ - __CTOR_LIST__) / 4 - 2)@}
|
$@{CONSTRUCTING+ LONG((__CTOR_END__ - __CTOR_LIST__) / 4 - 2)@}
|
$@{CONSTRUCTING+ *(.ctors)@}
|
$@{CONSTRUCTING+ *(.ctors)@}
|
$@{CONSTRUCTING+ LONG(0)@}
|
$@{CONSTRUCTING+ LONG(0)@}
|
$@{CONSTRUCTING+ __CTOR_END__ = .;@}
|
$@{CONSTRUCTING+ __CTOR_END__ = .;@}
|
$@{CONSTRUCTING+ __DTOR_LIST__ = .;@}
|
$@{CONSTRUCTING+ __DTOR_LIST__ = .;@}
|
$@{CONSTRUCTING+ LONG((__DTOR_END__ - __DTOR_LIST__) / 4 - 2)@}
|
$@{CONSTRUCTING+ LONG((__DTOR_END__ - __DTOR_LIST__) / 4 - 2)@}
|
$@{CONSTRUCTING+ *(.dtors)@}
|
$@{CONSTRUCTING+ *(.dtors)@}
|
$@{CONSTRUCTING+ LONG(0)@}
|
$@{CONSTRUCTING+ LONG(0)@}
|
$@{CONSTRUCTING+ __DTOR_END__ = .;@}
|
$@{CONSTRUCTING+ __DTOR_END__ = .;@}
|
@end smallexample
|
@end smallexample
|
The use of @code{CONSTRUCTING} ensures that these linker script commands
|
The use of @code{CONSTRUCTING} ensures that these linker script commands
|
will only appear when the linker is supposed to be building the
|
will only appear when the linker is supposed to be building the
|
constructor and destructor tables. This example is written for a target
|
constructor and destructor tables. This example is written for a target
|
which uses 4 byte pointers.
|
which uses 4 byte pointers.
|
|
|
Embedded systems often need to set a stack address. This is normally
|
Embedded systems often need to set a stack address. This is normally
|
best done by using the @code{PROVIDE} construct with a default stack
|
best done by using the @code{PROVIDE} construct with a default stack
|
address. This permits the user to easily override the stack address
|
address. This permits the user to easily override the stack address
|
using the @code{--defsym} option. Here is an example:
|
using the @code{--defsym} option. Here is an example:
|
@smallexample
|
@smallexample
|
$@{RELOCATING+ PROVIDE (__stack = 0x80000000);@}
|
$@{RELOCATING+ PROVIDE (__stack = 0x80000000);@}
|
@end smallexample
|
@end smallexample
|
The value of the symbol @code{__stack} would then be used in the startup
|
The value of the symbol @code{__stack} would then be used in the startup
|
code to initialize the stack pointer.
|
code to initialize the stack pointer.
|
|
|
@node linker emulations
|
@node linker emulations
|
@section @file{emultempl} scripts
|
@section @file{emultempl} scripts
|
|
|
Each linker target uses an @file{emultempl} script to generate the
|
Each linker target uses an @file{emultempl} script to generate the
|
emulation code. The name of the @file{emultempl} script is set by the
|
emulation code. The name of the @file{emultempl} script is set by the
|
@code{TEMPLATE_NAME} variable in the @file{emulparams} script. If the
|
@code{TEMPLATE_NAME} variable in the @file{emulparams} script. If the
|
@code{TEMPLATE_NAME} variable is not set, the default is
|
@code{TEMPLATE_NAME} variable is not set, the default is
|
@samp{generic}. If the value of @code{TEMPLATE_NAME} is @var{template},
|
@samp{generic}. If the value of @code{TEMPLATE_NAME} is @var{template},
|
@file{genscripts.sh} will use @file{emultempl/@var{template}.em}.
|
@file{genscripts.sh} will use @file{emultempl/@var{template}.em}.
|
|
|
Most targets use the generic @file{emultempl} script,
|
Most targets use the generic @file{emultempl} script,
|
@file{emultempl/generic.em}. A different @file{emultempl} script is
|
@file{emultempl/generic.em}. A different @file{emultempl} script is
|
only needed if the linker must support unusual actions, such as linking
|
only needed if the linker must support unusual actions, such as linking
|
against shared libraries.
|
against shared libraries.
|
|
|
The @file{emultempl} script is normally written as a simple invocation
|
The @file{emultempl} script is normally written as a simple invocation
|
of @code{cat} with a here document. The document will use a few
|
of @code{cat} with a here document. The document will use a few
|
variable substitutions. Typically each function names uses a
|
variable substitutions. Typically each function names uses a
|
substitution involving @code{EMULATION_NAME}, for ease of debugging when
|
substitution involving @code{EMULATION_NAME}, for ease of debugging when
|
the linker supports multiple emulations.
|
the linker supports multiple emulations.
|
|
|
Every function and variable in the emitted file should be static. The
|
Every function and variable in the emitted file should be static. The
|
only globally visible object must be named
|
only globally visible object must be named
|
@code{ld_@var{EMULATION_NAME}_emulation}, where @var{EMULATION_NAME} is
|
@code{ld_@var{EMULATION_NAME}_emulation}, where @var{EMULATION_NAME} is
|
the name of the emulation set in @file{configure.tgt} (this is also the
|
the name of the emulation set in @file{configure.tgt} (this is also the
|
name of the @file{emulparams} file without the @file{.sh} extension).
|
name of the @file{emulparams} file without the @file{.sh} extension).
|
The @file{genscripts.sh} script will set the shell variable
|
The @file{genscripts.sh} script will set the shell variable
|
@code{EMULATION_NAME} before invoking the @file{emultempl} script.
|
@code{EMULATION_NAME} before invoking the @file{emultempl} script.
|
|
|
The @code{ld_@var{EMULATION_NAME}_emulation} variable must be a
|
The @code{ld_@var{EMULATION_NAME}_emulation} variable must be a
|
@code{struct ld_emulation_xfer_struct}, as defined in @file{ldemul.h}.
|
@code{struct ld_emulation_xfer_struct}, as defined in @file{ldemul.h}.
|
It defines a set of function pointers which are invoked by the linker,
|
It defines a set of function pointers which are invoked by the linker,
|
as well as strings for the emulation name (normally set from the shell
|
as well as strings for the emulation name (normally set from the shell
|
variable @code{EMULATION_NAME} and the default BFD target name (normally
|
variable @code{EMULATION_NAME} and the default BFD target name (normally
|
set from the shell variable @code{OUTPUT_FORMAT} which is normally set
|
set from the shell variable @code{OUTPUT_FORMAT} which is normally set
|
by the @file{emulparams} file).
|
by the @file{emulparams} file).
|
|
|
The @file{genscripts.sh} script will set the shell variable
|
The @file{genscripts.sh} script will set the shell variable
|
@code{COMPILE_IN} when it invokes the @file{emultempl} script for the
|
@code{COMPILE_IN} when it invokes the @file{emultempl} script for the
|
default emulation. In this case, the @file{emultempl} script should
|
default emulation. In this case, the @file{emultempl} script should
|
include the linker scripts directly, and return them from the
|
include the linker scripts directly, and return them from the
|
@code{get_scripts} entry point. When the emulation is not the default,
|
@code{get_scripts} entry point. When the emulation is not the default,
|
the @code{get_scripts} entry point should just return a file name. See
|
the @code{get_scripts} entry point should just return a file name. See
|
@file{emultempl/generic.em} for an example of how this is done.
|
@file{emultempl/generic.em} for an example of how this is done.
|
|
|
At some point, the linker emulation entry points should be documented.
|
At some point, the linker emulation entry points should be documented.
|
|
|
@node Emulation Walkthrough
|
@node Emulation Walkthrough
|
@chapter A Walkthrough of a Typical Emulation
|
@chapter A Walkthrough of a Typical Emulation
|
|
|
This chapter is to help people who are new to the way emulations
|
This chapter is to help people who are new to the way emulations
|
interact with the linker, or who are suddenly thrust into the position
|
interact with the linker, or who are suddenly thrust into the position
|
of having to work with existing emulations. It will discuss the files
|
of having to work with existing emulations. It will discuss the files
|
you need to be aware of. It will tell you when the given "hooks" in
|
you need to be aware of. It will tell you when the given "hooks" in
|
the emulation will be called. It will, hopefully, give you enough
|
the emulation will be called. It will, hopefully, give you enough
|
information about when and how things happen that you'll be able to
|
information about when and how things happen that you'll be able to
|
get by. As always, the source is the definitive reference to this.
|
get by. As always, the source is the definitive reference to this.
|
|
|
The starting point for the linker is in @file{ldmain.c} where
|
The starting point for the linker is in @file{ldmain.c} where
|
@code{main} is defined. The bulk of the code that's emulation
|
@code{main} is defined. The bulk of the code that's emulation
|
specific will initially be in @code{emultempl/@var{emulation}.em} but
|
specific will initially be in @code{emultempl/@var{emulation}.em} but
|
will end up in @code{e@var{emulation}.c} when the build is done.
|
will end up in @code{e@var{emulation}.c} when the build is done.
|
Most of the work to select and interface with emulations is in
|
Most of the work to select and interface with emulations is in
|
@code{ldemul.h} and @code{ldemul.c}. Specifically, @code{ldemul.h}
|
@code{ldemul.h} and @code{ldemul.c}. Specifically, @code{ldemul.h}
|
defines the @code{ld_emulation_xfer_struct} structure your emulation
|
defines the @code{ld_emulation_xfer_struct} structure your emulation
|
exports.
|
exports.
|
|
|
Your emulation file exports a symbol
|
Your emulation file exports a symbol
|
@code{ld_@var{EMULATION_NAME}_emulation}. If your emulation is
|
@code{ld_@var{EMULATION_NAME}_emulation}. If your emulation is
|
selected (it usually is, since usually there's only one),
|
selected (it usually is, since usually there's only one),
|
@code{ldemul.c} sets the variable @var{ld_emulation} to point to it.
|
@code{ldemul.c} sets the variable @var{ld_emulation} to point to it.
|
@code{ldemul.c} also defines a number of API functions that interface
|
@code{ldemul.c} also defines a number of API functions that interface
|
to your emulation, like @code{ldemul_after_parse} which simply calls
|
to your emulation, like @code{ldemul_after_parse} which simply calls
|
your @code{ld_@var{EMULATION}_emulation.after_parse} function. For
|
your @code{ld_@var{EMULATION}_emulation.after_parse} function. For
|
the rest of this section, the functions will be mentioned, but you
|
the rest of this section, the functions will be mentioned, but you
|
should assume the indirect reference to your emulation also.
|
should assume the indirect reference to your emulation also.
|
|
|
We will also skip or gloss over parts of the link process that don't
|
We will also skip or gloss over parts of the link process that don't
|
relate to emulations, like setting up internationalization.
|
relate to emulations, like setting up internationalization.
|
|
|
After initialization, @code{main} selects an emulation by pre-scanning
|
After initialization, @code{main} selects an emulation by pre-scanning
|
the command line arguments. It calls @code{ldemul_choose_target} to
|
the command line arguments. It calls @code{ldemul_choose_target} to
|
choose a target. If you set @code{choose_target} to
|
choose a target. If you set @code{choose_target} to
|
@code{ldemul_default_target}, it picks your @code{target_name} by
|
@code{ldemul_default_target}, it picks your @code{target_name} by
|
default.
|
default.
|
|
|
@code{main} calls @code{ldemul_before_parse}, then @code{parse_args}.
|
@code{main} calls @code{ldemul_before_parse}, then @code{parse_args}.
|
@code{parse_args} calls @code{ldemul_parse_args} for each arg, which
|
@code{parse_args} calls @code{ldemul_parse_args} for each arg, which
|
must update the @code{getopt} globals if it recognizes the argument.
|
must update the @code{getopt} globals if it recognizes the argument.
|
If the emulation doesn't recognize it, then parse_args checks to see
|
If the emulation doesn't recognize it, then parse_args checks to see
|
if it recognizes it.
|
if it recognizes it.
|
|
|
Now that the emulation has had access to all its command-line options,
|
Now that the emulation has had access to all its command-line options,
|
@code{main} calls @code{ldemul_set_symbols}. This can be used for any
|
@code{main} calls @code{ldemul_set_symbols}. This can be used for any
|
initialization that may be affected by options. It is also supposed
|
initialization that may be affected by options. It is also supposed
|
to set up any variables needed by the emulation script.
|
to set up any variables needed by the emulation script.
|
|
|
@code{main} now calls @code{ldemul_get_script} to get the emulation
|
@code{main} now calls @code{ldemul_get_script} to get the emulation
|
script to use (based on arguments, no doubt, @pxref{Emulations}) and
|
script to use (based on arguments, no doubt, @pxref{Emulations}) and
|
runs it. While parsing, @code{ldgram.y} may call @code{ldemul_hll} or
|
runs it. While parsing, @code{ldgram.y} may call @code{ldemul_hll} or
|
@code{ldemul_syslib} to handle the @code{HLL} or @code{SYSLIB}
|
@code{ldemul_syslib} to handle the @code{HLL} or @code{SYSLIB}
|
commands. It may call @code{ldemul_unrecognized_file} if you asked
|
commands. It may call @code{ldemul_unrecognized_file} if you asked
|
the linker to link a file it doesn't recognize. It will call
|
the linker to link a file it doesn't recognize. It will call
|
@code{ldemul_recognized_file} for each file it does recognize, in case
|
@code{ldemul_recognized_file} for each file it does recognize, in case
|
the emulation wants to handle some files specially. All the while,
|
the emulation wants to handle some files specially. All the while,
|
it's loading the files (possibly calling
|
it's loading the files (possibly calling
|
@code{ldemul_open_dynamic_archive}) and symbols and stuff. After it's
|
@code{ldemul_open_dynamic_archive}) and symbols and stuff. After it's
|
done reading the script, @code{main} calls @code{ldemul_after_parse}.
|
done reading the script, @code{main} calls @code{ldemul_after_parse}.
|
Use the after-parse hook to set up anything that depends on stuff the
|
Use the after-parse hook to set up anything that depends on stuff the
|
script might have set up, like the entry point.
|
script might have set up, like the entry point.
|
|
|
@code{main} next calls @code{lang_process} in @code{ldlang.c}. This
|
@code{main} next calls @code{lang_process} in @code{ldlang.c}. This
|
appears to be the main core of the linking itself, as far as emulation
|
appears to be the main core of the linking itself, as far as emulation
|
hooks are concerned(*). It first opens the output file's BFD, calling
|
hooks are concerned(*). It first opens the output file's BFD, calling
|
@code{ldemul_set_output_arch}, and calls
|
@code{ldemul_set_output_arch}, and calls
|
@code{ldemul_create_output_section_statements} in case you need to use
|
@code{ldemul_create_output_section_statements} in case you need to use
|
other means to find or create object files (i.e. shared libraries
|
other means to find or create object files (i.e. shared libraries
|
found on a path, or fake stub objects). Despite the name, nobody
|
found on a path, or fake stub objects). Despite the name, nobody
|
creates output sections here.
|
creates output sections here.
|
|
|
(*) In most cases, the BFD library does the bulk of the actual
|
(*) In most cases, the BFD library does the bulk of the actual
|
linking, handling symbol tables, symbol resolution, relocations, and
|
linking, handling symbol tables, symbol resolution, relocations, and
|
building the final output file. See the BFD reference for all the
|
building the final output file. See the BFD reference for all the
|
details. Your emulation is usually concerned more with managing
|
details. Your emulation is usually concerned more with managing
|
things at the file and section level, like "put this here, add this
|
things at the file and section level, like "put this here, add this
|
section", etc.
|
section", etc.
|
|
|
Next, the objects to be linked are opened and BFDs created for them,
|
Next, the objects to be linked are opened and BFDs created for them,
|
and @code{ldemul_after_open} is called. At this point, you have all
|
and @code{ldemul_after_open} is called. At this point, you have all
|
the objects and symbols loaded, but none of the data has been placed
|
the objects and symbols loaded, but none of the data has been placed
|
yet.
|
yet.
|
|
|
Next comes the Big Linking Thingy (except for the parts BFD does).
|
Next comes the Big Linking Thingy (except for the parts BFD does).
|
All input sections are mapped to output sections according to the
|
All input sections are mapped to output sections according to the
|
script. If a section doesn't get mapped by default,
|
script. If a section doesn't get mapped by default,
|
@code{ldemul_place_orphan} will get called to figure out where it goes.
|
@code{ldemul_place_orphan} will get called to figure out where it goes.
|
Next it figures out the offsets for each section, calling
|
Next it figures out the offsets for each section, calling
|
@code{ldemul_before_allocation} before and
|
@code{ldemul_before_allocation} before and
|
@code{ldemul_after_allocation} after deciding where each input section
|
@code{ldemul_after_allocation} after deciding where each input section
|
ends up in the output sections.
|
ends up in the output sections.
|
|
|
The last part of @code{lang_process} is to figure out all the symbols'
|
The last part of @code{lang_process} is to figure out all the symbols'
|
values. After assigning final values to the symbols,
|
values. After assigning final values to the symbols,
|
@code{ldemul_finish} is called, and after that, any undefined symbols
|
@code{ldemul_finish} is called, and after that, any undefined symbols
|
are turned into fatal errors.
|
are turned into fatal errors.
|
|
|
OK, back to @code{main}, which calls @code{ldwrite} in
|
OK, back to @code{main}, which calls @code{ldwrite} in
|
@file{ldwrite.c}. @code{ldwrite} calls BFD's final_link, which does
|
@file{ldwrite.c}. @code{ldwrite} calls BFD's final_link, which does
|
all the relocation fixups and writes the output bfd to disk, and we're
|
all the relocation fixups and writes the output bfd to disk, and we're
|
done.
|
done.
|
|
|
In summary,
|
In summary,
|
|
|
@itemize @bullet
|
@itemize @bullet
|
|
|
@item @code{main()} in @file{ldmain.c}
|
@item @code{main()} in @file{ldmain.c}
|
@item @file{emultempl/@var{EMULATION}.em} has your code
|
@item @file{emultempl/@var{EMULATION}.em} has your code
|
@item @code{ldemul_choose_target} (defaults to your @code{target_name})
|
@item @code{ldemul_choose_target} (defaults to your @code{target_name})
|
@item @code{ldemul_before_parse}
|
@item @code{ldemul_before_parse}
|
@item Parse argv, calls @code{ldemul_parse_args} for each
|
@item Parse argv, calls @code{ldemul_parse_args} for each
|
@item @code{ldemul_set_symbols}
|
@item @code{ldemul_set_symbols}
|
@item @code{ldemul_get_script}
|
@item @code{ldemul_get_script}
|
@item parse script
|
@item parse script
|
|
|
@itemize @bullet
|
@itemize @bullet
|
@item may call @code{ldemul_hll} or @code{ldemul_syslib}
|
@item may call @code{ldemul_hll} or @code{ldemul_syslib}
|
@item may call @code{ldemul_open_dynamic_archive}
|
@item may call @code{ldemul_open_dynamic_archive}
|
@end itemize
|
@end itemize
|
|
|
@item @code{ldemul_after_parse}
|
@item @code{ldemul_after_parse}
|
@item @code{lang_process()} in @file{ldlang.c}
|
@item @code{lang_process()} in @file{ldlang.c}
|
|
|
@itemize @bullet
|
@itemize @bullet
|
@item create @code{output_bfd}
|
@item create @code{output_bfd}
|
@item @code{ldemul_set_output_arch}
|
@item @code{ldemul_set_output_arch}
|
@item @code{ldemul_create_output_section_statements}
|
@item @code{ldemul_create_output_section_statements}
|
@item read objects, create input bfds - all symbols exist, but have no values
|
@item read objects, create input bfds - all symbols exist, but have no values
|
@item may call @code{ldemul_unrecognized_file}
|
@item may call @code{ldemul_unrecognized_file}
|
@item will call @code{ldemul_recognized_file}
|
@item will call @code{ldemul_recognized_file}
|
@item @code{ldemul_after_open}
|
@item @code{ldemul_after_open}
|
@item map input sections to output sections
|
@item map input sections to output sections
|
@item may call @code{ldemul_place_orphan} for remaining sections
|
@item may call @code{ldemul_place_orphan} for remaining sections
|
@item @code{ldemul_before_allocation}
|
@item @code{ldemul_before_allocation}
|
@item gives input sections offsets into output sections, places output sections
|
@item gives input sections offsets into output sections, places output sections
|
@item @code{ldemul_after_allocation} - section addresses valid
|
@item @code{ldemul_after_allocation} - section addresses valid
|
@item assigns values to symbols
|
@item assigns values to symbols
|
@item @code{ldemul_finish} - symbol values valid
|
@item @code{ldemul_finish} - symbol values valid
|
@end itemize
|
@end itemize
|
|
|
@item output bfd is written to disk
|
@item output bfd is written to disk
|
|
|
@end itemize
|
@end itemize
|
|
|
@node Architecture Specific
|
@node Architecture Specific
|
@chapter Some Architecture Specific Notes
|
@chapter Some Architecture Specific Notes
|
|
|
This is the place for notes on the behavior of @code{ld} on
|
This is the place for notes on the behavior of @code{ld} on
|
specific platforms. Currently, only Intel x86 is documented (and
|
specific platforms. Currently, only Intel x86 is documented (and
|
of that, only the auto-import behavior for DLLs).
|
of that, only the auto-import behavior for DLLs).
|
|
|
@menu
|
@menu
|
* ix86:: Intel x86
|
* ix86:: Intel x86
|
@end menu
|
@end menu
|
|
|
@node ix86
|
@node ix86
|
@section Intel x86
|
@section Intel x86
|
|
|
@table @emph
|
@table @emph
|
@code{ld} can create DLLs that operate with various runtimes available
|
@code{ld} can create DLLs that operate with various runtimes available
|
on a common x86 operating system. These runtimes include native (using
|
on a common x86 operating system. These runtimes include native (using
|
the mingw "platform"), cygwin, and pw.
|
the mingw "platform"), cygwin, and pw.
|
|
|
@item auto-import from DLLs
|
@item auto-import from DLLs
|
@enumerate
|
@enumerate
|
@item
|
@item
|
With this feature on, DLL clients can import variables from DLL
|
With this feature on, DLL clients can import variables from DLL
|
without any concern from their side (for example, without any source
|
without any concern from their side (for example, without any source
|
code modifications). Auto-import can be enabled using the
|
code modifications). Auto-import can be enabled using the
|
@code{--enable-auto-import} flag, or disabled via the
|
@code{--enable-auto-import} flag, or disabled via the
|
@code{--disable-auto-import} flag. Auto-import is disabled by default.
|
@code{--disable-auto-import} flag. Auto-import is disabled by default.
|
|
|
@item
|
@item
|
This is done completely in bounds of the PE specification (to be fair,
|
This is done completely in bounds of the PE specification (to be fair,
|
there's a minor violation of the spec at one point, but in practice
|
there's a minor violation of the spec at one point, but in practice
|
auto-import works on all known variants of that common x86 operating
|
auto-import works on all known variants of that common x86 operating
|
system) So, the resulting DLL can be used with any other PE
|
system) So, the resulting DLL can be used with any other PE
|
compiler/linker.
|
compiler/linker.
|
|
|
@item
|
@item
|
Auto-import is fully compatible with standard import method, in which
|
Auto-import is fully compatible with standard import method, in which
|
variables are decorated using attribute modifiers. Libraries of either
|
variables are decorated using attribute modifiers. Libraries of either
|
type may be mixed together.
|
type may be mixed together.
|
|
|
@item
|
@item
|
Overhead (space): 8 bytes per imported symbol, plus 20 for each
|
Overhead (space): 8 bytes per imported symbol, plus 20 for each
|
reference to it; Overhead (load time): negligible; Overhead
|
reference to it; Overhead (load time): negligible; Overhead
|
(virtual/physical memory): should be less than effect of DLL
|
(virtual/physical memory): should be less than effect of DLL
|
relocation.
|
relocation.
|
@end enumerate
|
@end enumerate
|
|
|
Motivation
|
Motivation
|
|
|
The obvious and only way to get rid of dllimport insanity is
|
The obvious and only way to get rid of dllimport insanity is
|
to make client access variable directly in the DLL, bypassing
|
to make client access variable directly in the DLL, bypassing
|
the extra dereference imposed by ordinary DLL runtime linking.
|
the extra dereference imposed by ordinary DLL runtime linking.
|
I.e., whenever client contains something like
|
I.e., whenever client contains something like
|
|
|
@code{mov dll_var,%eax,}
|
@code{mov dll_var,%eax,}
|
|
|
address of dll_var in the command should be relocated to point
|
address of dll_var in the command should be relocated to point
|
into loaded DLL. The aim is to make OS loader do so, and than
|
into loaded DLL. The aim is to make OS loader do so, and than
|
make ld help with that. Import section of PE made following
|
make ld help with that. Import section of PE made following
|
way: there's a vector of structures each describing imports
|
way: there's a vector of structures each describing imports
|
from particular DLL. Each such structure points to two other
|
from particular DLL. Each such structure points to two other
|
parallel vectors: one holding imported names, and one which
|
parallel vectors: one holding imported names, and one which
|
will hold address of corresponding imported name. So, the
|
will hold address of corresponding imported name. So, the
|
solution is de-vectorize these structures, making import
|
solution is de-vectorize these structures, making import
|
locations be sparse and pointing directly into code.
|
locations be sparse and pointing directly into code.
|
|
|
Implementation
|
Implementation
|
|
|
For each reference of data symbol to be imported from DLL (to
|
For each reference of data symbol to be imported from DLL (to
|
set of which belong symbols with name <sym>, if __imp_<sym> is
|
set of which belong symbols with name <sym>, if __imp_<sym> is
|
found in implib), the import fixup entry is generated. That
|
found in implib), the import fixup entry is generated. That
|
entry is of type IMAGE_IMPORT_DESCRIPTOR and stored in .idata$3
|
entry is of type IMAGE_IMPORT_DESCRIPTOR and stored in .idata$3
|
subsection. Each fixup entry contains pointer to symbol's address
|
subsection. Each fixup entry contains pointer to symbol's address
|
within .text section (marked with __fuN_<sym> symbol, where N is
|
within .text section (marked with __fuN_<sym> symbol, where N is
|
integer), pointer to DLL name (so, DLL name is referenced by
|
integer), pointer to DLL name (so, DLL name is referenced by
|
multiple entries), and pointer to symbol name thunk. Symbol name
|
multiple entries), and pointer to symbol name thunk. Symbol name
|
thunk is singleton vector (__nm_th_<symbol>) pointing to
|
thunk is singleton vector (__nm_th_<symbol>) pointing to
|
IMAGE_IMPORT_BY_NAME structure (__nm_<symbol>) directly containing
|
IMAGE_IMPORT_BY_NAME structure (__nm_<symbol>) directly containing
|
imported name. Here comes that "om the edge" problem mentioned above:
|
imported name. Here comes that "om the edge" problem mentioned above:
|
PE specification rambles that name vector (OriginalFirstThunk) should
|
PE specification rambles that name vector (OriginalFirstThunk) should
|
run in parallel with addresses vector (FirstThunk), i.e. that they
|
run in parallel with addresses vector (FirstThunk), i.e. that they
|
should have same number of elements and terminated with zero. We violate
|
should have same number of elements and terminated with zero. We violate
|
this, since FirstThunk points directly into machine code. But in
|
this, since FirstThunk points directly into machine code. But in
|
practice, OS loader implemented the sane way: it goes thru
|
practice, OS loader implemented the sane way: it goes thru
|
OriginalFirstThunk and puts addresses to FirstThunk, not something
|
OriginalFirstThunk and puts addresses to FirstThunk, not something
|
else. It once again should be noted that dll and symbol name
|
else. It once again should be noted that dll and symbol name
|
structures are reused across fixup entries and should be there
|
structures are reused across fixup entries and should be there
|
anyway to support standard import stuff, so sustained overhead is
|
anyway to support standard import stuff, so sustained overhead is
|
20 bytes per reference. Other question is whether having several
|
20 bytes per reference. Other question is whether having several
|
IMAGE_IMPORT_DESCRIPTORS for the same DLL is possible. Answer is yes,
|
IMAGE_IMPORT_DESCRIPTORS for the same DLL is possible. Answer is yes,
|
it is done even by native compiler/linker (libth32's functions are in
|
it is done even by native compiler/linker (libth32's functions are in
|
fact resident in windows9x kernel32.dll, so if you use it, you have
|
fact resident in windows9x kernel32.dll, so if you use it, you have
|
two IMAGE_IMPORT_DESCRIPTORS for kernel32.dll). Yet other question is
|
two IMAGE_IMPORT_DESCRIPTORS for kernel32.dll). Yet other question is
|
whether referencing the same PE structures several times is valid.
|
whether referencing the same PE structures several times is valid.
|
The answer is why not, prohibiting that (detecting violation) would
|
The answer is why not, prohibiting that (detecting violation) would
|
require more work on behalf of loader than not doing it.
|
require more work on behalf of loader than not doing it.
|
|
|
@end table
|
@end table
|
|
|
@node GNU Free Documentation License
|
@node GNU Free Documentation License
|
@chapter GNU Free Documentation License
|
@chapter GNU Free Documentation License
|
|
|
GNU Free Documentation License
|
GNU Free Documentation License
|
|
|
Version 1.1, March 2000
|
Version 1.1, March 2000
|
|
|
Copyright (C) 2000 Free Software Foundation, Inc.
|
Copyright (C) 2000 Free Software Foundation, Inc.
|
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
|
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
|
|
|
Everyone is permitted to copy and distribute verbatim copies
|
Everyone is permitted to copy and distribute verbatim copies
|
of this license document, but changing it is not allowed.
|
of this license document, but changing it is not allowed.
|
|
|
|
|
0. PREAMBLE
|
0. PREAMBLE
|
|
|
The purpose of this License is to make a manual, textbook, or other
|
The purpose of this License is to make a manual, textbook, or other
|
written document "free" in the sense of freedom: to assure everyone
|
written document "free" in the sense of freedom: to assure everyone
|
the effective freedom to copy and redistribute it, with or without
|
the effective freedom to copy and redistribute it, with or without
|
modifying it, either commercially or noncommercially. Secondarily,
|
modifying it, either commercially or noncommercially. Secondarily,
|
this License preserves for the author and publisher a way to get
|
this License preserves for the author and publisher a way to get
|
credit for their work, while not being considered responsible for
|
credit for their work, while not being considered responsible for
|
modifications made by others.
|
modifications made by others.
|
|
|
This License is a kind of "copyleft", which means that derivative
|
This License is a kind of "copyleft", which means that derivative
|
works of the document must themselves be free in the same sense. It
|
works of the document must themselves be free in the same sense. It
|
complements the GNU General Public License, which is a copyleft
|
complements the GNU General Public License, which is a copyleft
|
license designed for free software.
|
license designed for free software.
|
|
|
We have designed this License in order to use it for manuals for free
|
We have designed this License in order to use it for manuals for free
|
software, because free software needs free documentation: a free
|
software, because free software needs free documentation: a free
|
program should come with manuals providing the same freedoms that the
|
program should come with manuals providing the same freedoms that the
|
software does. But this License is not limited to software manuals;
|
software does. But this License is not limited to software manuals;
|
it can be used for any textual work, regardless of subject matter or
|
it can be used for any textual work, regardless of subject matter or
|
whether it is published as a printed book. We recommend this License
|
whether it is published as a printed book. We recommend this License
|
principally for works whose purpose is instruction or reference.
|
principally for works whose purpose is instruction or reference.
|
|
|
|
|
1. APPLICABILITY AND DEFINITIONS
|
1. APPLICABILITY AND DEFINITIONS
|
|
|
This License applies to any manual or other work that contains a
|
This License applies to any manual or other work that contains a
|
notice placed by the copyright holder saying it can be distributed
|
notice placed by the copyright holder saying it can be distributed
|
under the terms of this License. The "Document", below, refers to any
|
under the terms of this License. The "Document", below, refers to any
|
such manual or work. Any member of the public is a licensee, and is
|
such manual or work. Any member of the public is a licensee, and is
|
addressed as "you".
|
addressed as "you".
|
|
|
A "Modified Version" of the Document means any work containing the
|
A "Modified Version" of the Document means any work containing the
|
Document or a portion of it, either copied verbatim, or with
|
Document or a portion of it, either copied verbatim, or with
|
modifications and/or translated into another language.
|
modifications and/or translated into another language.
|
|
|
A "Secondary Section" is a named appendix or a front-matter section of
|
A "Secondary Section" is a named appendix or a front-matter section of
|
the Document that deals exclusively with the relationship of the
|
the Document that deals exclusively with the relationship of the
|
publishers or authors of the Document to the Document's overall subject
|
publishers or authors of the Document to the Document's overall subject
|
(or to related matters) and contains nothing that could fall directly
|
(or to related matters) and contains nothing that could fall directly
|
within that overall subject. (For example, if the Document is in part a
|
within that overall subject. (For example, if the Document is in part a
|
textbook of mathematics, a Secondary Section may not explain any
|
textbook of mathematics, a Secondary Section may not explain any
|
mathematics.) The relationship could be a matter of historical
|
mathematics.) The relationship could be a matter of historical
|
connection with the subject or with related matters, or of legal,
|
connection with the subject or with related matters, or of legal,
|
commercial, philosophical, ethical or political position regarding
|
commercial, philosophical, ethical or political position regarding
|
them.
|
them.
|
|
|
The "Invariant Sections" are certain Secondary Sections whose titles
|
The "Invariant Sections" are certain Secondary Sections whose titles
|
are designated, as being those of Invariant Sections, in the notice
|
are designated, as being those of Invariant Sections, in the notice
|
that says that the Document is released under this License.
|
that says that the Document is released under this License.
|
|
|
The "Cover Texts" are certain short passages of text that are listed,
|
The "Cover Texts" are certain short passages of text that are listed,
|
as Front-Cover Texts or Back-Cover Texts, in the notice that says that
|
as Front-Cover Texts or Back-Cover Texts, in the notice that says that
|
the Document is released under this License.
|
the Document is released under this License.
|
|
|
A "Transparent" copy of the Document means a machine-readable copy,
|
A "Transparent" copy of the Document means a machine-readable copy,
|
represented in a format whose specification is available to the
|
represented in a format whose specification is available to the
|
general public, whose contents can be viewed and edited directly and
|
general public, whose contents can be viewed and edited directly and
|
straightforwardly with generic text editors or (for images composed of
|
straightforwardly with generic text editors or (for images composed of
|
pixels) generic paint programs or (for drawings) some widely available
|
pixels) generic paint programs or (for drawings) some widely available
|
drawing editor, and that is suitable for input to text formatters or
|
drawing editor, and that is suitable for input to text formatters or
|
for automatic translation to a variety of formats suitable for input
|
for automatic translation to a variety of formats suitable for input
|
to text formatters. A copy made in an otherwise Transparent file
|
to text formatters. A copy made in an otherwise Transparent file
|
format whose markup has been designed to thwart or discourage
|
format whose markup has been designed to thwart or discourage
|
subsequent modification by readers is not Transparent. A copy that is
|
subsequent modification by readers is not Transparent. A copy that is
|
not "Transparent" is called "Opaque".
|
not "Transparent" is called "Opaque".
|
|
|
Examples of suitable formats for Transparent copies include plain
|
Examples of suitable formats for Transparent copies include plain
|
ASCII without markup, Texinfo input format, LaTeX input format, SGML
|
ASCII without markup, Texinfo input format, LaTeX input format, SGML
|
or XML using a publicly available DTD, and standard-conforming simple
|
or XML using a publicly available DTD, and standard-conforming simple
|
HTML designed for human modification. Opaque formats include
|
HTML designed for human modification. Opaque formats include
|
PostScript, PDF, proprietary formats that can be read and edited only
|
PostScript, PDF, proprietary formats that can be read and edited only
|
by proprietary word processors, SGML or XML for which the DTD and/or
|
by proprietary word processors, SGML or XML for which the DTD and/or
|
processing tools are not generally available, and the
|
processing tools are not generally available, and the
|
machine-generated HTML produced by some word processors for output
|
machine-generated HTML produced by some word processors for output
|
purposes only.
|
purposes only.
|
|
|
The "Title Page" means, for a printed book, the title page itself,
|
The "Title Page" means, for a printed book, the title page itself,
|
plus such following pages as are needed to hold, legibly, the material
|
plus such following pages as are needed to hold, legibly, the material
|
this License requires to appear in the title page. For works in
|
this License requires to appear in the title page. For works in
|
formats which do not have any title page as such, "Title Page" means
|
formats which do not have any title page as such, "Title Page" means
|
the text near the most prominent appearance of the work's title,
|
the text near the most prominent appearance of the work's title,
|
preceding the beginning of the body of the text.
|
preceding the beginning of the body of the text.
|
|
|
|
|
2. VERBATIM COPYING
|
2. VERBATIM COPYING
|
|
|
You may copy and distribute the Document in any medium, either
|
You may copy and distribute the Document in any medium, either
|
commercially or noncommercially, provided that this License, the
|
commercially or noncommercially, provided that this License, the
|
copyright notices, and the license notice saying this License applies
|
copyright notices, and the license notice saying this License applies
|
to the Document are reproduced in all copies, and that you add no other
|
to the Document are reproduced in all copies, and that you add no other
|
conditions whatsoever to those of this License. You may not use
|
conditions whatsoever to those of this License. You may not use
|
technical measures to obstruct or control the reading or further
|
technical measures to obstruct or control the reading or further
|
copying of the copies you make or distribute. However, you may accept
|
copying of the copies you make or distribute. However, you may accept
|
compensation in exchange for copies. If you distribute a large enough
|
compensation in exchange for copies. If you distribute a large enough
|
number of copies you must also follow the conditions in section 3.
|
number of copies you must also follow the conditions in section 3.
|
|
|
You may also lend copies, under the same conditions stated above, and
|
You may also lend copies, under the same conditions stated above, and
|
you may publicly display copies.
|
you may publicly display copies.
|
|
|
|
|
3. COPYING IN QUANTITY
|
3. COPYING IN QUANTITY
|
|
|
If you publish printed copies of the Document numbering more than 100,
|
If you publish printed copies of the Document numbering more than 100,
|
and the Document's license notice requires Cover Texts, you must enclose
|
and the Document's license notice requires Cover Texts, you must enclose
|
the copies in covers that carry, clearly and legibly, all these Cover
|
the copies in covers that carry, clearly and legibly, all these Cover
|
Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
|
Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
|
the back cover. Both covers must also clearly and legibly identify
|
the back cover. Both covers must also clearly and legibly identify
|
you as the publisher of these copies. The front cover must present
|
you as the publisher of these copies. The front cover must present
|
the full title with all words of the title equally prominent and
|
the full title with all words of the title equally prominent and
|
visible. You may add other material on the covers in addition.
|
visible. You may add other material on the covers in addition.
|
Copying with changes limited to the covers, as long as they preserve
|
Copying with changes limited to the covers, as long as they preserve
|
the title of the Document and satisfy these conditions, can be treated
|
the title of the Document and satisfy these conditions, can be treated
|
as verbatim copying in other respects.
|
as verbatim copying in other respects.
|
|
|
If the required texts for either cover are too voluminous to fit
|
If the required texts for either cover are too voluminous to fit
|
legibly, you should put the first ones listed (as many as fit
|
legibly, you should put the first ones listed (as many as fit
|
reasonably) on the actual cover, and continue the rest onto adjacent
|
reasonably) on the actual cover, and continue the rest onto adjacent
|
pages.
|
pages.
|
|
|
If you publish or distribute Opaque copies of the Document numbering
|
If you publish or distribute Opaque copies of the Document numbering
|
more than 100, you must either include a machine-readable Transparent
|
more than 100, you must either include a machine-readable Transparent
|
copy along with each Opaque copy, or state in or with each Opaque copy
|
copy along with each Opaque copy, or state in or with each Opaque copy
|
a publicly-accessible computer-network location containing a complete
|
a publicly-accessible computer-network location containing a complete
|
Transparent copy of the Document, free of added material, which the
|
Transparent copy of the Document, free of added material, which the
|
general network-using public has access to download anonymously at no
|
general network-using public has access to download anonymously at no
|
charge using public-standard network protocols. If you use the latter
|
charge using public-standard network protocols. If you use the latter
|
option, you must take reasonably prudent steps, when you begin
|
option, you must take reasonably prudent steps, when you begin
|
distribution of Opaque copies in quantity, to ensure that this
|
distribution of Opaque copies in quantity, to ensure that this
|
Transparent copy will remain thus accessible at the stated location
|
Transparent copy will remain thus accessible at the stated location
|
until at least one year after the last time you distribute an Opaque
|
until at least one year after the last time you distribute an Opaque
|
copy (directly or through your agents or retailers) of that edition to
|
copy (directly or through your agents or retailers) of that edition to
|
the public.
|
the public.
|
|
|
It is requested, but not required, that you contact the authors of the
|
It is requested, but not required, that you contact the authors of the
|
Document well before redistributing any large number of copies, to give
|
Document well before redistributing any large number of copies, to give
|
them a chance to provide you with an updated version of the Document.
|
them a chance to provide you with an updated version of the Document.
|
|
|
|
|
4. MODIFICATIONS
|
4. MODIFICATIONS
|
|
|
You may copy and distribute a Modified Version of the Document under
|
You may copy and distribute a Modified Version of the Document under
|
the conditions of sections 2 and 3 above, provided that you release
|
the conditions of sections 2 and 3 above, provided that you release
|
the Modified Version under precisely this License, with the Modified
|
the Modified Version under precisely this License, with the Modified
|
Version filling the role of the Document, thus licensing distribution
|
Version filling the role of the Document, thus licensing distribution
|
and modification of the Modified Version to whoever possesses a copy
|
and modification of the Modified Version to whoever possesses a copy
|
of it. In addition, you must do these things in the Modified Version:
|
of it. In addition, you must do these things in the Modified Version:
|
|
|
A. Use in the Title Page (and on the covers, if any) a title distinct
|
A. Use in the Title Page (and on the covers, if any) a title distinct
|
from that of the Document, and from those of previous versions
|
from that of the Document, and from those of previous versions
|
(which should, if there were any, be listed in the History section
|
(which should, if there were any, be listed in the History section
|
of the Document). You may use the same title as a previous version
|
of the Document). You may use the same title as a previous version
|
if the original publisher of that version gives permission.
|
if the original publisher of that version gives permission.
|
B. List on the Title Page, as authors, one or more persons or entities
|
B. List on the Title Page, as authors, one or more persons or entities
|
responsible for authorship of the modifications in the Modified
|
responsible for authorship of the modifications in the Modified
|
Version, together with at least five of the principal authors of the
|
Version, together with at least five of the principal authors of the
|
Document (all of its principal authors, if it has less than five).
|
Document (all of its principal authors, if it has less than five).
|
C. State on the Title page the name of the publisher of the
|
C. State on the Title page the name of the publisher of the
|
Modified Version, as the publisher.
|
Modified Version, as the publisher.
|
D. Preserve all the copyright notices of the Document.
|
D. Preserve all the copyright notices of the Document.
|
E. Add an appropriate copyright notice for your modifications
|
E. Add an appropriate copyright notice for your modifications
|
adjacent to the other copyright notices.
|
adjacent to the other copyright notices.
|
F. Include, immediately after the copyright notices, a license notice
|
F. Include, immediately after the copyright notices, a license notice
|
giving the public permission to use the Modified Version under the
|
giving the public permission to use the Modified Version under the
|
terms of this License, in the form shown in the Addendum below.
|
terms of this License, in the form shown in the Addendum below.
|
G. Preserve in that license notice the full lists of Invariant Sections
|
G. Preserve in that license notice the full lists of Invariant Sections
|
and required Cover Texts given in the Document's license notice.
|
and required Cover Texts given in the Document's license notice.
|
H. Include an unaltered copy of this License.
|
H. Include an unaltered copy of this License.
|
I. Preserve the section entitled "History", and its title, and add to
|
I. Preserve the section entitled "History", and its title, and add to
|
it an item stating at least the title, year, new authors, and
|
it an item stating at least the title, year, new authors, and
|
publisher of the Modified Version as given on the Title Page. If
|
publisher of the Modified Version as given on the Title Page. If
|
there is no section entitled "History" in the Document, create one
|
there is no section entitled "History" in the Document, create one
|
stating the title, year, authors, and publisher of the Document as
|
stating the title, year, authors, and publisher of the Document as
|
given on its Title Page, then add an item describing the Modified
|
given on its Title Page, then add an item describing the Modified
|
Version as stated in the previous sentence.
|
Version as stated in the previous sentence.
|
J. Preserve the network location, if any, given in the Document for
|
J. Preserve the network location, if any, given in the Document for
|
public access to a Transparent copy of the Document, and likewise
|
public access to a Transparent copy of the Document, and likewise
|
the network locations given in the Document for previous versions
|
the network locations given in the Document for previous versions
|
it was based on. These may be placed in the "History" section.
|
it was based on. These may be placed in the "History" section.
|
You may omit a network location for a work that was published at
|
You may omit a network location for a work that was published at
|
least four years before the Document itself, or if the original
|
least four years before the Document itself, or if the original
|
publisher of the version it refers to gives permission.
|
publisher of the version it refers to gives permission.
|
K. In any section entitled "Acknowledgements" or "Dedications",
|
K. In any section entitled "Acknowledgements" or "Dedications",
|
preserve the section's title, and preserve in the section all the
|
preserve the section's title, and preserve in the section all the
|
substance and tone of each of the contributor acknowledgements
|
substance and tone of each of the contributor acknowledgements
|
and/or dedications given therein.
|
and/or dedications given therein.
|
L. Preserve all the Invariant Sections of the Document,
|
L. Preserve all the Invariant Sections of the Document,
|
unaltered in their text and in their titles. Section numbers
|
unaltered in their text and in their titles. Section numbers
|
or the equivalent are not considered part of the section titles.
|
or the equivalent are not considered part of the section titles.
|
M. Delete any section entitled "Endorsements". Such a section
|
M. Delete any section entitled "Endorsements". Such a section
|
may not be included in the Modified Version.
|
may not be included in the Modified Version.
|
N. Do not retitle any existing section as "Endorsements"
|
N. Do not retitle any existing section as "Endorsements"
|
or to conflict in title with any Invariant Section.
|
or to conflict in title with any Invariant Section.
|
|
|
If the Modified Version includes new front-matter sections or
|
If the Modified Version includes new front-matter sections or
|
appendices that qualify as Secondary Sections and contain no material
|
appendices that qualify as Secondary Sections and contain no material
|
copied from the Document, you may at your option designate some or all
|
copied from the Document, you may at your option designate some or all
|
of these sections as invariant. To do this, add their titles to the
|
of these sections as invariant. To do this, add their titles to the
|
list of Invariant Sections in the Modified Version's license notice.
|
list of Invariant Sections in the Modified Version's license notice.
|
These titles must be distinct from any other section titles.
|
These titles must be distinct from any other section titles.
|
|
|
You may add a section entitled "Endorsements", provided it contains
|
You may add a section entitled "Endorsements", provided it contains
|
nothing but endorsements of your Modified Version by various
|
nothing but endorsements of your Modified Version by various
|
parties--for example, statements of peer review or that the text has
|
parties--for example, statements of peer review or that the text has
|
been approved by an organization as the authoritative definition of a
|
been approved by an organization as the authoritative definition of a
|
standard.
|
standard.
|
|
|
You may add a passage of up to five words as a Front-Cover Text, and a
|
You may add a passage of up to five words as a Front-Cover Text, and a
|
passage of up to 25 words as a Back-Cover Text, to the end of the list
|
passage of up to 25 words as a Back-Cover Text, to the end of the list
|
of Cover Texts in the Modified Version. Only one passage of
|
of Cover Texts in the Modified Version. Only one passage of
|
Front-Cover Text and one of Back-Cover Text may be added by (or
|
Front-Cover Text and one of Back-Cover Text may be added by (or
|
through arrangements made by) any one entity. If the Document already
|
through arrangements made by) any one entity. If the Document already
|
includes a cover text for the same cover, previously added by you or
|
includes a cover text for the same cover, previously added by you or
|
by arrangement made by the same entity you are acting on behalf of,
|
by arrangement made by the same entity you are acting on behalf of,
|
you may not add another; but you may replace the old one, on explicit
|
you may not add another; but you may replace the old one, on explicit
|
permission from the previous publisher that added the old one.
|
permission from the previous publisher that added the old one.
|
|
|
The author(s) and publisher(s) of the Document do not by this License
|
The author(s) and publisher(s) of the Document do not by this License
|
give permission to use their names for publicity for or to assert or
|
give permission to use their names for publicity for or to assert or
|
imply endorsement of any Modified Version.
|
imply endorsement of any Modified Version.
|
|
|
|
|
5. COMBINING DOCUMENTS
|
5. COMBINING DOCUMENTS
|
|
|
You may combine the Document with other documents released under this
|
You may combine the Document with other documents released under this
|
License, under the terms defined in section 4 above for modified
|
License, under the terms defined in section 4 above for modified
|
versions, provided that you include in the combination all of the
|
versions, provided that you include in the combination all of the
|
Invariant Sections of all of the original documents, unmodified, and
|
Invariant Sections of all of the original documents, unmodified, and
|
list them all as Invariant Sections of your combined work in its
|
list them all as Invariant Sections of your combined work in its
|
license notice.
|
license notice.
|
|
|
The combined work need only contain one copy of this License, and
|
The combined work need only contain one copy of this License, and
|
multiple identical Invariant Sections may be replaced with a single
|
multiple identical Invariant Sections may be replaced with a single
|
copy. If there are multiple Invariant Sections with the same name but
|
copy. If there are multiple Invariant Sections with the same name but
|
different contents, make the title of each such section unique by
|
different contents, make the title of each such section unique by
|
adding at the end of it, in parentheses, the name of the original
|
adding at the end of it, in parentheses, the name of the original
|
author or publisher of that section if known, or else a unique number.
|
author or publisher of that section if known, or else a unique number.
|
Make the same adjustment to the section titles in the list of
|
Make the same adjustment to the section titles in the list of
|
Invariant Sections in the license notice of the combined work.
|
Invariant Sections in the license notice of the combined work.
|
|
|
In the combination, you must combine any sections entitled "History"
|
In the combination, you must combine any sections entitled "History"
|
in the various original documents, forming one section entitled
|
in the various original documents, forming one section entitled
|
"History"; likewise combine any sections entitled "Acknowledgements",
|
"History"; likewise combine any sections entitled "Acknowledgements",
|
and any sections entitled "Dedications". You must delete all sections
|
and any sections entitled "Dedications". You must delete all sections
|
entitled "Endorsements."
|
entitled "Endorsements."
|
|
|
|
|
6. COLLECTIONS OF DOCUMENTS
|
6. COLLECTIONS OF DOCUMENTS
|
|
|
You may make a collection consisting of the Document and other documents
|
You may make a collection consisting of the Document and other documents
|
released under this License, and replace the individual copies of this
|
released under this License, and replace the individual copies of this
|
License in the various documents with a single copy that is included in
|
License in the various documents with a single copy that is included in
|
the collection, provided that you follow the rules of this License for
|
the collection, provided that you follow the rules of this License for
|
verbatim copying of each of the documents in all other respects.
|
verbatim copying of each of the documents in all other respects.
|
|
|
You may extract a single document from such a collection, and distribute
|
You may extract a single document from such a collection, and distribute
|
it individually under this License, provided you insert a copy of this
|
it individually under this License, provided you insert a copy of this
|
License into the extracted document, and follow this License in all
|
License into the extracted document, and follow this License in all
|
other respects regarding verbatim copying of that document.
|
other respects regarding verbatim copying of that document.
|
|
|
|
|
7. AGGREGATION WITH INDEPENDENT WORKS
|
7. AGGREGATION WITH INDEPENDENT WORKS
|
|
|
A compilation of the Document or its derivatives with other separate
|
A compilation of the Document or its derivatives with other separate
|
and independent documents or works, in or on a volume of a storage or
|
and independent documents or works, in or on a volume of a storage or
|
distribution medium, does not as a whole count as a Modified Version
|
distribution medium, does not as a whole count as a Modified Version
|
of the Document, provided no compilation copyright is claimed for the
|
of the Document, provided no compilation copyright is claimed for the
|
compilation. Such a compilation is called an "aggregate", and this
|
compilation. Such a compilation is called an "aggregate", and this
|
License does not apply to the other self-contained works thus compiled
|
License does not apply to the other self-contained works thus compiled
|
with the Document, on account of their being thus compiled, if they
|
with the Document, on account of their being thus compiled, if they
|
are not themselves derivative works of the Document.
|
are not themselves derivative works of the Document.
|
|
|
If the Cover Text requirement of section 3 is applicable to these
|
If the Cover Text requirement of section 3 is applicable to these
|
copies of the Document, then if the Document is less than one quarter
|
copies of the Document, then if the Document is less than one quarter
|
of the entire aggregate, the Document's Cover Texts may be placed on
|
of the entire aggregate, the Document's Cover Texts may be placed on
|
covers that surround only the Document within the aggregate.
|
covers that surround only the Document within the aggregate.
|
Otherwise they must appear on covers around the whole aggregate.
|
Otherwise they must appear on covers around the whole aggregate.
|
|
|
|
|
8. TRANSLATION
|
8. TRANSLATION
|
|
|
Translation is considered a kind of modification, so you may
|
Translation is considered a kind of modification, so you may
|
distribute translations of the Document under the terms of section 4.
|
distribute translations of the Document under the terms of section 4.
|
Replacing Invariant Sections with translations requires special
|
Replacing Invariant Sections with translations requires special
|
permission from their copyright holders, but you may include
|
permission from their copyright holders, but you may include
|
translations of some or all Invariant Sections in addition to the
|
translations of some or all Invariant Sections in addition to the
|
original versions of these Invariant Sections. You may include a
|
original versions of these Invariant Sections. You may include a
|
translation of this License provided that you also include the
|
translation of this License provided that you also include the
|
original English version of this License. In case of a disagreement
|
original English version of this License. In case of a disagreement
|
between the translation and the original English version of this
|
between the translation and the original English version of this
|
License, the original English version will prevail.
|
License, the original English version will prevail.
|
|
|
|
|
9. TERMINATION
|
9. TERMINATION
|
|
|
You may not copy, modify, sublicense, or distribute the Document except
|
You may not copy, modify, sublicense, or distribute the Document except
|
as expressly provided for under this License. Any other attempt to
|
as expressly provided for under this License. Any other attempt to
|
copy, modify, sublicense or distribute the Document is void, and will
|
copy, modify, sublicense or distribute the Document is void, and will
|
automatically terminate your rights under this License. However,
|
automatically terminate your rights under this License. However,
|
parties who have received copies, or rights, from you under this
|
parties who have received copies, or rights, from you under this
|
License will not have their licenses terminated so long as such
|
License will not have their licenses terminated so long as such
|
parties remain in full compliance.
|
parties remain in full compliance.
|
|
|
|
|
10. FUTURE REVISIONS OF THIS LICENSE
|
10. FUTURE REVISIONS OF THIS LICENSE
|
|
|
The Free Software Foundation may publish new, revised versions
|
The Free Software Foundation may publish new, revised versions
|
of the GNU Free Documentation License from time to time. Such new
|
of the GNU Free Documentation License from time to time. Such new
|
versions will be similar in spirit to the present version, but may
|
versions will be similar in spirit to the present version, but may
|
differ in detail to address new problems or concerns. See
|
differ in detail to address new problems or concerns. See
|
http://www.gnu.org/copyleft/.
|
http://www.gnu.org/copyleft/.
|
|
|
Each version of the License is given a distinguishing version number.
|
Each version of the License is given a distinguishing version number.
|
If the Document specifies that a particular numbered version of this
|
If the Document specifies that a particular numbered version of this
|
License "or any later version" applies to it, you have the option of
|
License "or any later version" applies to it, you have the option of
|
following the terms and conditions either of that specified version or
|
following the terms and conditions either of that specified version or
|
of any later version that has been published (not as a draft) by the
|
of any later version that has been published (not as a draft) by the
|
Free Software Foundation. If the Document does not specify a version
|
Free Software Foundation. If the Document does not specify a version
|
number of this License, you may choose any version ever published (not
|
number of this License, you may choose any version ever published (not
|
as a draft) by the Free Software Foundation.
|
as a draft) by the Free Software Foundation.
|
|
|
|
|
ADDENDUM: How to use this License for your documents
|
ADDENDUM: How to use this License for your documents
|
|
|
To use this License in a document you have written, include a copy of
|
To use this License in a document you have written, include a copy of
|
the License in the document and put the following copyright and
|
the License in the document and put the following copyright and
|
license notices just after the title page:
|
license notices just after the title page:
|
|
|
@smallexample
|
@smallexample
|
Copyright (c) YEAR YOUR NAME.
|
Copyright (c) YEAR YOUR NAME.
|
Permission is granted to copy, distribute and/or modify this document
|
Permission is granted to copy, distribute and/or modify this document
|
under the terms of the GNU Free Documentation License, Version 1.1
|
under the terms of the GNU Free Documentation License, Version 1.1
|
or any later version published by the Free Software Foundation;
|
or any later version published by the Free Software Foundation;
|
with the Invariant Sections being LIST THEIR TITLES, with the
|
with the Invariant Sections being LIST THEIR TITLES, with the
|
Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
|
Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
|
A copy of the license is included in the section entitled "GNU
|
A copy of the license is included in the section entitled "GNU
|
Free Documentation License".
|
Free Documentation License".
|
@end smallexample
|
@end smallexample
|
|
|
If you have no Invariant Sections, write "with no Invariant Sections"
|
If you have no Invariant Sections, write "with no Invariant Sections"
|
instead of saying which ones are invariant. If you have no
|
instead of saying which ones are invariant. If you have no
|
Front-Cover Texts, write "no Front-Cover Texts" instead of
|
Front-Cover Texts, write "no Front-Cover Texts" instead of
|
"Front-Cover Texts being LIST"; likewise for Back-Cover Texts.
|
"Front-Cover Texts being LIST"; likewise for Back-Cover Texts.
|
|
|
If your document contains nontrivial examples of program code, we
|
If your document contains nontrivial examples of program code, we
|
recommend releasing these examples in parallel under your choice of
|
recommend releasing these examples in parallel under your choice of
|
free software license, such as the GNU General Public License,
|
free software license, such as the GNU General Public License,
|
to permit their use in free software.
|
to permit their use in free software.
|
|
|
@contents
|
@contents
|
@bye
|
@bye
|
|
|
