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