1 /* BFD support for handling relocation entries.
2 Copyright (C) 1990-1991 Free Software Foundation, Inc.
3 Written by Cygnus Support.
5 This file is part of BFD, the Binary File Descriptor library.
7 This program is free software; you can redistribute it and/or modify
8 it under the terms of the GNU General Public License as published by
9 the Free Software Foundation; either version 2 of the License, or
10 (at your option) any later version.
12 This program is distributed in the hope that it will be useful,
13 but WITHOUT ANY WARRANTY; without even the implied warranty of
14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 GNU General Public License for more details.
17 You should have received a copy of the GNU General Public License
18 along with this program; if not, write to the Free Software
19 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. */
24 BFD maintains relocations in much the same was as it maintains
25 symbols; they are left alone until required, then read in en-mass and
26 traslated into an internal form. There is a common routine
27 @code{bfd_perform_relocation} which acts upon the canonical form to to
30 Note that relocations are maintained on a per section basis, whilst
31 symbols are maintained on a per BFD basis.
33 All a back end has to do to fit the BFD interface is to create as many
34 @code{struct reloc_cache_entry} as there are relocations in a
35 particuar section, and fill in the right bits:
39 * reloc handling functions::
47 @node typedef arelent, Relocations, reloc handling functions, Relocations
48 @section typedef arelent
53 /*proto* bfd_perform_relocation
54 The relocation routine returns as a status an enumerated type:
58 $typedef enum bfd_reloc_status {
63 The relocation was performed, but there was an overflow.
67 The address to relocate was not within the section supplied
69 $ bfd_reloc_outofrange,
71 Used by special functions
77 $ bfd_reloc_notsupported,
79 Unsupported relocation size requested.
83 The symbol to relocate against was undefined.
85 $ bfd_reloc_undefined,
87 The relocation was performed, but may not be ok - presently generated
88 only when linking i960 coff files with i960 b.out symbols.
92 $ bfd_reloc_status_enum_type;
102 $typedef struct reloc_cache_entry
105 A pointer into the canonical table of pointers
107 $ struct symbol_cache_entry **sym_ptr_ptr;
111 $ rawdata_offset address;
113 addend for relocation value
117 if sym is null this is the section
119 $ struct sec *section;
121 Pointer to how to perform the required relocation
123 $ CONST struct reloc_howto_struct *howto;
133 The symbol table pointer points to a pointer to the symbol associated with the
134 relocation request. This would naturally be the pointer into the table
135 returned by the back end's get_symtab action. @xref{Symbols}. The
136 symbol is referenced through a pointer to a pointer so that tools like
137 the linker can fix up all the symbols of the same name by modifying
138 only one pointer. The relocation routine looks in the symbol and uses
139 the base of the section the symbol is attached to and the value of
140 the symbol as the initial relocation offset. If the symbol pointer is
141 zero, then the section provided is looked up.
143 The address field gives the offset in bytes from the base of the
144 section data which owns the relocation record to the first byte of
145 relocatable information. The actual data relocated will be relative to
146 this point - for example, a relocation type which modifies the bottom
147 two bytes of a four byte word would not touch the first byte pointed
148 to in a big endian world.
150 The addend is a value provided by the back end to be added (!) to the
151 relocation offset. Its interpretation is dependent upon the howto.
152 For example, on the 68k the code:
158 return foo[0x12345678];
161 Could be compiled into:
171 This could create a reloc pointing to foo, but leave the offset in the data
175 RELOCATION RECORDS FOR [.text]:
179 00000000 4e56 fffc ; linkw fp,#-4
180 00000004 1039 1234 5678 ; moveb @@#12345678,d0
181 0000000a 49c0 ; extbl d0
182 0000000c 4e5e ; unlk fp
185 Using coff and an 88k, some instructions don't have enough space in them to
186 represent the full address range, and pointers have to be loaded in
187 two parts. So you'd get something like:
190 or.u r13,r0,hi16(_foo+0x12345678)
191 ld.b r2,r13,lo16(_foo+0x12345678)
194 This whould create two relocs, both pointing to _foo, and with 0x12340000
195 in their addend field. The data would consist of:
199 RELOCATION RECORDS FOR [.text]:
201 00000002 HVRT16 _foo+0x12340000
202 00000006 LVRT16 _foo+0x12340000
204 00000000 5da05678 ; or.u r13,r0,0x5678
205 00000004 1c4d5678 ; ld.b r2,r13,0x5678
206 00000008 f400c001 ; jmp r1
208 The relocation routine digs out the value from the data, adds it to
209 the addend to get the original offset and then adds the value of _foo.
210 Note that all 32 bits have to be kept around somewhere, to cope with
211 carry from bit 15 to bit 16.
213 On further example is the sparc and the a.out format. The sparc has a
214 similar problem to the 88k, in that some instructions don't have
215 room for an entire offset, but on the sparc the parts are created odd
216 sized lumps. The designers of the a.out format chose not to use the
217 data within the section for storing part of the offset; all the offset
218 is kept within the reloc. Any thing in the data should be ignored.
222 sethi %hi(_foo+0x12345678),%g2
223 ldsb [%g2+%lo(_foo+0x12345678)],%i0
227 Both relocs contains a pointer to foo, and the offsets would contain junk.
230 RELOCATION RECORDS FOR [.text]:
232 00000004 HI22 _foo+0x12345678
233 00000008 LO10 _foo+0x12345678
235 00000000 9de3bf90 ; save %sp,-112,%sp
236 00000004 05000000 ; sethi %hi(_foo+0),%g2
237 00000008 f048a000 ; ldsb [%g2+%lo(_foo+0)],%i0
238 0000000c 81c7e008 ; ret
239 00000010 81e80000 ; restore
242 The section field is only used when the symbol pointer field is null.
243 It supplies the section into which the data should be relocated. The
244 field's main use comes from assemblers which do most of the symbol fixups
245 themselves; an assembler may take an internal reference to a label,
246 but since it knows where the label is, it can turn the relocation
247 request from a symbol lookup into a section relative relocation - the
248 relocation emitted has no symbol, just a section to relocate against.
250 I'm not sure what it means when both a symbol pointer an a section
251 pointer are present. Some formats use this sort of mechanism to
252 describe PIC relocations, but BFD can't to that sort of thing yet.
254 The howto field can be imagined as a relocation instruction. It is a
255 pointer to a struct which contains information on what to do with all
256 the other information in the reloc record and data section. A back end
257 would normally have a relocation instruction set and turn relocations
258 into pointers to the correct structure on input - but it would be
259 possible to create each howto field on demand.
264 /*proto* reloc_howto_type
265 The @code{reloc_howto_type} is a structure which contains all the
266 information that BFD needs to know to tie up a back end's data.
270 $typedef CONST struct reloc_howto_struct
272 The type field has mainly a documetary use - the back end can to what
273 it wants with it, though the normally the back end's external idea of
274 what a reloc number would be would be stored in this field. For
275 example, the a PC relative word relocation in a coff environment would
276 have the type 023 - because that's what the outside world calls a
281 The value the final relocation is shifted right by. This drops
282 unwanted data from the relocation.
284 $ unsigned int rightshift;
286 The size of the item to be relocated - 0, is one byte, 1 is 2 bytes, 3
293 $ unsigned int bitsize;
295 Notes that the relocation is relative to the location in the data
296 section of the addend. The relocation function will subtract from the
297 relocation value the address of the location being relocated.
299 $ boolean pc_relative;
303 $ unsigned int bitpos;
309 Causes the relocation routine to return an error if overflow is
310 detected when relocating.
312 $ boolean complain_on_overflow;
314 If this field is non null, then the supplied function is called rather
315 than the normal function. This allows really strange relocation
316 methods to be accomodated (eg, i960 callj instructions).
318 $ bfd_reloc_status_enum_type (*special_function)();
320 The textual name of the relocation type.
324 When performing a partial link, some formats must modify the
325 relocations rather than the data - this flag signals this.
327 $ boolean partial_inplace;
329 The src_mask is used to select what parts of the read in data are to
330 be used in the relocation sum. Eg, if this was an 8 bit bit of data
331 which we read and relocated, this would be 0x000000ff. When we have
332 relocs which have an addend, such as sun4 extended relocs, the value
333 in the offset part of a relocating field is garbage so we never use
334 it. In this case the mask would be 0x00000000.
337 The dst_mask is what parts of the instruction are replaced into the
338 instruction. In most cases src_mask == dst_mask, except in the above
339 special case, where dst_mask would be 0x000000ff, and src_mask would
344 When some formats create PC relative instructions, they leave the
345 value of the pc of the place being relocated in the offset slot of the
346 instruction, so that a PC relative relocation can be made just by
347 adding in an ordinary offset (eg sun3 a.out). Some formats leave the
348 displacement part of an instruction empty (eg m88k bcs), this flag
351 $ boolean pcrel_offset;
358 The HOWTO define is horrible and will go away.
360 #define HOWTO(C, R,S,B, P, BI, ABS, O, SF, NAME, INPLACE, MASKSRC, MASKDST, PC) \
361 {(unsigned)C,R,S,B, P, BI, ABS,O,SF,NAME,INPLACE,MASKSRC,MASKDST,PC}
364 And will be replaced with the totally magic way. But for the moment,
365 we are compatible, so do it this way..
368 #define NEWHOWTO( FUNCTION, NAME,SIZE,REL) HOWTO(0,0,SIZE,0,REL,0,false,false,FUNCTION, NAME,false,0,0,false)
371 Helper routine to turn a symbol into a relocation value.
376 #define HOWTO_PREPARE(relocation, symbol) \
378 if (symbol != (asymbol *)NULL) { \
379 if (symbol->flags & BSF_FORT_COMM) { \
383 relocation = symbol->value; \
386 if (symbol->section != (asection *)NULL) { \
387 relocation += symbol->section->output_section->vma + \
388 symbol->section->output_offset; \
396 typedef unsigned char bfd_byte;
398 typedef struct relent_chain {
400 struct relent_chain *next;
410 If an output_bfd is supplied to this function the generated image
411 will be relocatable, the relocations are copied to the output file
412 after they have been changed to reflect the new state of the world.
413 There are two ways of reflecting the results of partial linkage in an
414 output file; by modifying the output data in place, and by modifying
415 the relocation record. Some native formats (eg basic a.out and basic
416 coff) have no way of specifying an addend in the relocation type, so
417 the addend has to go in the output data. This is no big deal since in
418 these formats the output data slot will always be big enough for the
419 addend. Complex reloc types with addends were invented to solve just
421 *; PROTO(bfd_reloc_status_enum_type,
422 bfd_perform_relocation,
424 arelent *reloc_entry,
426 asection *input_section,
431 bfd_reloc_status_enum_type
432 DEFUN(bfd_perform_relocation,(abfd,
438 arelent *reloc_entry AND
440 asection *input_section AND
444 bfd_reloc_status_enum_type flag = bfd_reloc_ok;
445 bfd_vma addr = reloc_entry->address ;
446 bfd_vma output_base = 0;
447 reloc_howto_type *howto = reloc_entry->howto;
448 asection *reloc_target_output_section;
449 asection *reloc_target_input_section;
452 if (reloc_entry->sym_ptr_ptr) {
453 symbol = *( reloc_entry->sym_ptr_ptr);
454 if ((symbol->flags & BSF_UNDEFINED) && output_bfd == (bfd *)NULL) {
455 flag = bfd_reloc_undefined;
459 symbol = (asymbol*)NULL;
462 if (howto->special_function){
463 bfd_reloc_status_enum_type cont;
464 cont = howto->special_function(abfd,
469 if (cont != bfd_reloc_continue) return cont;
473 Work out which section the relocation is targetted at and the
474 initial relocation command value.
478 if (symbol != (asymbol *)NULL){
479 if (symbol->flags & BSF_FORT_COMM) {
483 relocation = symbol->value;
485 if (symbol->section != (asection *)NULL)
487 reloc_target_input_section = symbol->section;
490 reloc_target_input_section = (asection *)NULL;
493 else if (reloc_entry->section != (asection *)NULL)
496 reloc_target_input_section = reloc_entry->section;
500 reloc_target_input_section = (asection *)NULL;
504 if (reloc_target_input_section != (asection *)NULL) {
506 reloc_target_output_section =
507 reloc_target_input_section->output_section;
509 if (output_bfd && howto->partial_inplace==false) {
513 output_base = reloc_target_output_section->vma;
517 relocation += output_base + reloc_target_input_section->output_offset;
520 relocation += reloc_entry->addend ;
523 if(reloc_entry->address > (bfd_vma)(input_section->size))
525 return bfd_reloc_outofrange;
529 if (howto->pc_relative == true)
532 Anything which started out as pc relative should end up that
535 There are two ways we can see a pcrel instruction. Sometimes
536 the pcrel displacement has been partially calculated, it
537 includes the distance from the start of the section to the
538 instruction in it (eg sun3), and sometimes the field is
539 totally blank - eg m88kbcs.
544 input_section->output_section->vma + input_section->output_offset;
546 if (howto->pcrel_offset == true) {
547 relocation -= reloc_entry->address;
552 if (output_bfd!= (bfd *)NULL) {
553 if ( howto->partial_inplace == false) {
555 This is a partial relocation, and we want to apply the relocation
556 to the reloc entry rather than the raw data. Modify the reloc
557 inplace to reflect what we now know.
559 reloc_entry->addend = relocation ;
560 reloc_entry->section = reloc_target_input_section;
561 if (reloc_target_input_section != (asection *)NULL) {
562 /* If we know the output section we can forget the symbol */
563 reloc_entry->sym_ptr_ptr = (asymbol**)NULL;
565 reloc_entry->address +=
566 input_section->output_offset;
571 /* This is a partial relocation, but inplace, so modify the
574 If we've relocated with a symbol with a section, change
575 into a ref to the section belonging to the symbol
578 if (symbol != (asymbol *)NULL && reloc_target_input_section != (asection *)NULL)
580 reloc_entry->section = reloc_target_input_section;
581 reloc_entry->sym_ptr_ptr = (asymbol **)NULL;
587 reloc_entry->addend = 0;
591 Either we are relocating all the way, or we don't want to apply
592 the relocation to the reloc entry (probably because there isn't
593 any room in the output format to describe addends to relocs)
595 relocation >>= howto->rightshift;
597 /* Shift everything up to where it's going to be used */
599 relocation <<= howto->bitpos;
601 /* Wait for the day when all have the mask in them */
604 i instruction to be left alone
605 o offset within instruction
606 r relocation offset to apply
615 i i i i i o o o o o from bfd_get<size>
616 and S S S S S to get the size offset we want
617 + r r r r r r r r r r to get the final value to place
618 and D D D D D to chop to right size
619 -----------------------
622 ... i i i i i o o o o o from bfd_get<size>
623 and N N N N N get instruction
624 -----------------------
630 -----------------------
631 R R R R R R R R R R put into bfd_put<size>
635 x = ( (x & ~howto->dst_mask) | (((x & howto->src_mask) + relocation) & howto->dst_mask))
641 char x = bfd_get_8(abfd, (char *)data + addr);
643 bfd_put_8(abfd,x, (unsigned char *) data + addr);
649 short x = bfd_get_16(abfd, (bfd_byte *)data + addr);
651 bfd_put_16(abfd, x, (unsigned char *)data + addr);
656 long x = bfd_get_32(abfd, (bfd_byte *) data + addr);
658 bfd_put_32(abfd,x, (bfd_byte *)data + addr);
666 return bfd_reloc_other;
676 @section The howto manager
679 When an application wants to create a relocation, but doesn't know
680 what the target machine might call it, it can find out by using this
685 /*proto* bfd_reloc_code_enum_type
692 16 bits wide, simple reloc
696 8 bits wide, but used to form an address like 0xffnn
704 8 bits wide, pc relative
707 $ } bfd_reloc_code_enum_real_type;
715 /*proto* bfd_reloc_type_lookup
716 This routine returns a pointer to a howto struct which when invoked,
717 will perform the supplied relocation on data from the architecture
720 [Note] This function will go away.
722 *; PROTO(CONST struct reloc_howto_struct *,
723 bfd_reloc_type_lookup,
724 (CONST bfd_arch_info_struct_type *arch, bfd_reloc_code_enum_type code));
728 CONST struct reloc_howto_struct *
729 DEFUN(bfd_reloc_type_lookup,(arch, code),
730 CONST bfd_arch_info_struct_type *arch AND
731 bfd_reloc_code_enum_type code)
733 return arch->reloc_type_lookup(arch, code);