contrib/binutils/bfd/doc/reloc.texi

   1 @section Relocations
   2 BFD maintains relocations in much the same way it maintains
   3 symbols: they are left alone until required, then read in
   4 en-mass and translated into an internal form.  A common
   5 routine @code{bfd_perform_relocation} acts upon the
   6 canonical form to do the fixup.
   7
   8 Relocations are maintained on a per section basis,
   9 while symbols are maintained on a per BFD basis.
  10
  11 All that a back end has to do to fit the BFD interface is to create
  12 a @code{struct reloc_cache_entry} for each relocation
  13 in a particular section, and fill in the right bits of the structures.
  14
  15 @menu
  16 * typedef arelent::
  17 * howto manager::
  18 @end menu
  19
  20
  21 @node typedef arelent, howto manager, Relocations, Relocations
  22 @subsection typedef arelent
  23 This is the structure of a relocation entry:
  24
  25
  26 @example
  27
  28 typedef enum bfd_reloc_status
  29 @{
  30        /* No errors detected */
  31   bfd_reloc_ok,
  32
  33        /* The relocation was performed, but there was an overflow. */
  34   bfd_reloc_overflow,
  35
  36        /* The address to relocate was not within the section supplied. */
  37   bfd_reloc_outofrange,
  38
  39        /* Used by special functions */
  40   bfd_reloc_continue,
  41
  42        /* Unsupported relocation size requested. */
  43   bfd_reloc_notsupported,
  44
  45        /* Unused */
  46   bfd_reloc_other,
  47
  48        /* The symbol to relocate against was undefined. */
  49   bfd_reloc_undefined,
  50
  51        /* The relocation was performed, but may not be ok - presently
  52           generated only when linking i960 coff files with i960 b.out
  53           symbols.  If this type is returned, the error_message argument
  54           to bfd_perform_relocation will be set.  */
  55   bfd_reloc_dangerous
  56  @}
  57  bfd_reloc_status_type;
  58
  59
  60 typedef struct reloc_cache_entry
  61 @{
  62        /* A pointer into the canonical table of pointers  */
  63   struct symbol_cache_entry **sym_ptr_ptr;
  64
  65        /* offset in section */
  66   bfd_size_type address;
  67
  68        /* addend for relocation value */
  69   bfd_vma addend;
  70
  71        /* Pointer to how to perform the required relocation */
  72   reloc_howto_type *howto;
  73
  74 @} arelent;
  75 @end example
  76 @strong{Description}@*
  77 Here is a description of each of the fields within an @code{arelent}:
  78
  79 @itemize @bullet
  80
  81 @item
  82 @code{sym_ptr_ptr}
  83 @end itemize
  84 The symbol table pointer points to a pointer to the symbol
  85 associated with the relocation request.  It is
  86 the pointer into the table returned by the back end's
  87 @code{get_symtab} action. @xref{Symbols}. The symbol is referenced
  88 through a pointer to a pointer so that tools like the linker
  89 can fix up all the symbols of the same name by modifying only
  90 one pointer. The relocation routine looks in the symbol and
  91 uses the base of the section the symbol is attached to and the
  92 value of the symbol as the initial relocation offset. If the
  93 symbol pointer is zero, then the section provided is looked up.
  94
  95 @itemize @bullet
  96
  97 @item
  98 @code{address}
  99 @end itemize
 100 The @code{address} field gives the offset in bytes from the base of
 101 the section data which owns the relocation record to the first
 102 byte of relocatable information. The actual data relocated
 103 will be relative to this point; for example, a relocation
 104 type which modifies the bottom two bytes of a four byte word
 105 would not touch the first byte pointed to in a big endian
 106 world.
 107
 108 @itemize @bullet
 109
 110 @item
 111 @code{addend}
 112 @end itemize
 113 The @code{addend} is a value provided by the back end to be added (!)
 114 to the relocation offset. Its interpretation is dependent upon
 115 the howto. For example, on the 68k the code:
 116
 117 @example
 118         char foo[];
 119         main()
 120                 @{
 121                 return foo[0x12345678];
 122                 @}
 123 @end example
 124
 125 Could be compiled into:
 126
 127 @example
 128         linkw fp,#-4
 129         moveb @@#12345678,d0
 130         extbl d0
 131         unlk fp
 132         rts
 133 @end example
 134
 135 This could create a reloc pointing to @code{foo}, but leave the
 136 offset in the data, something like:
 137
 138 @example
 139 RELOCATION RECORDS FOR [.text]:
 140 offset   type      value
 141 00000006 32        _foo
 142
 143 00000000 4e56 fffc          ; linkw fp,#-4
 144 00000004 1039 1234 5678     ; moveb @@#12345678,d0
 145 0000000a 49c0               ; extbl d0
 146 0000000c 4e5e               ; unlk fp
 147 0000000e 4e75               ; rts
 148 @end example
 149
 150 Using coff and an 88k, some instructions don't have enough
 151 space in them to represent the full address range, and
 152 pointers have to be loaded in two parts. So you'd get something like:
 153
 154 @example
 155         or.u     r13,r0,hi16(_foo+0x12345678)
 156         ld.b     r2,r13,lo16(_foo+0x12345678)
 157         jmp      r1
 158 @end example
 159
 160 This should create two relocs, both pointing to @code{_foo}, and with
 161 0x12340000 in their addend field. The data would consist of:
 162
 163 @example
 164 RELOCATION RECORDS FOR [.text]:
 165 offset   type      value
 166 00000002 HVRT16    _foo+0x12340000
 167 00000006 LVRT16    _foo+0x12340000
 168
 169 00000000 5da05678           ; or.u r13,r0,0x5678
 170 00000004 1c4d5678           ; ld.b r2,r13,0x5678
 171 00000008 f400c001           ; jmp r1
 172 @end example
 173
 174 The relocation routine digs out the value from the data, adds
 175 it to the addend to get the original offset, and then adds the
 176 value of @code{_foo}. Note that all 32 bits have to be kept around
 177 somewhere, to cope with carry from bit 15 to bit 16.
 178
 179 One further example is the sparc and the a.out format. The
 180 sparc has a similar problem to the 88k, in that some
 181 instructions don't have room for an entire offset, but on the
 182 sparc the parts are created in odd sized lumps. The designers of
 183 the a.out format chose to not use the data within the section
 184 for storing part of the offset; all the offset is kept within
 185 the reloc. Anything in the data should be ignored.
 186
 187 @example
 188         save %sp,-112,%sp
 189         sethi %hi(_foo+0x12345678),%g2
 190         ldsb [%g2+%lo(_foo+0x12345678)],%i0
 191         ret
 192         restore
 193 @end example
 194
 195 Both relocs contain a pointer to @code{foo}, and the offsets
 196 contain junk.
 197
 198 @example
 199 RELOCATION RECORDS FOR [.text]:
 200 offset   type      value
 201 00000004 HI22      _foo+0x12345678
 202 00000008 LO10      _foo+0x12345678
 203
 204 00000000 9de3bf90     ; save %sp,-112,%sp
 205 00000004 05000000     ; sethi %hi(_foo+0),%g2
 206 00000008 f048a000     ; ldsb [%g2+%lo(_foo+0)],%i0
 207 0000000c 81c7e008     ; ret
 208 00000010 81e80000     ; restore
 209 @end example
 210
 211 @itemize @bullet
 212
 213 @item
 214 @code{howto}
 215 @end itemize
 216 The @code{howto} field can be imagined as a
 217 relocation instruction. It is a pointer to a structure which
 218 contains information on what to do with all of the other
 219 information in the reloc record and data section. A back end
 220 would normally have a relocation instruction set and turn
 221 relocations into pointers to the correct structure on input -
 222 but it would be possible to create each howto field on demand.
 223
 224 @subsubsection @code{enum complain_overflow}
 225 Indicates what sort of overflow checking should be done when
 226 performing a relocation.
 227
 228
 229 @example
 230
 231 enum complain_overflow
 232 @{
 233        /* Do not complain on overflow. */
 234   complain_overflow_dont,
 235
 236        /* Complain if the bitfield overflows, whether it is considered
 237           as signed or unsigned. */
 238   complain_overflow_bitfield,
 239
 240        /* Complain if the value overflows when considered as signed
 241           number. */
 242   complain_overflow_signed,
 243
 244        /* Complain if the value overflows when considered as an
 245           unsigned number. */
 246   complain_overflow_unsigned
 247 @};
 248 @end example
 249 @subsubsection @code{reloc_howto_type}
 250 The @code{reloc_howto_type} is a structure which contains all the
 251 information that libbfd needs to know to tie up a back end's data.
 252
 253
 254 @example
 255 struct symbol_cache_entry;             /* Forward declaration */
 256
 257 struct reloc_howto_struct
 258 @{
 259        /*  The type field has mainly a documentary use - the back end can
 260            do what it wants with it, though normally the back end's
 261            external idea of what a reloc number is stored
 262            in this field. For example, a PC relative word relocation
 263            in a coff environment has the type 023 - because that's
 264            what the outside world calls a R_PCRWORD reloc. */
 265   unsigned int type;
 266
 267        /*  The value the final relocation is shifted right by. This drops
 268            unwanted data from the relocation.  */
 269   unsigned int rightshift;
 270
 271        /*  The size of the item to be relocated.  This is *not* a
 272            power-of-two measure.  To get the number of bytes operated
 273            on by a type of relocation, use bfd_get_reloc_size.  */
 274   int size;
 275
 276        /*  The number of bits in the item to be relocated.  This is used
 277            when doing overflow checking.  */
 278   unsigned int bitsize;
 279
 280        /*  Notes that the relocation is relative to the location in the
 281            data section of the addend. The relocation function will
 282            subtract from the relocation value the address of the location
 283            being relocated. */
 284   boolean pc_relative;
 285
 286        /*  The bit position of the reloc value in the destination.
 287            The relocated value is left shifted by this amount. */
 288   unsigned int bitpos;
 289
 290        /* What type of overflow error should be checked for when
 291           relocating. */
 292   enum complain_overflow complain_on_overflow;
 293
 294        /* If this field is non null, then the supplied function is
 295           called rather than the normal function. This allows really
 296           strange relocation methods to be accomodated (e.g., i960 callj
 297           instructions). */
 298   bfd_reloc_status_type (*special_function)
 299                                    PARAMS ((bfd *abfd,
 300                                             arelent *reloc_entry,
 301                                             struct symbol_cache_entry *symbol,
 302                                             PTR data,
 303                                             asection *input_section,
 304                                             bfd *output_bfd,
 305                                             char **error_message));
 306
 307        /* The textual name of the relocation type. */
 308   char *name;
 309
 310        /* When performing a partial link, some formats must modify the
 311           relocations rather than the data - this flag signals this.*/
 312   boolean partial_inplace;
 313
 314        /* The src_mask selects which parts of the read in data
 315           are to be used in the relocation sum.  E.g., if this was an 8 bit
 316           bit of data which we read and relocated, this would be
 317           0x000000ff. When we have relocs which have an addend, such as
 318           sun4 extended relocs, the value in the offset part of a
 319           relocating field is garbage so we never use it. In this case
 320           the mask would be 0x00000000. */
 321   bfd_vma src_mask;
 322
 323        /* The dst_mask selects which parts of the instruction are replaced
 324           into the instruction. In most cases src_mask == dst_mask,
 325           except in the above special case, where dst_mask would be
 326           0x000000ff, and src_mask would be 0x00000000.   */
 327   bfd_vma dst_mask;
 328
 329        /* When some formats create PC relative instructions, they leave
 330           the value of the pc of the place being relocated in the offset
 331           slot of the instruction, so that a PC relative relocation can
 332           be made just by adding in an ordinary offset (e.g., sun3 a.out).
 333           Some formats leave the displacement part of an instruction
 334           empty (e.g., m88k bcs); this flag signals the fact.*/
 335   boolean pcrel_offset;
 336
 337 @};
 338 @end example
 339 @findex The HOWTO Macro
 340 @subsubsection @code{The HOWTO Macro}
 341 @strong{Description}@*
 342 The HOWTO define is horrible and will go away.
 343 @example
 344 #define HOWTO(C, R,S,B, P, BI, O, SF, NAME, INPLACE, MASKSRC, MASKDST, PC) \
 345   @{(unsigned)C,R,S,B, P, BI, O,SF,NAME,INPLACE,MASKSRC,MASKDST,PC@}
 346 @end example
 347
 348 @strong{Description}@*
 349 And will be replaced with the totally magic way. But for the
 350 moment, we are compatible, so do it this way.
 351 @example
 352 #define NEWHOWTO( FUNCTION, NAME,SIZE,REL,IN) HOWTO(0,0,SIZE,0,REL,0,complain_overflow_dont,FUNCTION, NAME,false,0,0,IN)
 353
 354 @end example
 355
 356 @strong{Description}@*
 357 Helper routine to turn a symbol into a relocation value.
 358 @example
 359 #define HOWTO_PREPARE(relocation, symbol)      \
 360   @{                                            \
 361   if (symbol != (asymbol *)NULL) @{             \
 362     if (bfd_is_com_section (symbol->section)) @{ \
 363       relocation = 0;                          \
 364     @}                                          \
 365     else @{                                     \
 366       relocation = symbol->value;              \
 367     @}                                          \
 368   @}                                            \
 369 @}
 370 @end example
 371
 372 @findex bfd_get_reloc_size
 373 @subsubsection @code{bfd_get_reloc_size}
 374 @strong{Synopsis}
 375 @example
 376 unsigned int bfd_get_reloc_size (reloc_howto_type *);
 377 @end example
 378 @strong{Description}@*
 379 For a reloc_howto_type that operates on a fixed number of bytes,
 380 this returns the number of bytes operated on.
 381
 382 @findex arelent_chain
 383 @subsubsection @code{arelent_chain}
 384 @strong{Description}@*
 385 How relocs are tied together in an @code{asection}:
 386 @example
 387 typedef struct relent_chain @{
 388   arelent relent;
 389   struct   relent_chain *next;
 390 @} arelent_chain;
 391 @end example
 392
 393 @findex bfd_check_overflow
 394 @subsubsection @code{bfd_check_overflow}
 395 @strong{Synopsis}
 396 @example
 397 bfd_reloc_status_type
 398 bfd_check_overflow
 399    (enum complain_overflow how,
 400     unsigned int bitsize,
 401     unsigned int rightshift,
 402     bfd_vma relocation);
 403 @end example
 404 @strong{Description}@*
 405 Perform overflow checking on @var{relocation} which has @var{bitsize}
 406 significant bits and will be shifted right by @var{rightshift} bits.
 407 The result is either of @code{bfd_reloc_ok} or
 408 @code{bfd_reloc_overflow}.
 409
 410 @findex bfd_perform_relocation
 411 @subsubsection @code{bfd_perform_relocation}
 412 @strong{Synopsis}
 413 @example
 414 bfd_reloc_status_type
 415 bfd_perform_relocation
 416    (bfd *abfd,
 417     arelent *reloc_entry,
 418     PTR data,
 419     asection *input_section,
 420     bfd *output_bfd,
 421     char **error_message);
 422 @end example
 423 @strong{Description}@*
 424 If @var{output_bfd} is supplied to this function, the
 425 generated image will be relocatable; the relocations are
 426 copied to the output file after they have been changed to
 427 reflect the new state of the world. There are two ways of
 428 reflecting the results of partial linkage in an output file:
 429 by modifying the output data in place, and by modifying the
 430 relocation record.  Some native formats (e.g., basic a.out and
 431 basic coff) have no way of specifying an addend in the
 432 relocation type, so the addend has to go in the output data.
 433 This is no big deal since in these formats the output data
 434 slot will always be big enough for the addend. Complex reloc
 435 types with addends were invented to solve just this problem.
 436 The @var{error_message} argument is set to an error message if
 437 this return @code{bfd_reloc_dangerous}.
 438
 439 @findex bfd_install_relocation
 440 @subsubsection @code{bfd_install_relocation}
 441 @strong{Synopsis}
 442 @example
 443 bfd_reloc_status_type
 444 bfd_install_relocation
 445    (bfd *abfd,
 446     arelent *reloc_entry,
 447     PTR data, bfd_vma data_start,
 448     asection *input_section,
 449     char **error_message);
 450 @end example
 451 @strong{Description}@*
 452 This looks remarkably like @code{bfd_perform_relocation}, except it
 453 does not expect that the section contents have been filled in.
 454 I.e., it's suitable for use when creating, rather than applying
 455 a relocation.
 456
 457 For now, this function should be considered reserved for the
 458 assembler.
 459
 460
 461 @node howto manager,  , typedef arelent, Relocations
 462 @section The howto manager
 463 When an application wants to create a relocation, but doesn't
 464 know what the target machine might call it, it can find out by
 465 using this bit of code.
 466
 467 @findex bfd_reloc_code_type
 468 @subsubsection @code{bfd_reloc_code_type}
 469 @strong{Description}@*
 470 The insides of a reloc code.  The idea is that, eventually, there
 471 will be one enumerator for every type of relocation we ever do.
 472 Pass one of these values to @code{bfd_reloc_type_lookup}, and it'll
 473 return a howto pointer.
 474
 475 This does mean that the application must determine the correct
 476 enumerator value; you can't get a howto pointer from a random set
 477 of attributes.
 478
 479 Here are the possible values for @code{enum bfd_reloc_code_real}:
 480
 481 @deffn {} BFD_RELOC_64
 482 @deffnx {} BFD_RELOC_32
 483 @deffnx {} BFD_RELOC_26
 484 @deffnx {} BFD_RELOC_24
 485 @deffnx {} BFD_RELOC_16
 486 @deffnx {} BFD_RELOC_14
 487 @deffnx {} BFD_RELOC_8
 488 Basic absolute relocations of N bits.
 489 @end deffn
 490 @deffn {} BFD_RELOC_64_PCREL
 491 @deffnx {} BFD_RELOC_32_PCREL
 492 @deffnx {} BFD_RELOC_24_PCREL
 493 @deffnx {} BFD_RELOC_16_PCREL
 494 @deffnx {} BFD_RELOC_12_PCREL
 495 @deffnx {} BFD_RELOC_8_PCREL
 496 PC-relative relocations.  Sometimes these are relative to the address
 497 of the relocation itself; sometimes they are relative to the start of
 498 the section containing the relocation.  It depends on the specific target.
 499
 500 The 24-bit relocation is used in some Intel 960 configurations.
 501 @end deffn
 502 @deffn {} BFD_RELOC_32_GOT_PCREL
 503 @deffnx {} BFD_RELOC_16_GOT_PCREL
 504 @deffnx {} BFD_RELOC_8_GOT_PCREL
 505 @deffnx {} BFD_RELOC_32_GOTOFF
 506 @deffnx {} BFD_RELOC_16_GOTOFF
 507 @deffnx {} BFD_RELOC_LO16_GOTOFF
 508 @deffnx {} BFD_RELOC_HI16_GOTOFF
 509 @deffnx {} BFD_RELOC_HI16_S_GOTOFF
 510 @deffnx {} BFD_RELOC_8_GOTOFF
 511 @deffnx {} BFD_RELOC_32_PLT_PCREL
 512 @deffnx {} BFD_RELOC_24_PLT_PCREL
 513 @deffnx {} BFD_RELOC_16_PLT_PCREL
 514 @deffnx {} BFD_RELOC_8_PLT_PCREL
 515 @deffnx {} BFD_RELOC_32_PLTOFF
 516 @deffnx {} BFD_RELOC_16_PLTOFF
 517 @deffnx {} BFD_RELOC_LO16_PLTOFF
 518 @deffnx {} BFD_RELOC_HI16_PLTOFF
 519 @deffnx {} BFD_RELOC_HI16_S_PLTOFF
 520 @deffnx {} BFD_RELOC_8_PLTOFF
 521 For ELF.
 522 @end deffn
 523 @deffn {} BFD_RELOC_68K_GLOB_DAT
 524 @deffnx {} BFD_RELOC_68K_JMP_SLOT
 525 @deffnx {} BFD_RELOC_68K_RELATIVE
 526 Relocations used by 68K ELF.
 527 @end deffn
 528 @deffn {} BFD_RELOC_32_BASEREL
 529 @deffnx {} BFD_RELOC_16_BASEREL
 530 @deffnx {} BFD_RELOC_LO16_BASEREL
 531 @deffnx {} BFD_RELOC_HI16_BASEREL
 532 @deffnx {} BFD_RELOC_HI16_S_BASEREL
 533 @deffnx {} BFD_RELOC_8_BASEREL
 534 @deffnx {} BFD_RELOC_RVA
 535 Linkage-table relative.
 536 @end deffn
 537 @deffn {} BFD_RELOC_8_FFnn
 538 Absolute 8-bit relocation, but used to form an address like 0xFFnn.
 539 @end deffn
 540 @deffn {} BFD_RELOC_32_PCREL_S2
 541 @deffnx {} BFD_RELOC_16_PCREL_S2
 542 @deffnx {} BFD_RELOC_23_PCREL_S2
 543 These PC-relative relocations are stored as word displacements --
 544 i.e., byte displacements shifted right two bits.  The 30-bit word
 545 displacement (<<32_PCREL_S2>> -- 32 bits, shifted 2) is used on the
 546 SPARC.  (SPARC tools generally refer to this as <<WDISP30>>.)  The
 547 signed 16-bit displacement is used on the MIPS, and the 23-bit
 548 displacement is used on the Alpha.
 549 @end deffn
 550 @deffn {} BFD_RELOC_HI22
 551 @deffnx {} BFD_RELOC_LO10
 552 High 22 bits and low 10 bits of 32-bit value, placed into lower bits of
 553 the target word.  These are used on the SPARC.
 554 @end deffn
 555 @deffn {} BFD_RELOC_GPREL16
 556 @deffnx {} BFD_RELOC_GPREL32
 557 For systems that allocate a Global Pointer register, these are
 558 displacements off that register.  These relocation types are
 559 handled specially, because the value the register will have is
 560 decided relatively late.
 561 @end deffn
 562 @deffn {} BFD_RELOC_I960_CALLJ
 563 Reloc types used for i960/b.out.
 564 @end deffn
 565 @deffn {} BFD_RELOC_NONE
 566 @deffnx {} BFD_RELOC_SPARC_WDISP22
 567 @deffnx {} BFD_RELOC_SPARC22
 568 @deffnx {} BFD_RELOC_SPARC13
 569 @deffnx {} BFD_RELOC_SPARC_GOT10
 570 @deffnx {} BFD_RELOC_SPARC_GOT13
 571 @deffnx {} BFD_RELOC_SPARC_GOT22
 572 @deffnx {} BFD_RELOC_SPARC_PC10
 573 @deffnx {} BFD_RELOC_SPARC_PC22
 574 @deffnx {} BFD_RELOC_SPARC_WPLT30
 575 @deffnx {} BFD_RELOC_SPARC_COPY
 576 @deffnx {} BFD_RELOC_SPARC_GLOB_DAT
 577 @deffnx {} BFD_RELOC_SPARC_JMP_SLOT
 578 @deffnx {} BFD_RELOC_SPARC_RELATIVE
 579 @deffnx {} BFD_RELOC_SPARC_UA32
 580 SPARC ELF relocations.  There is probably some overlap with other
 581 relocation types already defined.
 582 @end deffn
 583 @deffn {} BFD_RELOC_SPARC_BASE13
 584 @deffnx {} BFD_RELOC_SPARC_BASE22
 585 I think these are specific to SPARC a.out (e.g., Sun 4).
 586 @end deffn
 587 @deffn {} BFD_RELOC_SPARC_64
 588 @deffnx {} BFD_RELOC_SPARC_10
 589 @deffnx {} BFD_RELOC_SPARC_11
 590 @deffnx {} BFD_RELOC_SPARC_OLO10
 591 @deffnx {} BFD_RELOC_SPARC_HH22
 592 @deffnx {} BFD_RELOC_SPARC_HM10
 593 @deffnx {} BFD_RELOC_SPARC_LM22
 594 @deffnx {} BFD_RELOC_SPARC_PC_HH22
 595 @deffnx {} BFD_RELOC_SPARC_PC_HM10
 596 @deffnx {} BFD_RELOC_SPARC_PC_LM22
 597 @deffnx {} BFD_RELOC_SPARC_WDISP16
 598 @deffnx {} BFD_RELOC_SPARC_WDISP19
 599 @deffnx {} BFD_RELOC_SPARC_7
 600 @deffnx {} BFD_RELOC_SPARC_6
 601 @deffnx {} BFD_RELOC_SPARC_5
 602 @deffnx {} BFD_RELOC_SPARC_DISP64
 603 @deffnx {} BFD_RELOC_SPARC_PLT64
 604 @deffnx {} BFD_RELOC_SPARC_HIX22
 605 @deffnx {} BFD_RELOC_SPARC_LOX10
 606 @deffnx {} BFD_RELOC_SPARC_H44
 607 @deffnx {} BFD_RELOC_SPARC_M44
 608 @deffnx {} BFD_RELOC_SPARC_L44
 609 @deffnx {} BFD_RELOC_SPARC_REGISTER
 610 SPARC64 relocations
 611 @end deffn
 612 @deffn {} BFD_RELOC_ALPHA_GPDISP_HI16
 613 Alpha ECOFF and ELF relocations.  Some of these treat the symbol or
 614 "addend" in some special way.
 615 For GPDISP_HI16 ("gpdisp") relocations, the symbol is ignored when
 616 writing; when reading, it will be the absolute section symbol.  The
 617 addend is the displacement in bytes of the "lda" instruction from
 618 the "ldah" instruction (which is at the address of this reloc).
 619 @end deffn
 620 @deffn {} BFD_RELOC_ALPHA_GPDISP_LO16
 621 For GPDISP_LO16 ("ignore") relocations, the symbol is handled as
 622 with GPDISP_HI16 relocs.  The addend is ignored when writing the
 623 relocations out, and is filled in with the file's GP value on
 624 reading, for convenience.
 625 @end deffn
 626 @deffn {} BFD_RELOC_ALPHA_GPDISP
 627 The ELF GPDISP relocation is exactly the same as the GPDISP_HI16
 628 relocation except that there is no accompanying GPDISP_LO16
 629 relocation.
 630 @end deffn
 631 @deffn {} BFD_RELOC_ALPHA_LITERAL
 632 @deffnx {} BFD_RELOC_ALPHA_ELF_LITERAL
 633 @deffnx {} BFD_RELOC_ALPHA_LITUSE
 634 The Alpha LITERAL/LITUSE relocs are produced by a symbol reference;
 635 the assembler turns it into a LDQ instruction to load the address of
 636 the symbol, and then fills in a register in the real instruction.
 637
 638 The LITERAL reloc, at the LDQ instruction, refers to the .lita
 639 section symbol.  The addend is ignored when writing, but is filled
 640 in with the file's GP value on reading, for convenience, as with the
 641 GPDISP_LO16 reloc.
 642
 643 The ELF_LITERAL reloc is somewhere between 16_GOTOFF and GPDISP_LO16.
 644 It should refer to the symbol to be referenced, as with 16_GOTOFF,
 645 but it generates output not based on the position within the .got
 646 section, but relative to the GP value chosen for the file during the
 647 final link stage.
 648
 649 The LITUSE reloc, on the instruction using the loaded address, gives
 650 information to the linker that it might be able to use to optimize
 651 away some literal section references.  The symbol is ignored (read
 652 as the absolute section symbol), and the "addend" indicates the type
 653 of instruction using the register:
 654 1 - "memory" fmt insn
 655 2 - byte-manipulation (byte offset reg)
 656 3 - jsr (target of branch)
 657
 658 The GNU linker currently doesn't do any of this optimizing.
 659 @end deffn
 660 @deffn {} BFD_RELOC_ALPHA_HINT
 661 The HINT relocation indicates a value that should be filled into the
 662 "hint" field of a jmp/jsr/ret instruction, for possible branch-
 663 prediction logic which may be provided on some processors.
 664 @end deffn
 665 @deffn {} BFD_RELOC_ALPHA_LINKAGE
 666 The LINKAGE relocation outputs a linkage pair in the object file,
 667 which is filled by the linker.
 668 @end deffn
 669 @deffn {} BFD_RELOC_ALPHA_CODEADDR
 670 The CODEADDR relocation outputs a STO_CA in the object file,
 671 which is filled by the linker.
 672 @end deffn
 673 @deffn {} BFD_RELOC_MIPS_JMP
 674 Bits 27..2 of the relocation address shifted right 2 bits;
 675 simple reloc otherwise.
 676 @end deffn
 677 @deffn {} BFD_RELOC_MIPS16_JMP
 678 The MIPS16 jump instruction.
 679 @end deffn
 680 @deffn {} BFD_RELOC_MIPS16_GPREL
 681 MIPS16 GP relative reloc.
 682 @end deffn
 683 @deffn {} BFD_RELOC_HI16
 684 High 16 bits of 32-bit value; simple reloc.
 685 @end deffn
 686 @deffn {} BFD_RELOC_HI16_S
 687 High 16 bits of 32-bit value but the low 16 bits will be sign
 688 extended and added to form the final result.  If the low 16
 689 bits form a negative number, we need to add one to the high value
 690 to compensate for the borrow when the low bits are added.
 691 @end deffn
 692 @deffn {} BFD_RELOC_LO16
 693 Low 16 bits.
 694 @end deffn
 695 @deffn {} BFD_RELOC_PCREL_HI16_S
 696 Like BFD_RELOC_HI16_S, but PC relative.
 697 @end deffn
 698 @deffn {} BFD_RELOC_PCREL_LO16
 699 Like BFD_RELOC_LO16, but PC relative.
 700 @end deffn
 701 @deffn {} BFD_RELOC_MIPS_GPREL
 702 Relocation relative to the global pointer.
 703 @end deffn
 704 @deffn {} BFD_RELOC_MIPS_LITERAL
 705 Relocation against a MIPS literal section.
 706 @end deffn
 707 @deffn {} BFD_RELOC_MIPS_GOT16
 708 @deffnx {} BFD_RELOC_MIPS_CALL16
 709 @deffnx {} BFD_RELOC_MIPS_GPREL32
 710 @deffnx {} BFD_RELOC_MIPS_GOT_HI16
 711 @deffnx {} BFD_RELOC_MIPS_GOT_LO16
 712 @deffnx {} BFD_RELOC_MIPS_CALL_HI16
 713 @deffnx {} BFD_RELOC_MIPS_CALL_LO16
 714 MIPS ELF relocations.
 715 @end deffn
 716 @deffn {} BFD_RELOC_386_GOT32
 717 @deffnx {} BFD_RELOC_386_PLT32
 718 @deffnx {} BFD_RELOC_386_COPY
 719 @deffnx {} BFD_RELOC_386_GLOB_DAT
 720 @deffnx {} BFD_RELOC_386_JUMP_SLOT
 721 @deffnx {} BFD_RELOC_386_RELATIVE
 722 @deffnx {} BFD_RELOC_386_GOTOFF
 723 @deffnx {} BFD_RELOC_386_GOTPC
 724 i386/elf relocations
 725 @end deffn
 726 @deffn {} BFD_RELOC_NS32K_IMM_8
 727 @deffnx {} BFD_RELOC_NS32K_IMM_16
 728 @deffnx {} BFD_RELOC_NS32K_IMM_32
 729 @deffnx {} BFD_RELOC_NS32K_IMM_8_PCREL
 730 @deffnx {} BFD_RELOC_NS32K_IMM_16_PCREL
 731 @deffnx {} BFD_RELOC_NS32K_IMM_32_PCREL
 732 @deffnx {} BFD_RELOC_NS32K_DISP_8
 733 @deffnx {} BFD_RELOC_NS32K_DISP_16
 734 @deffnx {} BFD_RELOC_NS32K_DISP_32
 735 @deffnx {} BFD_RELOC_NS32K_DISP_8_PCREL
 736 @deffnx {} BFD_RELOC_NS32K_DISP_16_PCREL
 737 @deffnx {} BFD_RELOC_NS32K_DISP_32_PCREL
 738 ns32k relocations
 739 @end deffn
 740 @deffn {} BFD_RELOC_PPC_B26
 741 @deffnx {} BFD_RELOC_PPC_BA26
 742 @deffnx {} BFD_RELOC_PPC_TOC16
 743 @deffnx {} BFD_RELOC_PPC_B16
 744 @deffnx {} BFD_RELOC_PPC_B16_BRTAKEN
 745 @deffnx {} BFD_RELOC_PPC_B16_BRNTAKEN
 746 @deffnx {} BFD_RELOC_PPC_BA16
 747 @deffnx {} BFD_RELOC_PPC_BA16_BRTAKEN
 748 @deffnx {} BFD_RELOC_PPC_BA16_BRNTAKEN
 749 @deffnx {} BFD_RELOC_PPC_COPY
 750 @deffnx {} BFD_RELOC_PPC_GLOB_DAT
 751 @deffnx {} BFD_RELOC_PPC_JMP_SLOT
 752 @deffnx {} BFD_RELOC_PPC_RELATIVE
 753 @deffnx {} BFD_RELOC_PPC_LOCAL24PC
 754 @deffnx {} BFD_RELOC_PPC_EMB_NADDR32
 755 @deffnx {} BFD_RELOC_PPC_EMB_NADDR16
 756 @deffnx {} BFD_RELOC_PPC_EMB_NADDR16_LO
 757 @deffnx {} BFD_RELOC_PPC_EMB_NADDR16_HI
 758 @deffnx {} BFD_RELOC_PPC_EMB_NADDR16_HA
 759 @deffnx {} BFD_RELOC_PPC_EMB_SDAI16
 760 @deffnx {} BFD_RELOC_PPC_EMB_SDA2I16
 761 @deffnx {} BFD_RELOC_PPC_EMB_SDA2REL
 762 @deffnx {} BFD_RELOC_PPC_EMB_SDA21
 763 @deffnx {} BFD_RELOC_PPC_EMB_MRKREF
 764 @deffnx {} BFD_RELOC_PPC_EMB_RELSEC16
 765 @deffnx {} BFD_RELOC_PPC_EMB_RELST_LO
 766 @deffnx {} BFD_RELOC_PPC_EMB_RELST_HI
 767 @deffnx {} BFD_RELOC_PPC_EMB_RELST_HA
 768 @deffnx {} BFD_RELOC_PPC_EMB_BIT_FLD
 769 @deffnx {} BFD_RELOC_PPC_EMB_RELSDA
 770 Power(rs6000) and PowerPC relocations.
 771 @end deffn
 772 @deffn {} BFD_RELOC_CTOR
 773 The type of reloc used to build a contructor table - at the moment
 774 probably a 32 bit wide absolute relocation, but the target can choose.
 775 It generally does map to one of the other relocation types.
 776 @end deffn
 777 @deffn {} BFD_RELOC_ARM_PCREL_BRANCH
 778 ARM 26 bit pc-relative branch.  The lowest two bits must be zero and are
 779 not stored in the instruction.
 780 @end deffn
 781 @deffn {} BFD_RELOC_ARM_IMMEDIATE
 782 @deffnx {} BFD_RELOC_ARM_OFFSET_IMM
 783 @deffnx {} BFD_RELOC_ARM_SHIFT_IMM
 784 @deffnx {} BFD_RELOC_ARM_SWI
 785 @deffnx {} BFD_RELOC_ARM_MULTI
 786 @deffnx {} BFD_RELOC_ARM_CP_OFF_IMM
 787 @deffnx {} BFD_RELOC_ARM_ADR_IMM
 788 @deffnx {} BFD_RELOC_ARM_LDR_IMM
 789 @deffnx {} BFD_RELOC_ARM_LITERAL
 790 @deffnx {} BFD_RELOC_ARM_IN_POOL
 791 @deffnx {} BFD_RELOC_ARM_OFFSET_IMM8
 792 @deffnx {} BFD_RELOC_ARM_HWLITERAL
 793 @deffnx {} BFD_RELOC_ARM_THUMB_ADD
 794 @deffnx {} BFD_RELOC_ARM_THUMB_IMM
 795 @deffnx {} BFD_RELOC_ARM_THUMB_SHIFT
 796 @deffnx {} BFD_RELOC_ARM_THUMB_OFFSET
 797 These relocs are only used within the ARM assembler.  They are not
 798 (at present) written to any object files.
 799 @end deffn
 800 @deffn {} BFD_RELOC_SH_PCDISP8BY2
 801 @deffnx {} BFD_RELOC_SH_PCDISP12BY2
 802 @deffnx {} BFD_RELOC_SH_IMM4
 803 @deffnx {} BFD_RELOC_SH_IMM4BY2
 804 @deffnx {} BFD_RELOC_SH_IMM4BY4
 805 @deffnx {} BFD_RELOC_SH_IMM8
 806 @deffnx {} BFD_RELOC_SH_IMM8BY2
 807 @deffnx {} BFD_RELOC_SH_IMM8BY4
 808 @deffnx {} BFD_RELOC_SH_PCRELIMM8BY2
 809 @deffnx {} BFD_RELOC_SH_PCRELIMM8BY4
 810 @deffnx {} BFD_RELOC_SH_SWITCH16
 811 @deffnx {} BFD_RELOC_SH_SWITCH32
 812 @deffnx {} BFD_RELOC_SH_USES
 813 @deffnx {} BFD_RELOC_SH_COUNT
 814 @deffnx {} BFD_RELOC_SH_ALIGN
 815 @deffnx {} BFD_RELOC_SH_CODE
 816 @deffnx {} BFD_RELOC_SH_DATA
 817 @deffnx {} BFD_RELOC_SH_LABEL
 818 Hitachi SH relocs.  Not all of these appear in object files.
 819 @end deffn
 820 @deffn {} BFD_RELOC_THUMB_PCREL_BRANCH9
 821 @deffnx {} BFD_RELOC_THUMB_PCREL_BRANCH12
 822 @deffnx {} BFD_RELOC_THUMB_PCREL_BRANCH23
 823 Thumb 23-, 12- and 9-bit pc-relative branches.  The lowest bit must
 824 be zero and is not stored in the instruction.
 825 @end deffn
 826 @deffn {} BFD_RELOC_ARC_B22_PCREL
 827 Argonaut RISC Core (ARC) relocs.
 828 ARC 22 bit pc-relative branch.  The lowest two bits must be zero and are
 829 not stored in the instruction.  The high 20 bits are installed in bits 26
 830 through 7 of the instruction.
 831 @end deffn
 832 @deffn {} BFD_RELOC_ARC_B26
 833 ARC 26 bit absolute branch.  The lowest two bits must be zero and are not
 834 stored in the instruction.  The high 24 bits are installed in bits 23
 835 through 0.
 836 @end deffn
 837 @deffn {} BFD_RELOC_D10V_10_PCREL_R
 838 Mitsubishi D10V relocs.
 839 This is a 10-bit reloc with the right 2 bits
 840 assumed to be 0.
 841 @end deffn
 842 @deffn {} BFD_RELOC_D10V_10_PCREL_L
 843 Mitsubishi D10V relocs.
 844 This is a 10-bit reloc with the right 2 bits
 845 assumed to be 0.  This is the same as the previous reloc
 846 except it is in the left container, i.e.,
 847 shifted left 15 bits.
 848 @end deffn
 849 @deffn {} BFD_RELOC_D10V_18
 850 This is an 18-bit reloc with the right 2 bits
 851 assumed to be 0.
 852 @end deffn
 853 @deffn {} BFD_RELOC_D10V_18_PCREL
 854 This is an 18-bit reloc with the right 2 bits
 855 assumed to be 0.
 856 @end deffn
 857 @deffn {} BFD_RELOC_M32R_24
 858 Mitsubishi M32R relocs.
 859 This is a 24 bit absolute address.
 860 @end deffn
 861 @deffn {} BFD_RELOC_M32R_10_PCREL
 862 This is a 10-bit pc-relative reloc with the right 2 bits assumed to be 0.
 863 @end deffn
 864 @deffn {} BFD_RELOC_M32R_18_PCREL
 865 This is an 18-bit reloc with the right 2 bits assumed to be 0.
 866 @end deffn
 867 @deffn {} BFD_RELOC_M32R_26_PCREL
 868 This is a 26-bit reloc with the right 2 bits assumed to be 0.
 869 @end deffn
 870 @deffn {} BFD_RELOC_M32R_HI16_ULO
 871 This is a 16-bit reloc containing the high 16 bits of an address
 872 used when the lower 16 bits are treated as unsigned.
 873 @end deffn
 874 @deffn {} BFD_RELOC_M32R_HI16_SLO
 875 This is a 16-bit reloc containing the high 16 bits of an address
 876 used when the lower 16 bits are treated as signed.
 877 @end deffn
 878 @deffn {} BFD_RELOC_M32R_LO16
 879 This is a 16-bit reloc containing the lower 16 bits of an address.
 880 @end deffn
 881 @deffn {} BFD_RELOC_M32R_SDA16
 882 This is a 16-bit reloc containing the small data area offset for use in
 883 add3, load, and store instructions.
 884 @end deffn
 885 @deffn {} BFD_RELOC_V850_9_PCREL
 886 This is a 9-bit reloc
 887 @end deffn
 888 @deffn {} BFD_RELOC_V850_22_PCREL
 889 This is a 22-bit reloc
 890 @end deffn
 891 @deffn {} BFD_RELOC_V850_SDA_16_16_OFFSET
 892 This is a 16 bit offset from the short data area pointer.
 893 @end deffn
 894 @deffn {} BFD_RELOC_V850_SDA_15_16_OFFSET
 895 This is a 16 bit offset (of which only 15 bits are used) from the
 896 short data area pointer.
 897 @end deffn
 898 @deffn {} BFD_RELOC_V850_ZDA_16_16_OFFSET
 899 This is a 16 bit offset from the zero data area pointer.
 900 @end deffn
 901 @deffn {} BFD_RELOC_V850_ZDA_15_16_OFFSET
 902 This is a 16 bit offset (of which only 15 bits are used) from the
 903 zero data area pointer.
 904 @end deffn
 905 @deffn {} BFD_RELOC_V850_TDA_6_8_OFFSET
 906 This is an 8 bit offset (of which only 6 bits are used) from the
 907 tiny data area pointer.
 908 @end deffn
 909 @deffn {} BFD_RELOC_V850_TDA_7_8_OFFSET
 910 This is an 8bit offset (of which only 7 bits are used) from the tiny
 911 data area pointer.
 912 @end deffn
 913 @deffn {} BFD_RELOC_V850_TDA_7_7_OFFSET
 914 This is a 7 bit offset from the tiny data area pointer.
 915 @end deffn
 916 @deffn {} BFD_RELOC_V850_TDA_16_16_OFFSET
 917 This is a 16 bit offset from the tiny data area pointer.
 918 @end deffn
 919 @deffn {} BFD_RELOC_MN10300_32_PCREL
 920 This is a 32bit pcrel reloc for the mn10300, offset by two bytes in the
 921 instruction.
 922 @end deffn
 923 @deffn {} BFD_RELOC_MN10300_16_PCREL
 924 This is a 16bit pcrel reloc for the mn10300, offset by two bytes in the
 925 instruction.
 926 @end deffn
 927 @deffn {} BFD_RELOC_TIC30_LDP
 928 This is a 8bit DP reloc for the tms320c30, where the most
 929 significant 8 bits of a 24 bit word are placed into the least
 930 significant 8 bits of the opcode.
 931 @end deffn
 932
 933 @example
 934
 935 typedef enum bfd_reloc_code_real bfd_reloc_code_real_type;
 936 @end example
 937 @findex bfd_reloc_type_lookup
 938 @subsubsection @code{bfd_reloc_type_lookup}
 939 @strong{Synopsis}
 940 @example
 941 reloc_howto_type *
 942 bfd_reloc_type_lookup (bfd *abfd, bfd_reloc_code_real_type code);
 943 @end example
 944 @strong{Description}@*
 945 Return a pointer to a howto structure which, when
 946 invoked, will perform the relocation @var{code} on data from the
 947 architecture noted.
 948
 949 @findex bfd_default_reloc_type_lookup
 950 @subsubsection @code{bfd_default_reloc_type_lookup}
 951 @strong{Synopsis}
 952 @example
 953 reloc_howto_type *bfd_default_reloc_type_lookup
 954    (bfd *abfd, bfd_reloc_code_real_type  code);
 955 @end example
 956 @strong{Description}@*
 957 Provides a default relocation lookup routine for any architecture.
 958
 959 @findex bfd_get_reloc_code_name
 960 @subsubsection @code{bfd_get_reloc_code_name}
 961 @strong{Synopsis}
 962 @example
 963 const char *bfd_get_reloc_code_name (bfd_reloc_code_real_type code);
 964 @end example
 965 @strong{Description}@*
 966 Provides a printable name for the supplied relocation code.
 967 Useful mainly for printing error messages.
 968
 969 @findex bfd_generic_relax_section
 970 @subsubsection @code{bfd_generic_relax_section}
 971 @strong{Synopsis}
 972 @example
 973 boolean bfd_generic_relax_section
 974    (bfd *abfd,
 975     asection *section,
 976     struct bfd_link_info *,
 977     boolean *);
 978 @end example
 979 @strong{Description}@*
 980 Provides default handling for relaxing for back ends which
 981 don't do relaxing -- i.e., does nothing.
 982
 983 @findex bfd_generic_get_relocated_section_contents
 984 @subsubsection @code{bfd_generic_get_relocated_section_contents}
 985 @strong{Synopsis}
 986 @example
 987 bfd_byte *
 988 bfd_generic_get_relocated_section_contents (bfd *abfd,
 989     struct bfd_link_info *link_info,
 990     struct bfd_link_order *link_order,
 991     bfd_byte *data,
 992     boolean relocateable,
 993     asymbol **symbols);
 994 @end example
 995 @strong{Description}@*
 996 Provides default handling of relocation effort for back ends
 997 which can't be bothered to do it efficiently.
 998