daily update
[binutils.git] / ld / ldint.texinfo
blob54867648a52dccbc83b460ef104f59a7eb7ccdb1
1 \input texinfo
2 @setfilename ldint.info
3 @c Copyright 1992, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2003
4 @c Free Software Foundation, Inc.
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
14 @ifinfo
15 This file documents the internals of the GNU linker ld.
17 Copyright 1992, 1994, 1995, 1996, 1997, 1998, 1999, 2000
18 Free Software Foundation, Inc.
19 Contributed by Cygnus Support.
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".
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).
34 @end ignore
35 @end ifinfo
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
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
55 @end tex
57 @vskip 0pt plus 1filll
58 Copyright @copyright{} 1992, 93, 94, 95, 96, 97, 1998, 2000
59 Free Software Foundation, Inc.
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".
68 @end titlepage
69 @end iftex
71 @node Top
72 @top
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}).
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".
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
91 @node README
92 @chapter The @file{README} File
94 Check the @file{README} file; it often has useful information that does not
95 appear anywhere else in the directory.
97 @node Emulations
98 @chapter How linker emulations are generated
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.
104 Emulations are created during the build process by the shell script
105 @file{genscripts.sh}.
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.
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.
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}.
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.
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}.
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.
142 @menu
143 * emulation parameters::        @file{emulparams} scripts
144 * linker scripts::              @file{scripttempl} scripts
145 * linker emulations::           @file{emultempl} scripts
146 @end menu
148 @node emulation parameters
149 @section @file{emulparams} scripts
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.
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.
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.
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.
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}.
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}.
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}.
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.
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.
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.
209 @item TEXT_START_ADDR
210 Some @file{scripttempl} scripts use this to set the start address of the
211 @samp{.text} section.
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}).
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.
223 @item TARGET_PAGE_SIZE
224 If @code{SEGMENT_SIZE} is not defined, the @file{genscripts.sh} script
225 uses this to define it.
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
232 @node linker scripts
233 @section @file{scripttempl} scripts
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}.
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).
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.
256 Here is the list of values assigned to @code{LD_FLAG}.
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
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.
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}).
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}).
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.
317 @item CREATE_SHLIB
318 This will be set to a non-empty string when generating a @code{-shared}
319 script.
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
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.
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 relocatable 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.
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.
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.
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.
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.
402 @node linker emulations
403 @section @file{emultempl} scripts
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}.
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.
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.
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.
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).
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.
447 At some point, the linker emulation entry points should be documented.
449 @node Emulation Walkthrough
450 @chapter A Walkthrough of a Typical Emulation
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.
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.
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.
479 We will also skip or gloss over parts of the link process that don't
480 relate to emulations, like setting up internationalization.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
553 In summary,
555 @itemize @bullet
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
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
571 @item @code{ldemul_after_parse}
572 @item @code{lang_process()} in @file{ldlang.c}
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
591 @item output bfd is written to disk
593 @end itemize
595 @node Architecture Specific
596 @chapter Some Architecture Specific Notes
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).
602 @menu
603 * ix86::                        Intel x86
604 @end menu
606 @node ix86
607 @section Intel x86
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.
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.
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.
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.
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
642 Motivation
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
649 @code{mov dll_var,%eax,}
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.
661 Implementation
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.
692 @end table
694 @node GNU Free Documentation License
695 @chapter GNU Free Documentation License
697                 GNU Free Documentation License
698                 
699                    Version 1.1, March 2000
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.
708 0. PREAMBLE
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.
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.
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.
732 1. APPLICABILITY AND DEFINITIONS
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".
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.
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.
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.
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.
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".
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.
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.
793 2. VERBATIM COPYING
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.
805 You may also lend copies, under the same conditions stated above, and
806 you may publicly display copies.
809 3. COPYING IN QUANTITY
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.
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.
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.
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.
847 4. MODIFICATIONS
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:
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.
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.
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.
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.
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.
930 5. COMBINING DOCUMENTS
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.
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.
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."
955 6. COLLECTIONS OF DOCUMENTS
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.
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.
969 7. AGGREGATION WITH INDEPENDENT WORKS
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.
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.
987 8. TRANSLATION
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.
1001 9. TERMINATION
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.
1012 10. FUTURE REVISIONS OF THIS LICENSE
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/.
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.
1030 ADDENDUM: How to use this License for your documents
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:
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
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.
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.
1057 @contents
1058 @bye