Commit | Line | Data |
---|---|---|
252b5132 RH |
1 | \input texinfo |
2 | @setfilename ldint.info | |
0e9517a9 | 3 | @c Copyright 1992, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, |
aa820537 | 4 | @c 2003, 2005, 2006, 2007 |
a2b64bed | 5 | @c Free Software Foundation, Inc. |
252b5132 RH |
6 | |
7 | @ifinfo | |
8 | @format | |
9 | START-INFO-DIR-ENTRY | |
10 | * Ld-Internals: (ldint). The GNU linker internals. | |
11 | END-INFO-DIR-ENTRY | |
12 | @end format | |
13 | @end ifinfo | |
14 | ||
0e9517a9 | 15 | @copying |
252b5132 RH |
16 | This file documents the internals of the GNU linker ld. |
17 | ||
0e9517a9 | 18 | Copyright @copyright{} 1992, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2007 |
a2b64bed | 19 | Free Software Foundation, Inc. |
252b5132 RH |
20 | Contributed by Cygnus Support. |
21 | ||
0e9517a9 | 22 | Permission is granted to copy, distribute and/or modify this document |
9fbcbd81 | 23 | under the terms of the GNU Free Documentation License, Version 1.3 or |
0e9517a9 NC |
24 | any later version published by the Free Software Foundation; with the |
25 | Invariant Sections being ``GNU General Public License'' and ``Funding | |
26 | Free Software'', the Front-Cover texts being (a) (see below), and with | |
27 | the Back-Cover Texts being (b) (see below). A copy of the license is | |
28 | included in the section entitled ``GNU Free Documentation License''. | |
252b5132 | 29 | |
0e9517a9 | 30 | (a) The FSF's Front-Cover Text is: |
252b5132 | 31 | |
0e9517a9 NC |
32 | A GNU Manual |
33 | ||
34 | (b) The FSF's Back-Cover Text is: | |
35 | ||
36 | You have freedom to copy and modify this GNU Manual, like GNU | |
37 | software. Copies published by the Free Software Foundation raise | |
38 | funds for GNU development. | |
39 | @end copying | |
252b5132 RH |
40 | |
41 | @iftex | |
42 | @finalout | |
43 | @setchapternewpage off | |
44 | @settitle GNU Linker Internals | |
45 | @titlepage | |
46 | @title{A guide to the internals of the GNU linker} | |
47 | @author Per Bothner, Steve Chamberlain, Ian Lance Taylor, DJ Delorie | |
48 | @author Cygnus Support | |
49 | @page | |
50 | ||
51 | @tex | |
52 | \def\$#1${{#1}} % Kluge: collect RCS revision info without $...$ | |
5b343f5a | 53 | \xdef\manvers{2.10.91} % For use in headers, footers too |
252b5132 RH |
54 | {\parskip=0pt |
55 | \hfill Cygnus Support\par | |
56 | \hfill \manvers\par | |
57 | \hfill \TeX{}info \texinfoversion\par | |
58 | } | |
59 | @end tex | |
60 | ||
61 | @vskip 0pt plus 1filll | |
9fbcbd81 | 62 | Copyright @copyright{} 1992, 1993, 1994, 1995, 1996, 1997, 1998, 2000 |
252b5132 RH |
63 | Free Software Foundation, Inc. |
64 | ||
704c465c | 65 | Permission is granted to copy, distribute and/or modify this document |
9fbcbd81 | 66 | under the terms of the GNU Free Documentation License, Version 1.3 |
704c465c NC |
67 | or any later version published by the Free Software Foundation; |
68 | with no Invariant Sections, with no Front-Cover Texts, and with no | |
69 | Back-Cover Texts. A copy of the license is included in the | |
70 | section entitled "GNU Free Documentation License". | |
252b5132 RH |
71 | |
72 | @end titlepage | |
73 | @end iftex | |
74 | ||
75 | @node Top | |
76 | @top | |
77 | ||
78 | This file documents the internals of the GNU linker @code{ld}. It is a | |
79 | collection of miscellaneous information with little form at this point. | |
80 | Mostly, it is a repository into which you can put information about | |
81 | GNU @code{ld} as you discover it (or as you design changes to @code{ld}). | |
82 | ||
cf055d54 NC |
83 | This document is distributed under the terms of the GNU Free |
84 | Documentation License. A copy of the license is included in the | |
85 | section entitled "GNU Free Documentation License". | |
86 | ||
252b5132 RH |
87 | @menu |
88 | * README:: The README File | |
89 | * Emulations:: How linker emulations are generated | |
90 | * Emulation Walkthrough:: A Walkthrough of a Typical Emulation | |
b044cda1 | 91 | * Architecture Specific:: Some Architecture Specific Notes |
704c465c | 92 | * GNU Free Documentation License:: GNU Free Documentation License |
252b5132 RH |
93 | @end menu |
94 | ||
95 | @node README | |
96 | @chapter The @file{README} File | |
97 | ||
98 | Check the @file{README} file; it often has useful information that does not | |
99 | appear anywhere else in the directory. | |
100 | ||
101 | @node Emulations | |
102 | @chapter How linker emulations are generated | |
103 | ||
104 | Each linker target has an @dfn{emulation}. The emulation includes the | |
105 | default linker script, and certain emulations also modify certain types | |
106 | of linker behaviour. | |
107 | ||
108 | Emulations are created during the build process by the shell script | |
109 | @file{genscripts.sh}. | |
110 | ||
111 | The @file{genscripts.sh} script starts by reading a file in the | |
112 | @file{emulparams} directory. This is a shell script which sets various | |
113 | shell variables used by @file{genscripts.sh} and the other shell scripts | |
114 | it invokes. | |
115 | ||
116 | The @file{genscripts.sh} script will invoke a shell script in the | |
117 | @file{scripttempl} directory in order to create default linker scripts | |
118 | written in the linker command language. The @file{scripttempl} script | |
119 | will be invoked 5 (or, in some cases, 6) times, with different | |
120 | assignments to shell variables, to create different default scripts. | |
121 | The choice of script is made based on the command line options. | |
122 | ||
123 | After creating the scripts, @file{genscripts.sh} will invoke yet another | |
124 | shell script, this time in the @file{emultempl} directory. That shell | |
125 | script will create the emulation source file, which contains C code. | |
126 | This C code permits the linker emulation to override various linker | |
127 | behaviours. Most targets use the generic emulation code, which is in | |
128 | @file{emultempl/generic.em}. | |
129 | ||
130 | To summarize, @file{genscripts.sh} reads three shell scripts: an | |
131 | emulation parameters script in the @file{emulparams} directory, a linker | |
132 | script generation script in the @file{scripttempl} directory, and an | |
133 | emulation source file generation script in the @file{emultempl} | |
134 | directory. | |
135 | ||
136 | For example, the Sun 4 linker sets up variables in | |
137 | @file{emulparams/sun4.sh}, creates linker scripts using | |
138 | @file{scripttempl/aout.sc}, and creates the emulation code using | |
139 | @file{emultempl/sunos.em}. | |
140 | ||
141 | Note that the linker can support several emulations simultaneously, | |
142 | depending upon how it is configured. An emulation can be selected with | |
143 | the @code{-m} option. The @code{-V} option will list all supported | |
144 | emulations. | |
145 | ||
146 | @menu | |
147 | * emulation parameters:: @file{emulparams} scripts | |
148 | * linker scripts:: @file{scripttempl} scripts | |
149 | * linker emulations:: @file{emultempl} scripts | |
150 | @end menu | |
151 | ||
152 | @node emulation parameters | |
153 | @section @file{emulparams} scripts | |
154 | ||
155 | Each target selects a particular file in the @file{emulparams} directory | |
156 | by setting the shell variable @code{targ_emul} in @file{configure.tgt}. | |
157 | This shell variable is used by the @file{configure} script to control | |
158 | building an emulation source file. | |
159 | ||
160 | Certain conventions are enforced. Suppose the @code{targ_emul} variable | |
161 | is set to @var{emul} in @file{configure.tgt}. The name of the emulation | |
162 | shell script will be @file{emulparams/@var{emul}.sh}. The | |
163 | @file{Makefile} must have a target named @file{e@var{emul}.c}; this | |
164 | target must depend upon @file{emulparams/@var{emul}.sh}, as well as the | |
165 | appropriate scripts in the @file{scripttempl} and @file{emultempl} | |
166 | directories. The @file{Makefile} target must invoke @code{GENSCRIPTS} | |
167 | with two arguments: @var{emul}, and the value of the make variable | |
168 | @code{tdir_@var{emul}}. The value of the latter variable will be set by | |
169 | the @file{configure} script, and is used to set the default target | |
170 | directory to search. | |
171 | ||
172 | By convention, the @file{emulparams/@var{emul}.sh} shell script should | |
173 | only set shell variables. It may set shell variables which are to be | |
174 | interpreted by the @file{scripttempl} and the @file{emultempl} scripts. | |
175 | Certain shell variables are interpreted directly by the | |
176 | @file{genscripts.sh} script. | |
177 | ||
178 | Here is a list of shell variables interpreted by @file{genscripts.sh}, | |
179 | as well as some conventional shell variables interpreted by the | |
180 | @file{scripttempl} and @file{emultempl} scripts. | |
181 | ||
182 | @table @code | |
183 | @item SCRIPT_NAME | |
184 | This is the name of the @file{scripttempl} script to use. If | |
185 | @code{SCRIPT_NAME} is set to @var{script}, @file{genscripts.sh} will use | |
b45619c0 | 186 | the script @file{scripttempl/@var{script}.sc}. |
252b5132 RH |
187 | |
188 | @item TEMPLATE_NAME | |
b45619c0 | 189 | This is the name of the @file{emultempl} script to use. If |
252b5132 RH |
190 | @code{TEMPLATE_NAME} is set to @var{template}, @file{genscripts.sh} will |
191 | use the script @file{emultempl/@var{template}.em}. If this variable is | |
192 | not set, the default value is @samp{generic}. | |
193 | ||
194 | @item GENERATE_SHLIB_SCRIPT | |
195 | If this is set to a nonempty string, @file{genscripts.sh} will invoke | |
196 | the @file{scripttempl} script an extra time to create a shared library | |
197 | script. @ref{linker scripts}. | |
198 | ||
199 | @item OUTPUT_FORMAT | |
200 | This is normally set to indicate the BFD output format use (e.g., | |
201 | @samp{"a.out-sunos-big"}. The @file{scripttempl} script will normally | |
202 | use it in an @code{OUTPUT_FORMAT} expression in the linker script. | |
203 | ||
204 | @item ARCH | |
205 | This is normally set to indicate the architecture to use (e.g., | |
206 | @samp{sparc}). The @file{scripttempl} script will normally use it in an | |
207 | @code{OUTPUT_ARCH} expression in the linker script. | |
208 | ||
209 | @item ENTRY | |
210 | Some @file{scripttempl} scripts use this to set the entry address, in an | |
211 | @code{ENTRY} expression in the linker script. | |
212 | ||
213 | @item TEXT_START_ADDR | |
214 | Some @file{scripttempl} scripts use this to set the start address of the | |
215 | @samp{.text} section. | |
216 | ||
252b5132 RH |
217 | @item SEGMENT_SIZE |
218 | The @file{genscripts.sh} script uses this to set the default value of | |
219 | @code{DATA_ALIGNMENT} when running the @file{scripttempl} script. | |
220 | ||
221 | @item TARGET_PAGE_SIZE | |
222 | If @code{SEGMENT_SIZE} is not defined, the @file{genscripts.sh} script | |
223 | uses this to define it. | |
224 | ||
225 | @item ALIGNMENT | |
226 | Some @file{scripttempl} scripts set this to a number to pass to | |
227 | @code{ALIGN} to set the required alignment for the @code{end} symbol. | |
228 | @end table | |
229 | ||
230 | @node linker scripts | |
231 | @section @file{scripttempl} scripts | |
232 | ||
233 | Each linker target uses a @file{scripttempl} script to generate the | |
234 | default linker scripts. The name of the @file{scripttempl} script is | |
235 | set by the @code{SCRIPT_NAME} variable in the @file{emulparams} script. | |
236 | If @code{SCRIPT_NAME} is set to @var{script}, @code{genscripts.sh} will | |
237 | invoke @file{scripttempl/@var{script}.sc}. | |
238 | ||
239 | The @file{genscripts.sh} script will invoke the @file{scripttempl} | |
e2a83dd0 | 240 | script 5 to 9 times. Each time it will set the shell variable |
252b5132 RH |
241 | @code{LD_FLAG} to a different value. When the linker is run, the |
242 | options used will direct it to select a particular script. (Script | |
243 | selection is controlled by the @code{get_script} emulation entry point; | |
244 | this describes the conventional behaviour). | |
245 | ||
246 | The @file{scripttempl} script should just write a linker script, written | |
247 | in the linker command language, to standard output. If the emulation | |
248 | name--the name of the @file{emulparams} file without the @file{.sc} | |
249 | extension--is @var{emul}, then the output will be directed to | |
250 | @file{ldscripts/@var{emul}.@var{extension}} in the build directory, | |
251 | where @var{extension} changes each time the @file{scripttempl} script is | |
252 | invoked. | |
253 | ||
254 | Here is the list of values assigned to @code{LD_FLAG}. | |
255 | ||
256 | @table @code | |
257 | @item (empty) | |
258 | The script generated is used by default (when none of the following | |
259 | cases apply). The output has an extension of @file{.x}. | |
260 | @item n | |
261 | The script generated is used when the linker is invoked with the | |
262 | @code{-n} option. The output has an extension of @file{.xn}. | |
263 | @item N | |
264 | The script generated is used when the linker is invoked with the | |
265 | @code{-N} option. The output has an extension of @file{.xbn}. | |
266 | @item r | |
267 | The script generated is used when the linker is invoked with the | |
268 | @code{-r} option. The output has an extension of @file{.xr}. | |
269 | @item u | |
270 | The script generated is used when the linker is invoked with the | |
271 | @code{-Ur} option. The output has an extension of @file{.xu}. | |
272 | @item shared | |
273 | The @file{scripttempl} script is only invoked with @code{LD_FLAG} set to | |
274 | this value if @code{GENERATE_SHLIB_SCRIPT} is defined in the | |
275 | @file{emulparams} file. The @file{emultempl} script must arrange to use | |
276 | this script at the appropriate time, normally when the linker is invoked | |
277 | with the @code{-shared} option. The output has an extension of | |
278 | @file{.xs}. | |
db6751f2 JJ |
279 | @item c |
280 | The @file{scripttempl} script is only invoked with @code{LD_FLAG} set to | |
281 | this value if @code{GENERATE_COMBRELOC_SCRIPT} is defined in the | |
282 | @file{emulparams} file or if @code{SCRIPT_NAME} is @code{elf}. The | |
283 | @file{emultempl} script must arrange to use this script at the appropriate | |
284 | time, normally when the linker is invoked with the @code{-z combreloc} | |
285 | option. The output has an extension of | |
286 | @file{.xc}. | |
287 | @item cshared | |
288 | The @file{scripttempl} script is only invoked with @code{LD_FLAG} set to | |
289 | this value if @code{GENERATE_COMBRELOC_SCRIPT} is defined in the | |
290 | @file{emulparams} file or if @code{SCRIPT_NAME} is @code{elf} and | |
b45619c0 | 291 | @code{GENERATE_SHLIB_SCRIPT} is defined in the @file{emulparams} file. |
db6751f2 JJ |
292 | The @file{emultempl} script must arrange to use this script at the |
293 | appropriate time, normally when the linker is invoked with the @code{-shared | |
294 | -z combreloc} option. The output has an extension of @file{.xsc}. | |
e2a83dd0 NC |
295 | @item auto_import |
296 | The @file{scripttempl} script is only invoked with @code{LD_FLAG} set to | |
297 | this value if @code{GENERATE_AUTO_IMPORT_SCRIPT} is defined in the | |
298 | @file{emulparams} file. The @file{emultempl} script must arrange to | |
299 | use this script at the appropriate time, normally when the linker is | |
300 | invoked with the @code{--enable-auto-import} option. The output has | |
301 | an extension of @file{.xa}. | |
252b5132 RH |
302 | @end table |
303 | ||
304 | Besides the shell variables set by the @file{emulparams} script, and the | |
305 | @code{LD_FLAG} variable, the @file{genscripts.sh} script will set | |
306 | certain variables for each run of the @file{scripttempl} script. | |
307 | ||
308 | @table @code | |
309 | @item RELOCATING | |
310 | This will be set to a non-empty string when the linker is doing a final | |
311 | relocation (e.g., all scripts other than @code{-r} and @code{-Ur}). | |
312 | ||
313 | @item CONSTRUCTING | |
314 | This will be set to a non-empty string when the linker is building | |
315 | global constructor and destructor tables (e.g., all scripts other than | |
316 | @code{-r}). | |
317 | ||
318 | @item DATA_ALIGNMENT | |
319 | This will be set to an @code{ALIGN} expression when the output should be | |
320 | page aligned, or to @samp{.} when generating the @code{-N} script. | |
321 | ||
322 | @item CREATE_SHLIB | |
323 | This will be set to a non-empty string when generating a @code{-shared} | |
324 | script. | |
db6751f2 JJ |
325 | |
326 | @item COMBRELOC | |
327 | This will be set to a non-empty string when generating @code{-z combreloc} | |
328 | scripts to a temporary file name which can be used during script generation. | |
252b5132 RH |
329 | @end table |
330 | ||
331 | The conventional way to write a @file{scripttempl} script is to first | |
332 | set a few shell variables, and then write out a linker script using | |
333 | @code{cat} with a here document. The linker script will use variable | |
334 | substitutions, based on the above variables and those set in the | |
335 | @file{emulparams} script, to control its behaviour. | |
336 | ||
337 | When there are parts of the @file{scripttempl} script which should only | |
338 | be run when doing a final relocation, they should be enclosed within a | |
339 | variable substitution based on @code{RELOCATING}. For example, on many | |
340 | targets special symbols such as @code{_end} should be defined when doing | |
341 | a final link. Naturally, those symbols should not be defined when doing | |
1049f94e | 342 | a relocatable link using @code{-r}. The @file{scripttempl} script |
252b5132 RH |
343 | could use a construct like this to define those symbols: |
344 | @smallexample | |
345 | $@{RELOCATING+ _end = .;@} | |
346 | @end smallexample | |
347 | This will do the symbol assignment only if the @code{RELOCATING} | |
348 | variable is defined. | |
349 | ||
350 | The basic job of the linker script is to put the sections in the correct | |
351 | order, and at the correct memory addresses. For some targets, the | |
352 | linker script may have to do some other operations. | |
353 | ||
354 | For example, on most MIPS platforms, the linker is responsible for | |
355 | defining the special symbol @code{_gp}, used to initialize the | |
356 | @code{$gp} register. It must be set to the start of the small data | |
357 | section plus @code{0x8000}. Naturally, it should only be defined when | |
358 | doing a final relocation. This will typically be done like this: | |
359 | @smallexample | |
360 | $@{RELOCATING+ _gp = ALIGN(16) + 0x8000;@} | |
361 | @end smallexample | |
362 | This line would appear just before the sections which compose the small | |
363 | data section (@samp{.sdata}, @samp{.sbss}). All those sections would be | |
364 | contiguous in memory. | |
365 | ||
366 | Many COFF systems build constructor tables in the linker script. The | |
367 | compiler will arrange to output the address of each global constructor | |
368 | in a @samp{.ctor} section, and the address of each global destructor in | |
369 | a @samp{.dtor} section (this is done by defining | |
370 | @code{ASM_OUTPUT_CONSTRUCTOR} and @code{ASM_OUTPUT_DESTRUCTOR} in the | |
371 | @code{gcc} configuration files). The @code{gcc} runtime support | |
372 | routines expect the constructor table to be named @code{__CTOR_LIST__}. | |
373 | They expect it to be a list of words, with the first word being the | |
374 | count of the number of entries. There should be a trailing zero word. | |
375 | (Actually, the count may be -1 if the trailing word is present, and the | |
376 | trailing word may be omitted if the count is correct, but, as the | |
377 | @code{gcc} behaviour has changed slightly over the years, it is safest | |
378 | to provide both). Here is a typical way that might be handled in a | |
379 | @file{scripttempl} file. | |
380 | @smallexample | |
381 | $@{CONSTRUCTING+ __CTOR_LIST__ = .;@} | |
382 | $@{CONSTRUCTING+ LONG((__CTOR_END__ - __CTOR_LIST__) / 4 - 2)@} | |
383 | $@{CONSTRUCTING+ *(.ctors)@} | |
384 | $@{CONSTRUCTING+ LONG(0)@} | |
385 | $@{CONSTRUCTING+ __CTOR_END__ = .;@} | |
386 | $@{CONSTRUCTING+ __DTOR_LIST__ = .;@} | |
387 | $@{CONSTRUCTING+ LONG((__DTOR_END__ - __DTOR_LIST__) / 4 - 2)@} | |
388 | $@{CONSTRUCTING+ *(.dtors)@} | |
389 | $@{CONSTRUCTING+ LONG(0)@} | |
390 | $@{CONSTRUCTING+ __DTOR_END__ = .;@} | |
391 | @end smallexample | |
392 | The use of @code{CONSTRUCTING} ensures that these linker script commands | |
393 | will only appear when the linker is supposed to be building the | |
394 | constructor and destructor tables. This example is written for a target | |
395 | which uses 4 byte pointers. | |
396 | ||
397 | Embedded systems often need to set a stack address. This is normally | |
398 | best done by using the @code{PROVIDE} construct with a default stack | |
399 | address. This permits the user to easily override the stack address | |
400 | using the @code{--defsym} option. Here is an example: | |
401 | @smallexample | |
402 | $@{RELOCATING+ PROVIDE (__stack = 0x80000000);@} | |
403 | @end smallexample | |
404 | The value of the symbol @code{__stack} would then be used in the startup | |
405 | code to initialize the stack pointer. | |
406 | ||
407 | @node linker emulations | |
408 | @section @file{emultempl} scripts | |
409 | ||
410 | Each linker target uses an @file{emultempl} script to generate the | |
411 | emulation code. The name of the @file{emultempl} script is set by the | |
412 | @code{TEMPLATE_NAME} variable in the @file{emulparams} script. If the | |
413 | @code{TEMPLATE_NAME} variable is not set, the default is | |
414 | @samp{generic}. If the value of @code{TEMPLATE_NAME} is @var{template}, | |
415 | @file{genscripts.sh} will use @file{emultempl/@var{template}.em}. | |
416 | ||
417 | Most targets use the generic @file{emultempl} script, | |
418 | @file{emultempl/generic.em}. A different @file{emultempl} script is | |
419 | only needed if the linker must support unusual actions, such as linking | |
420 | against shared libraries. | |
421 | ||
422 | The @file{emultempl} script is normally written as a simple invocation | |
423 | of @code{cat} with a here document. The document will use a few | |
424 | variable substitutions. Typically each function names uses a | |
425 | substitution involving @code{EMULATION_NAME}, for ease of debugging when | |
426 | the linker supports multiple emulations. | |
427 | ||
428 | Every function and variable in the emitted file should be static. The | |
429 | only globally visible object must be named | |
430 | @code{ld_@var{EMULATION_NAME}_emulation}, where @var{EMULATION_NAME} is | |
431 | the name of the emulation set in @file{configure.tgt} (this is also the | |
432 | name of the @file{emulparams} file without the @file{.sh} extension). | |
433 | The @file{genscripts.sh} script will set the shell variable | |
434 | @code{EMULATION_NAME} before invoking the @file{emultempl} script. | |
435 | ||
436 | The @code{ld_@var{EMULATION_NAME}_emulation} variable must be a | |
437 | @code{struct ld_emulation_xfer_struct}, as defined in @file{ldemul.h}. | |
438 | It defines a set of function pointers which are invoked by the linker, | |
439 | as well as strings for the emulation name (normally set from the shell | |
440 | variable @code{EMULATION_NAME} and the default BFD target name (normally | |
441 | set from the shell variable @code{OUTPUT_FORMAT} which is normally set | |
442 | by the @file{emulparams} file). | |
443 | ||
444 | The @file{genscripts.sh} script will set the shell variable | |
445 | @code{COMPILE_IN} when it invokes the @file{emultempl} script for the | |
446 | default emulation. In this case, the @file{emultempl} script should | |
447 | include the linker scripts directly, and return them from the | |
448 | @code{get_scripts} entry point. When the emulation is not the default, | |
449 | the @code{get_scripts} entry point should just return a file name. See | |
450 | @file{emultempl/generic.em} for an example of how this is done. | |
451 | ||
452 | At some point, the linker emulation entry points should be documented. | |
453 | ||
454 | @node Emulation Walkthrough | |
455 | @chapter A Walkthrough of a Typical Emulation | |
456 | ||
457 | This chapter is to help people who are new to the way emulations | |
458 | interact with the linker, or who are suddenly thrust into the position | |
459 | of having to work with existing emulations. It will discuss the files | |
460 | you need to be aware of. It will tell you when the given "hooks" in | |
461 | the emulation will be called. It will, hopefully, give you enough | |
462 | information about when and how things happen that you'll be able to | |
463 | get by. As always, the source is the definitive reference to this. | |
464 | ||
465 | The starting point for the linker is in @file{ldmain.c} where | |
466 | @code{main} is defined. The bulk of the code that's emulation | |
467 | specific will initially be in @code{emultempl/@var{emulation}.em} but | |
468 | will end up in @code{e@var{emulation}.c} when the build is done. | |
469 | Most of the work to select and interface with emulations is in | |
470 | @code{ldemul.h} and @code{ldemul.c}. Specifically, @code{ldemul.h} | |
471 | defines the @code{ld_emulation_xfer_struct} structure your emulation | |
472 | exports. | |
473 | ||
474 | Your emulation file exports a symbol | |
475 | @code{ld_@var{EMULATION_NAME}_emulation}. If your emulation is | |
476 | selected (it usually is, since usually there's only one), | |
477 | @code{ldemul.c} sets the variable @var{ld_emulation} to point to it. | |
478 | @code{ldemul.c} also defines a number of API functions that interface | |
479 | to your emulation, like @code{ldemul_after_parse} which simply calls | |
480 | your @code{ld_@var{EMULATION}_emulation.after_parse} function. For | |
481 | the rest of this section, the functions will be mentioned, but you | |
482 | should assume the indirect reference to your emulation also. | |
483 | ||
484 | We will also skip or gloss over parts of the link process that don't | |
485 | relate to emulations, like setting up internationalization. | |
486 | ||
487 | After initialization, @code{main} selects an emulation by pre-scanning | |
488 | the command line arguments. It calls @code{ldemul_choose_target} to | |
489 | choose a target. If you set @code{choose_target} to | |
490 | @code{ldemul_default_target}, it picks your @code{target_name} by | |
491 | default. | |
492 | ||
493 | @code{main} calls @code{ldemul_before_parse}, then @code{parse_args}. | |
494 | @code{parse_args} calls @code{ldemul_parse_args} for each arg, which | |
495 | must update the @code{getopt} globals if it recognizes the argument. | |
496 | If the emulation doesn't recognize it, then parse_args checks to see | |
497 | if it recognizes it. | |
498 | ||
499 | Now that the emulation has had access to all its command-line options, | |
500 | @code{main} calls @code{ldemul_set_symbols}. This can be used for any | |
501 | initialization that may be affected by options. It is also supposed | |
502 | to set up any variables needed by the emulation script. | |
503 | ||
504 | @code{main} now calls @code{ldemul_get_script} to get the emulation | |
505 | script to use (based on arguments, no doubt, @pxref{Emulations}) and | |
506 | runs it. While parsing, @code{ldgram.y} may call @code{ldemul_hll} or | |
507 | @code{ldemul_syslib} to handle the @code{HLL} or @code{SYSLIB} | |
508 | commands. It may call @code{ldemul_unrecognized_file} if you asked | |
509 | the linker to link a file it doesn't recognize. It will call | |
510 | @code{ldemul_recognized_file} for each file it does recognize, in case | |
511 | the emulation wants to handle some files specially. All the while, | |
512 | it's loading the files (possibly calling | |
513 | @code{ldemul_open_dynamic_archive}) and symbols and stuff. After it's | |
514 | done reading the script, @code{main} calls @code{ldemul_after_parse}. | |
515 | Use the after-parse hook to set up anything that depends on stuff the | |
516 | script might have set up, like the entry point. | |
517 | ||
518 | @code{main} next calls @code{lang_process} in @code{ldlang.c}. This | |
519 | appears to be the main core of the linking itself, as far as emulation | |
520 | hooks are concerned(*). It first opens the output file's BFD, calling | |
521 | @code{ldemul_set_output_arch}, and calls | |
522 | @code{ldemul_create_output_section_statements} in case you need to use | |
523 | other means to find or create object files (i.e. shared libraries | |
524 | found on a path, or fake stub objects). Despite the name, nobody | |
525 | creates output sections here. | |
526 | ||
527 | (*) In most cases, the BFD library does the bulk of the actual | |
528 | linking, handling symbol tables, symbol resolution, relocations, and | |
529 | building the final output file. See the BFD reference for all the | |
530 | details. Your emulation is usually concerned more with managing | |
531 | things at the file and section level, like "put this here, add this | |
532 | section", etc. | |
533 | ||
534 | Next, the objects to be linked are opened and BFDs created for them, | |
535 | and @code{ldemul_after_open} is called. At this point, you have all | |
536 | the objects and symbols loaded, but none of the data has been placed | |
537 | yet. | |
538 | ||
539 | Next comes the Big Linking Thingy (except for the parts BFD does). | |
540 | All input sections are mapped to output sections according to the | |
541 | script. If a section doesn't get mapped by default, | |
542 | @code{ldemul_place_orphan} will get called to figure out where it goes. | |
543 | Next it figures out the offsets for each section, calling | |
544 | @code{ldemul_before_allocation} before and | |
545 | @code{ldemul_after_allocation} after deciding where each input section | |
546 | ends up in the output sections. | |
547 | ||
548 | The last part of @code{lang_process} is to figure out all the symbols' | |
549 | values. After assigning final values to the symbols, | |
550 | @code{ldemul_finish} is called, and after that, any undefined symbols | |
551 | are turned into fatal errors. | |
552 | ||
553 | OK, back to @code{main}, which calls @code{ldwrite} in | |
554 | @file{ldwrite.c}. @code{ldwrite} calls BFD's final_link, which does | |
555 | all the relocation fixups and writes the output bfd to disk, and we're | |
556 | done. | |
557 | ||
558 | In summary, | |
559 | ||
560 | @itemize @bullet | |
561 | ||
562 | @item @code{main()} in @file{ldmain.c} | |
563 | @item @file{emultempl/@var{EMULATION}.em} has your code | |
564 | @item @code{ldemul_choose_target} (defaults to your @code{target_name}) | |
565 | @item @code{ldemul_before_parse} | |
566 | @item Parse argv, calls @code{ldemul_parse_args} for each | |
567 | @item @code{ldemul_set_symbols} | |
568 | @item @code{ldemul_get_script} | |
569 | @item parse script | |
570 | ||
571 | @itemize @bullet | |
572 | @item may call @code{ldemul_hll} or @code{ldemul_syslib} | |
573 | @item may call @code{ldemul_open_dynamic_archive} | |
574 | @end itemize | |
575 | ||
576 | @item @code{ldemul_after_parse} | |
577 | @item @code{lang_process()} in @file{ldlang.c} | |
578 | ||
579 | @itemize @bullet | |
580 | @item create @code{output_bfd} | |
581 | @item @code{ldemul_set_output_arch} | |
582 | @item @code{ldemul_create_output_section_statements} | |
583 | @item read objects, create input bfds - all symbols exist, but have no values | |
584 | @item may call @code{ldemul_unrecognized_file} | |
585 | @item will call @code{ldemul_recognized_file} | |
586 | @item @code{ldemul_after_open} | |
587 | @item map input sections to output sections | |
588 | @item may call @code{ldemul_place_orphan} for remaining sections | |
589 | @item @code{ldemul_before_allocation} | |
590 | @item gives input sections offsets into output sections, places output sections | |
591 | @item @code{ldemul_after_allocation} - section addresses valid | |
592 | @item assigns values to symbols | |
593 | @item @code{ldemul_finish} - symbol values valid | |
594 | @end itemize | |
595 | ||
596 | @item output bfd is written to disk | |
597 | ||
598 | @end itemize | |
599 | ||
b044cda1 CW |
600 | @node Architecture Specific |
601 | @chapter Some Architecture Specific Notes | |
602 | ||
603 | This is the place for notes on the behavior of @code{ld} on | |
604 | specific platforms. Currently, only Intel x86 is documented (and | |
605 | of that, only the auto-import behavior for DLLs). | |
606 | ||
607 | @menu | |
608 | * ix86:: Intel x86 | |
609 | @end menu | |
610 | ||
611 | @node ix86 | |
612 | @section Intel x86 | |
613 | ||
614 | @table @emph | |
615 | @code{ld} can create DLLs that operate with various runtimes available | |
616 | on a common x86 operating system. These runtimes include native (using | |
617 | the mingw "platform"), cygwin, and pw. | |
618 | ||
619 | @item auto-import from DLLs | |
620 | @enumerate | |
621 | @item | |
622 | With this feature on, DLL clients can import variables from DLL | |
623 | without any concern from their side (for example, without any source | |
624 | code modifications). Auto-import can be enabled using the | |
625 | @code{--enable-auto-import} flag, or disabled via the | |
626 | @code{--disable-auto-import} flag. Auto-import is disabled by default. | |
627 | ||
628 | @item | |
629 | This is done completely in bounds of the PE specification (to be fair, | |
630 | there's a minor violation of the spec at one point, but in practice | |
631 | auto-import works on all known variants of that common x86 operating | |
632 | system) So, the resulting DLL can be used with any other PE | |
633 | compiler/linker. | |
634 | ||
635 | @item | |
636 | Auto-import is fully compatible with standard import method, in which | |
637 | variables are decorated using attribute modifiers. Libraries of either | |
638 | type may be mixed together. | |
639 | ||
640 | @item | |
641 | Overhead (space): 8 bytes per imported symbol, plus 20 for each | |
642 | reference to it; Overhead (load time): negligible; Overhead | |
643 | (virtual/physical memory): should be less than effect of DLL | |
644 | relocation. | |
645 | @end enumerate | |
646 | ||
647 | Motivation | |
648 | ||
649 | The obvious and only way to get rid of dllimport insanity is | |
650 | to make client access variable directly in the DLL, bypassing | |
651 | the extra dereference imposed by ordinary DLL runtime linking. | |
b45619c0 | 652 | I.e., whenever client contains something like |
b044cda1 CW |
653 | |
654 | @code{mov dll_var,%eax,} | |
655 | ||
656 | address of dll_var in the command should be relocated to point | |
657 | into loaded DLL. The aim is to make OS loader do so, and than | |
658 | make ld help with that. Import section of PE made following | |
659 | way: there's a vector of structures each describing imports | |
660 | from particular DLL. Each such structure points to two other | |
b45619c0 | 661 | parallel vectors: one holding imported names, and one which |
b044cda1 CW |
662 | will hold address of corresponding imported name. So, the |
663 | solution is de-vectorize these structures, making import | |
664 | locations be sparse and pointing directly into code. | |
665 | ||
666 | Implementation | |
667 | ||
668 | For each reference of data symbol to be imported from DLL (to | |
669 | set of which belong symbols with name <sym>, if __imp_<sym> is | |
670 | found in implib), the import fixup entry is generated. That | |
671 | entry is of type IMAGE_IMPORT_DESCRIPTOR and stored in .idata$3 | |
672 | subsection. Each fixup entry contains pointer to symbol's address | |
673 | within .text section (marked with __fuN_<sym> symbol, where N is | |
674 | integer), pointer to DLL name (so, DLL name is referenced by | |
675 | multiple entries), and pointer to symbol name thunk. Symbol name | |
676 | thunk is singleton vector (__nm_th_<symbol>) pointing to | |
677 | IMAGE_IMPORT_BY_NAME structure (__nm_<symbol>) directly containing | |
678 | imported name. Here comes that "om the edge" problem mentioned above: | |
679 | PE specification rambles that name vector (OriginalFirstThunk) should | |
680 | run in parallel with addresses vector (FirstThunk), i.e. that they | |
681 | should have same number of elements and terminated with zero. We violate | |
682 | this, since FirstThunk points directly into machine code. But in | |
683 | practice, OS loader implemented the sane way: it goes thru | |
684 | OriginalFirstThunk and puts addresses to FirstThunk, not something | |
685 | else. It once again should be noted that dll and symbol name | |
686 | structures are reused across fixup entries and should be there | |
687 | anyway to support standard import stuff, so sustained overhead is | |
688 | 20 bytes per reference. Other question is whether having several | |
689 | IMAGE_IMPORT_DESCRIPTORS for the same DLL is possible. Answer is yes, | |
690 | it is done even by native compiler/linker (libth32's functions are in | |
691 | fact resident in windows9x kernel32.dll, so if you use it, you have | |
692 | two IMAGE_IMPORT_DESCRIPTORS for kernel32.dll). Yet other question is | |
693 | whether referencing the same PE structures several times is valid. | |
694 | The answer is why not, prohibiting that (detecting violation) would | |
695 | require more work on behalf of loader than not doing it. | |
696 | ||
697 | @end table | |
698 | ||
704c465c NC |
699 | @node GNU Free Documentation License |
700 | @chapter GNU Free Documentation License | |
701 | ||
9fbcbd81 | 702 | @include fdl.texi |
704c465c | 703 | |
252b5132 RH |
704 | @contents |
705 | @bye |