\input texinfo
@c Copyright 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998,
-@c 2000
+@c 2000, 2001, 2002, 2003
@c Free Software Foundation, Inc.
@setfilename bfdint.info
@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
MS-DOS.
@item bfd_target_evax_flavour
openVMS.
+@item bfd_target_mmo_flavour
+Donald Knuth's MMIXware object format.
@end table
@item byteorder
@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
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).
@item _bfd_get_relocated_section_contents
Read the contents of a section and apply the relocation information.
-This handles both a final link and a relocateable link; in the latter
+This handles both a final link and a relocatable link; in the latter
case, it adjust the relocation information as well. This is called via
@samp{bfd_get_relocated_section_contents}. Most targets implement it by
calling @samp{bfd_generic_get_relocated_section_contents}.
section as the value to store. In the IEEE object file format,
relocations may involve arbitrary expressions.
-When doing a relocateable link, the linker may or may not have to do
+When doing a relocatable link, the linker may or may not have to do
anything with a relocation, depending upon the definition of the
relocation. Simple relocations generally do not require any special
action.
@itemize @bullet
@item
Make sure you clearly understand what the contents of the section should
-look like after assembly, after a relocateable link, and after a final
+look like after assembly, after a relocatable link, and after a final
link. Make sure you clearly understand the operations the linker must
-perform during a relocateable link and during a final link.
+perform during a relocatable link and during a final link.
@item
Write a howto structure for the relocation. The howto structure is
able to handle that. You may need to set the @samp{special_function}
field to handle assembly correctly. Be careful to ensure that any code
you write to handle the assembler will also work correctly when doing a
-relocateable link. For example, see @samp{bfd_elf_generic_reloc}.
+relocatable link. For example, see @samp{bfd_elf_generic_reloc}.
@item
Test the assembler. Consider the cases of relocation against an
required handling to the target specific relocation function. In simple
cases this will just involve a call to @samp{_bfd_final_link_relocate}
or @samp{_bfd_relocate_contents}, depending upon the definition of the
-relocation and whether the link is relocateable or not.
+relocation and whether the link is relocatable or not.
@item
Test the linker. Test the case of a final link. If the relocation can
overflow, use a linker script to force an overflow and make sure the
-error is reported correctly. Test a relocateable link, whether the
-symbol is defined or undefined in the relocateable output. For both the
-final and relocateable link, test the case when the symbol is a common
+error is reported correctly. Test a relocatable link, whether the
+symbol is defined or undefined in the relocatable output. For both the
+final and relocatable link, test the case when the symbol is a common
symbol, when the symbol looked like a common symbol but became a defined
symbol, when the symbol is defined in a different object file, and when
the symbol is defined in the same object file.
doing a link in which the output object file format is S-records.
@item
-Using the linker to generate relocateable output in a different object
+Using the linker to generate relocatable 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
of howto structure was being used by a particular format.
The new howto structure would clearly define the relocation behaviour in
-the case of an assembly, a relocateable link, and a final link. At
+the case of an assembly, a relocatable link, and a final link. At
least one special function would be defined as an escape, and it might
make sense to define more.
@item
Define @samp{ELF_MACHINE_CODE} to the magic number which should appear
in the @samp{e_machine} field of the ELF header. As of this writing,
-these magic numbers are assigned by SCO; if you want to get a magic
+these magic numbers are assigned by Caldera; if you want to get a magic
number for a particular processor, try sending a note to
-@email{registry@@sco.com}. In the BFD sources, the magic numbers are
+@email{registry@@caldera.com}. In the BFD sources, the magic numbers are
found in @file{include/elf/common.h}; they have names beginning with
@samp{EM_}.
@item
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 section contents, which makes relocateable links
+must be stored in the section contents, which makes relocatable links
more complex.
For example, consider C code like @code{i = a[1000];} where @samp{a} is
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
+This makes linking awkward, particularly when doing a relocatable 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.
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
+macros to create a table mapping the number used to identify a
relocation to a name describing that relocation.
While not a BFD component, you probably also want to make the binutils
information. In simple cases, this is little more than a loop over the
relocations which computes the value of each relocation and calls
@samp{_bfd_final_link_relocate}. The function must check for a
-relocateable link, and in that case normally needs to do nothing other
+relocatable link, and in that case normally needs to do nothing other
than adjust the addend for relocations against a section symbol.
The complex cases generally have to do with dynamic linker support. GOT
set of functions which appear in a particular target vector.
@item BFD
-The BFD library itself. Also, each object file, archive, or exectable
+The BFD library itself. Also, each object file, archive, or executable
opened by the BFD library has the type @samp{bfd *}, and is sometimes
referred to as a bfd.
projects / deliverable / binutils-gdb.git / blobdiff