\input texinfo
+@c Copyright 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998,
+@c 2000
+@c Free Software Foundation, Inc.
@setfilename bfdint.info
@settitle BFD Internals
This document describes some BFD internal information which may be
helpful when working on BFD. It is very incomplete.
-This document is not updated regularly, and may be out of date. It was
-last modified on $Date$.
+This document is not updated regularly, and may be out of date.
The initial version of this document was written by Ian Lance Taylor
@email{ian@@cygnus.com}.
@item name
The name of the target vector. This is an arbitrary string. This is
how the target vector is named in command line options for tools which
-use BFD, such as the @samp{-oformat} linker option.
+use BFD, such as the @samp{--oformat} linker option.
@item flavour
A general description of the type of target. The following flavours are
functions: @samp{_get_reloc_upper_bound}, @samp{_canonicalize_reloc},
and @samp{_bfd_reloc_type_lookup}. A reference like
@samp{BFD_JUMP_TABLE_RELOCS (foo)} will expand into three functions
-prefixed with @samp{foo}: @samp{foo_get_reloc_upper_found}, etc. The
+prefixed with @samp{foo}: @samp{foo_get_reloc_upper_bound}, etc. The
@samp{BFD_JUMP_TABLE_RELOCS} macro will be placed such that those three
functions initialize the appropriate fields in the BFD target vector.
BFD contains several automatically generated files. This section
describes them. Some files are created at configure time, when you
configure BFD. Some files are created at make time, when you build
-time. Some files are automatically rebuilt at make time, but only if
+BFD. Some files are automatically rebuilt at make time, but only if
you configure with the @samp{--enable-maintainer-mode} option. Some
files live in the object directory---the directory from which you run
configure---and some live in the source directory. All files that live
The ELF object file format is defined in two parts: a generic ABI and a
processor specific supplement. The ELF support in BFD is split in a
similar fashion. The processor specific support is largely kept within
-a single file. The generic support is provided by several other file.
+a single file. The generic support is provided by several other files.
The processor specific support provides a set of function pointers and
constants used by the generic support.
files (but not in executables, except when using dynamic linking).
However, this is outweighed by the simplicity of addend handling when
using @samp{Rela} relocations. With @samp{Rel} relocations, the addend
-must be stored in the object file, which makes relocateable links more
-complex. In particular, split relocations, in which an address is built
-up using two or more instructions, become very awkward; such relocations
-are used on RISC chips which can not load an address in a single
-instruction.
+must be stored in the section contents, which makes relocateable links
+more complex.
+
+For example, consider C code like @code{i = a[1000];} where @samp{a} is
+a global array. The instructions which load the value of @samp{a[1000]}
+will most likely use a relocation which refers to the symbol
+representing @samp{a}, with an addend that gives the offset from the
+start of @samp{a} to element @samp{1000}. When using @samp{Rel}
+relocations, that addend must be stored in the instructions themselves.
+If you are adding support for a RISC chip which uses two or more
+instructions to load an address, then the addend may not fit in a single
+instruction, and will have to be somehow split among the instructions.
+This makes linking awkward, particularly when doing a relocateable link
+in which the addend may have to be updated. It can be done---the MIPS
+ELF support does it---but it should be avoided when possible.
It is possible, though somewhat awkward, to support both @samp{Rel} and
@samp{Rela} relocations for a single target; @file{elf64-mips.c} does it
You must also add the magic number for this processor to the
@samp{prep_headers} function in @file{elf.c}.
+You must also create a header file in the @file{include/elf} directory
+called @file{@var{cpu}.h}. This file should define any target specific
+information which may be needed outside of the BFD code. In particular
+it should use the @samp{START_RELOC_NUMBERS}, @samp{RELOC_NUMBER},
+@samp{FAKE_RELOC}, @samp{EMPTY_RELOC} and @samp{END_RELOC_NUMBERS}
+macros to create a table mapping the number used to indentify a
+relocation to a name describing that relocation.
+
+While not a BFD component, you probably also want to make the binutils
+program @samp{readelf} parse your ELF objects. For this, you need to add
+code for @code{EM_@var{cpu}} as appropriate in @file{binutils/readelf.c}.
+
@node BFD ELF processor linker
@subsubsection Processor specific linker support