Initial import of GNU binutils version 2.8.1. Believe it or not,

this is heavily stripped down.

1 files changed, 914 insertions, 0 deletions

diff --git a/contrib/binutils/bfd/doc/reloc.texi b/contrib/binutils/bfd/doc/reloc.texi
new file mode 100644
index 0000000..63c079e
--- /dev/null
+++ b/contrib/binutils/bfd/doc/reloc.texi
@@ -0,0 +1,914 @@
+@section Relocations
+BFD maintains relocations in much the same way it maintains
+symbols: they are left alone until required, then read in
+en-mass and translated into an internal form.  A common
+routine @code{bfd_perform_relocation} acts upon the
+canonical form to do the fixup.
+
+Relocations are maintained on a per section basis,
+while symbols are maintained on a per BFD basis.
+
+All that a back end has to do to fit the BFD interface is to create
+a @code{struct reloc_cache_entry} for each relocation
+in a particular section, and fill in the right bits of the structures.
+
+@menu
+* typedef arelent::
+* howto manager::
+@end menu
+@*
+
+@node typedef arelent, howto manager, Relocations, Relocations
+@subsection typedef arelent
+This is the structure of a relocation entry:
+@*
+.
+@example
+typedef enum bfd_reloc_status
+@{
+       /* No errors detected */
+  bfd_reloc_ok,
+
+       /* The relocation was performed, but there was an overflow. */
+  bfd_reloc_overflow,
+
+       /* The address to relocate was not within the section supplied. */
+  bfd_reloc_outofrange,
+
+       /* Used by special functions */
+  bfd_reloc_continue,
+
+       /* Unsupported relocation size requested. */
+  bfd_reloc_notsupported,
+
+       /* Unused */
+  bfd_reloc_other,
+
+       /* The symbol to relocate against was undefined. */
+  bfd_reloc_undefined,
+
+       /* The relocation was performed, but may not be ok - presently
+          generated only when linking i960 coff files with i960 b.out
+          symbols.  If this type is returned, the error_message argument
+          to bfd_perform_relocation will be set.  */
+  bfd_reloc_dangerous
+ @}
+ bfd_reloc_status_type;
+
+
+typedef struct reloc_cache_entry
+@{
+       /* A pointer into the canonical table of pointers  */
+  struct symbol_cache_entry **sym_ptr_ptr;
+
+       /* offset in section */
+  bfd_size_type address;
+
+       /* addend for relocation value */
+  bfd_vma addend;
+
+       /* Pointer to how to perform the required relocation */
+  reloc_howto_type *howto;
+
+@} arelent;
+@end example
+@strong{Description}@*
+Here is a description of each of the fields within an @code{arelent}:
+
+@itemize @bullet
+
+@item
+@code{sym_ptr_ptr}
+@end itemize
+The symbol table pointer points to a pointer to the symbol
+associated with the relocation request.  It is
+the pointer into the table returned by the back end's
+@code{get_symtab} action. @xref{Symbols}. The symbol is referenced
+through a pointer to a pointer so that tools like the linker
+can fix up all the symbols of the same name by modifying only
+one pointer. The relocation routine looks in the symbol and
+uses the base of the section the symbol is attached to and the
+value of the symbol as the initial relocation offset. If the
+symbol pointer is zero, then the section provided is looked up.
+
+@itemize @bullet
+
+@item
+@code{address}
+@end itemize
+The @code{address} field gives the offset in bytes from the base of
+the section data which owns the relocation record to the first
+byte of relocatable information. The actual data relocated
+will be relative to this point; for example, a relocation
+type which modifies the bottom two bytes of a four byte word
+would not touch the first byte pointed to in a big endian
+world.
+
+@itemize @bullet
+
+@item
+@code{addend}
+@end itemize
+The @code{addend} is a value provided by the back end to be added (!)
+to the relocation offset. Its interpretation is dependent upon
+the howto. For example, on the 68k the code:
+
+@example
+        char foo[];
+        main()
+                @{
+                return foo[0x12345678];
+                @}
+@end example
+
+Could be compiled into:
+
+@example
+        linkw fp,#-4
+        moveb @@#12345678,d0
+        extbl d0
+        unlk fp
+        rts
+@end example
+
+This could create a reloc pointing to @code{foo}, but leave the
+offset in the data, something like:
+
+@example
+RELOCATION RECORDS FOR [.text]:
+offset   type      value
+00000006 32        _foo
+
+00000000 4e56 fffc          ; linkw fp,#-4
+00000004 1039 1234 5678     ; moveb @@#12345678,d0
+0000000a 49c0               ; extbl d0
+0000000c 4e5e               ; unlk fp
+0000000e 4e75               ; rts
+@end example
+
+Using coff and an 88k, some instructions don't have enough
+space in them to represent the full address range, and
+pointers have to be loaded in two parts. So you'd get something like:
+
+@example
+        or.u     r13,r0,hi16(_foo+0x12345678)
+        ld.b     r2,r13,lo16(_foo+0x12345678)
+        jmp      r1
+@end example
+
+This should create two relocs, both pointing to @code{_foo}, and with
+0x12340000 in their addend field. The data would consist of:
+
+@example
+RELOCATION RECORDS FOR [.text]:
+offset   type      value
+00000002 HVRT16    _foo+0x12340000
+00000006 LVRT16    _foo+0x12340000
+
+00000000 5da05678           ; or.u r13,r0,0x5678
+00000004 1c4d5678           ; ld.b r2,r13,0x5678
+00000008 f400c001           ; jmp r1
+@end example
+
+The relocation routine digs out the value from the data, adds
+it to the addend to get the original offset, and then adds the
+value of @code{_foo}. Note that all 32 bits have to be kept around
+somewhere, to cope with carry from bit 15 to bit 16.
+
+One further example is the sparc and the a.out format. The
+sparc has a similar problem to the 88k, in that some
+instructions don't have room for an entire offset, but on the
+sparc the parts are created in odd sized lumps. The designers of
+the a.out format chose to not use the data within the section
+for storing part of the offset; all the offset is kept within
+the reloc. Anything in the data should be ignored.
+
+@example
+        save %sp,-112,%sp
+        sethi %hi(_foo+0x12345678),%g2
+        ldsb [%g2+%lo(_foo+0x12345678)],%i0
+        ret
+        restore
+@end example
+
+Both relocs contain a pointer to @code{foo}, and the offsets
+contain junk.
+
+@example
+RELOCATION RECORDS FOR [.text]:
+offset   type      value
+00000004 HI22      _foo+0x12345678
+00000008 LO10      _foo+0x12345678
+
+00000000 9de3bf90     ; save %sp,-112,%sp
+00000004 05000000     ; sethi %hi(_foo+0),%g2
+00000008 f048a000     ; ldsb [%g2+%lo(_foo+0)],%i0
+0000000c 81c7e008     ; ret
+00000010 81e80000     ; restore
+@end example
+
+@itemize @bullet
+
+@item
+@code{howto}
+@end itemize
+The @code{howto} field can be imagined as a
+relocation instruction. It is a pointer to a structure which
+contains information on what to do with all of the other
+information in the reloc record and data section. A back end
+would normally have a relocation instruction set and turn
+relocations into pointers to the correct structure on input -
+but it would be possible to create each howto field on demand.
+@*
+@subsubsection @code{enum complain_overflow}
+Indicates what sort of overflow checking should be done when
+performing a relocation.
+@*
+.
+@example
+enum complain_overflow
+@{
+	/* Do not complain on overflow. */
+  complain_overflow_dont,
+
+	/* Complain if the bitfield overflows, whether it is considered
+	   as signed or unsigned. */
+  complain_overflow_bitfield,
+
+	/* Complain if the value overflows when considered as signed
+	   number. */
+  complain_overflow_signed,
+
+	/* Complain if the value overflows when considered as an
+	   unsigned number. */
+  complain_overflow_unsigned
+@};
+@end example
+@subsubsection @code{reloc_howto_type}
+The @code{reloc_howto_type} is a structure which contains all the
+information that libbfd needs to know to tie up a back end's data.
+@*
+.struct symbol_cache_entry;		/* Forward declaration */
+@example
+
+struct reloc_howto_struct
+@{
+       /*  The type field has mainly a documentary use - the back end can
+           do what it wants with it, though normally the back end's
+           external idea of what a reloc number is stored
+           in this field. For example, a PC relative word relocation
+           in a coff environment has the type 023 - because that's
+           what the outside world calls a R_PCRWORD reloc. */
+  unsigned int type;
+
+       /*  The value the final relocation is shifted right by. This drops
+           unwanted data from the relocation.  */
+  unsigned int rightshift;
+
+	/*  The size of the item to be relocated.  This is *not* a
+	    power-of-two measure.  To get the number of bytes operated
+	    on by a type of relocation, use bfd_get_reloc_size.  */
+  int size;
+
+       /*  The number of bits in the item to be relocated.  This is used
+	    when doing overflow checking.  */
+  unsigned int bitsize;
+
+       /*  Notes that the relocation is relative to the location in the
+           data section of the addend. The relocation function will
+           subtract from the relocation value the address of the location
+           being relocated. */
+  boolean pc_relative;
+
+	/*  The bit position of the reloc value in the destination.
+	    The relocated value is left shifted by this amount. */
+  unsigned int bitpos;
+
+	/* What type of overflow error should be checked for when
+	   relocating. */
+  enum complain_overflow complain_on_overflow;
+
+       /* If this field is non null, then the supplied function is
+          called rather than the normal function. This allows really
+          strange relocation methods to be accomodated (e.g., i960 callj
+          instructions). */
+  bfd_reloc_status_type (*special_function)
+				    PARAMS ((bfd *abfd,
+					     arelent *reloc_entry,
+                                            struct symbol_cache_entry *symbol,
+                                            PTR data,
+                                            asection *input_section,
+                                            bfd *output_bfd,
+                                            char **error_message));
+
+       /* The textual name of the relocation type. */
+  char *name;
+
+       /* When performing a partial link, some formats must modify the
+          relocations rather than the data - this flag signals this.*/
+  boolean partial_inplace;
+
+       /* The src_mask selects which parts of the read in data
+          are to be used in the relocation sum.  E.g., if this was an 8 bit
+          bit of data which we read and relocated, this would be
+          0x000000ff. When we have relocs which have an addend, such as
+          sun4 extended relocs, the value in the offset part of a
+          relocating field is garbage so we never use it. In this case
+          the mask would be 0x00000000. */
+  bfd_vma src_mask;
+
+       /* The dst_mask selects which parts of the instruction are replaced
+          into the instruction. In most cases src_mask == dst_mask,
+          except in the above special case, where dst_mask would be
+          0x000000ff, and src_mask would be 0x00000000.   */
+  bfd_vma dst_mask;
+
+       /* When some formats create PC relative instructions, they leave
+          the value of the pc of the place being relocated in the offset
+          slot of the instruction, so that a PC relative relocation can
+          be made just by adding in an ordinary offset (e.g., sun3 a.out).
+          Some formats leave the displacement part of an instruction
+          empty (e.g., m88k bcs); this flag signals the fact.*/
+  boolean pcrel_offset;
+
+@};
+@end example
+@findex The HOWTO Macro
+@subsubsection @code{The HOWTO Macro}
+@strong{Description}@*
+The HOWTO define is horrible and will go away.
+@example
+#define HOWTO(C, R,S,B, P, BI, O, SF, NAME, INPLACE, MASKSRC, MASKDST, PC) \
+  @{(unsigned)C,R,S,B, P, BI, O,SF,NAME,INPLACE,MASKSRC,MASKDST,PC@}
+@end example
+@*
+@strong{Description}@*
+And will be replaced with the totally magic way. But for the
+moment, we are compatible, so do it this way.
+@example
+#define NEWHOWTO( FUNCTION, NAME,SIZE,REL,IN) HOWTO(0,0,SIZE,0,REL,0,complain_overflow_dont,FUNCTION, NAME,false,0,0,IN)
+
+@end example
+@*
+@strong{Description}@*
+Helper routine to turn a symbol into a relocation value.
+@example
+#define HOWTO_PREPARE(relocation, symbol)      \
+  @{                                            \
+  if (symbol != (asymbol *)NULL) @{             \
+    if (bfd_is_com_section (symbol->section)) @{ \
+      relocation = 0;                          \
+    @}                                          \
+    else @{                                     \
+      relocation = symbol->value;              \
+    @}                                          \
+  @}                                            \
+@}
+@end example
+@*
+@findex bfd_get_reloc_size
+@subsubsection @code{bfd_get_reloc_size}
+@strong{Synopsis}
+@example
+int bfd_get_reloc_size (reloc_howto_type *);
+@end example
+@strong{Description}@*
+For a reloc_howto_type that operates on a fixed number of bytes,
+this returns the number of bytes operated on.
+@*
+@findex arelent_chain
+@subsubsection @code{arelent_chain}
+@strong{Description}@*
+How relocs are tied together in an @code{asection}:
+@example
+typedef struct relent_chain @{
+  arelent relent;
+  struct   relent_chain *next;
+@} arelent_chain;
+@end example
+@*
+@findex bfd_perform_relocation
+@subsubsection @code{bfd_perform_relocation}
+@strong{Synopsis}
+@example
+bfd_reloc_status_type
+bfd_perform_relocation
+   (bfd *abfd,
+    arelent *reloc_entry,
+    PTR data,
+    asection *input_section,
+    bfd *output_bfd,
+    char **error_message);
+@end example
+@strong{Description}@*
+If @var{output_bfd} is supplied to this function, the
+generated image will be relocatable; the relocations are
+copied to the output file after they have been changed to
+reflect the new state of the world. There are two ways of
+reflecting the results of partial linkage in an output file:
+by modifying the output data in place, and by modifying the
+relocation record.  Some native formats (e.g., basic a.out and
+basic coff) have no way of specifying an addend in the
+relocation type, so the addend has to go in the output data.
+This is no big deal since in these formats the output data
+slot will always be big enough for the addend. Complex reloc
+types with addends were invented to solve just this problem.
+The @var{error_message} argument is set to an error message if
+this return @code{bfd_reloc_dangerous}.
+@*
+@findex bfd_install_relocation
+@subsubsection @code{bfd_install_relocation}
+@strong{Synopsis}
+@example
+bfd_reloc_status_type
+bfd_install_relocation
+   (bfd *abfd,
+    arelent *reloc_entry,
+    PTR data, bfd_vma data_start,
+    asection *input_section,
+    char **error_message);
+@end example
+@strong{Description}@*
+This looks remarkably like @code{bfd_perform_relocation}, except it
+does not expect that the section contents have been filled in.
+I.e., it's suitable for use when creating, rather than applying
+a relocation.
+
+For now, this function should be considered reserved for the
+assembler.
+@*
+
+@node howto manager,  , typedef arelent, Relocations
+@section The howto manager
+When an application wants to create a relocation, but doesn't
+know what the target machine might call it, it can find out by
+using this bit of code.
+@*
+@findex bfd_reloc_code_type
+@subsubsection @code{bfd_reloc_code_type}
+@strong{Description}@*
+The insides of a reloc code.  The idea is that, eventually, there
+will be one enumerator for every type of relocation we ever do.
+Pass one of these values to @code{bfd_reloc_type_lookup}, and it'll
+return a howto pointer.
+
+This does mean that the application must determine the correct
+enumerator value; you can't get a howto pointer from a random set
+of attributes.
+@*
+Here are the possible values for @code{enum bfd_reloc_code_real}:
+
+@deffn {} BFD_RELOC_64
+@deffnx {} BFD_RELOC_32
+@deffnx {} BFD_RELOC_26
+@deffnx {} BFD_RELOC_24
+@deffnx {} BFD_RELOC_16
+@deffnx {} BFD_RELOC_14
+@deffnx {} BFD_RELOC_8
+Basic absolute relocations of N bits.
+@end deffn
+@deffn {} BFD_RELOC_64_PCREL
+@deffnx {} BFD_RELOC_32_PCREL
+@deffnx {} BFD_RELOC_24_PCREL
+@deffnx {} BFD_RELOC_16_PCREL
+@deffnx {} BFD_RELOC_12_PCREL
+@deffnx {} BFD_RELOC_8_PCREL
+PC-relative relocations.  Sometimes these are relative to the address
+of the relocation itself; sometimes they are relative to the start of
+the section containing the relocation.  It depends on the specific target.
+
+The 24-bit relocation is used in some Intel 960 configurations.
+@end deffn
+@deffn {} BFD_RELOC_32_GOT_PCREL
+@deffnx {} BFD_RELOC_16_GOT_PCREL
+@deffnx {} BFD_RELOC_8_GOT_PCREL
+@deffnx {} BFD_RELOC_32_GOTOFF
+@deffnx {} BFD_RELOC_16_GOTOFF
+@deffnx {} BFD_RELOC_LO16_GOTOFF
+@deffnx {} BFD_RELOC_HI16_GOTOFF
+@deffnx {} BFD_RELOC_HI16_S_GOTOFF
+@deffnx {} BFD_RELOC_8_GOTOFF
+@deffnx {} BFD_RELOC_32_PLT_PCREL
+@deffnx {} BFD_RELOC_24_PLT_PCREL
+@deffnx {} BFD_RELOC_16_PLT_PCREL
+@deffnx {} BFD_RELOC_8_PLT_PCREL
+@deffnx {} BFD_RELOC_32_PLTOFF
+@deffnx {} BFD_RELOC_16_PLTOFF
+@deffnx {} BFD_RELOC_LO16_PLTOFF
+@deffnx {} BFD_RELOC_HI16_PLTOFF
+@deffnx {} BFD_RELOC_HI16_S_PLTOFF
+@deffnx {} BFD_RELOC_8_PLTOFF
+For ELF.
+@end deffn
+@deffn {} BFD_RELOC_68K_GLOB_DAT
+@deffnx {} BFD_RELOC_68K_JMP_SLOT
+@deffnx {} BFD_RELOC_68K_RELATIVE
+Relocations used by 68K ELF.
+@end deffn
+@deffn {} BFD_RELOC_32_BASEREL
+@deffnx {} BFD_RELOC_16_BASEREL
+@deffnx {} BFD_RELOC_LO16_BASEREL
+@deffnx {} BFD_RELOC_HI16_BASEREL
+@deffnx {} BFD_RELOC_HI16_S_BASEREL
+@deffnx {} BFD_RELOC_8_BASEREL
+@deffnx {} BFD_RELOC_RVA
+Linkage-table relative.
+@end deffn
+@deffn {} BFD_RELOC_8_FFnn
+Absolute 8-bit relocation, but used to form an address like 0xFFnn.
+@end deffn
+@deffn {} BFD_RELOC_32_PCREL_S2
+@deffnx {} BFD_RELOC_16_PCREL_S2
+@deffnx {} BFD_RELOC_23_PCREL_S2
+These PC-relative relocations are stored as word displacements --
+i.e., byte displacements shifted right two bits.  The 30-bit word
+displacement (<<32_PCREL_S2>> -- 32 bits, shifted 2) is used on the
+SPARC.  (SPARC tools generally refer to this as <<WDISP30>>.)  The
+signed 16-bit displacement is used on the MIPS, and the 23-bit
+displacement is used on the Alpha.
+@end deffn
+@deffn {} BFD_RELOC_HI22
+@deffnx {} BFD_RELOC_LO10
+High 22 bits and low 10 bits of 32-bit value, placed into lower bits of
+the target word.  These are used on the SPARC.
+@end deffn
+@deffn {} BFD_RELOC_GPREL16
+@deffnx {} BFD_RELOC_GPREL32
+For systems that allocate a Global Pointer register, these are
+displacements off that register.  These relocation types are
+handled specially, because the value the register will have is
+decided relatively late.
+@end deffn
+@deffn {} BFD_RELOC_I960_CALLJ
+Reloc types used for i960/b.out.
+@end deffn
+@deffn {} BFD_RELOC_NONE
+@deffnx {} BFD_RELOC_SPARC_WDISP22
+@deffnx {} BFD_RELOC_SPARC22
+@deffnx {} BFD_RELOC_SPARC13
+@deffnx {} BFD_RELOC_SPARC_GOT10
+@deffnx {} BFD_RELOC_SPARC_GOT13
+@deffnx {} BFD_RELOC_SPARC_GOT22
+@deffnx {} BFD_RELOC_SPARC_PC10
+@deffnx {} BFD_RELOC_SPARC_PC22
+@deffnx {} BFD_RELOC_SPARC_WPLT30
+@deffnx {} BFD_RELOC_SPARC_COPY
+@deffnx {} BFD_RELOC_SPARC_GLOB_DAT
+@deffnx {} BFD_RELOC_SPARC_JMP_SLOT
+@deffnx {} BFD_RELOC_SPARC_RELATIVE
+@deffnx {} BFD_RELOC_SPARC_UA32
+SPARC ELF relocations.  There is probably some overlap with other
+relocation types already defined.
+@end deffn
+@deffn {} BFD_RELOC_SPARC_BASE13
+@deffnx {} BFD_RELOC_SPARC_BASE22
+I think these are specific to SPARC a.out (e.g., Sun 4).
+@end deffn
+@deffn {} BFD_RELOC_SPARC_64
+@deffnx {} BFD_RELOC_SPARC_10
+@deffnx {} BFD_RELOC_SPARC_11
+@deffnx {} BFD_RELOC_SPARC_OLO10
+@deffnx {} BFD_RELOC_SPARC_HH22
+@deffnx {} BFD_RELOC_SPARC_HM10
+@deffnx {} BFD_RELOC_SPARC_LM22
+@deffnx {} BFD_RELOC_SPARC_PC_HH22
+@deffnx {} BFD_RELOC_SPARC_PC_HM10
+@deffnx {} BFD_RELOC_SPARC_PC_LM22
+@deffnx {} BFD_RELOC_SPARC_WDISP16
+@deffnx {} BFD_RELOC_SPARC_WDISP19
+@deffnx {} BFD_RELOC_SPARC_GLOB_JMP
+@deffnx {} BFD_RELOC_SPARC_7
+@deffnx {} BFD_RELOC_SPARC_6
+@deffnx {} BFD_RELOC_SPARC_5
+Some relocations we're using for SPARC V9 -- subject to change.
+@end deffn
+@deffn {} BFD_RELOC_ALPHA_GPDISP_HI16
+Alpha ECOFF and ELF relocations.  Some of these treat the symbol or
+"addend" in some special way.
+For GPDISP_HI16 ("gpdisp") relocations, the symbol is ignored when
+writing; when reading, it will be the absolute section symbol.  The
+addend is the displacement in bytes of the "lda" instruction from
+the "ldah" instruction (which is at the address of this reloc).
+@end deffn
+@deffn {} BFD_RELOC_ALPHA_GPDISP_LO16
+For GPDISP_LO16 ("ignore") relocations, the symbol is handled as
+with GPDISP_HI16 relocs.  The addend is ignored when writing the
+relocations out, and is filled in with the file's GP value on
+reading, for convenience.
+@end deffn
+@deffn {} BFD_RELOC_ALPHA_GPDISP
+The ELF GPDISP relocation is exactly the same as the GPDISP_HI16
+relocation except that there is no accompanying GPDISP_LO16
+relocation.
+@end deffn
+@deffn {} BFD_RELOC_ALPHA_LITERAL
+@deffnx {} BFD_RELOC_ALPHA_ELF_LITERAL
+@deffnx {} BFD_RELOC_ALPHA_LITUSE
+The Alpha LITERAL/LITUSE relocs are produced by a symbol reference;
+the assembler turns it into a LDQ instruction to load the address of
+the symbol, and then fills in a register in the real instruction.
+
+The LITERAL reloc, at the LDQ instruction, refers to the .lita
+section symbol.  The addend is ignored when writing, but is filled
+in with the file's GP value on reading, for convenience, as with the
+GPDISP_LO16 reloc.
+
+The ELF_LITERAL reloc is somewhere between 16_GOTOFF and GPDISP_LO16.
+It should refer to the symbol to be referenced, as with 16_GOTOFF,
+but it generates output not based on the position within the .got
+section, but relative to the GP value chosen for the file during the
+final link stage.
+
+The LITUSE reloc, on the instruction using the loaded address, gives
+information to the linker that it might be able to use to optimize
+away some literal section references.  The symbol is ignored (read
+as the absolute section symbol), and the "addend" indicates the type
+of instruction using the register:
+1 - "memory" fmt insn
+2 - byte-manipulation (byte offset reg)
+3 - jsr (target of branch)
+
+The GNU linker currently doesn't do any of this optimizing.
+@end deffn
+@deffn {} BFD_RELOC_ALPHA_HINT
+The HINT relocation indicates a value that should be filled into the
+"hint" field of a jmp/jsr/ret instruction, for possible branch-
+prediction logic which may be provided on some processors.
+@end deffn
+@deffn {} BFD_RELOC_ALPHA_LINKAGE
+The LINKAGE relocation outputs a linkage pair in the object file,
+which is filled by the linker.
+@end deffn
+@deffn {} BFD_RELOC_ALPHA_CODEADDR
+The CODEADDR relocation outputs a STO_CA in the object file,
+which is filled by the linker.
+@end deffn
+@deffn {} BFD_RELOC_MIPS_JMP
+Bits 27..2 of the relocation address shifted right 2 bits;
+simple reloc otherwise.
+@end deffn
+@deffn {} BFD_RELOC_MIPS16_JMP
+The MIPS16 jump instruction.
+@end deffn
+@deffn {} BFD_RELOC_MIPS16_GPREL
+MIPS16 GP relative reloc.
+@end deffn
+@deffn {} BFD_RELOC_HI16
+High 16 bits of 32-bit value; simple reloc.
+@end deffn
+@deffn {} BFD_RELOC_HI16_S
+High 16 bits of 32-bit value but the low 16 bits will be sign
+extended and added to form the final result.  If the low 16
+bits form a negative number, we need to add one to the high value
+to compensate for the borrow when the low bits are added.
+@end deffn
+@deffn {} BFD_RELOC_LO16
+Low 16 bits.
+@end deffn
+@deffn {} BFD_RELOC_PCREL_HI16_S
+Like BFD_RELOC_HI16_S, but PC relative.
+@end deffn
+@deffn {} BFD_RELOC_PCREL_LO16
+Like BFD_RELOC_LO16, but PC relative.
+@end deffn
+@deffn {} BFD_RELOC_MIPS_GPREL
+Relocation relative to the global pointer.
+@end deffn
+@deffn {} BFD_RELOC_MIPS_LITERAL
+Relocation against a MIPS literal section.
+@end deffn
+@deffn {} BFD_RELOC_MIPS_GOT16
+@deffnx {} BFD_RELOC_MIPS_CALL16
+@deffnx {} BFD_RELOC_MIPS_GPREL32
+@deffnx {} BFD_RELOC_MIPS_GOT_HI16
+@deffnx {} BFD_RELOC_MIPS_GOT_LO16
+@deffnx {} BFD_RELOC_MIPS_CALL_HI16
+@deffnx {} BFD_RELOC_MIPS_CALL_LO16
+MIPS ELF relocations.
+@end deffn
+@deffn {} BFD_RELOC_386_GOT32
+@deffnx {} BFD_RELOC_386_PLT32
+@deffnx {} BFD_RELOC_386_COPY
+@deffnx {} BFD_RELOC_386_GLOB_DAT
+@deffnx {} BFD_RELOC_386_JUMP_SLOT
+@deffnx {} BFD_RELOC_386_RELATIVE
+@deffnx {} BFD_RELOC_386_GOTOFF
+@deffnx {} BFD_RELOC_386_GOTPC
+i386/elf relocations
+@end deffn
+@deffn {} BFD_RELOC_NS32K_IMM_8
+@deffnx {} BFD_RELOC_NS32K_IMM_16
+@deffnx {} BFD_RELOC_NS32K_IMM_32
+@deffnx {} BFD_RELOC_NS32K_IMM_8_PCREL
+@deffnx {} BFD_RELOC_NS32K_IMM_16_PCREL
+@deffnx {} BFD_RELOC_NS32K_IMM_32_PCREL
+@deffnx {} BFD_RELOC_NS32K_DISP_8
+@deffnx {} BFD_RELOC_NS32K_DISP_16
+@deffnx {} BFD_RELOC_NS32K_DISP_32
+@deffnx {} BFD_RELOC_NS32K_DISP_8_PCREL
+@deffnx {} BFD_RELOC_NS32K_DISP_16_PCREL
+@deffnx {} BFD_RELOC_NS32K_DISP_32_PCREL
+ns32k relocations
+@end deffn
+@deffn {} BFD_RELOC_PPC_B26
+@deffnx {} BFD_RELOC_PPC_BA26
+@deffnx {} BFD_RELOC_PPC_TOC16
+@deffnx {} BFD_RELOC_PPC_B16
+@deffnx {} BFD_RELOC_PPC_B16_BRTAKEN
+@deffnx {} BFD_RELOC_PPC_B16_BRNTAKEN
+@deffnx {} BFD_RELOC_PPC_BA16
+@deffnx {} BFD_RELOC_PPC_BA16_BRTAKEN
+@deffnx {} BFD_RELOC_PPC_BA16_BRNTAKEN
+@deffnx {} BFD_RELOC_PPC_COPY
+@deffnx {} BFD_RELOC_PPC_GLOB_DAT
+@deffnx {} BFD_RELOC_PPC_JMP_SLOT
+@deffnx {} BFD_RELOC_PPC_RELATIVE
+@deffnx {} BFD_RELOC_PPC_LOCAL24PC
+@deffnx {} BFD_RELOC_PPC_EMB_NADDR32
+@deffnx {} BFD_RELOC_PPC_EMB_NADDR16
+@deffnx {} BFD_RELOC_PPC_EMB_NADDR16_LO
+@deffnx {} BFD_RELOC_PPC_EMB_NADDR16_HI
+@deffnx {} BFD_RELOC_PPC_EMB_NADDR16_HA
+@deffnx {} BFD_RELOC_PPC_EMB_SDAI16
+@deffnx {} BFD_RELOC_PPC_EMB_SDA2I16
+@deffnx {} BFD_RELOC_PPC_EMB_SDA2REL
+@deffnx {} BFD_RELOC_PPC_EMB_SDA21
+@deffnx {} BFD_RELOC_PPC_EMB_MRKREF
+@deffnx {} BFD_RELOC_PPC_EMB_RELSEC16
+@deffnx {} BFD_RELOC_PPC_EMB_RELST_LO
+@deffnx {} BFD_RELOC_PPC_EMB_RELST_HI
+@deffnx {} BFD_RELOC_PPC_EMB_RELST_HA
+@deffnx {} BFD_RELOC_PPC_EMB_BIT_FLD
+@deffnx {} BFD_RELOC_PPC_EMB_RELSDA
+Power(rs6000) and PowerPC relocations.
+@end deffn
+@deffn {} BFD_RELOC_CTOR
+The type of reloc used to build a contructor table - at the moment
+probably a 32 bit wide absolute relocation, but the target can choose.
+It generally does map to one of the other relocation types.
+@end deffn
+@deffn {} BFD_RELOC_ARM_PCREL_BRANCH
+ARM 26 bit pc-relative branch.  The lowest two bits must be zero and are
+not stored in the instruction.
+@end deffn
+@deffn {} BFD_RELOC_ARM_IMMEDIATE
+@deffnx {} BFD_RELOC_ARM_OFFSET_IMM
+@deffnx {} BFD_RELOC_ARM_SHIFT_IMM
+@deffnx {} BFD_RELOC_ARM_SWI
+@deffnx {} BFD_RELOC_ARM_MULTI
+@deffnx {} BFD_RELOC_ARM_CP_OFF_IMM
+@deffnx {} BFD_RELOC_ARM_ADR_IMM
+@deffnx {} BFD_RELOC_ARM_LDR_IMM
+@deffnx {} BFD_RELOC_ARM_LITERAL
+@deffnx {} BFD_RELOC_ARM_IN_POOL
+@deffnx {} BFD_RELOC_ARM_OFFSET_IMM8
+@deffnx {} BFD_RELOC_ARM_HWLITERAL
+@deffnx {} BFD_RELOC_ARM_THUMB_ADD
+@deffnx {} BFD_RELOC_ARM_THUMB_IMM
+@deffnx {} BFD_RELOC_ARM_THUMB_SHIFT
+@deffnx {} BFD_RELOC_ARM_THUMB_OFFSET
+These relocs are only used within the ARM assembler.  They are not
+(at present) written to any object files.
+@end deffn
+@deffn {} BFD_RELOC_SH_PCDISP8BY2
+@deffnx {} BFD_RELOC_SH_PCDISP12BY2
+@deffnx {} BFD_RELOC_SH_IMM4
+@deffnx {} BFD_RELOC_SH_IMM4BY2
+@deffnx {} BFD_RELOC_SH_IMM4BY4
+@deffnx {} BFD_RELOC_SH_IMM8
+@deffnx {} BFD_RELOC_SH_IMM8BY2
+@deffnx {} BFD_RELOC_SH_IMM8BY4
+@deffnx {} BFD_RELOC_SH_PCRELIMM8BY2
+@deffnx {} BFD_RELOC_SH_PCRELIMM8BY4
+@deffnx {} BFD_RELOC_SH_SWITCH16
+@deffnx {} BFD_RELOC_SH_SWITCH32
+@deffnx {} BFD_RELOC_SH_USES
+@deffnx {} BFD_RELOC_SH_COUNT
+@deffnx {} BFD_RELOC_SH_ALIGN
+@deffnx {} BFD_RELOC_SH_CODE
+@deffnx {} BFD_RELOC_SH_DATA
+@deffnx {} BFD_RELOC_SH_LABEL
+Hitachi SH relocs.  Not all of these appear in object files.
+@end deffn
+@deffn {} BFD_RELOC_D10V_10_PCREL_R
+Mitsubishi D10V relocs.
+This is a 10-bit reloc with the right 2 bits
+assumed to be 0.
+@end deffn
+@deffn {} BFD_RELOC_D10V_10_PCREL_L
+Mitsubishi D10V relocs.
+This is a 10-bit reloc with the right 2 bits
+assumed to be 0.  This is the same as the previous reloc
+except it is in the left container, i.e.,
+shifted left 15 bits.
+@end deffn
+@deffn {} BFD_RELOC_D10V_18
+This is an 18-bit reloc with the right 2 bits
+assumed to be 0.
+@end deffn
+@deffn {} BFD_RELOC_D10V_18_PCREL
+This is an 18-bit reloc with the right 2 bits
+assumed to be 0.
+@end deffn
+@deffn {} BFD_RELOC_M32R_24
+Mitsubishi M32R relocs.
+This is a 24 bit absolute address.
+@end deffn
+@deffn {} BFD_RELOC_M32R_10_PCREL
+This is a 10-bit pc-relative reloc with the right 2 bits assumed to be 0.
+@end deffn
+@deffn {} BFD_RELOC_M32R_18_PCREL
+This is an 18-bit reloc with the right 2 bits assumed to be 0.
+@end deffn
+@deffn {} BFD_RELOC_M32R_26_PCREL
+This is a 26-bit reloc with the right 2 bits assumed to be 0.
+@end deffn
+@deffn {} BFD_RELOC_M32R_HI16_ULO
+This is a 16-bit reloc containing the high 16 bits of an address
+used when the lower 16 bits are treated as unsigned.
+@end deffn
+@deffn {} BFD_RELOC_M32R_HI16_SLO
+This is a 16-bit reloc containing the high 16 bits of an address
+used when the lower 16 bits are treated as signed.
+@end deffn
+@deffn {} BFD_RELOC_M32R_LO16
+This is a 16-bit reloc containing the lower 16 bits of an address.
+@end deffn
+@deffn {} BFD_RELOC_M32R_SDA16
+This is a 16-bit reloc containing the small data area offset for use in
+add3, load, and store instructions.
+@end deffn
+@deffn {} BFD_RELOC_MN10300_32_PCREL
+This is a 32bit pcrel reloc for the mn10300, offset by two bytes in the
+instruction.
+@end deffn
+@deffn {} BFD_RELOC_MN10300_16_PCREL
+This is a 16bit pcrel reloc for the mn10300, offset by two bytes in the
+instruction.
+@end deffn
+.
+@example
+typedef enum bfd_reloc_code_real bfd_reloc_code_real_type;
+@end example
+@findex bfd_reloc_type_lookup
+@subsubsection @code{bfd_reloc_type_lookup}
+@strong{Synopsis}
+@example
+reloc_howto_type *
+bfd_reloc_type_lookup (bfd *abfd, bfd_reloc_code_real_type code);
+@end example
+@strong{Description}@*
+Return a pointer to a howto structure which, when
+invoked, will perform the relocation @var{code} on data from the
+architecture noted.
+@*
+@findex bfd_default_reloc_type_lookup
+@subsubsection @code{bfd_default_reloc_type_lookup}
+@strong{Synopsis}
+@example
+reloc_howto_type *bfd_default_reloc_type_lookup
+   (bfd *abfd, bfd_reloc_code_real_type  code);
+@end example
+@strong{Description}@*
+Provides a default relocation lookup routine for any architecture.
+@*
+@findex bfd_get_reloc_code_name
+@subsubsection @code{bfd_get_reloc_code_name}
+@strong{Synopsis}
+@example
+const char *bfd_get_reloc_code_name (bfd_reloc_code_real_type code);
+@end example
+@strong{Description}@*
+Provides a printable name for the supplied relocation code.
+Useful mainly for printing error messages.
+@*
+@findex bfd_generic_relax_section
+@subsubsection @code{bfd_generic_relax_section}
+@strong{Synopsis}
+@example
+boolean bfd_generic_relax_section
+   (bfd *abfd,
+    asection *section,
+    struct bfd_link_info *,
+    boolean *);
+@end example
+@strong{Description}@*
+Provides default handling for relaxing for back ends which
+don't do relaxing -- i.e., does nothing.
+@*
+@findex bfd_generic_get_relocated_section_contents
+@subsubsection @code{bfd_generic_get_relocated_section_contents}
+@strong{Synopsis}
+@example
+bfd_byte *
+bfd_generic_get_relocated_section_contents (bfd *abfd,
+    struct bfd_link_info *link_info,
+    struct bfd_link_order *link_order,
+    bfd_byte *data,
+    boolean relocateable,
+    asymbol **symbols);
+@end example
+@strong{Description}@*
+Provides default handling of relocation effort for back ends
+which can't be bothered to do it efficiently.
+@*