bfd/doc/bfd.info-3

   1 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 \x1f
  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