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