1 |
1181 |
sfurman |
This is bfd.info, produced by makeinfo version 4.1 from bfd.texinfo.
|
2 |
|
|
|
3 |
|
|
START-INFO-DIR-ENTRY
|
4 |
|
|
* Bfd: (bfd). The Binary File Descriptor library.
|
5 |
|
|
END-INFO-DIR-ENTRY
|
6 |
|
|
|
7 |
|
|
This file documents the BFD library.
|
8 |
|
|
|
9 |
|
|
Copyright (C) 1991, 2000, 2001 Free Software Foundation, Inc.
|
10 |
|
|
|
11 |
|
|
Permission is granted to copy, distribute and/or modify this document
|
12 |
|
|
under the terms of the GNU Free Documentation License, Version 1.1
|
13 |
|
|
or any later version published by the Free Software Foundation;
|
14 |
|
|
with no Invariant Sections, with no Front-Cover Texts, and with no
|
15 |
|
|
Back-Cover Texts. A copy of the license is included in the
|
16 |
|
|
section entitled "GNU Free Documentation License".
|
17 |
|
|
|
18 |
|
|
|
19 |
|
|
File: bfd.info, Node: typedef arelent, Next: howto manager, Prev: Relocations, Up: Relocations
|
20 |
|
|
|
21 |
|
|
typedef arelent
|
22 |
|
|
---------------
|
23 |
|
|
|
24 |
|
|
This is the structure of a relocation entry:
|
25 |
|
|
|
26 |
|
|
|
27 |
|
|
typedef enum bfd_reloc_status
|
28 |
|
|
{
|
29 |
|
|
/* No errors detected. */
|
30 |
|
|
bfd_reloc_ok,
|
31 |
|
|
|
32 |
|
|
/* The relocation was performed, but there was an overflow. */
|
33 |
|
|
bfd_reloc_overflow,
|
34 |
|
|
|
35 |
|
|
/* The address to relocate was not within the section supplied. */
|
36 |
|
|
bfd_reloc_outofrange,
|
37 |
|
|
|
38 |
|
|
/* Used by special functions. */
|
39 |
|
|
bfd_reloc_continue,
|
40 |
|
|
|
41 |
|
|
/* Unsupported relocation size requested. */
|
42 |
|
|
bfd_reloc_notsupported,
|
43 |
|
|
|
44 |
|
|
/* Unused. */
|
45 |
|
|
bfd_reloc_other,
|
46 |
|
|
|
47 |
|
|
/* The symbol to relocate against was undefined. */
|
48 |
|
|
bfd_reloc_undefined,
|
49 |
|
|
|
50 |
|
|
/* The relocation was performed, but may not be ok - presently
|
51 |
|
|
generated only when linking i960 coff files with i960 b.out
|
52 |
|
|
symbols. If this type is returned, the error_message argument
|
53 |
|
|
to bfd_perform_relocation will be set. */
|
54 |
|
|
bfd_reloc_dangerous
|
55 |
|
|
}
|
56 |
|
|
bfd_reloc_status_type;
|
57 |
|
|
|
58 |
|
|
|
59 |
|
|
typedef struct reloc_cache_entry
|
60 |
|
|
{
|
61 |
|
|
/* A pointer into the canonical table of pointers. */
|
62 |
|
|
struct symbol_cache_entry **sym_ptr_ptr;
|
63 |
|
|
|
64 |
|
|
/* offset in section. */
|
65 |
|
|
bfd_size_type address;
|
66 |
|
|
|
67 |
|
|
/* addend for relocation value. */
|
68 |
|
|
bfd_vma addend;
|
69 |
|
|
|
70 |
|
|
/* Pointer to how to perform the required relocation. */
|
71 |
|
|
reloc_howto_type *howto;
|
72 |
|
|
|
73 |
|
|
}
|
74 |
|
|
arelent;
|
75 |
|
|
*Description*
|
76 |
|
|
Here is a description of each of the fields within an `arelent':
|
77 |
|
|
|
78 |
|
|
* `sym_ptr_ptr'
|
79 |
|
|
The symbol table pointer points to a pointer to the symbol
|
80 |
|
|
associated with the relocation request. It is the pointer into the
|
81 |
|
|
table returned by the back end's `get_symtab' action. *Note Symbols::.
|
82 |
|
|
The symbol is referenced through a pointer to a pointer so that tools
|
83 |
|
|
like the linker can fix up all the symbols of the same name by
|
84 |
|
|
modifying only one pointer. The relocation routine looks in the symbol
|
85 |
|
|
and uses the base of the section the symbol is attached to and the
|
86 |
|
|
value of the symbol as the initial relocation offset. If the symbol
|
87 |
|
|
pointer is zero, then the section provided is looked up.
|
88 |
|
|
|
89 |
|
|
* `address'
|
90 |
|
|
The `address' field gives the offset in bytes from the base of the
|
91 |
|
|
section data which owns the relocation record to the first byte of
|
92 |
|
|
relocatable information. The actual data relocated will be relative to
|
93 |
|
|
this point; for example, a relocation type which modifies the bottom
|
94 |
|
|
two bytes of a four byte word would not touch the first byte pointed to
|
95 |
|
|
in a big endian world.
|
96 |
|
|
|
97 |
|
|
* `addend'
|
98 |
|
|
The `addend' is a value provided by the back end to be added (!) to
|
99 |
|
|
the relocation offset. Its interpretation is dependent upon the howto.
|
100 |
|
|
For example, on the 68k the code:
|
101 |
|
|
|
102 |
|
|
char foo[];
|
103 |
|
|
main()
|
104 |
|
|
{
|
105 |
|
|
return foo[0x12345678];
|
106 |
|
|
}
|
107 |
|
|
|
108 |
|
|
Could be compiled into:
|
109 |
|
|
|
110 |
|
|
linkw fp,#-4
|
111 |
|
|
moveb @#12345678,d0
|
112 |
|
|
extbl d0
|
113 |
|
|
unlk fp
|
114 |
|
|
rts
|
115 |
|
|
|
116 |
|
|
This could create a reloc pointing to `foo', but leave the offset in
|
117 |
|
|
the data, something like:
|
118 |
|
|
|
119 |
|
|
RELOCATION RECORDS FOR [.text]:
|
120 |
|
|
offset type value
|
121 |
|
|
00000006 32 _foo
|
122 |
|
|
|
123 |
|
|
00000000 4e56 fffc ; linkw fp,#-4
|
124 |
|
|
00000004 1039 1234 5678 ; moveb @#12345678,d0
|
125 |
|
|
0000000a 49c0 ; extbl d0
|
126 |
|
|
0000000c 4e5e ; unlk fp
|
127 |
|
|
0000000e 4e75 ; rts
|
128 |
|
|
|
129 |
|
|
Using coff and an 88k, some instructions don't have enough space in
|
130 |
|
|
them to represent the full address range, and pointers have to be
|
131 |
|
|
loaded in two parts. So you'd get something like:
|
132 |
|
|
|
133 |
|
|
or.u r13,r0,hi16(_foo+0x12345678)
|
134 |
|
|
ld.b r2,r13,lo16(_foo+0x12345678)
|
135 |
|
|
jmp r1
|
136 |
|
|
|
137 |
|
|
This should create two relocs, both pointing to `_foo', and with
|
138 |
|
|
0x12340000 in their addend field. The data would consist of:
|
139 |
|
|
|
140 |
|
|
RELOCATION RECORDS FOR [.text]:
|
141 |
|
|
offset type value
|
142 |
|
|
00000002 HVRT16 _foo+0x12340000
|
143 |
|
|
00000006 LVRT16 _foo+0x12340000
|
144 |
|
|
|
145 |
|
|
00000000 5da05678 ; or.u r13,r0,0x5678
|
146 |
|
|
00000004 1c4d5678 ; ld.b r2,r13,0x5678
|
147 |
|
|
00000008 f400c001 ; jmp r1
|
148 |
|
|
|
149 |
|
|
The relocation routine digs out the value from the data, adds it to
|
150 |
|
|
the addend to get the original offset, and then adds the value of
|
151 |
|
|
`_foo'. Note that all 32 bits have to be kept around somewhere, to cope
|
152 |
|
|
with carry from bit 15 to bit 16.
|
153 |
|
|
|
154 |
|
|
One further example is the sparc and the a.out format. The sparc has
|
155 |
|
|
a similar problem to the 88k, in that some instructions don't have room
|
156 |
|
|
for an entire offset, but on the sparc the parts are created in odd
|
157 |
|
|
sized lumps. The designers of the a.out format chose to not use the
|
158 |
|
|
data within the section for storing part of the offset; all the offset
|
159 |
|
|
is kept within the reloc. Anything in the data should be ignored.
|
160 |
|
|
|
161 |
|
|
save %sp,-112,%sp
|
162 |
|
|
sethi %hi(_foo+0x12345678),%g2
|
163 |
|
|
ldsb [%g2+%lo(_foo+0x12345678)],%i0
|
164 |
|
|
ret
|
165 |
|
|
restore
|
166 |
|
|
|
167 |
|
|
Both relocs contain a pointer to `foo', and the offsets contain junk.
|
168 |
|
|
|
169 |
|
|
RELOCATION RECORDS FOR [.text]:
|
170 |
|
|
offset type value
|
171 |
|
|
00000004 HI22 _foo+0x12345678
|
172 |
|
|
00000008 LO10 _foo+0x12345678
|
173 |
|
|
|
174 |
|
|
00000000 9de3bf90 ; save %sp,-112,%sp
|
175 |
|
|
00000004 05000000 ; sethi %hi(_foo+0),%g2
|
176 |
|
|
00000008 f048a000 ; ldsb [%g2+%lo(_foo+0)],%i0
|
177 |
|
|
0000000c 81c7e008 ; ret
|
178 |
|
|
00000010 81e80000 ; restore
|
179 |
|
|
|
180 |
|
|
* `howto'
|
181 |
|
|
The `howto' field can be imagined as a relocation instruction. It is
|
182 |
|
|
a pointer to a structure which contains information on what to do with
|
183 |
|
|
all of the other information in the reloc record and data section. A
|
184 |
|
|
back end would normally have a relocation instruction set and turn
|
185 |
|
|
relocations into pointers to the correct structure on input - but it
|
186 |
|
|
would be possible to create each howto field on demand.
|
187 |
|
|
|
188 |
|
|
`enum complain_overflow'
|
189 |
|
|
........................
|
190 |
|
|
|
191 |
|
|
Indicates what sort of overflow checking should be done when
|
192 |
|
|
performing a relocation.
|
193 |
|
|
|
194 |
|
|
|
195 |
|
|
enum complain_overflow
|
196 |
|
|
{
|
197 |
|
|
/* Do not complain on overflow. */
|
198 |
|
|
complain_overflow_dont,
|
199 |
|
|
|
200 |
|
|
/* Complain if the bitfield overflows, whether it is considered
|
201 |
|
|
as signed or unsigned. */
|
202 |
|
|
complain_overflow_bitfield,
|
203 |
|
|
|
204 |
|
|
/* Complain if the value overflows when considered as signed
|
205 |
|
|
number. */
|
206 |
|
|
complain_overflow_signed,
|
207 |
|
|
|
208 |
|
|
/* Complain if the value overflows when considered as an
|
209 |
|
|
unsigned number. */
|
210 |
|
|
complain_overflow_unsigned
|
211 |
|
|
};
|
212 |
|
|
|
213 |
|
|
`reloc_howto_type'
|
214 |
|
|
..................
|
215 |
|
|
|
216 |
|
|
The `reloc_howto_type' is a structure which contains all the
|
217 |
|
|
information that libbfd needs to know to tie up a back end's data.
|
218 |
|
|
|
219 |
|
|
struct symbol_cache_entry; /* Forward declaration. */
|
220 |
|
|
|
221 |
|
|
struct reloc_howto_struct
|
222 |
|
|
{
|
223 |
|
|
/* The type field has mainly a documentary use - the back end can
|
224 |
|
|
do what it wants with it, though normally the back end's
|
225 |
|
|
external idea of what a reloc number is stored
|
226 |
|
|
in this field. For example, a PC relative word relocation
|
227 |
|
|
in a coff environment has the type 023 - because that's
|
228 |
|
|
what the outside world calls a R_PCRWORD reloc. */
|
229 |
|
|
unsigned int type;
|
230 |
|
|
|
231 |
|
|
/* The value the final relocation is shifted right by. This drops
|
232 |
|
|
unwanted data from the relocation. */
|
233 |
|
|
unsigned int rightshift;
|
234 |
|
|
|
235 |
|
|
/* The size of the item to be relocated. This is *not* a
|
236 |
|
|
power-of-two measure. To get the number of bytes operated
|
237 |
|
|
on by a type of relocation, use bfd_get_reloc_size. */
|
238 |
|
|
int size;
|
239 |
|
|
|
240 |
|
|
/* The number of bits in the item to be relocated. This is used
|
241 |
|
|
when doing overflow checking. */
|
242 |
|
|
unsigned int bitsize;
|
243 |
|
|
|
244 |
|
|
/* Notes that the relocation is relative to the location in the
|
245 |
|
|
data section of the addend. The relocation function will
|
246 |
|
|
subtract from the relocation value the address of the location
|
247 |
|
|
being relocated. */
|
248 |
|
|
boolean pc_relative;
|
249 |
|
|
|
250 |
|
|
/* The bit position of the reloc value in the destination.
|
251 |
|
|
The relocated value is left shifted by this amount. */
|
252 |
|
|
unsigned int bitpos;
|
253 |
|
|
|
254 |
|
|
/* What type of overflow error should be checked for when
|
255 |
|
|
relocating. */
|
256 |
|
|
enum complain_overflow complain_on_overflow;
|
257 |
|
|
|
258 |
|
|
/* If this field is non null, then the supplied function is
|
259 |
|
|
called rather than the normal function. This allows really
|
260 |
|
|
strange relocation methods to be accomodated (e.g., i960 callj
|
261 |
|
|
instructions). */
|
262 |
|
|
bfd_reloc_status_type (*special_function)
|
263 |
|
|
PARAMS ((bfd *, arelent *, struct symbol_cache_entry *, PTR, asection *,
|
264 |
|
|
bfd *, char **));
|
265 |
|
|
|
266 |
|
|
/* The textual name of the relocation type. */
|
267 |
|
|
char *name;
|
268 |
|
|
|
269 |
|
|
/* Some formats record a relocation addend in the section contents
|
270 |
|
|
rather than with the relocation. For ELF formats this is the
|
271 |
|
|
distinction between USE_REL and USE_RELA (though the code checks
|
272 |
|
|
for USE_REL == 1/0). The value of this field is TRUE if the
|
273 |
|
|
addend is recorded with the section contents; when performing a
|
274 |
|
|
partial link (ld -r) the section contents (the data) will be
|
275 |
|
|
modified. The value of this field is FALSE if addends are
|
276 |
|
|
recorded with the relocation (in arelent.addend); when performing
|
277 |
|
|
a partial link the relocation will be modified.
|
278 |
|
|
All relocations for all ELF USE_RELA targets should set this field
|
279 |
|
|
to FALSE (values of TRUE should be looked on with suspicion).
|
280 |
|
|
However, the converse is not true: not all relocations of all ELF
|
281 |
|
|
USE_REL targets set this field to TRUE. Why this is so is peculiar
|
282 |
|
|
to each particular target. For relocs that aren't used in partial
|
283 |
|
|
links (e.g. GOT stuff) it doesn't matter what this is set to. */
|
284 |
|
|
boolean partial_inplace;
|
285 |
|
|
|
286 |
|
|
/* The src_mask selects which parts of the read in data
|
287 |
|
|
are to be used in the relocation sum. E.g., if this was an 8 bit
|
288 |
|
|
byte of data which we read and relocated, this would be
|
289 |
|
|
0x000000ff. When we have relocs which have an addend, such as
|
290 |
|
|
sun4 extended relocs, the value in the offset part of a
|
291 |
|
|
relocating field is garbage so we never use it. In this case
|
292 |
|
|
the mask would be 0x00000000. */
|
293 |
|
|
bfd_vma src_mask;
|
294 |
|
|
|
295 |
|
|
/* The dst_mask selects which parts of the instruction are replaced
|
296 |
|
|
into the instruction. In most cases src_mask == dst_mask,
|
297 |
|
|
except in the above special case, where dst_mask would be
|
298 |
|
|
0x000000ff, and src_mask would be 0x00000000. */
|
299 |
|
|
bfd_vma dst_mask;
|
300 |
|
|
|
301 |
|
|
/* When some formats create PC relative instructions, they leave
|
302 |
|
|
the value of the pc of the place being relocated in the offset
|
303 |
|
|
slot of the instruction, so that a PC relative relocation can
|
304 |
|
|
be made just by adding in an ordinary offset (e.g., sun3 a.out).
|
305 |
|
|
Some formats leave the displacement part of an instruction
|
306 |
|
|
empty (e.g., m88k bcs); this flag signals the fact. */
|
307 |
|
|
boolean pcrel_offset;
|
308 |
|
|
};
|
309 |
|
|
|
310 |
|
|
`The HOWTO Macro'
|
311 |
|
|
.................
|
312 |
|
|
|
313 |
|
|
*Description*
|
314 |
|
|
The HOWTO define is horrible and will go away.
|
315 |
|
|
#define HOWTO(C, R, S, B, P, BI, O, SF, NAME, INPLACE, MASKSRC, MASKDST, PC) \
|
316 |
|
|
{ (unsigned) C, R, S, B, P, BI, O, SF, NAME, INPLACE, MASKSRC, MASKDST, PC }
|
317 |
|
|
|
318 |
|
|
*Description*
|
319 |
|
|
And will be replaced with the totally magic way. But for the moment, we
|
320 |
|
|
are compatible, so do it this way.
|
321 |
|
|
#define NEWHOWTO(FUNCTION, NAME, SIZE, REL, IN) \
|
322 |
|
|
HOWTO (0, 0, SIZE, 0, REL, 0, complain_overflow_dont, FUNCTION, \
|
323 |
|
|
NAME, false, 0, 0, IN)
|
324 |
|
|
|
325 |
|
|
*Description*
|
326 |
|
|
This is used to fill in an empty howto entry in an array.
|
327 |
|
|
#define EMPTY_HOWTO(C) \
|
328 |
|
|
HOWTO ((C), 0, 0, 0, false, 0, complain_overflow_dont, NULL, \
|
329 |
|
|
NULL, false, 0, 0, false)
|
330 |
|
|
|
331 |
|
|
*Description*
|
332 |
|
|
Helper routine to turn a symbol into a relocation value.
|
333 |
|
|
#define HOWTO_PREPARE(relocation, symbol) \
|
334 |
|
|
{ \
|
335 |
|
|
if (symbol != (asymbol *) NULL) \
|
336 |
|
|
{ \
|
337 |
|
|
if (bfd_is_com_section (symbol->section)) \
|
338 |
|
|
{ \
|
339 |
|
|
relocation = 0; \
|
340 |
|
|
} \
|
341 |
|
|
else \
|
342 |
|
|
{ \
|
343 |
|
|
relocation = symbol->value; \
|
344 |
|
|
} \
|
345 |
|
|
} \
|
346 |
|
|
}
|
347 |
|
|
|
348 |
|
|
`bfd_get_reloc_size'
|
349 |
|
|
....................
|
350 |
|
|
|
351 |
|
|
*Synopsis*
|
352 |
|
|
unsigned int bfd_get_reloc_size (reloc_howto_type *);
|
353 |
|
|
*Description*
|
354 |
|
|
For a reloc_howto_type that operates on a fixed number of bytes, this
|
355 |
|
|
returns the number of bytes operated on.
|
356 |
|
|
|
357 |
|
|
`arelent_chain'
|
358 |
|
|
...............
|
359 |
|
|
|
360 |
|
|
*Description*
|
361 |
|
|
How relocs are tied together in an `asection':
|
362 |
|
|
typedef struct relent_chain
|
363 |
|
|
{
|
364 |
|
|
arelent relent;
|
365 |
|
|
struct relent_chain *next;
|
366 |
|
|
}
|
367 |
|
|
arelent_chain;
|
368 |
|
|
|
369 |
|
|
`bfd_check_overflow'
|
370 |
|
|
....................
|
371 |
|
|
|
372 |
|
|
*Synopsis*
|
373 |
|
|
bfd_reloc_status_type
|
374 |
|
|
bfd_check_overflow
|
375 |
|
|
(enum complain_overflow how,
|
376 |
|
|
unsigned int bitsize,
|
377 |
|
|
unsigned int rightshift,
|
378 |
|
|
unsigned int addrsize,
|
379 |
|
|
bfd_vma relocation);
|
380 |
|
|
*Description*
|
381 |
|
|
Perform overflow checking on RELOCATION which has BITSIZE significant
|
382 |
|
|
bits and will be shifted right by RIGHTSHIFT bits, on a machine with
|
383 |
|
|
addresses containing ADDRSIZE significant bits. The result is either of
|
384 |
|
|
`bfd_reloc_ok' or `bfd_reloc_overflow'.
|
385 |
|
|
|
386 |
|
|
`bfd_perform_relocation'
|
387 |
|
|
........................
|
388 |
|
|
|
389 |
|
|
*Synopsis*
|
390 |
|
|
bfd_reloc_status_type
|
391 |
|
|
bfd_perform_relocation
|
392 |
|
|
(bfd *abfd,
|
393 |
|
|
arelent *reloc_entry,
|
394 |
|
|
PTR data,
|
395 |
|
|
asection *input_section,
|
396 |
|
|
bfd *output_bfd,
|
397 |
|
|
char **error_message);
|
398 |
|
|
*Description*
|
399 |
|
|
If OUTPUT_BFD is supplied to this function, the generated image will be
|
400 |
|
|
relocatable; the relocations are copied to the output file after they
|
401 |
|
|
have been changed to reflect the new state of the world. There are two
|
402 |
|
|
ways of reflecting the results of partial linkage in an output file: by
|
403 |
|
|
modifying the output data in place, and by modifying the relocation
|
404 |
|
|
record. Some native formats (e.g., basic a.out and basic coff) have no
|
405 |
|
|
way of specifying an addend in the relocation type, so the addend has
|
406 |
|
|
to go in the output data. This is no big deal since in these formats
|
407 |
|
|
the output data slot will always be big enough for the addend. Complex
|
408 |
|
|
reloc types with addends were invented to solve just this problem. The
|
409 |
|
|
ERROR_MESSAGE argument is set to an error message if this return
|
410 |
|
|
`bfd_reloc_dangerous'.
|
411 |
|
|
|
412 |
|
|
`bfd_install_relocation'
|
413 |
|
|
........................
|
414 |
|
|
|
415 |
|
|
*Synopsis*
|
416 |
|
|
bfd_reloc_status_type
|
417 |
|
|
bfd_install_relocation
|
418 |
|
|
(bfd *abfd,
|
419 |
|
|
arelent *reloc_entry,
|
420 |
|
|
PTR data, bfd_vma data_start,
|
421 |
|
|
asection *input_section,
|
422 |
|
|
char **error_message);
|
423 |
|
|
*Description*
|
424 |
|
|
This looks remarkably like `bfd_perform_relocation', except it does not
|
425 |
|
|
expect that the section contents have been filled in. I.e., it's
|
426 |
|
|
suitable for use when creating, rather than applying a relocation.
|
427 |
|
|
|
428 |
|
|
For now, this function should be considered reserved for the
|
429 |
|
|
assembler.
|
430 |
|
|
|