\input texinfo
+@c Copyright 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998,
+@c 2000, 2001
+@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
@node BFD target vector swap
@subsection Swapping functions
-Every target vector has fuction pointers used for swapping information
+Every target vector has function pointers used for swapping information
in and out of the target representation. There are two sets of
functions: one for data information, and one for header information.
Each set has three sizes: 64-bit, 32-bit, and 16-bit. Each size has
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.
Get the contents of a section. This is called from
@samp{bfd_get_section_contents}. Most targets set this to
@samp{_bfd_generic_get_section_contents}, which does a @samp{bfd_seek}
-based on the section's @samp{filepos} field and a @samp{bfd_read}. The
+based on the section's @samp{filepos} field and a @samp{bfd_bread}. The
corresponding field in the target vector is named
@samp{_bfd_get_section_contents}.
target vector is named @samp{_bfd_truncate_arname}.
@item _write_armap
-Write out the archive symbol table using calls to @samp{bfd_write}.
+Write out the archive symbol table using calls to @samp{bfd_bwrite}.
This is normally called from the archive @samp{write_contents} routine.
The corresponding field in the target vector is named @samp{write_armap}
(no leading underscore).
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
@item
Using the linker to generate relocateable output in a different object
file format is impossible in the general case, so you generally don't
-have to worry about that. Linking input files of different object file
-formats together is quite unusual, but if you're really dedicated you
-may want to consider testing this case, both when the output object file
-format is the same as your format, and when it is different.
+have to worry about that. The GNU linker makes sure to stop that from
+happening when an input file in a different format has relocations.
+
+Linking input files of different object file formats together is quite
+unusual, but if you're really dedicated you may want to consider testing
+this case, both when the output object file format is the same as your
+format, and when it is different.
@end itemize
@node BFD relocation codes
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
projects / deliverable / binutils-gdb.git / blobdiff