| 1 | \input texinfo |
| 2 | @setfilename ldint.info |
| 3 | @c Copyright 1992, 1994, 1995, 1996, 1997, 1998, 1999, 2000 |
| 4 | @c Free Software Foundation, Inc. |
| 5 | |
| 6 | @ifinfo |
| 7 | @format |
| 8 | START-INFO-DIR-ENTRY |
| 9 | * Ld-Internals: (ldint). The GNU linker internals. |
| 10 | END-INFO-DIR-ENTRY |
| 11 | @end format |
| 12 | @end ifinfo |
| 13 | |
| 14 | @ifinfo |
| 15 | This file documents the internals of the GNU linker ld. |
| 16 | |
| 17 | Copyright 1992, 1994, 1995, 1996, 1997, 1998, 1999, 2000 |
| 18 | Free Software Foundation, Inc. |
| 19 | Contributed by Cygnus Support. |
| 20 | |
| 21 | Permission is granted to copy, distribute and/or modify this document |
| 22 | under the terms of the GNU Free Documentation License, Version 1.1 |
| 23 | or any later version published by the Free Software Foundation; |
| 24 | with no Invariant Sections, with no Front-Cover Texts, and with no |
| 25 | Back-Cover Texts. A copy of the license is included in the |
| 26 | section entitled "GNU Free Documentation License". |
| 27 | |
| 28 | @ignore |
| 29 | Permission is granted to process this file through Tex and print the |
| 30 | results, provided the printed document carries copying permission |
| 31 | notice identical to this one except for the removal of this paragraph |
| 32 | (this paragraph not being relevant to the printed manual). |
| 33 | |
| 34 | @end ignore |
| 35 | @end ifinfo |
| 36 | |
| 37 | @iftex |
| 38 | @finalout |
| 39 | @setchapternewpage off |
| 40 | @settitle GNU Linker Internals |
| 41 | @titlepage |
| 42 | @title{A guide to the internals of the GNU linker} |
| 43 | @author Per Bothner, Steve Chamberlain, Ian Lance Taylor, DJ Delorie |
| 44 | @author Cygnus Support |
| 45 | @page |
| 46 | |
| 47 | @tex |
| 48 | \def\$#1${{#1}} % Kluge: collect RCS revision info without $...$ |
| 49 | \xdef\manvers{2.10.91} % For use in headers, footers too |
| 50 | {\parskip=0pt |
| 51 | \hfill Cygnus Support\par |
| 52 | \hfill \manvers\par |
| 53 | \hfill \TeX{}info \texinfoversion\par |
| 54 | } |
| 55 | @end tex |
| 56 | |
| 57 | @vskip 0pt plus 1filll |
| 58 | Copyright @copyright{} 1992, 93, 94, 95, 96, 97, 1998, 2000 |
| 59 | Free Software Foundation, Inc. |
| 60 | |
| 61 | Permission is granted to copy, distribute and/or modify this document |
| 62 | under the terms of the GNU Free Documentation License, Version 1.1 |
| 63 | or any later version published by the Free Software Foundation; |
| 64 | with no Invariant Sections, with no Front-Cover Texts, and with no |
| 65 | Back-Cover Texts. A copy of the license is included in the |
| 66 | section entitled "GNU Free Documentation License". |
| 67 | |
| 68 | @end titlepage |
| 69 | @end iftex |
| 70 | |
| 71 | @node Top |
| 72 | @top |
| 73 | |
| 74 | This file documents the internals of the GNU linker @code{ld}. It is a |
| 75 | collection of miscellaneous information with little form at this point. |
| 76 | Mostly, it is a repository into which you can put information about |
| 77 | GNU @code{ld} as you discover it (or as you design changes to @code{ld}). |
| 78 | |
| 79 | This document is distributed under the terms of the GNU Free |
| 80 | Documentation License. A copy of the license is included in the |
| 81 | section entitled "GNU Free Documentation License". |
| 82 | |
| 83 | @menu |
| 84 | * README:: The README File |
| 85 | * Emulations:: How linker emulations are generated |
| 86 | * Emulation Walkthrough:: A Walkthrough of a Typical Emulation |
| 87 | * Architecture Specific:: Some Architecture Specific Notes |
| 88 | * GNU Free Documentation License:: GNU Free Documentation License |
| 89 | @end menu |
| 90 | |
| 91 | @node README |
| 92 | @chapter The @file{README} File |
| 93 | |
| 94 | Check the @file{README} file; it often has useful information that does not |
| 95 | appear anywhere else in the directory. |
| 96 | |
| 97 | @node Emulations |
| 98 | @chapter How linker emulations are generated |
| 99 | |
| 100 | Each linker target has an @dfn{emulation}. The emulation includes the |
| 101 | default linker script, and certain emulations also modify certain types |
| 102 | of linker behaviour. |
| 103 | |
| 104 | Emulations are created during the build process by the shell script |
| 105 | @file{genscripts.sh}. |
| 106 | |
| 107 | The @file{genscripts.sh} script starts by reading a file in the |
| 108 | @file{emulparams} directory. This is a shell script which sets various |
| 109 | shell variables used by @file{genscripts.sh} and the other shell scripts |
| 110 | it invokes. |
| 111 | |
| 112 | The @file{genscripts.sh} script will invoke a shell script in the |
| 113 | @file{scripttempl} directory in order to create default linker scripts |
| 114 | written in the linker command language. The @file{scripttempl} script |
| 115 | will be invoked 5 (or, in some cases, 6) times, with different |
| 116 | assignments to shell variables, to create different default scripts. |
| 117 | The choice of script is made based on the command line options. |
| 118 | |
| 119 | After creating the scripts, @file{genscripts.sh} will invoke yet another |
| 120 | shell script, this time in the @file{emultempl} directory. That shell |
| 121 | script will create the emulation source file, which contains C code. |
| 122 | This C code permits the linker emulation to override various linker |
| 123 | behaviours. Most targets use the generic emulation code, which is in |
| 124 | @file{emultempl/generic.em}. |
| 125 | |
| 126 | To summarize, @file{genscripts.sh} reads three shell scripts: an |
| 127 | emulation parameters script in the @file{emulparams} directory, a linker |
| 128 | script generation script in the @file{scripttempl} directory, and an |
| 129 | emulation source file generation script in the @file{emultempl} |
| 130 | directory. |
| 131 | |
| 132 | For example, the Sun 4 linker sets up variables in |
| 133 | @file{emulparams/sun4.sh}, creates linker scripts using |
| 134 | @file{scripttempl/aout.sc}, and creates the emulation code using |
| 135 | @file{emultempl/sunos.em}. |
| 136 | |
| 137 | Note that the linker can support several emulations simultaneously, |
| 138 | depending upon how it is configured. An emulation can be selected with |
| 139 | the @code{-m} option. The @code{-V} option will list all supported |
| 140 | emulations. |
| 141 | |
| 142 | @menu |
| 143 | * emulation parameters:: @file{emulparams} scripts |
| 144 | * linker scripts:: @file{scripttempl} scripts |
| 145 | * linker emulations:: @file{emultempl} scripts |
| 146 | @end menu |
| 147 | |
| 148 | @node emulation parameters |
| 149 | @section @file{emulparams} scripts |
| 150 | |
| 151 | Each target selects a particular file in the @file{emulparams} directory |
| 152 | by setting the shell variable @code{targ_emul} in @file{configure.tgt}. |
| 153 | This shell variable is used by the @file{configure} script to control |
| 154 | building an emulation source file. |
| 155 | |
| 156 | Certain conventions are enforced. Suppose the @code{targ_emul} variable |
| 157 | is set to @var{emul} in @file{configure.tgt}. The name of the emulation |
| 158 | shell script will be @file{emulparams/@var{emul}.sh}. The |
| 159 | @file{Makefile} must have a target named @file{e@var{emul}.c}; this |
| 160 | target must depend upon @file{emulparams/@var{emul}.sh}, as well as the |
| 161 | appropriate scripts in the @file{scripttempl} and @file{emultempl} |
| 162 | directories. The @file{Makefile} target must invoke @code{GENSCRIPTS} |
| 163 | with two arguments: @var{emul}, and the value of the make variable |
| 164 | @code{tdir_@var{emul}}. The value of the latter variable will be set by |
| 165 | the @file{configure} script, and is used to set the default target |
| 166 | directory to search. |
| 167 | |
| 168 | By convention, the @file{emulparams/@var{emul}.sh} shell script should |
| 169 | only set shell variables. It may set shell variables which are to be |
| 170 | interpreted by the @file{scripttempl} and the @file{emultempl} scripts. |
| 171 | Certain shell variables are interpreted directly by the |
| 172 | @file{genscripts.sh} script. |
| 173 | |
| 174 | Here is a list of shell variables interpreted by @file{genscripts.sh}, |
| 175 | as well as some conventional shell variables interpreted by the |
| 176 | @file{scripttempl} and @file{emultempl} scripts. |
| 177 | |
| 178 | @table @code |
| 179 | @item SCRIPT_NAME |
| 180 | This is the name of the @file{scripttempl} script to use. If |
| 181 | @code{SCRIPT_NAME} is set to @var{script}, @file{genscripts.sh} will use |
| 182 | the script @file{scriptteml/@var{script}.sc}. |
| 183 | |
| 184 | @item TEMPLATE_NAME |
| 185 | This is the name of the @file{emultemlp} script to use. If |
| 186 | @code{TEMPLATE_NAME} is set to @var{template}, @file{genscripts.sh} will |
| 187 | use the script @file{emultempl/@var{template}.em}. If this variable is |
| 188 | not set, the default value is @samp{generic}. |
| 189 | |
| 190 | @item GENERATE_SHLIB_SCRIPT |
| 191 | If this is set to a nonempty string, @file{genscripts.sh} will invoke |
| 192 | the @file{scripttempl} script an extra time to create a shared library |
| 193 | script. @ref{linker scripts}. |
| 194 | |
| 195 | @item OUTPUT_FORMAT |
| 196 | This is normally set to indicate the BFD output format use (e.g., |
| 197 | @samp{"a.out-sunos-big"}. The @file{scripttempl} script will normally |
| 198 | use it in an @code{OUTPUT_FORMAT} expression in the linker script. |
| 199 | |
| 200 | @item ARCH |
| 201 | This is normally set to indicate the architecture to use (e.g., |
| 202 | @samp{sparc}). The @file{scripttempl} script will normally use it in an |
| 203 | @code{OUTPUT_ARCH} expression in the linker script. |
| 204 | |
| 205 | @item ENTRY |
| 206 | Some @file{scripttempl} scripts use this to set the entry address, in an |
| 207 | @code{ENTRY} expression in the linker script. |
| 208 | |
| 209 | @item TEXT_START_ADDR |
| 210 | Some @file{scripttempl} scripts use this to set the start address of the |
| 211 | @samp{.text} section. |
| 212 | |
| 213 | @item NONPAGED_TEXT_START_ADDR |
| 214 | If this is defined, the @file{genscripts.sh} script sets |
| 215 | @code{TEXT_START_ADDR} to its value before running the |
| 216 | @file{scripttempl} script for the @code{-n} and @code{-N} options |
| 217 | (@pxref{linker scripts}). |
| 218 | |
| 219 | @item SEGMENT_SIZE |
| 220 | The @file{genscripts.sh} script uses this to set the default value of |
| 221 | @code{DATA_ALIGNMENT} when running the @file{scripttempl} script. |
| 222 | |
| 223 | @item TARGET_PAGE_SIZE |
| 224 | If @code{SEGMENT_SIZE} is not defined, the @file{genscripts.sh} script |
| 225 | uses this to define it. |
| 226 | |
| 227 | @item ALIGNMENT |
| 228 | Some @file{scripttempl} scripts set this to a number to pass to |
| 229 | @code{ALIGN} to set the required alignment for the @code{end} symbol. |
| 230 | @end table |
| 231 | |
| 232 | @node linker scripts |
| 233 | @section @file{scripttempl} scripts |
| 234 | |
| 235 | Each linker target uses a @file{scripttempl} script to generate the |
| 236 | default linker scripts. The name of the @file{scripttempl} script is |
| 237 | set by the @code{SCRIPT_NAME} variable in the @file{emulparams} script. |
| 238 | If @code{SCRIPT_NAME} is set to @var{script}, @code{genscripts.sh} will |
| 239 | invoke @file{scripttempl/@var{script}.sc}. |
| 240 | |
| 241 | The @file{genscripts.sh} script will invoke the @file{scripttempl} |
| 242 | script 5 to 8 times. Each time it will set the shell variable |
| 243 | @code{LD_FLAG} to a different value. When the linker is run, the |
| 244 | options used will direct it to select a particular script. (Script |
| 245 | selection is controlled by the @code{get_script} emulation entry point; |
| 246 | this describes the conventional behaviour). |
| 247 | |
| 248 | The @file{scripttempl} script should just write a linker script, written |
| 249 | in the linker command language, to standard output. If the emulation |
| 250 | name--the name of the @file{emulparams} file without the @file{.sc} |
| 251 | extension--is @var{emul}, then the output will be directed to |
| 252 | @file{ldscripts/@var{emul}.@var{extension}} in the build directory, |
| 253 | where @var{extension} changes each time the @file{scripttempl} script is |
| 254 | invoked. |
| 255 | |
| 256 | Here is the list of values assigned to @code{LD_FLAG}. |
| 257 | |
| 258 | @table @code |
| 259 | @item (empty) |
| 260 | The script generated is used by default (when none of the following |
| 261 | cases apply). The output has an extension of @file{.x}. |
| 262 | @item n |
| 263 | The script generated is used when the linker is invoked with the |
| 264 | @code{-n} option. The output has an extension of @file{.xn}. |
| 265 | @item N |
| 266 | The script generated is used when the linker is invoked with the |
| 267 | @code{-N} option. The output has an extension of @file{.xbn}. |
| 268 | @item r |
| 269 | The script generated is used when the linker is invoked with the |
| 270 | @code{-r} option. The output has an extension of @file{.xr}. |
| 271 | @item u |
| 272 | The script generated is used when the linker is invoked with the |
| 273 | @code{-Ur} option. The output has an extension of @file{.xu}. |
| 274 | @item shared |
| 275 | The @file{scripttempl} script is only invoked with @code{LD_FLAG} set to |
| 276 | this value if @code{GENERATE_SHLIB_SCRIPT} is defined in the |
| 277 | @file{emulparams} file. The @file{emultempl} script must arrange to use |
| 278 | this script at the appropriate time, normally when the linker is invoked |
| 279 | with the @code{-shared} option. The output has an extension of |
| 280 | @file{.xs}. |
| 281 | @item c |
| 282 | The @file{scripttempl} script is only invoked with @code{LD_FLAG} set to |
| 283 | this value if @code{GENERATE_COMBRELOC_SCRIPT} is defined in the |
| 284 | @file{emulparams} file or if @code{SCRIPT_NAME} is @code{elf}. The |
| 285 | @file{emultempl} script must arrange to use this script at the appropriate |
| 286 | time, normally when the linker is invoked with the @code{-z combreloc} |
| 287 | option. The output has an extension of |
| 288 | @file{.xc}. |
| 289 | @item cshared |
| 290 | The @file{scripttempl} script is only invoked with @code{LD_FLAG} set to |
| 291 | this value if @code{GENERATE_COMBRELOC_SCRIPT} is defined in the |
| 292 | @file{emulparams} file or if @code{SCRIPT_NAME} is @code{elf} and |
| 293 | @code{GENERATE_SHLIB_SCRIPT} is defined in the @file{emulparms} file. |
| 294 | The @file{emultempl} script must arrange to use this script at the |
| 295 | appropriate time, normally when the linker is invoked with the @code{-shared |
| 296 | -z combreloc} option. The output has an extension of @file{.xsc}. |
| 297 | @end table |
| 298 | |
| 299 | Besides the shell variables set by the @file{emulparams} script, and the |
| 300 | @code{LD_FLAG} variable, the @file{genscripts.sh} script will set |
| 301 | certain variables for each run of the @file{scripttempl} script. |
| 302 | |
| 303 | @table @code |
| 304 | @item RELOCATING |
| 305 | This will be set to a non-empty string when the linker is doing a final |
| 306 | relocation (e.g., all scripts other than @code{-r} and @code{-Ur}). |
| 307 | |
| 308 | @item CONSTRUCTING |
| 309 | This will be set to a non-empty string when the linker is building |
| 310 | global constructor and destructor tables (e.g., all scripts other than |
| 311 | @code{-r}). |
| 312 | |
| 313 | @item DATA_ALIGNMENT |
| 314 | This will be set to an @code{ALIGN} expression when the output should be |
| 315 | page aligned, or to @samp{.} when generating the @code{-N} script. |
| 316 | |
| 317 | @item CREATE_SHLIB |
| 318 | This will be set to a non-empty string when generating a @code{-shared} |
| 319 | script. |
| 320 | |
| 321 | @item COMBRELOC |
| 322 | This will be set to a non-empty string when generating @code{-z combreloc} |
| 323 | scripts to a temporary file name which can be used during script generation. |
| 324 | @end table |
| 325 | |
| 326 | The conventional way to write a @file{scripttempl} script is to first |
| 327 | set a few shell variables, and then write out a linker script using |
| 328 | @code{cat} with a here document. The linker script will use variable |
| 329 | substitutions, based on the above variables and those set in the |
| 330 | @file{emulparams} script, to control its behaviour. |
| 331 | |
| 332 | When there are parts of the @file{scripttempl} script which should only |
| 333 | be run when doing a final relocation, they should be enclosed within a |
| 334 | variable substitution based on @code{RELOCATING}. For example, on many |
| 335 | targets special symbols such as @code{_end} should be defined when doing |
| 336 | a final link. Naturally, those symbols should not be defined when doing |
| 337 | a relocateable link using @code{-r}. The @file{scripttempl} script |
| 338 | could use a construct like this to define those symbols: |
| 339 | @smallexample |
| 340 | $@{RELOCATING+ _end = .;@} |
| 341 | @end smallexample |
| 342 | This will do the symbol assignment only if the @code{RELOCATING} |
| 343 | variable is defined. |
| 344 | |
| 345 | The basic job of the linker script is to put the sections in the correct |
| 346 | order, and at the correct memory addresses. For some targets, the |
| 347 | linker script may have to do some other operations. |
| 348 | |
| 349 | For example, on most MIPS platforms, the linker is responsible for |
| 350 | defining the special symbol @code{_gp}, used to initialize the |
| 351 | @code{$gp} register. It must be set to the start of the small data |
| 352 | section plus @code{0x8000}. Naturally, it should only be defined when |
| 353 | doing a final relocation. This will typically be done like this: |
| 354 | @smallexample |
| 355 | $@{RELOCATING+ _gp = ALIGN(16) + 0x8000;@} |
| 356 | @end smallexample |
| 357 | This line would appear just before the sections which compose the small |
| 358 | data section (@samp{.sdata}, @samp{.sbss}). All those sections would be |
| 359 | contiguous in memory. |
| 360 | |
| 361 | Many COFF systems build constructor tables in the linker script. The |
| 362 | compiler will arrange to output the address of each global constructor |
| 363 | in a @samp{.ctor} section, and the address of each global destructor in |
| 364 | a @samp{.dtor} section (this is done by defining |
| 365 | @code{ASM_OUTPUT_CONSTRUCTOR} and @code{ASM_OUTPUT_DESTRUCTOR} in the |
| 366 | @code{gcc} configuration files). The @code{gcc} runtime support |
| 367 | routines expect the constructor table to be named @code{__CTOR_LIST__}. |
| 368 | They expect it to be a list of words, with the first word being the |
| 369 | count of the number of entries. There should be a trailing zero word. |
| 370 | (Actually, the count may be -1 if the trailing word is present, and the |
| 371 | trailing word may be omitted if the count is correct, but, as the |
| 372 | @code{gcc} behaviour has changed slightly over the years, it is safest |
| 373 | to provide both). Here is a typical way that might be handled in a |
| 374 | @file{scripttempl} file. |
| 375 | @smallexample |
| 376 | $@{CONSTRUCTING+ __CTOR_LIST__ = .;@} |
| 377 | $@{CONSTRUCTING+ LONG((__CTOR_END__ - __CTOR_LIST__) / 4 - 2)@} |
| 378 | $@{CONSTRUCTING+ *(.ctors)@} |
| 379 | $@{CONSTRUCTING+ LONG(0)@} |
| 380 | $@{CONSTRUCTING+ __CTOR_END__ = .;@} |
| 381 | $@{CONSTRUCTING+ __DTOR_LIST__ = .;@} |
| 382 | $@{CONSTRUCTING+ LONG((__DTOR_END__ - __DTOR_LIST__) / 4 - 2)@} |
| 383 | $@{CONSTRUCTING+ *(.dtors)@} |
| 384 | $@{CONSTRUCTING+ LONG(0)@} |
| 385 | $@{CONSTRUCTING+ __DTOR_END__ = .;@} |
| 386 | @end smallexample |
| 387 | The use of @code{CONSTRUCTING} ensures that these linker script commands |
| 388 | will only appear when the linker is supposed to be building the |
| 389 | constructor and destructor tables. This example is written for a target |
| 390 | which uses 4 byte pointers. |
| 391 | |
| 392 | Embedded systems often need to set a stack address. This is normally |
| 393 | best done by using the @code{PROVIDE} construct with a default stack |
| 394 | address. This permits the user to easily override the stack address |
| 395 | using the @code{--defsym} option. Here is an example: |
| 396 | @smallexample |
| 397 | $@{RELOCATING+ PROVIDE (__stack = 0x80000000);@} |
| 398 | @end smallexample |
| 399 | The value of the symbol @code{__stack} would then be used in the startup |
| 400 | code to initialize the stack pointer. |
| 401 | |
| 402 | @node linker emulations |
| 403 | @section @file{emultempl} scripts |
| 404 | |
| 405 | Each linker target uses an @file{emultempl} script to generate the |
| 406 | emulation code. The name of the @file{emultempl} script is set by the |
| 407 | @code{TEMPLATE_NAME} variable in the @file{emulparams} script. If the |
| 408 | @code{TEMPLATE_NAME} variable is not set, the default is |
| 409 | @samp{generic}. If the value of @code{TEMPLATE_NAME} is @var{template}, |
| 410 | @file{genscripts.sh} will use @file{emultempl/@var{template}.em}. |
| 411 | |
| 412 | Most targets use the generic @file{emultempl} script, |
| 413 | @file{emultempl/generic.em}. A different @file{emultempl} script is |
| 414 | only needed if the linker must support unusual actions, such as linking |
| 415 | against shared libraries. |
| 416 | |
| 417 | The @file{emultempl} script is normally written as a simple invocation |
| 418 | of @code{cat} with a here document. The document will use a few |
| 419 | variable substitutions. Typically each function names uses a |
| 420 | substitution involving @code{EMULATION_NAME}, for ease of debugging when |
| 421 | the linker supports multiple emulations. |
| 422 | |
| 423 | Every function and variable in the emitted file should be static. The |
| 424 | only globally visible object must be named |
| 425 | @code{ld_@var{EMULATION_NAME}_emulation}, where @var{EMULATION_NAME} is |
| 426 | the name of the emulation set in @file{configure.tgt} (this is also the |
| 427 | name of the @file{emulparams} file without the @file{.sh} extension). |
| 428 | The @file{genscripts.sh} script will set the shell variable |
| 429 | @code{EMULATION_NAME} before invoking the @file{emultempl} script. |
| 430 | |
| 431 | The @code{ld_@var{EMULATION_NAME}_emulation} variable must be a |
| 432 | @code{struct ld_emulation_xfer_struct}, as defined in @file{ldemul.h}. |
| 433 | It defines a set of function pointers which are invoked by the linker, |
| 434 | as well as strings for the emulation name (normally set from the shell |
| 435 | variable @code{EMULATION_NAME} and the default BFD target name (normally |
| 436 | set from the shell variable @code{OUTPUT_FORMAT} which is normally set |
| 437 | by the @file{emulparams} file). |
| 438 | |
| 439 | The @file{genscripts.sh} script will set the shell variable |
| 440 | @code{COMPILE_IN} when it invokes the @file{emultempl} script for the |
| 441 | default emulation. In this case, the @file{emultempl} script should |
| 442 | include the linker scripts directly, and return them from the |
| 443 | @code{get_scripts} entry point. When the emulation is not the default, |
| 444 | the @code{get_scripts} entry point should just return a file name. See |
| 445 | @file{emultempl/generic.em} for an example of how this is done. |
| 446 | |
| 447 | At some point, the linker emulation entry points should be documented. |
| 448 | |
| 449 | @node Emulation Walkthrough |
| 450 | @chapter A Walkthrough of a Typical Emulation |
| 451 | |
| 452 | This chapter is to help people who are new to the way emulations |
| 453 | interact with the linker, or who are suddenly thrust into the position |
| 454 | of having to work with existing emulations. It will discuss the files |
| 455 | you need to be aware of. It will tell you when the given "hooks" in |
| 456 | the emulation will be called. It will, hopefully, give you enough |
| 457 | information about when and how things happen that you'll be able to |
| 458 | get by. As always, the source is the definitive reference to this. |
| 459 | |
| 460 | The starting point for the linker is in @file{ldmain.c} where |
| 461 | @code{main} is defined. The bulk of the code that's emulation |
| 462 | specific will initially be in @code{emultempl/@var{emulation}.em} but |
| 463 | will end up in @code{e@var{emulation}.c} when the build is done. |
| 464 | Most of the work to select and interface with emulations is in |
| 465 | @code{ldemul.h} and @code{ldemul.c}. Specifically, @code{ldemul.h} |
| 466 | defines the @code{ld_emulation_xfer_struct} structure your emulation |
| 467 | exports. |
| 468 | |
| 469 | Your emulation file exports a symbol |
| 470 | @code{ld_@var{EMULATION_NAME}_emulation}. If your emulation is |
| 471 | selected (it usually is, since usually there's only one), |
| 472 | @code{ldemul.c} sets the variable @var{ld_emulation} to point to it. |
| 473 | @code{ldemul.c} also defines a number of API functions that interface |
| 474 | to your emulation, like @code{ldemul_after_parse} which simply calls |
| 475 | your @code{ld_@var{EMULATION}_emulation.after_parse} function. For |
| 476 | the rest of this section, the functions will be mentioned, but you |
| 477 | should assume the indirect reference to your emulation also. |
| 478 | |
| 479 | We will also skip or gloss over parts of the link process that don't |
| 480 | relate to emulations, like setting up internationalization. |
| 481 | |
| 482 | After initialization, @code{main} selects an emulation by pre-scanning |
| 483 | the command line arguments. It calls @code{ldemul_choose_target} to |
| 484 | choose a target. If you set @code{choose_target} to |
| 485 | @code{ldemul_default_target}, it picks your @code{target_name} by |
| 486 | default. |
| 487 | |
| 488 | @code{main} calls @code{ldemul_before_parse}, then @code{parse_args}. |
| 489 | @code{parse_args} calls @code{ldemul_parse_args} for each arg, which |
| 490 | must update the @code{getopt} globals if it recognizes the argument. |
| 491 | If the emulation doesn't recognize it, then parse_args checks to see |
| 492 | if it recognizes it. |
| 493 | |
| 494 | Now that the emulation has had access to all its command-line options, |
| 495 | @code{main} calls @code{ldemul_set_symbols}. This can be used for any |
| 496 | initialization that may be affected by options. It is also supposed |
| 497 | to set up any variables needed by the emulation script. |
| 498 | |
| 499 | @code{main} now calls @code{ldemul_get_script} to get the emulation |
| 500 | script to use (based on arguments, no doubt, @pxref{Emulations}) and |
| 501 | runs it. While parsing, @code{ldgram.y} may call @code{ldemul_hll} or |
| 502 | @code{ldemul_syslib} to handle the @code{HLL} or @code{SYSLIB} |
| 503 | commands. It may call @code{ldemul_unrecognized_file} if you asked |
| 504 | the linker to link a file it doesn't recognize. It will call |
| 505 | @code{ldemul_recognized_file} for each file it does recognize, in case |
| 506 | the emulation wants to handle some files specially. All the while, |
| 507 | it's loading the files (possibly calling |
| 508 | @code{ldemul_open_dynamic_archive}) and symbols and stuff. After it's |
| 509 | done reading the script, @code{main} calls @code{ldemul_after_parse}. |
| 510 | Use the after-parse hook to set up anything that depends on stuff the |
| 511 | script might have set up, like the entry point. |
| 512 | |
| 513 | @code{main} next calls @code{lang_process} in @code{ldlang.c}. This |
| 514 | appears to be the main core of the linking itself, as far as emulation |
| 515 | hooks are concerned(*). It first opens the output file's BFD, calling |
| 516 | @code{ldemul_set_output_arch}, and calls |
| 517 | @code{ldemul_create_output_section_statements} in case you need to use |
| 518 | other means to find or create object files (i.e. shared libraries |
| 519 | found on a path, or fake stub objects). Despite the name, nobody |
| 520 | creates output sections here. |
| 521 | |
| 522 | (*) In most cases, the BFD library does the bulk of the actual |
| 523 | linking, handling symbol tables, symbol resolution, relocations, and |
| 524 | building the final output file. See the BFD reference for all the |
| 525 | details. Your emulation is usually concerned more with managing |
| 526 | things at the file and section level, like "put this here, add this |
| 527 | section", etc. |
| 528 | |
| 529 | Next, the objects to be linked are opened and BFDs created for them, |
| 530 | and @code{ldemul_after_open} is called. At this point, you have all |
| 531 | the objects and symbols loaded, but none of the data has been placed |
| 532 | yet. |
| 533 | |
| 534 | Next comes the Big Linking Thingy (except for the parts BFD does). |
| 535 | All input sections are mapped to output sections according to the |
| 536 | script. If a section doesn't get mapped by default, |
| 537 | @code{ldemul_place_orphan} will get called to figure out where it goes. |
| 538 | Next it figures out the offsets for each section, calling |
| 539 | @code{ldemul_before_allocation} before and |
| 540 | @code{ldemul_after_allocation} after deciding where each input section |
| 541 | ends up in the output sections. |
| 542 | |
| 543 | The last part of @code{lang_process} is to figure out all the symbols' |
| 544 | values. After assigning final values to the symbols, |
| 545 | @code{ldemul_finish} is called, and after that, any undefined symbols |
| 546 | are turned into fatal errors. |
| 547 | |
| 548 | OK, back to @code{main}, which calls @code{ldwrite} in |
| 549 | @file{ldwrite.c}. @code{ldwrite} calls BFD's final_link, which does |
| 550 | all the relocation fixups and writes the output bfd to disk, and we're |
| 551 | done. |
| 552 | |
| 553 | In summary, |
| 554 | |
| 555 | @itemize @bullet |
| 556 | |
| 557 | @item @code{main()} in @file{ldmain.c} |
| 558 | @item @file{emultempl/@var{EMULATION}.em} has your code |
| 559 | @item @code{ldemul_choose_target} (defaults to your @code{target_name}) |
| 560 | @item @code{ldemul_before_parse} |
| 561 | @item Parse argv, calls @code{ldemul_parse_args} for each |
| 562 | @item @code{ldemul_set_symbols} |
| 563 | @item @code{ldemul_get_script} |
| 564 | @item parse script |
| 565 | |
| 566 | @itemize @bullet |
| 567 | @item may call @code{ldemul_hll} or @code{ldemul_syslib} |
| 568 | @item may call @code{ldemul_open_dynamic_archive} |
| 569 | @end itemize |
| 570 | |
| 571 | @item @code{ldemul_after_parse} |
| 572 | @item @code{lang_process()} in @file{ldlang.c} |
| 573 | |
| 574 | @itemize @bullet |
| 575 | @item create @code{output_bfd} |
| 576 | @item @code{ldemul_set_output_arch} |
| 577 | @item @code{ldemul_create_output_section_statements} |
| 578 | @item read objects, create input bfds - all symbols exist, but have no values |
| 579 | @item may call @code{ldemul_unrecognized_file} |
| 580 | @item will call @code{ldemul_recognized_file} |
| 581 | @item @code{ldemul_after_open} |
| 582 | @item map input sections to output sections |
| 583 | @item may call @code{ldemul_place_orphan} for remaining sections |
| 584 | @item @code{ldemul_before_allocation} |
| 585 | @item gives input sections offsets into output sections, places output sections |
| 586 | @item @code{ldemul_after_allocation} - section addresses valid |
| 587 | @item assigns values to symbols |
| 588 | @item @code{ldemul_finish} - symbol values valid |
| 589 | @end itemize |
| 590 | |
| 591 | @item output bfd is written to disk |
| 592 | |
| 593 | @end itemize |
| 594 | |
| 595 | @node Architecture Specific |
| 596 | @chapter Some Architecture Specific Notes |
| 597 | |
| 598 | This is the place for notes on the behavior of @code{ld} on |
| 599 | specific platforms. Currently, only Intel x86 is documented (and |
| 600 | of that, only the auto-import behavior for DLLs). |
| 601 | |
| 602 | @menu |
| 603 | * ix86:: Intel x86 |
| 604 | @end menu |
| 605 | |
| 606 | @node ix86 |
| 607 | @section Intel x86 |
| 608 | |
| 609 | @table @emph |
| 610 | @code{ld} can create DLLs that operate with various runtimes available |
| 611 | on a common x86 operating system. These runtimes include native (using |
| 612 | the mingw "platform"), cygwin, and pw. |
| 613 | |
| 614 | @item auto-import from DLLs |
| 615 | @enumerate |
| 616 | @item |
| 617 | With this feature on, DLL clients can import variables from DLL |
| 618 | without any concern from their side (for example, without any source |
| 619 | code modifications). Auto-import can be enabled using the |
| 620 | @code{--enable-auto-import} flag, or disabled via the |
| 621 | @code{--disable-auto-import} flag. Auto-import is disabled by default. |
| 622 | |
| 623 | @item |
| 624 | This is done completely in bounds of the PE specification (to be fair, |
| 625 | there's a minor violation of the spec at one point, but in practice |
| 626 | auto-import works on all known variants of that common x86 operating |
| 627 | system) So, the resulting DLL can be used with any other PE |
| 628 | compiler/linker. |
| 629 | |
| 630 | @item |
| 631 | Auto-import is fully compatible with standard import method, in which |
| 632 | variables are decorated using attribute modifiers. Libraries of either |
| 633 | type may be mixed together. |
| 634 | |
| 635 | @item |
| 636 | Overhead (space): 8 bytes per imported symbol, plus 20 for each |
| 637 | reference to it; Overhead (load time): negligible; Overhead |
| 638 | (virtual/physical memory): should be less than effect of DLL |
| 639 | relocation. |
| 640 | @end enumerate |
| 641 | |
| 642 | Motivation |
| 643 | |
| 644 | The obvious and only way to get rid of dllimport insanity is |
| 645 | to make client access variable directly in the DLL, bypassing |
| 646 | the extra dereference imposed by ordinary DLL runtime linking. |
| 647 | I.e., whenever client contains someting like |
| 648 | |
| 649 | @code{mov dll_var,%eax,} |
| 650 | |
| 651 | address of dll_var in the command should be relocated to point |
| 652 | into loaded DLL. The aim is to make OS loader do so, and than |
| 653 | make ld help with that. Import section of PE made following |
| 654 | way: there's a vector of structures each describing imports |
| 655 | from particular DLL. Each such structure points to two other |
| 656 | parellel vectors: one holding imported names, and one which |
| 657 | will hold address of corresponding imported name. So, the |
| 658 | solution is de-vectorize these structures, making import |
| 659 | locations be sparse and pointing directly into code. |
| 660 | |
| 661 | Implementation |
| 662 | |
| 663 | For each reference of data symbol to be imported from DLL (to |
| 664 | set of which belong symbols with name <sym>, if __imp_<sym> is |
| 665 | found in implib), the import fixup entry is generated. That |
| 666 | entry is of type IMAGE_IMPORT_DESCRIPTOR and stored in .idata$3 |
| 667 | subsection. Each fixup entry contains pointer to symbol's address |
| 668 | within .text section (marked with __fuN_<sym> symbol, where N is |
| 669 | integer), pointer to DLL name (so, DLL name is referenced by |
| 670 | multiple entries), and pointer to symbol name thunk. Symbol name |
| 671 | thunk is singleton vector (__nm_th_<symbol>) pointing to |
| 672 | IMAGE_IMPORT_BY_NAME structure (__nm_<symbol>) directly containing |
| 673 | imported name. Here comes that "om the edge" problem mentioned above: |
| 674 | PE specification rambles that name vector (OriginalFirstThunk) should |
| 675 | run in parallel with addresses vector (FirstThunk), i.e. that they |
| 676 | should have same number of elements and terminated with zero. We violate |
| 677 | this, since FirstThunk points directly into machine code. But in |
| 678 | practice, OS loader implemented the sane way: it goes thru |
| 679 | OriginalFirstThunk and puts addresses to FirstThunk, not something |
| 680 | else. It once again should be noted that dll and symbol name |
| 681 | structures are reused across fixup entries and should be there |
| 682 | anyway to support standard import stuff, so sustained overhead is |
| 683 | 20 bytes per reference. Other question is whether having several |
| 684 | IMAGE_IMPORT_DESCRIPTORS for the same DLL is possible. Answer is yes, |
| 685 | it is done even by native compiler/linker (libth32's functions are in |
| 686 | fact resident in windows9x kernel32.dll, so if you use it, you have |
| 687 | two IMAGE_IMPORT_DESCRIPTORS for kernel32.dll). Yet other question is |
| 688 | whether referencing the same PE structures several times is valid. |
| 689 | The answer is why not, prohibiting that (detecting violation) would |
| 690 | require more work on behalf of loader than not doing it. |
| 691 | |
| 692 | @end table |
| 693 | |
| 694 | @node GNU Free Documentation License |
| 695 | @chapter GNU Free Documentation License |
| 696 | |
| 697 | GNU Free Documentation License |
| 698 | |
| 699 | Version 1.1, March 2000 |
| 700 | |
| 701 | Copyright (C) 2000 Free Software Foundation, Inc. |
| 702 | 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA |
| 703 | |
| 704 | Everyone is permitted to copy and distribute verbatim copies |
| 705 | of this license document, but changing it is not allowed. |
| 706 | |
| 707 | |
| 708 | 0. PREAMBLE |
| 709 | |
| 710 | The purpose of this License is to make a manual, textbook, or other |
| 711 | written document "free" in the sense of freedom: to assure everyone |
| 712 | the effective freedom to copy and redistribute it, with or without |
| 713 | modifying it, either commercially or noncommercially. Secondarily, |
| 714 | this License preserves for the author and publisher a way to get |
| 715 | credit for their work, while not being considered responsible for |
| 716 | modifications made by others. |
| 717 | |
| 718 | This License is a kind of "copyleft", which means that derivative |
| 719 | works of the document must themselves be free in the same sense. It |
| 720 | complements the GNU General Public License, which is a copyleft |
| 721 | license designed for free software. |
| 722 | |
| 723 | We have designed this License in order to use it for manuals for free |
| 724 | software, because free software needs free documentation: a free |
| 725 | program should come with manuals providing the same freedoms that the |
| 726 | software does. But this License is not limited to software manuals; |
| 727 | it can be used for any textual work, regardless of subject matter or |
| 728 | whether it is published as a printed book. We recommend this License |
| 729 | principally for works whose purpose is instruction or reference. |
| 730 | |
| 731 | |
| 732 | 1. APPLICABILITY AND DEFINITIONS |
| 733 | |
| 734 | This License applies to any manual or other work that contains a |
| 735 | notice placed by the copyright holder saying it can be distributed |
| 736 | under the terms of this License. The "Document", below, refers to any |
| 737 | such manual or work. Any member of the public is a licensee, and is |
| 738 | addressed as "you". |
| 739 | |
| 740 | A "Modified Version" of the Document means any work containing the |
| 741 | Document or a portion of it, either copied verbatim, or with |
| 742 | modifications and/or translated into another language. |
| 743 | |
| 744 | A "Secondary Section" is a named appendix or a front-matter section of |
| 745 | the Document that deals exclusively with the relationship of the |
| 746 | publishers or authors of the Document to the Document's overall subject |
| 747 | (or to related matters) and contains nothing that could fall directly |
| 748 | within that overall subject. (For example, if the Document is in part a |
| 749 | textbook of mathematics, a Secondary Section may not explain any |
| 750 | mathematics.) The relationship could be a matter of historical |
| 751 | connection with the subject or with related matters, or of legal, |
| 752 | commercial, philosophical, ethical or political position regarding |
| 753 | them. |
| 754 | |
| 755 | The "Invariant Sections" are certain Secondary Sections whose titles |
| 756 | are designated, as being those of Invariant Sections, in the notice |
| 757 | that says that the Document is released under this License. |
| 758 | |
| 759 | The "Cover Texts" are certain short passages of text that are listed, |
| 760 | as Front-Cover Texts or Back-Cover Texts, in the notice that says that |
| 761 | the Document is released under this License. |
| 762 | |
| 763 | A "Transparent" copy of the Document means a machine-readable copy, |
| 764 | represented in a format whose specification is available to the |
| 765 | general public, whose contents can be viewed and edited directly and |
| 766 | straightforwardly with generic text editors or (for images composed of |
| 767 | pixels) generic paint programs or (for drawings) some widely available |
| 768 | drawing editor, and that is suitable for input to text formatters or |
| 769 | for automatic translation to a variety of formats suitable for input |
| 770 | to text formatters. A copy made in an otherwise Transparent file |
| 771 | format whose markup has been designed to thwart or discourage |
| 772 | subsequent modification by readers is not Transparent. A copy that is |
| 773 | not "Transparent" is called "Opaque". |
| 774 | |
| 775 | Examples of suitable formats for Transparent copies include plain |
| 776 | ASCII without markup, Texinfo input format, LaTeX input format, SGML |
| 777 | or XML using a publicly available DTD, and standard-conforming simple |
| 778 | HTML designed for human modification. Opaque formats include |
| 779 | PostScript, PDF, proprietary formats that can be read and edited only |
| 780 | by proprietary word processors, SGML or XML for which the DTD and/or |
| 781 | processing tools are not generally available, and the |
| 782 | machine-generated HTML produced by some word processors for output |
| 783 | purposes only. |
| 784 | |
| 785 | The "Title Page" means, for a printed book, the title page itself, |
| 786 | plus such following pages as are needed to hold, legibly, the material |
| 787 | this License requires to appear in the title page. For works in |
| 788 | formats which do not have any title page as such, "Title Page" means |
| 789 | the text near the most prominent appearance of the work's title, |
| 790 | preceding the beginning of the body of the text. |
| 791 | |
| 792 | |
| 793 | 2. VERBATIM COPYING |
| 794 | |
| 795 | You may copy and distribute the Document in any medium, either |
| 796 | commercially or noncommercially, provided that this License, the |
| 797 | copyright notices, and the license notice saying this License applies |
| 798 | to the Document are reproduced in all copies, and that you add no other |
| 799 | conditions whatsoever to those of this License. You may not use |
| 800 | technical measures to obstruct or control the reading or further |
| 801 | copying of the copies you make or distribute. However, you may accept |
| 802 | compensation in exchange for copies. If you distribute a large enough |
| 803 | number of copies you must also follow the conditions in section 3. |
| 804 | |
| 805 | You may also lend copies, under the same conditions stated above, and |
| 806 | you may publicly display copies. |
| 807 | |
| 808 | |
| 809 | 3. COPYING IN QUANTITY |
| 810 | |
| 811 | If you publish printed copies of the Document numbering more than 100, |
| 812 | and the Document's license notice requires Cover Texts, you must enclose |
| 813 | the copies in covers that carry, clearly and legibly, all these Cover |
| 814 | Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on |
| 815 | the back cover. Both covers must also clearly and legibly identify |
| 816 | you as the publisher of these copies. The front cover must present |
| 817 | the full title with all words of the title equally prominent and |
| 818 | visible. You may add other material on the covers in addition. |
| 819 | Copying with changes limited to the covers, as long as they preserve |
| 820 | the title of the Document and satisfy these conditions, can be treated |
| 821 | as verbatim copying in other respects. |
| 822 | |
| 823 | If the required texts for either cover are too voluminous to fit |
| 824 | legibly, you should put the first ones listed (as many as fit |
| 825 | reasonably) on the actual cover, and continue the rest onto adjacent |
| 826 | pages. |
| 827 | |
| 828 | If you publish or distribute Opaque copies of the Document numbering |
| 829 | more than 100, you must either include a machine-readable Transparent |
| 830 | copy along with each Opaque copy, or state in or with each Opaque copy |
| 831 | a publicly-accessible computer-network location containing a complete |
| 832 | Transparent copy of the Document, free of added material, which the |
| 833 | general network-using public has access to download anonymously at no |
| 834 | charge using public-standard network protocols. If you use the latter |
| 835 | option, you must take reasonably prudent steps, when you begin |
| 836 | distribution of Opaque copies in quantity, to ensure that this |
| 837 | Transparent copy will remain thus accessible at the stated location |
| 838 | until at least one year after the last time you distribute an Opaque |
| 839 | copy (directly or through your agents or retailers) of that edition to |
| 840 | the public. |
| 841 | |
| 842 | It is requested, but not required, that you contact the authors of the |
| 843 | Document well before redistributing any large number of copies, to give |
| 844 | them a chance to provide you with an updated version of the Document. |
| 845 | |
| 846 | |
| 847 | 4. MODIFICATIONS |
| 848 | |
| 849 | You may copy and distribute a Modified Version of the Document under |
| 850 | the conditions of sections 2 and 3 above, provided that you release |
| 851 | the Modified Version under precisely this License, with the Modified |
| 852 | Version filling the role of the Document, thus licensing distribution |
| 853 | and modification of the Modified Version to whoever possesses a copy |
| 854 | of it. In addition, you must do these things in the Modified Version: |
| 855 | |
| 856 | A. Use in the Title Page (and on the covers, if any) a title distinct |
| 857 | from that of the Document, and from those of previous versions |
| 858 | (which should, if there were any, be listed in the History section |
| 859 | of the Document). You may use the same title as a previous version |
| 860 | if the original publisher of that version gives permission. |
| 861 | B. List on the Title Page, as authors, one or more persons or entities |
| 862 | responsible for authorship of the modifications in the Modified |
| 863 | Version, together with at least five of the principal authors of the |
| 864 | Document (all of its principal authors, if it has less than five). |
| 865 | C. State on the Title page the name of the publisher of the |
| 866 | Modified Version, as the publisher. |
| 867 | D. Preserve all the copyright notices of the Document. |
| 868 | E. Add an appropriate copyright notice for your modifications |
| 869 | adjacent to the other copyright notices. |
| 870 | F. Include, immediately after the copyright notices, a license notice |
| 871 | giving the public permission to use the Modified Version under the |
| 872 | terms of this License, in the form shown in the Addendum below. |
| 873 | G. Preserve in that license notice the full lists of Invariant Sections |
| 874 | and required Cover Texts given in the Document's license notice. |
| 875 | H. Include an unaltered copy of this License. |
| 876 | I. Preserve the section entitled "History", and its title, and add to |
| 877 | it an item stating at least the title, year, new authors, and |
| 878 | publisher of the Modified Version as given on the Title Page. If |
| 879 | there is no section entitled "History" in the Document, create one |
| 880 | stating the title, year, authors, and publisher of the Document as |
| 881 | given on its Title Page, then add an item describing the Modified |
| 882 | Version as stated in the previous sentence. |
| 883 | J. Preserve the network location, if any, given in the Document for |
| 884 | public access to a Transparent copy of the Document, and likewise |
| 885 | the network locations given in the Document for previous versions |
| 886 | it was based on. These may be placed in the "History" section. |
| 887 | You may omit a network location for a work that was published at |
| 888 | least four years before the Document itself, or if the original |
| 889 | publisher of the version it refers to gives permission. |
| 890 | K. In any section entitled "Acknowledgements" or "Dedications", |
| 891 | preserve the section's title, and preserve in the section all the |
| 892 | substance and tone of each of the contributor acknowledgements |
| 893 | and/or dedications given therein. |
| 894 | L. Preserve all the Invariant Sections of the Document, |
| 895 | unaltered in their text and in their titles. Section numbers |
| 896 | or the equivalent are not considered part of the section titles. |
| 897 | M. Delete any section entitled "Endorsements". Such a section |
| 898 | may not be included in the Modified Version. |
| 899 | N. Do not retitle any existing section as "Endorsements" |
| 900 | or to conflict in title with any Invariant Section. |
| 901 | |
| 902 | If the Modified Version includes new front-matter sections or |
| 903 | appendices that qualify as Secondary Sections and contain no material |
| 904 | copied from the Document, you may at your option designate some or all |
| 905 | of these sections as invariant. To do this, add their titles to the |
| 906 | list of Invariant Sections in the Modified Version's license notice. |
| 907 | These titles must be distinct from any other section titles. |
| 908 | |
| 909 | You may add a section entitled "Endorsements", provided it contains |
| 910 | nothing but endorsements of your Modified Version by various |
| 911 | parties--for example, statements of peer review or that the text has |
| 912 | been approved by an organization as the authoritative definition of a |
| 913 | standard. |
| 914 | |
| 915 | You may add a passage of up to five words as a Front-Cover Text, and a |
| 916 | passage of up to 25 words as a Back-Cover Text, to the end of the list |
| 917 | of Cover Texts in the Modified Version. Only one passage of |
| 918 | Front-Cover Text and one of Back-Cover Text may be added by (or |
| 919 | through arrangements made by) any one entity. If the Document already |
| 920 | includes a cover text for the same cover, previously added by you or |
| 921 | by arrangement made by the same entity you are acting on behalf of, |
| 922 | you may not add another; but you may replace the old one, on explicit |
| 923 | permission from the previous publisher that added the old one. |
| 924 | |
| 925 | The author(s) and publisher(s) of the Document do not by this License |
| 926 | give permission to use their names for publicity for or to assert or |
| 927 | imply endorsement of any Modified Version. |
| 928 | |
| 929 | |
| 930 | 5. COMBINING DOCUMENTS |
| 931 | |
| 932 | You may combine the Document with other documents released under this |
| 933 | License, under the terms defined in section 4 above for modified |
| 934 | versions, provided that you include in the combination all of the |
| 935 | Invariant Sections of all of the original documents, unmodified, and |
| 936 | list them all as Invariant Sections of your combined work in its |
| 937 | license notice. |
| 938 | |
| 939 | The combined work need only contain one copy of this License, and |
| 940 | multiple identical Invariant Sections may be replaced with a single |
| 941 | copy. If there are multiple Invariant Sections with the same name but |
| 942 | different contents, make the title of each such section unique by |
| 943 | adding at the end of it, in parentheses, the name of the original |
| 944 | author or publisher of that section if known, or else a unique number. |
| 945 | Make the same adjustment to the section titles in the list of |
| 946 | Invariant Sections in the license notice of the combined work. |
| 947 | |
| 948 | In the combination, you must combine any sections entitled "History" |
| 949 | in the various original documents, forming one section entitled |
| 950 | "History"; likewise combine any sections entitled "Acknowledgements", |
| 951 | and any sections entitled "Dedications". You must delete all sections |
| 952 | entitled "Endorsements." |
| 953 | |
| 954 | |
| 955 | 6. COLLECTIONS OF DOCUMENTS |
| 956 | |
| 957 | You may make a collection consisting of the Document and other documents |
| 958 | released under this License, and replace the individual copies of this |
| 959 | License in the various documents with a single copy that is included in |
| 960 | the collection, provided that you follow the rules of this License for |
| 961 | verbatim copying of each of the documents in all other respects. |
| 962 | |
| 963 | You may extract a single document from such a collection, and distribute |
| 964 | it individually under this License, provided you insert a copy of this |
| 965 | License into the extracted document, and follow this License in all |
| 966 | other respects regarding verbatim copying of that document. |
| 967 | |
| 968 | |
| 969 | 7. AGGREGATION WITH INDEPENDENT WORKS |
| 970 | |
| 971 | A compilation of the Document or its derivatives with other separate |
| 972 | and independent documents or works, in or on a volume of a storage or |
| 973 | distribution medium, does not as a whole count as a Modified Version |
| 974 | of the Document, provided no compilation copyright is claimed for the |
| 975 | compilation. Such a compilation is called an "aggregate", and this |
| 976 | License does not apply to the other self-contained works thus compiled |
| 977 | with the Document, on account of their being thus compiled, if they |
| 978 | are not themselves derivative works of the Document. |
| 979 | |
| 980 | If the Cover Text requirement of section 3 is applicable to these |
| 981 | copies of the Document, then if the Document is less than one quarter |
| 982 | of the entire aggregate, the Document's Cover Texts may be placed on |
| 983 | covers that surround only the Document within the aggregate. |
| 984 | Otherwise they must appear on covers around the whole aggregate. |
| 985 | |
| 986 | |
| 987 | 8. TRANSLATION |
| 988 | |
| 989 | Translation is considered a kind of modification, so you may |
| 990 | distribute translations of the Document under the terms of section 4. |
| 991 | Replacing Invariant Sections with translations requires special |
| 992 | permission from their copyright holders, but you may include |
| 993 | translations of some or all Invariant Sections in addition to the |
| 994 | original versions of these Invariant Sections. You may include a |
| 995 | translation of this License provided that you also include the |
| 996 | original English version of this License. In case of a disagreement |
| 997 | between the translation and the original English version of this |
| 998 | License, the original English version will prevail. |
| 999 | |
| 1000 | |
| 1001 | 9. TERMINATION |
| 1002 | |
| 1003 | You may not copy, modify, sublicense, or distribute the Document except |
| 1004 | as expressly provided for under this License. Any other attempt to |
| 1005 | copy, modify, sublicense or distribute the Document is void, and will |
| 1006 | automatically terminate your rights under this License. However, |
| 1007 | parties who have received copies, or rights, from you under this |
| 1008 | License will not have their licenses terminated so long as such |
| 1009 | parties remain in full compliance. |
| 1010 | |
| 1011 | |
| 1012 | 10. FUTURE REVISIONS OF THIS LICENSE |
| 1013 | |
| 1014 | The Free Software Foundation may publish new, revised versions |
| 1015 | of the GNU Free Documentation License from time to time. Such new |
| 1016 | versions will be similar in spirit to the present version, but may |
| 1017 | differ in detail to address new problems or concerns. See |
| 1018 | http://www.gnu.org/copyleft/. |
| 1019 | |
| 1020 | Each version of the License is given a distinguishing version number. |
| 1021 | If the Document specifies that a particular numbered version of this |
| 1022 | License "or any later version" applies to it, you have the option of |
| 1023 | following the terms and conditions either of that specified version or |
| 1024 | of any later version that has been published (not as a draft) by the |
| 1025 | Free Software Foundation. If the Document does not specify a version |
| 1026 | number of this License, you may choose any version ever published (not |
| 1027 | as a draft) by the Free Software Foundation. |
| 1028 | |
| 1029 | |
| 1030 | ADDENDUM: How to use this License for your documents |
| 1031 | |
| 1032 | To use this License in a document you have written, include a copy of |
| 1033 | the License in the document and put the following copyright and |
| 1034 | license notices just after the title page: |
| 1035 | |
| 1036 | @smallexample |
| 1037 | Copyright (c) YEAR YOUR NAME. |
| 1038 | Permission is granted to copy, distribute and/or modify this document |
| 1039 | under the terms of the GNU Free Documentation License, Version 1.1 |
| 1040 | or any later version published by the Free Software Foundation; |
| 1041 | with the Invariant Sections being LIST THEIR TITLES, with the |
| 1042 | Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. |
| 1043 | A copy of the license is included in the section entitled "GNU |
| 1044 | Free Documentation License". |
| 1045 | @end smallexample |
| 1046 | |
| 1047 | If you have no Invariant Sections, write "with no Invariant Sections" |
| 1048 | instead of saying which ones are invariant. If you have no |
| 1049 | Front-Cover Texts, write "no Front-Cover Texts" instead of |
| 1050 | "Front-Cover Texts being LIST"; likewise for Back-Cover Texts. |
| 1051 | |
| 1052 | If your document contains nontrivial examples of program code, we |
| 1053 | recommend releasing these examples in parallel under your choice of |
| 1054 | free software license, such as the GNU General Public License, |
| 1055 | to permit their use in free software. |
| 1056 | |
| 1057 | @contents |
| 1058 | @bye |