\input texinfo
|
\input texinfo
|
@c Copyright 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998,
|
@c Copyright 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998,
|
@c 2000, 2001, 2002, 2003, 2004, 2006, 2007, 2009
|
@c 2000, 2001, 2002, 2003, 2004, 2006, 2007, 2009
|
@c Free Software Foundation, Inc.
|
@c Free Software Foundation, Inc.
|
@setfilename bfdint.info
|
@setfilename bfdint.info
|
|
|
@settitle BFD Internals
|
@settitle BFD Internals
|
@iftex
|
@iftex
|
@titlepage
|
@titlepage
|
@title{BFD Internals}
|
@title{BFD Internals}
|
@author{Ian Lance Taylor}
|
@author{Ian Lance Taylor}
|
@author{Cygnus Solutions}
|
@author{Cygnus Solutions}
|
@page
|
@page
|
@end iftex
|
@end iftex
|
|
|
@copying
|
@copying
|
This file documents the internals of the BFD library.
|
This file documents the internals of the BFD library.
|
|
|
Copyright @copyright{} 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995,
|
Copyright @copyright{} 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995,
|
1996, 1998, 2000, 2001, 2002, 2003, 2004, 2006, 2007, 2009
|
1996, 1998, 2000, 2001, 2002, 2003, 2004, 2006, 2007, 2009
|
Free Software Foundation, Inc.
|
Free Software Foundation, Inc.
|
Contributed by Cygnus Support.
|
Contributed by Cygnus Support.
|
|
|
Permission is granted to copy, distribute and/or modify this document
|
Permission is granted to copy, distribute and/or modify this document
|
under the terms of the GNU Free Documentation License, Version 1.1 or
|
under the terms of the GNU Free Documentation License, Version 1.1 or
|
any later version published by the Free Software Foundation; with the
|
any later version published by the Free Software Foundation; with the
|
Invariant Sections being ``GNU General Public License'' and ``Funding
|
Invariant Sections being ``GNU General Public License'' and ``Funding
|
Free Software'', the Front-Cover texts being (a) (see below), and with
|
Free Software'', the Front-Cover texts being (a) (see below), and with
|
the Back-Cover Texts being (b) (see below). A copy of the license is
|
the Back-Cover Texts being (b) (see below). A copy of the license is
|
included in the section entitled ``GNU Free Documentation License''.
|
included in the section entitled ``GNU Free Documentation License''.
|
|
|
(a) The FSF's Front-Cover Text is:
|
(a) The FSF's Front-Cover Text is:
|
|
|
A GNU Manual
|
A GNU Manual
|
|
|
(b) The FSF's Back-Cover Text is:
|
(b) The FSF's Back-Cover Text is:
|
|
|
You have freedom to copy and modify this GNU Manual, like GNU
|
You have freedom to copy and modify this GNU Manual, like GNU
|
software. Copies published by the Free Software Foundation raise
|
software. Copies published by the Free Software Foundation raise
|
funds for GNU development.
|
funds for GNU development.
|
@end copying
|
@end copying
|
|
|
@node Top
|
@node Top
|
@top BFD Internals
|
@top BFD Internals
|
@raisesections
|
@raisesections
|
@cindex bfd internals
|
@cindex bfd internals
|
|
|
This document describes some BFD internal information which may be
|
This document describes some BFD internal information which may be
|
helpful when working on BFD. It is very incomplete.
|
helpful when working on BFD. It is very incomplete.
|
|
|
This document is not updated regularly, and may be out of 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
|
The initial version of this document was written by Ian Lance Taylor
|
@email{ian@@cygnus.com}.
|
@email{ian@@cygnus.com}.
|
|
|
@menu
|
@menu
|
* BFD overview:: BFD overview
|
* BFD overview:: BFD overview
|
* BFD guidelines:: BFD programming guidelines
|
* BFD guidelines:: BFD programming guidelines
|
* BFD target vector:: BFD target vector
|
* BFD target vector:: BFD target vector
|
* BFD generated files:: BFD generated files
|
* BFD generated files:: BFD generated files
|
* BFD multiple compilations:: Files compiled multiple times in BFD
|
* BFD multiple compilations:: Files compiled multiple times in BFD
|
* BFD relocation handling:: BFD relocation handling
|
* BFD relocation handling:: BFD relocation handling
|
* BFD ELF support:: BFD ELF support
|
* BFD ELF support:: BFD ELF support
|
* BFD glossary:: Glossary
|
* BFD glossary:: Glossary
|
* Index:: Index
|
* Index:: Index
|
@end menu
|
@end menu
|
|
|
@node BFD overview
|
@node BFD overview
|
@section BFD overview
|
@section BFD overview
|
|
|
BFD is a library which provides a single interface to read and write
|
BFD is a library which provides a single interface to read and write
|
object files, executables, archive files, and core files in any format.
|
object files, executables, archive files, and core files in any format.
|
|
|
@menu
|
@menu
|
* BFD library interfaces:: BFD library interfaces
|
* BFD library interfaces:: BFD library interfaces
|
* BFD library users:: BFD library users
|
* BFD library users:: BFD library users
|
* BFD view:: The BFD view of a file
|
* BFD view:: The BFD view of a file
|
* BFD blindness:: BFD loses information
|
* BFD blindness:: BFD loses information
|
@end menu
|
@end menu
|
|
|
@node BFD library interfaces
|
@node BFD library interfaces
|
@subsection BFD library interfaces
|
@subsection BFD library interfaces
|
|
|
One way to look at the BFD library is to divide it into four parts by
|
One way to look at the BFD library is to divide it into four parts by
|
type of interface.
|
type of interface.
|
|
|
The first interface is the set of generic functions which programs using
|
The first interface is the set of generic functions which programs using
|
the BFD library will call. These generic function normally translate
|
the BFD library will call. These generic function normally translate
|
directly or indirectly into calls to routines which are specific to a
|
directly or indirectly into calls to routines which are specific to a
|
particular object file format. Many of these generic functions are
|
particular object file format. Many of these generic functions are
|
actually defined as macros in @file{bfd.h}. These functions comprise
|
actually defined as macros in @file{bfd.h}. These functions comprise
|
the official BFD interface.
|
the official BFD interface.
|
|
|
The second interface is the set of functions which appear in the target
|
The second interface is the set of functions which appear in the target
|
vectors. This is the bulk of the code in BFD. A target vector is a set
|
vectors. This is the bulk of the code in BFD. A target vector is a set
|
of function pointers specific to a particular object file format. The
|
of function pointers specific to a particular object file format. The
|
target vector is used to implement the generic BFD functions. These
|
target vector is used to implement the generic BFD functions. These
|
functions are always called through the target vector, and are never
|
functions are always called through the target vector, and are never
|
called directly. The target vector is described in detail in @ref{BFD
|
called directly. The target vector is described in detail in @ref{BFD
|
target vector}. The set of functions which appear in a particular
|
target vector}. The set of functions which appear in a particular
|
target vector is often referred to as a BFD backend.
|
target vector is often referred to as a BFD backend.
|
|
|
The third interface is a set of oddball functions which are typically
|
The third interface is a set of oddball functions which are typically
|
specific to a particular object file format, are not generic functions,
|
specific to a particular object file format, are not generic functions,
|
and are called from outside of the BFD library. These are used as hooks
|
and are called from outside of the BFD library. These are used as hooks
|
by the linker and the assembler when a particular object file format
|
by the linker and the assembler when a particular object file format
|
requires some action which the BFD generic interface does not provide.
|
requires some action which the BFD generic interface does not provide.
|
These functions are typically declared in @file{bfd.h}, but in many
|
These functions are typically declared in @file{bfd.h}, but in many
|
cases they are only provided when BFD is configured with support for a
|
cases they are only provided when BFD is configured with support for a
|
particular object file format. These functions live in a grey area, and
|
particular object file format. These functions live in a grey area, and
|
are not really part of the official BFD interface.
|
are not really part of the official BFD interface.
|
|
|
The fourth interface is the set of BFD support functions which are
|
The fourth interface is the set of BFD support functions which are
|
called by the other BFD functions. These manage issues like memory
|
called by the other BFD functions. These manage issues like memory
|
allocation, error handling, file access, hash tables, swapping, and the
|
allocation, error handling, file access, hash tables, swapping, and the
|
like. These functions are never called from outside of the BFD library.
|
like. These functions are never called from outside of the BFD library.
|
|
|
@node BFD library users
|
@node BFD library users
|
@subsection BFD library users
|
@subsection BFD library users
|
|
|
Another way to look at the BFD library is to divide it into three parts
|
Another way to look at the BFD library is to divide it into three parts
|
by the manner in which it is used.
|
by the manner in which it is used.
|
|
|
The first use is to read an object file. The object file readers are
|
The first use is to read an object file. The object file readers are
|
programs like @samp{gdb}, @samp{nm}, @samp{objdump}, and @samp{objcopy}.
|
programs like @samp{gdb}, @samp{nm}, @samp{objdump}, and @samp{objcopy}.
|
These programs use BFD to view an object file in a generic form. The
|
These programs use BFD to view an object file in a generic form. The
|
official BFD interface is normally fully adequate for these programs.
|
official BFD interface is normally fully adequate for these programs.
|
|
|
The second use is to write an object file. The object file writers are
|
The second use is to write an object file. The object file writers are
|
programs like @samp{gas} and @samp{objcopy}. These programs use BFD to
|
programs like @samp{gas} and @samp{objcopy}. These programs use BFD to
|
create an object file. The official BFD interface is normally adequate
|
create an object file. The official BFD interface is normally adequate
|
for these programs, but for some object file formats the assembler needs
|
for these programs, but for some object file formats the assembler needs
|
some additional hooks in order to set particular flags or other
|
some additional hooks in order to set particular flags or other
|
information. The official BFD interface includes functions to copy
|
information. The official BFD interface includes functions to copy
|
private information from one object file to another, and these functions
|
private information from one object file to another, and these functions
|
are used by @samp{objcopy} to avoid information loss.
|
are used by @samp{objcopy} to avoid information loss.
|
|
|
The third use is to link object files. There is only one object file
|
The third use is to link object files. There is only one object file
|
linker, @samp{ld}. Originally, @samp{ld} was an object file reader and
|
linker, @samp{ld}. Originally, @samp{ld} was an object file reader and
|
an object file writer, and it did the link operation using the generic
|
an object file writer, and it did the link operation using the generic
|
BFD structures. However, this turned out to be too slow and too memory
|
BFD structures. However, this turned out to be too slow and too memory
|
intensive.
|
intensive.
|
|
|
The official BFD linker functions were written to permit specific BFD
|
The official BFD linker functions were written to permit specific BFD
|
backends to perform the link without translating through the generic
|
backends to perform the link without translating through the generic
|
structures, in the normal case where all the input files and output file
|
structures, in the normal case where all the input files and output file
|
have the same object file format. Not all of the backends currently
|
have the same object file format. Not all of the backends currently
|
implement the new interface, and there are default linking functions
|
implement the new interface, and there are default linking functions
|
within BFD which use the generic structures and which work with all
|
within BFD which use the generic structures and which work with all
|
backends.
|
backends.
|
|
|
For several object file formats the linker needs additional hooks which
|
For several object file formats the linker needs additional hooks which
|
are not provided by the official BFD interface, particularly for dynamic
|
are not provided by the official BFD interface, particularly for dynamic
|
linking support. These functions are typically called from the linker
|
linking support. These functions are typically called from the linker
|
emulation template.
|
emulation template.
|
|
|
@node BFD view
|
@node BFD view
|
@subsection The BFD view of a file
|
@subsection The BFD view of a file
|
|
|
BFD uses generic structures to manage information. It translates data
|
BFD uses generic structures to manage information. It translates data
|
into the generic form when reading files, and out of the generic form
|
into the generic form when reading files, and out of the generic form
|
when writing files.
|
when writing files.
|
|
|
BFD describes a file as a pointer to the @samp{bfd} type. A @samp{bfd}
|
BFD describes a file as a pointer to the @samp{bfd} type. A @samp{bfd}
|
is composed of the following elements. The BFD information can be
|
is composed of the following elements. The BFD information can be
|
displayed using the @samp{objdump} program with various options.
|
displayed using the @samp{objdump} program with various options.
|
|
|
@table @asis
|
@table @asis
|
@item general information
|
@item general information
|
The object file format, a few general flags, the start address.
|
The object file format, a few general flags, the start address.
|
@item architecture
|
@item architecture
|
The architecture, including both a general processor type (m68k, MIPS
|
The architecture, including both a general processor type (m68k, MIPS
|
etc.) and a specific machine number (m68000, R4000, etc.).
|
etc.) and a specific machine number (m68000, R4000, etc.).
|
@item sections
|
@item sections
|
A list of sections.
|
A list of sections.
|
@item symbols
|
@item symbols
|
A symbol table.
|
A symbol table.
|
@end table
|
@end table
|
|
|
BFD represents a section as a pointer to the @samp{asection} type. Each
|
BFD represents a section as a pointer to the @samp{asection} type. Each
|
section has a name and a size. Most sections also have an associated
|
section has a name and a size. Most sections also have an associated
|
block of data, known as the section contents. Sections also have
|
block of data, known as the section contents. Sections also have
|
associated flags, a virtual memory address, a load memory address, a
|
associated flags, a virtual memory address, a load memory address, a
|
required alignment, a list of relocations, and other miscellaneous
|
required alignment, a list of relocations, and other miscellaneous
|
information.
|
information.
|
|
|
BFD represents a relocation as a pointer to the @samp{arelent} type. A
|
BFD represents a relocation as a pointer to the @samp{arelent} type. A
|
relocation describes an action which the linker must take to modify the
|
relocation describes an action which the linker must take to modify the
|
section contents. Relocations have a symbol, an address, an addend, and
|
section contents. Relocations have a symbol, an address, an addend, and
|
a pointer to a howto structure which describes how to perform the
|
a pointer to a howto structure which describes how to perform the
|
relocation. For more information, see @ref{BFD relocation handling}.
|
relocation. For more information, see @ref{BFD relocation handling}.
|
|
|
BFD represents a symbol as a pointer to the @samp{asymbol} type. A
|
BFD represents a symbol as a pointer to the @samp{asymbol} type. A
|
symbol has a name, a pointer to a section, an offset within that
|
symbol has a name, a pointer to a section, an offset within that
|
section, and some flags.
|
section, and some flags.
|
|
|
Archive files do not have any sections or symbols. Instead, BFD
|
Archive files do not have any sections or symbols. Instead, BFD
|
represents an archive file as a file which contains a list of
|
represents an archive file as a file which contains a list of
|
@samp{bfd}s. BFD also provides access to the archive symbol map, as a
|
@samp{bfd}s. BFD also provides access to the archive symbol map, as a
|
list of symbol names. BFD provides a function to return the @samp{bfd}
|
list of symbol names. BFD provides a function to return the @samp{bfd}
|
within the archive which corresponds to a particular entry in the
|
within the archive which corresponds to a particular entry in the
|
archive symbol map.
|
archive symbol map.
|
|
|
@node BFD blindness
|
@node BFD blindness
|
@subsection BFD loses information
|
@subsection BFD loses information
|
|
|
Most object file formats have information which BFD can not represent in
|
Most object file formats have information which BFD can not represent in
|
its generic form, at least as currently defined.
|
its generic form, at least as currently defined.
|
|
|
There is often explicit information which BFD can not represent. For
|
There is often explicit information which BFD can not represent. For
|
example, the COFF version stamp, or the ELF program segments. BFD
|
example, the COFF version stamp, or the ELF program segments. BFD
|
provides special hooks to handle this information when copying,
|
provides special hooks to handle this information when copying,
|
printing, or linking an object file. The BFD support for a particular
|
printing, or linking an object file. The BFD support for a particular
|
object file format will normally store this information in private data
|
object file format will normally store this information in private data
|
and handle it using the special hooks.
|
and handle it using the special hooks.
|
|
|
In some cases there is also implicit information which BFD can not
|
In some cases there is also implicit information which BFD can not
|
represent. For example, the MIPS processor distinguishes small and
|
represent. For example, the MIPS processor distinguishes small and
|
large symbols, and requires that all small symbols be within 32K of the
|
large symbols, and requires that all small symbols be within 32K of the
|
GP register. This means that the MIPS assembler must be able to mark
|
GP register. This means that the MIPS assembler must be able to mark
|
variables as either small or large, and the MIPS linker must know to put
|
variables as either small or large, and the MIPS linker must know to put
|
small symbols within range of the GP register. Since BFD can not
|
small symbols within range of the GP register. Since BFD can not
|
represent this information, this means that the assembler and linker
|
represent this information, this means that the assembler and linker
|
must have information that is specific to a particular object file
|
must have information that is specific to a particular object file
|
format which is outside of the BFD library.
|
format which is outside of the BFD library.
|
|
|
This loss of information indicates areas where the BFD paradigm breaks
|
This loss of information indicates areas where the BFD paradigm breaks
|
down. It is not actually possible to represent the myriad differences
|
down. It is not actually possible to represent the myriad differences
|
among object file formats using a single generic interface, at least not
|
among object file formats using a single generic interface, at least not
|
in the manner which BFD does it today.
|
in the manner which BFD does it today.
|
|
|
Nevertheless, the BFD library does greatly simplify the task of dealing
|
Nevertheless, the BFD library does greatly simplify the task of dealing
|
with object files, and particular problems caused by information loss
|
with object files, and particular problems caused by information loss
|
can normally be solved using some sort of relatively constrained hook
|
can normally be solved using some sort of relatively constrained hook
|
into the library.
|
into the library.
|
|
|
|
|
|
|
@node BFD guidelines
|
@node BFD guidelines
|
@section BFD programming guidelines
|
@section BFD programming guidelines
|
@cindex bfd programming guidelines
|
@cindex bfd programming guidelines
|
@cindex programming guidelines for bfd
|
@cindex programming guidelines for bfd
|
@cindex guidelines, bfd programming
|
@cindex guidelines, bfd programming
|
|
|
There is a lot of poorly written and confusing code in BFD. New BFD
|
There is a lot of poorly written and confusing code in BFD. New BFD
|
code should be written to a higher standard. Merely because some BFD
|
code should be written to a higher standard. Merely because some BFD
|
code is written in a particular manner does not mean that you should
|
code is written in a particular manner does not mean that you should
|
emulate it.
|
emulate it.
|
|
|
Here are some general BFD programming guidelines:
|
Here are some general BFD programming guidelines:
|
|
|
@itemize @bullet
|
@itemize @bullet
|
@item
|
@item
|
Follow the GNU coding standards.
|
Follow the GNU coding standards.
|
|
|
@item
|
@item
|
Avoid global variables. We ideally want BFD to be fully reentrant, so
|
Avoid global variables. We ideally want BFD to be fully reentrant, so
|
that it can be used in multiple threads. All uses of global or static
|
that it can be used in multiple threads. All uses of global or static
|
variables interfere with that. Initialized constant variables are OK,
|
variables interfere with that. Initialized constant variables are OK,
|
and they should be explicitly marked with @samp{const}. Instead of global
|
and they should be explicitly marked with @samp{const}. Instead of global
|
variables, use data attached to a BFD or to a linker hash table.
|
variables, use data attached to a BFD or to a linker hash table.
|
|
|
@item
|
@item
|
All externally visible functions should have names which start with
|
All externally visible functions should have names which start with
|
@samp{bfd_}. All such functions should be declared in some header file,
|
@samp{bfd_}. All such functions should be declared in some header file,
|
typically @file{bfd.h}. See, for example, the various declarations near
|
typically @file{bfd.h}. See, for example, the various declarations near
|
the end of @file{bfd-in.h}, which mostly declare functions required by
|
the end of @file{bfd-in.h}, which mostly declare functions required by
|
specific linker emulations.
|
specific linker emulations.
|
|
|
@item
|
@item
|
All functions which need to be visible from one file to another within
|
All functions which need to be visible from one file to another within
|
BFD, but should not be visible outside of BFD, should start with
|
BFD, but should not be visible outside of BFD, should start with
|
@samp{_bfd_}. Although external names beginning with @samp{_} are
|
@samp{_bfd_}. Although external names beginning with @samp{_} are
|
prohibited by the ANSI standard, in practice this usage will always
|
prohibited by the ANSI standard, in practice this usage will always
|
work, and it is required by the GNU coding standards.
|
work, and it is required by the GNU coding standards.
|
|
|
@item
|
@item
|
Always remember that people can compile using @samp{--enable-targets} to
|
Always remember that people can compile using @samp{--enable-targets} to
|
build several, or all, targets at once. It must be possible to link
|
build several, or all, targets at once. It must be possible to link
|
together the files for all targets.
|
together the files for all targets.
|
|
|
@item
|
@item
|
BFD code should compile with few or no warnings using @samp{gcc -Wall}.
|
BFD code should compile with few or no warnings using @samp{gcc -Wall}.
|
Some warnings are OK, like the absence of certain function declarations
|
Some warnings are OK, like the absence of certain function declarations
|
which may or may not be declared in system header files. Warnings about
|
which may or may not be declared in system header files. Warnings about
|
ambiguous expressions and the like should always be fixed.
|
ambiguous expressions and the like should always be fixed.
|
@end itemize
|
@end itemize
|
|
|
@node BFD target vector
|
@node BFD target vector
|
@section BFD target vector
|
@section BFD target vector
|
@cindex bfd target vector
|
@cindex bfd target vector
|
@cindex target vector in bfd
|
@cindex target vector in bfd
|
|
|
BFD supports multiple object file formats by using the @dfn{target
|
BFD supports multiple object file formats by using the @dfn{target
|
vector}. This is simply a set of function pointers which implement
|
vector}. This is simply a set of function pointers which implement
|
behaviour that is specific to a particular object file format.
|
behaviour that is specific to a particular object file format.
|
|
|
In this section I list all of the entries in the target vector and
|
In this section I list all of the entries in the target vector and
|
describe what they do.
|
describe what they do.
|
|
|
@menu
|
@menu
|
* BFD target vector miscellaneous:: Miscellaneous constants
|
* BFD target vector miscellaneous:: Miscellaneous constants
|
* BFD target vector swap:: Swapping functions
|
* BFD target vector swap:: Swapping functions
|
* BFD target vector format:: Format type dependent functions
|
* BFD target vector format:: Format type dependent functions
|
* BFD_JUMP_TABLE macros:: BFD_JUMP_TABLE macros
|
* BFD_JUMP_TABLE macros:: BFD_JUMP_TABLE macros
|
* BFD target vector generic:: Generic functions
|
* BFD target vector generic:: Generic functions
|
* BFD target vector copy:: Copy functions
|
* BFD target vector copy:: Copy functions
|
* BFD target vector core:: Core file support functions
|
* BFD target vector core:: Core file support functions
|
* BFD target vector archive:: Archive functions
|
* BFD target vector archive:: Archive functions
|
* BFD target vector symbols:: Symbol table functions
|
* BFD target vector symbols:: Symbol table functions
|
* BFD target vector relocs:: Relocation support
|
* BFD target vector relocs:: Relocation support
|
* BFD target vector write:: Output functions
|
* BFD target vector write:: Output functions
|
* BFD target vector link:: Linker functions
|
* BFD target vector link:: Linker functions
|
* BFD target vector dynamic:: Dynamic linking information functions
|
* BFD target vector dynamic:: Dynamic linking information functions
|
@end menu
|
@end menu
|
|
|
@node BFD target vector miscellaneous
|
@node BFD target vector miscellaneous
|
@subsection Miscellaneous constants
|
@subsection Miscellaneous constants
|
|
|
The target vector starts with a set of constants.
|
The target vector starts with a set of constants.
|
|
|
@table @samp
|
@table @samp
|
@item name
|
@item name
|
The name of the target vector. This is an arbitrary string. This is
|
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
|
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
|
@item flavour
|
A general description of the type of target. The following flavours are
|
A general description of the type of target. The following flavours are
|
currently defined:
|
currently defined:
|
|
|
@table @samp
|
@table @samp
|
@item bfd_target_unknown_flavour
|
@item bfd_target_unknown_flavour
|
Undefined or unknown.
|
Undefined or unknown.
|
@item bfd_target_aout_flavour
|
@item bfd_target_aout_flavour
|
a.out.
|
a.out.
|
@item bfd_target_coff_flavour
|
@item bfd_target_coff_flavour
|
COFF.
|
COFF.
|
@item bfd_target_ecoff_flavour
|
@item bfd_target_ecoff_flavour
|
ECOFF.
|
ECOFF.
|
@item bfd_target_elf_flavour
|
@item bfd_target_elf_flavour
|
ELF.
|
ELF.
|
@item bfd_target_ieee_flavour
|
@item bfd_target_ieee_flavour
|
IEEE-695.
|
IEEE-695.
|
@item bfd_target_nlm_flavour
|
@item bfd_target_nlm_flavour
|
NLM.
|
NLM.
|
@item bfd_target_oasys_flavour
|
@item bfd_target_oasys_flavour
|
OASYS.
|
OASYS.
|
@item bfd_target_tekhex_flavour
|
@item bfd_target_tekhex_flavour
|
Tektronix hex format.
|
Tektronix hex format.
|
@item bfd_target_srec_flavour
|
@item bfd_target_srec_flavour
|
Motorola S-record format.
|
Motorola S-record format.
|
@item bfd_target_ihex_flavour
|
@item bfd_target_ihex_flavour
|
Intel hex format.
|
Intel hex format.
|
@item bfd_target_som_flavour
|
@item bfd_target_som_flavour
|
SOM (used on HP/UX).
|
SOM (used on HP/UX).
|
@item bfd_target_verilog_flavour
|
@item bfd_target_verilog_flavour
|
Verilog memory hex dump format.
|
Verilog memory hex dump format.
|
@item bfd_target_os9k_flavour
|
@item bfd_target_os9k_flavour
|
os9000.
|
os9000.
|
@item bfd_target_versados_flavour
|
@item bfd_target_versados_flavour
|
VERSAdos.
|
VERSAdos.
|
@item bfd_target_msdos_flavour
|
@item bfd_target_msdos_flavour
|
MS-DOS.
|
MS-DOS.
|
@item bfd_target_evax_flavour
|
@item bfd_target_evax_flavour
|
openVMS.
|
openVMS.
|
@item bfd_target_mmo_flavour
|
@item bfd_target_mmo_flavour
|
Donald Knuth's MMIXware object format.
|
Donald Knuth's MMIXware object format.
|
@end table
|
@end table
|
|
|
@item byteorder
|
@item byteorder
|
The byte order of data in the object file. One of
|
The byte order of data in the object file. One of
|
@samp{BFD_ENDIAN_BIG}, @samp{BFD_ENDIAN_LITTLE}, or
|
@samp{BFD_ENDIAN_BIG}, @samp{BFD_ENDIAN_LITTLE}, or
|
@samp{BFD_ENDIAN_UNKNOWN}. The latter would be used for a format such
|
@samp{BFD_ENDIAN_UNKNOWN}. The latter would be used for a format such
|
as S-records which do not record the architecture of the data.
|
as S-records which do not record the architecture of the data.
|
|
|
@item header_byteorder
|
@item header_byteorder
|
The byte order of header information in the object file. Normally the
|
The byte order of header information in the object file. Normally the
|
same as the @samp{byteorder} field, but there are certain cases where it
|
same as the @samp{byteorder} field, but there are certain cases where it
|
may be different.
|
may be different.
|
|
|
@item object_flags
|
@item object_flags
|
Flags which may appear in the @samp{flags} field of a BFD with this
|
Flags which may appear in the @samp{flags} field of a BFD with this
|
format.
|
format.
|
|
|
@item section_flags
|
@item section_flags
|
Flags which may appear in the @samp{flags} field of a section within a
|
Flags which may appear in the @samp{flags} field of a section within a
|
BFD with this format.
|
BFD with this format.
|
|
|
@item symbol_leading_char
|
@item symbol_leading_char
|
A character which the C compiler normally puts before a symbol. For
|
A character which the C compiler normally puts before a symbol. For
|
example, an a.out compiler will typically generate the symbol
|
example, an a.out compiler will typically generate the symbol
|
@samp{_foo} for a function named @samp{foo} in the C source, in which
|
@samp{_foo} for a function named @samp{foo} in the C source, in which
|
case this field would be @samp{_}. If there is no such character, this
|
case this field would be @samp{_}. If there is no such character, this
|
field will be @samp{0}.
|
field will be @samp{0}.
|
|
|
@item ar_pad_char
|
@item ar_pad_char
|
The padding character to use at the end of an archive name. Normally
|
The padding character to use at the end of an archive name. Normally
|
@samp{/}.
|
@samp{/}.
|
|
|
@item ar_max_namelen
|
@item ar_max_namelen
|
The maximum length of a short name in an archive. Normally @samp{14}.
|
The maximum length of a short name in an archive. Normally @samp{14}.
|
|
|
@item backend_data
|
@item backend_data
|
A pointer to constant backend data. This is used by backends to store
|
A pointer to constant backend data. This is used by backends to store
|
whatever additional information they need to distinguish similar target
|
whatever additional information they need to distinguish similar target
|
vectors which use the same sets of functions.
|
vectors which use the same sets of functions.
|
@end table
|
@end table
|
|
|
@node BFD target vector swap
|
@node BFD target vector swap
|
@subsection Swapping functions
|
@subsection Swapping functions
|
|
|
Every target vector has function 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
|
in and out of the target representation. There are two sets of
|
functions: one for data information, and one for header information.
|
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
|
Each set has three sizes: 64-bit, 32-bit, and 16-bit. Each size has
|
three actual functions: put, get unsigned, and get signed.
|
three actual functions: put, get unsigned, and get signed.
|
|
|
These 18 functions are used to convert data between the host and target
|
These 18 functions are used to convert data between the host and target
|
representations.
|
representations.
|
|
|
@node BFD target vector format
|
@node BFD target vector format
|
@subsection Format type dependent functions
|
@subsection Format type dependent functions
|
|
|
Every target vector has three arrays of function pointers which are
|
Every target vector has three arrays of function pointers which are
|
indexed by the BFD format type. The BFD format types are as follows:
|
indexed by the BFD format type. The BFD format types are as follows:
|
|
|
@table @samp
|
@table @samp
|
@item bfd_unknown
|
@item bfd_unknown
|
Unknown format. Not used for anything useful.
|
Unknown format. Not used for anything useful.
|
@item bfd_object
|
@item bfd_object
|
Object file.
|
Object file.
|
@item bfd_archive
|
@item bfd_archive
|
Archive file.
|
Archive file.
|
@item bfd_core
|
@item bfd_core
|
Core file.
|
Core file.
|
@end table
|
@end table
|
|
|
The three arrays of function pointers are as follows:
|
The three arrays of function pointers are as follows:
|
|
|
@table @samp
|
@table @samp
|
@item bfd_check_format
|
@item bfd_check_format
|
Check whether the BFD is of a particular format (object file, archive
|
Check whether the BFD is of a particular format (object file, archive
|
file, or core file) corresponding to this target vector. This is called
|
file, or core file) corresponding to this target vector. This is called
|
by the @samp{bfd_check_format} function when examining an existing BFD.
|
by the @samp{bfd_check_format} function when examining an existing BFD.
|
If the BFD matches the desired format, this function will initialize any
|
If the BFD matches the desired format, this function will initialize any
|
format specific information such as the @samp{tdata} field of the BFD.
|
format specific information such as the @samp{tdata} field of the BFD.
|
This function must be called before any other BFD target vector function
|
This function must be called before any other BFD target vector function
|
on a file opened for reading.
|
on a file opened for reading.
|
|
|
@item bfd_set_format
|
@item bfd_set_format
|
Set the format of a BFD which was created for output. This is called by
|
Set the format of a BFD which was created for output. This is called by
|
the @samp{bfd_set_format} function after creating the BFD with a
|
the @samp{bfd_set_format} function after creating the BFD with a
|
function such as @samp{bfd_openw}. This function will initialize format
|
function such as @samp{bfd_openw}. This function will initialize format
|
specific information required to write out an object file or whatever of
|
specific information required to write out an object file or whatever of
|
the given format. This function must be called before any other BFD
|
the given format. This function must be called before any other BFD
|
target vector function on a file opened for writing.
|
target vector function on a file opened for writing.
|
|
|
@item bfd_write_contents
|
@item bfd_write_contents
|
Write out the contents of the BFD in the given format. This is called
|
Write out the contents of the BFD in the given format. This is called
|
by @samp{bfd_close} function for a BFD opened for writing. This really
|
by @samp{bfd_close} function for a BFD opened for writing. This really
|
should not be an array selected by format type, as the
|
should not be an array selected by format type, as the
|
@samp{bfd_set_format} function provides all the required information.
|
@samp{bfd_set_format} function provides all the required information.
|
In fact, BFD will fail if a different format is used when calling
|
In fact, BFD will fail if a different format is used when calling
|
through the @samp{bfd_set_format} and the @samp{bfd_write_contents}
|
through the @samp{bfd_set_format} and the @samp{bfd_write_contents}
|
arrays; fortunately, since @samp{bfd_close} gets it right, this is a
|
arrays; fortunately, since @samp{bfd_close} gets it right, this is a
|
difficult error to make.
|
difficult error to make.
|
@end table
|
@end table
|
|
|
@node BFD_JUMP_TABLE macros
|
@node BFD_JUMP_TABLE macros
|
@subsection @samp{BFD_JUMP_TABLE} macros
|
@subsection @samp{BFD_JUMP_TABLE} macros
|
@cindex @samp{BFD_JUMP_TABLE}
|
@cindex @samp{BFD_JUMP_TABLE}
|
|
|
Most target vectors are defined using @samp{BFD_JUMP_TABLE} macros.
|
Most target vectors are defined using @samp{BFD_JUMP_TABLE} macros.
|
These macros take a single argument, which is a prefix applied to a set
|
These macros take a single argument, which is a prefix applied to a set
|
of functions. The macros are then used to initialize the fields in the
|
of functions. The macros are then used to initialize the fields in the
|
target vector.
|
target vector.
|
|
|
For example, the @samp{BFD_JUMP_TABLE_RELOCS} macro defines three
|
For example, the @samp{BFD_JUMP_TABLE_RELOCS} macro defines three
|
functions: @samp{_get_reloc_upper_bound}, @samp{_canonicalize_reloc},
|
functions: @samp{_get_reloc_upper_bound}, @samp{_canonicalize_reloc},
|
and @samp{_bfd_reloc_type_lookup}. A reference like
|
and @samp{_bfd_reloc_type_lookup}. A reference like
|
@samp{BFD_JUMP_TABLE_RELOCS (foo)} will expand into three functions
|
@samp{BFD_JUMP_TABLE_RELOCS (foo)} will expand into three functions
|
prefixed with @samp{foo}: @samp{foo_get_reloc_upper_bound}, 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
|
@samp{BFD_JUMP_TABLE_RELOCS} macro will be placed such that those three
|
functions initialize the appropriate fields in the BFD target vector.
|
functions initialize the appropriate fields in the BFD target vector.
|
|
|
This is done because it turns out that many different target vectors can
|
This is done because it turns out that many different target vectors can
|
share certain classes of functions. For example, archives are similar
|
share certain classes of functions. For example, archives are similar
|
on most platforms, so most target vectors can use the same archive
|
on most platforms, so most target vectors can use the same archive
|
functions. Those target vectors all use @samp{BFD_JUMP_TABLE_ARCHIVE}
|
functions. Those target vectors all use @samp{BFD_JUMP_TABLE_ARCHIVE}
|
with the same argument, calling a set of functions which is defined in
|
with the same argument, calling a set of functions which is defined in
|
@file{archive.c}.
|
@file{archive.c}.
|
|
|
Each of the @samp{BFD_JUMP_TABLE} macros is mentioned below along with
|
Each of the @samp{BFD_JUMP_TABLE} macros is mentioned below along with
|
the description of the function pointers which it defines. The function
|
the description of the function pointers which it defines. The function
|
pointers will be described using the name without the prefix which the
|
pointers will be described using the name without the prefix which the
|
@samp{BFD_JUMP_TABLE} macro defines. This name is normally the same as
|
@samp{BFD_JUMP_TABLE} macro defines. This name is normally the same as
|
the name of the field in the target vector structure. Any differences
|
the name of the field in the target vector structure. Any differences
|
will be noted.
|
will be noted.
|
|
|
@node BFD target vector generic
|
@node BFD target vector generic
|
@subsection Generic functions
|
@subsection Generic functions
|
@cindex @samp{BFD_JUMP_TABLE_GENERIC}
|
@cindex @samp{BFD_JUMP_TABLE_GENERIC}
|
|
|
The @samp{BFD_JUMP_TABLE_GENERIC} macro is used for some catch all
|
The @samp{BFD_JUMP_TABLE_GENERIC} macro is used for some catch all
|
functions which don't easily fit into other categories.
|
functions which don't easily fit into other categories.
|
|
|
@table @samp
|
@table @samp
|
@item _close_and_cleanup
|
@item _close_and_cleanup
|
Free any target specific information associated with the BFD. This is
|
Free any target specific information associated with the BFD. This is
|
called when any BFD is closed (the @samp{bfd_write_contents} function
|
called when any BFD is closed (the @samp{bfd_write_contents} function
|
mentioned earlier is only called for a BFD opened for writing). Most
|
mentioned earlier is only called for a BFD opened for writing). Most
|
targets use @samp{bfd_alloc} to allocate all target specific
|
targets use @samp{bfd_alloc} to allocate all target specific
|
information, and therefore don't have to do anything in this function.
|
information, and therefore don't have to do anything in this function.
|
This function pointer is typically set to
|
This function pointer is typically set to
|
@samp{_bfd_generic_close_and_cleanup}, which simply returns true.
|
@samp{_bfd_generic_close_and_cleanup}, which simply returns true.
|
|
|
@item _bfd_free_cached_info
|
@item _bfd_free_cached_info
|
Free any cached information associated with the BFD which can be
|
Free any cached information associated with the BFD which can be
|
recreated later if necessary. This is used to reduce the memory
|
recreated later if necessary. This is used to reduce the memory
|
consumption required by programs using BFD. This is normally called via
|
consumption required by programs using BFD. This is normally called via
|
the @samp{bfd_free_cached_info} macro. It is used by the default
|
the @samp{bfd_free_cached_info} macro. It is used by the default
|
archive routines when computing the archive map. Most targets do not
|
archive routines when computing the archive map. Most targets do not
|
do anything special for this entry point, and just set it to
|
do anything special for this entry point, and just set it to
|
@samp{_bfd_generic_free_cached_info}, which simply returns true.
|
@samp{_bfd_generic_free_cached_info}, which simply returns true.
|
|
|
@item _new_section_hook
|
@item _new_section_hook
|
This is called from @samp{bfd_make_section_anyway} whenever a new
|
This is called from @samp{bfd_make_section_anyway} whenever a new
|
section is created. Most targets use it to initialize section specific
|
section is created. Most targets use it to initialize section specific
|
information. This function is called whether or not the section
|
information. This function is called whether or not the section
|
corresponds to an actual section in an actual BFD.
|
corresponds to an actual section in an actual BFD.
|
|
|
@item _get_section_contents
|
@item _get_section_contents
|
Get the contents of a section. This is called from
|
Get the contents of a section. This is called from
|
@samp{bfd_get_section_contents}. Most targets set this to
|
@samp{bfd_get_section_contents}. Most targets set this to
|
@samp{_bfd_generic_get_section_contents}, which does a @samp{bfd_seek}
|
@samp{_bfd_generic_get_section_contents}, which does a @samp{bfd_seek}
|
based on the section's @samp{filepos} field and a @samp{bfd_bread}. The
|
based on the section's @samp{filepos} field and a @samp{bfd_bread}. The
|
corresponding field in the target vector is named
|
corresponding field in the target vector is named
|
@samp{_bfd_get_section_contents}.
|
@samp{_bfd_get_section_contents}.
|
|
|
@item _get_section_contents_in_window
|
@item _get_section_contents_in_window
|
Set a @samp{bfd_window} to hold the contents of a section. This is
|
Set a @samp{bfd_window} to hold the contents of a section. This is
|
called from @samp{bfd_get_section_contents_in_window}. The
|
called from @samp{bfd_get_section_contents_in_window}. The
|
@samp{bfd_window} idea never really caught on, and I don't think this is
|
@samp{bfd_window} idea never really caught on, and I don't think this is
|
ever called. Pretty much all targets implement this as
|
ever called. Pretty much all targets implement this as
|
@samp{bfd_generic_get_section_contents_in_window}, which uses
|
@samp{bfd_generic_get_section_contents_in_window}, which uses
|
@samp{bfd_get_section_contents} to do the right thing. The
|
@samp{bfd_get_section_contents} to do the right thing. The
|
corresponding field in the target vector is named
|
corresponding field in the target vector is named
|
@samp{_bfd_get_section_contents_in_window}.
|
@samp{_bfd_get_section_contents_in_window}.
|
@end table
|
@end table
|
|
|
@node BFD target vector copy
|
@node BFD target vector copy
|
@subsection Copy functions
|
@subsection Copy functions
|
@cindex @samp{BFD_JUMP_TABLE_COPY}
|
@cindex @samp{BFD_JUMP_TABLE_COPY}
|
|
|
The @samp{BFD_JUMP_TABLE_COPY} macro is used for functions which are
|
The @samp{BFD_JUMP_TABLE_COPY} macro is used for functions which are
|
called when copying BFDs, and for a couple of functions which deal with
|
called when copying BFDs, and for a couple of functions which deal with
|
internal BFD information.
|
internal BFD information.
|
|
|
@table @samp
|
@table @samp
|
@item _bfd_copy_private_bfd_data
|
@item _bfd_copy_private_bfd_data
|
This is called when copying a BFD, via @samp{bfd_copy_private_bfd_data}.
|
This is called when copying a BFD, via @samp{bfd_copy_private_bfd_data}.
|
If the input and output BFDs have the same format, this will copy any
|
If the input and output BFDs have the same format, this will copy any
|
private information over. This is called after all the section contents
|
private information over. This is called after all the section contents
|
have been written to the output file. Only a few targets do anything in
|
have been written to the output file. Only a few targets do anything in
|
this function.
|
this function.
|
|
|
@item _bfd_merge_private_bfd_data
|
@item _bfd_merge_private_bfd_data
|
This is called when linking, via @samp{bfd_merge_private_bfd_data}. It
|
This is called when linking, via @samp{bfd_merge_private_bfd_data}. It
|
gives the backend linker code a chance to set any special flags in the
|
gives the backend linker code a chance to set any special flags in the
|
output file based on the contents of the input file. Only a few targets
|
output file based on the contents of the input file. Only a few targets
|
do anything in this function.
|
do anything in this function.
|
|
|
@item _bfd_copy_private_section_data
|
@item _bfd_copy_private_section_data
|
This is similar to @samp{_bfd_copy_private_bfd_data}, but it is called
|
This is similar to @samp{_bfd_copy_private_bfd_data}, but it is called
|
for each section, via @samp{bfd_copy_private_section_data}. This
|
for each section, via @samp{bfd_copy_private_section_data}. This
|
function is called before any section contents have been written. Only
|
function is called before any section contents have been written. Only
|
a few targets do anything in this function.
|
a few targets do anything in this function.
|
|
|
@item _bfd_copy_private_symbol_data
|
@item _bfd_copy_private_symbol_data
|
This is called via @samp{bfd_copy_private_symbol_data}, but I don't
|
This is called via @samp{bfd_copy_private_symbol_data}, but I don't
|
think anything actually calls it. If it were defined, it could be used
|
think anything actually calls it. If it were defined, it could be used
|
to copy private symbol data from one BFD to another. However, most BFDs
|
to copy private symbol data from one BFD to another. However, most BFDs
|
store extra symbol information by allocating space which is larger than
|
store extra symbol information by allocating space which is larger than
|
the @samp{asymbol} structure and storing private information in the
|
the @samp{asymbol} structure and storing private information in the
|
extra space. Since @samp{objcopy} and other programs copy symbol
|
extra space. Since @samp{objcopy} and other programs copy symbol
|
information by copying pointers to @samp{asymbol} structures, the
|
information by copying pointers to @samp{asymbol} structures, the
|
private symbol information is automatically copied as well. Most
|
private symbol information is automatically copied as well. Most
|
targets do not do anything in this function.
|
targets do not do anything in this function.
|
|
|
@item _bfd_set_private_flags
|
@item _bfd_set_private_flags
|
This is called via @samp{bfd_set_private_flags}. It is basically a hook
|
This is called via @samp{bfd_set_private_flags}. It is basically a hook
|
for the assembler to set magic information. For example, the PowerPC
|
for the assembler to set magic information. For example, the PowerPC
|
ELF assembler uses it to set flags which appear in the e_flags field of
|
ELF assembler uses it to set flags which appear in the e_flags field of
|
the ELF header. Most targets do not do anything in this function.
|
the ELF header. Most targets do not do anything in this function.
|
|
|
@item _bfd_print_private_bfd_data
|
@item _bfd_print_private_bfd_data
|
This is called by @samp{objdump} when the @samp{-p} option is used. It
|
This is called by @samp{objdump} when the @samp{-p} option is used. It
|
is called via @samp{bfd_print_private_data}. It prints any interesting
|
is called via @samp{bfd_print_private_data}. It prints any interesting
|
information about the BFD which can not be otherwise represented by BFD
|
information about the BFD which can not be otherwise represented by BFD
|
and thus can not be printed by @samp{objdump}. Most targets do not do
|
and thus can not be printed by @samp{objdump}. Most targets do not do
|
anything in this function.
|
anything in this function.
|
@end table
|
@end table
|
|
|
@node BFD target vector core
|
@node BFD target vector core
|
@subsection Core file support functions
|
@subsection Core file support functions
|
@cindex @samp{BFD_JUMP_TABLE_CORE}
|
@cindex @samp{BFD_JUMP_TABLE_CORE}
|
|
|
The @samp{BFD_JUMP_TABLE_CORE} macro is used for functions which deal
|
The @samp{BFD_JUMP_TABLE_CORE} macro is used for functions which deal
|
with core files. Obviously, these functions only do something
|
with core files. Obviously, these functions only do something
|
interesting for targets which have core file support.
|
interesting for targets which have core file support.
|
|
|
@table @samp
|
@table @samp
|
@item _core_file_failing_command
|
@item _core_file_failing_command
|
Given a core file, this returns the command which was run to produce the
|
Given a core file, this returns the command which was run to produce the
|
core file.
|
core file.
|
|
|
@item _core_file_failing_signal
|
@item _core_file_failing_signal
|
Given a core file, this returns the signal number which produced the
|
Given a core file, this returns the signal number which produced the
|
core file.
|
core file.
|
|
|
@item _core_file_matches_executable_p
|
@item _core_file_matches_executable_p
|
Given a core file and a BFD for an executable, this returns whether the
|
Given a core file and a BFD for an executable, this returns whether the
|
core file was generated by the executable.
|
core file was generated by the executable.
|
@end table
|
@end table
|
|
|
@node BFD target vector archive
|
@node BFD target vector archive
|
@subsection Archive functions
|
@subsection Archive functions
|
@cindex @samp{BFD_JUMP_TABLE_ARCHIVE}
|
@cindex @samp{BFD_JUMP_TABLE_ARCHIVE}
|
|
|
The @samp{BFD_JUMP_TABLE_ARCHIVE} macro is used for functions which deal
|
The @samp{BFD_JUMP_TABLE_ARCHIVE} macro is used for functions which deal
|
with archive files. Most targets use COFF style archive files
|
with archive files. Most targets use COFF style archive files
|
(including ELF targets), and these use @samp{_bfd_archive_coff} as the
|
(including ELF targets), and these use @samp{_bfd_archive_coff} as the
|
argument to @samp{BFD_JUMP_TABLE_ARCHIVE}. Some targets use BSD/a.out
|
argument to @samp{BFD_JUMP_TABLE_ARCHIVE}. Some targets use BSD/a.out
|
style archives, and these use @samp{_bfd_archive_bsd}. (The main
|
style archives, and these use @samp{_bfd_archive_bsd}. (The main
|
difference between BSD and COFF archives is the format of the archive
|
difference between BSD and COFF archives is the format of the archive
|
symbol table). Targets with no archive support use
|
symbol table). Targets with no archive support use
|
@samp{_bfd_noarchive}. Finally, a few targets have unusual archive
|
@samp{_bfd_noarchive}. Finally, a few targets have unusual archive
|
handling.
|
handling.
|
|
|
@table @samp
|
@table @samp
|
@item _slurp_armap
|
@item _slurp_armap
|
Read in the archive symbol table, storing it in private BFD data. This
|
Read in the archive symbol table, storing it in private BFD data. This
|
is normally called from the archive @samp{check_format} routine. The
|
is normally called from the archive @samp{check_format} routine. The
|
corresponding field in the target vector is named
|
corresponding field in the target vector is named
|
@samp{_bfd_slurp_armap}.
|
@samp{_bfd_slurp_armap}.
|
|
|
@item _slurp_extended_name_table
|
@item _slurp_extended_name_table
|
Read in the extended name table from the archive, if there is one,
|
Read in the extended name table from the archive, if there is one,
|
storing it in private BFD data. This is normally called from the
|
storing it in private BFD data. This is normally called from the
|
archive @samp{check_format} routine. The corresponding field in the
|
archive @samp{check_format} routine. The corresponding field in the
|
target vector is named @samp{_bfd_slurp_extended_name_table}.
|
target vector is named @samp{_bfd_slurp_extended_name_table}.
|
|
|
@item construct_extended_name_table
|
@item construct_extended_name_table
|
Build and return an extended name table if one is needed to write out
|
Build and return an extended name table if one is needed to write out
|
the archive. This also adjusts the archive headers to refer to the
|
the archive. This also adjusts the archive headers to refer to the
|
extended name table appropriately. This is normally called from the
|
extended name table appropriately. This is normally called from the
|
archive @samp{write_contents} routine. The corresponding field in the
|
archive @samp{write_contents} routine. The corresponding field in the
|
target vector is named @samp{_bfd_construct_extended_name_table}.
|
target vector is named @samp{_bfd_construct_extended_name_table}.
|
|
|
@item _truncate_arname
|
@item _truncate_arname
|
This copies a file name into an archive header, truncating it as
|
This copies a file name into an archive header, truncating it as
|
required. It is normally called from the archive @samp{write_contents}
|
required. It is normally called from the archive @samp{write_contents}
|
routine. This function is more interesting in targets which do not
|
routine. This function is more interesting in targets which do not
|
support extended name tables, but I think the GNU @samp{ar} program
|
support extended name tables, but I think the GNU @samp{ar} program
|
always uses extended name tables anyhow. The corresponding field in the
|
always uses extended name tables anyhow. The corresponding field in the
|
target vector is named @samp{_bfd_truncate_arname}.
|
target vector is named @samp{_bfd_truncate_arname}.
|
|
|
@item _write_armap
|
@item _write_armap
|
Write out the archive symbol table using calls to @samp{bfd_bwrite}.
|
Write out the archive symbol table using calls to @samp{bfd_bwrite}.
|
This is normally called from the archive @samp{write_contents} routine.
|
This is normally called from the archive @samp{write_contents} routine.
|
The corresponding field in the target vector is named @samp{write_armap}
|
The corresponding field in the target vector is named @samp{write_armap}
|
(no leading underscore).
|
(no leading underscore).
|
|
|
@item _read_ar_hdr
|
@item _read_ar_hdr
|
Read and parse an archive header. This handles expanding the archive
|
Read and parse an archive header. This handles expanding the archive
|
header name into the real file name using the extended name table. This
|
header name into the real file name using the extended name table. This
|
is called by routines which read the archive symbol table or the archive
|
is called by routines which read the archive symbol table or the archive
|
itself. The corresponding field in the target vector is named
|
itself. The corresponding field in the target vector is named
|
@samp{_bfd_read_ar_hdr_fn}.
|
@samp{_bfd_read_ar_hdr_fn}.
|
|
|
@item _openr_next_archived_file
|
@item _openr_next_archived_file
|
Given an archive and a BFD representing a file stored within the
|
Given an archive and a BFD representing a file stored within the
|
archive, return a BFD for the next file in the archive. This is called
|
archive, return a BFD for the next file in the archive. This is called
|
via @samp{bfd_openr_next_archived_file}. The corresponding field in the
|
via @samp{bfd_openr_next_archived_file}. The corresponding field in the
|
target vector is named @samp{openr_next_archived_file} (no leading
|
target vector is named @samp{openr_next_archived_file} (no leading
|
underscore).
|
underscore).
|
|
|
@item _get_elt_at_index
|
@item _get_elt_at_index
|
Given an archive and an index, return a BFD for the file in the archive
|
Given an archive and an index, return a BFD for the file in the archive
|
corresponding to that entry in the archive symbol table. This is called
|
corresponding to that entry in the archive symbol table. This is called
|
via @samp{bfd_get_elt_at_index}. The corresponding field in the target
|
via @samp{bfd_get_elt_at_index}. The corresponding field in the target
|
vector is named @samp{_bfd_get_elt_at_index}.
|
vector is named @samp{_bfd_get_elt_at_index}.
|
|
|
@item _generic_stat_arch_elt
|
@item _generic_stat_arch_elt
|
Do a stat on an element of an archive, returning information read from
|
Do a stat on an element of an archive, returning information read from
|
the archive header (modification time, uid, gid, file mode, size). This
|
the archive header (modification time, uid, gid, file mode, size). This
|
is called via @samp{bfd_stat_arch_elt}. The corresponding field in the
|
is called via @samp{bfd_stat_arch_elt}. The corresponding field in the
|
target vector is named @samp{_bfd_stat_arch_elt}.
|
target vector is named @samp{_bfd_stat_arch_elt}.
|
|
|
@item _update_armap_timestamp
|
@item _update_armap_timestamp
|
After the entire contents of an archive have been written out, update
|
After the entire contents of an archive have been written out, update
|
the timestamp of the archive symbol table to be newer than that of the
|
the timestamp of the archive symbol table to be newer than that of the
|
file. This is required for a.out style archives. This is normally
|
file. This is required for a.out style archives. This is normally
|
called by the archive @samp{write_contents} routine. The corresponding
|
called by the archive @samp{write_contents} routine. The corresponding
|
field in the target vector is named @samp{_bfd_update_armap_timestamp}.
|
field in the target vector is named @samp{_bfd_update_armap_timestamp}.
|
@end table
|
@end table
|
|
|
@node BFD target vector symbols
|
@node BFD target vector symbols
|
@subsection Symbol table functions
|
@subsection Symbol table functions
|
@cindex @samp{BFD_JUMP_TABLE_SYMBOLS}
|
@cindex @samp{BFD_JUMP_TABLE_SYMBOLS}
|
|
|
The @samp{BFD_JUMP_TABLE_SYMBOLS} macro is used for functions which deal
|
The @samp{BFD_JUMP_TABLE_SYMBOLS} macro is used for functions which deal
|
with symbols.
|
with symbols.
|
|
|
@table @samp
|
@table @samp
|
@item _get_symtab_upper_bound
|
@item _get_symtab_upper_bound
|
Return a sensible upper bound on the amount of memory which will be
|
Return a sensible upper bound on the amount of memory which will be
|
required to read the symbol table. In practice most targets return the
|
required to read the symbol table. In practice most targets return the
|
amount of memory required to hold @samp{asymbol} pointers for all the
|
amount of memory required to hold @samp{asymbol} pointers for all the
|
symbols plus a trailing @samp{NULL} entry, and store the actual symbol
|
symbols plus a trailing @samp{NULL} entry, and store the actual symbol
|
information in BFD private data. This is called via
|
information in BFD private data. This is called via
|
@samp{bfd_get_symtab_upper_bound}. The corresponding field in the
|
@samp{bfd_get_symtab_upper_bound}. The corresponding field in the
|
target vector is named @samp{_bfd_get_symtab_upper_bound}.
|
target vector is named @samp{_bfd_get_symtab_upper_bound}.
|
|
|
@item _canonicalize_symtab
|
@item _canonicalize_symtab
|
Read in the symbol table. This is called via
|
Read in the symbol table. This is called via
|
@samp{bfd_canonicalize_symtab}. The corresponding field in the target
|
@samp{bfd_canonicalize_symtab}. The corresponding field in the target
|
vector is named @samp{_bfd_canonicalize_symtab}.
|
vector is named @samp{_bfd_canonicalize_symtab}.
|
|
|
@item _make_empty_symbol
|
@item _make_empty_symbol
|
Create an empty symbol for the BFD. This is needed because most targets
|
Create an empty symbol for the BFD. This is needed because most targets
|
store extra information with each symbol by allocating a structure
|
store extra information with each symbol by allocating a structure
|
larger than an @samp{asymbol} and storing the extra information at the
|
larger than an @samp{asymbol} and storing the extra information at the
|
end. This function will allocate the right amount of memory, and return
|
end. This function will allocate the right amount of memory, and return
|
what looks like a pointer to an empty @samp{asymbol}. This is called
|
what looks like a pointer to an empty @samp{asymbol}. This is called
|
via @samp{bfd_make_empty_symbol}. The corresponding field in the target
|
via @samp{bfd_make_empty_symbol}. The corresponding field in the target
|
vector is named @samp{_bfd_make_empty_symbol}.
|
vector is named @samp{_bfd_make_empty_symbol}.
|
|
|
@item _print_symbol
|
@item _print_symbol
|
Print information about the symbol. This is called via
|
Print information about the symbol. This is called via
|
@samp{bfd_print_symbol}. One of the arguments indicates what sort of
|
@samp{bfd_print_symbol}. One of the arguments indicates what sort of
|
information should be printed:
|
information should be printed:
|
|
|
@table @samp
|
@table @samp
|
@item bfd_print_symbol_name
|
@item bfd_print_symbol_name
|
Just print the symbol name.
|
Just print the symbol name.
|
@item bfd_print_symbol_more
|
@item bfd_print_symbol_more
|
Print the symbol name and some interesting flags. I don't think
|
Print the symbol name and some interesting flags. I don't think
|
anything actually uses this.
|
anything actually uses this.
|
@item bfd_print_symbol_all
|
@item bfd_print_symbol_all
|
Print all information about the symbol. This is used by @samp{objdump}
|
Print all information about the symbol. This is used by @samp{objdump}
|
when run with the @samp{-t} option.
|
when run with the @samp{-t} option.
|
@end table
|
@end table
|
The corresponding field in the target vector is named
|
The corresponding field in the target vector is named
|
@samp{_bfd_print_symbol}.
|
@samp{_bfd_print_symbol}.
|
|
|
@item _get_symbol_info
|
@item _get_symbol_info
|
Return a standard set of information about the symbol. This is called
|
Return a standard set of information about the symbol. This is called
|
via @samp{bfd_symbol_info}. The corresponding field in the target
|
via @samp{bfd_symbol_info}. The corresponding field in the target
|
vector is named @samp{_bfd_get_symbol_info}.
|
vector is named @samp{_bfd_get_symbol_info}.
|
|
|
@item _bfd_is_local_label_name
|
@item _bfd_is_local_label_name
|
Return whether the given string would normally represent the name of a
|
Return whether the given string would normally represent the name of a
|
local label. This is called via @samp{bfd_is_local_label} and
|
local label. This is called via @samp{bfd_is_local_label} and
|
@samp{bfd_is_local_label_name}. Local labels are normally discarded by
|
@samp{bfd_is_local_label_name}. Local labels are normally discarded by
|
the assembler. In the linker, this defines the difference between the
|
the assembler. In the linker, this defines the difference between the
|
@samp{-x} and @samp{-X} options.
|
@samp{-x} and @samp{-X} options.
|
|
|
@item _get_lineno
|
@item _get_lineno
|
Return line number information for a symbol. This is only meaningful
|
Return line number information for a symbol. This is only meaningful
|
for a COFF target. This is called when writing out COFF line numbers.
|
for a COFF target. This is called when writing out COFF line numbers.
|
|
|
@item _find_nearest_line
|
@item _find_nearest_line
|
Given an address within a section, use the debugging information to find
|
Given an address within a section, use the debugging information to find
|
the matching file name, function name, and line number, if any. This is
|
the matching file name, function name, and line number, if any. This is
|
called via @samp{bfd_find_nearest_line}. The corresponding field in the
|
called via @samp{bfd_find_nearest_line}. The corresponding field in the
|
target vector is named @samp{_bfd_find_nearest_line}.
|
target vector is named @samp{_bfd_find_nearest_line}.
|
|
|
@item _bfd_make_debug_symbol
|
@item _bfd_make_debug_symbol
|
Make a debugging symbol. This is only meaningful for a COFF target,
|
Make a debugging symbol. This is only meaningful for a COFF target,
|
where it simply returns a symbol which will be placed in the
|
where it simply returns a symbol which will be placed in the
|
@samp{N_DEBUG} section when it is written out. This is called via
|
@samp{N_DEBUG} section when it is written out. This is called via
|
@samp{bfd_make_debug_symbol}.
|
@samp{bfd_make_debug_symbol}.
|
|
|
@item _read_minisymbols
|
@item _read_minisymbols
|
Minisymbols are used to reduce the memory requirements of programs like
|
Minisymbols are used to reduce the memory requirements of programs like
|
@samp{nm}. A minisymbol is a cookie pointing to internal symbol
|
@samp{nm}. A minisymbol is a cookie pointing to internal symbol
|
information which the caller can use to extract complete symbol
|
information which the caller can use to extract complete symbol
|
information. This permits BFD to not convert all the symbols into
|
information. This permits BFD to not convert all the symbols into
|
generic form, but to instead convert them one at a time. This is called
|
generic form, but to instead convert them one at a time. This is called
|
via @samp{bfd_read_minisymbols}. Most targets do not implement this,
|
via @samp{bfd_read_minisymbols}. Most targets do not implement this,
|
and just use generic support which is based on using standard
|
and just use generic support which is based on using standard
|
@samp{asymbol} structures.
|
@samp{asymbol} structures.
|
|
|
@item _minisymbol_to_symbol
|
@item _minisymbol_to_symbol
|
Convert a minisymbol to a standard @samp{asymbol}. This is called via
|
Convert a minisymbol to a standard @samp{asymbol}. This is called via
|
@samp{bfd_minisymbol_to_symbol}.
|
@samp{bfd_minisymbol_to_symbol}.
|
@end table
|
@end table
|
|
|
@node BFD target vector relocs
|
@node BFD target vector relocs
|
@subsection Relocation support
|
@subsection Relocation support
|
@cindex @samp{BFD_JUMP_TABLE_RELOCS}
|
@cindex @samp{BFD_JUMP_TABLE_RELOCS}
|
|
|
The @samp{BFD_JUMP_TABLE_RELOCS} macro is used for functions which deal
|
The @samp{BFD_JUMP_TABLE_RELOCS} macro is used for functions which deal
|
with relocations.
|
with relocations.
|
|
|
@table @samp
|
@table @samp
|
@item _get_reloc_upper_bound
|
@item _get_reloc_upper_bound
|
Return a sensible upper bound on the amount of memory which will be
|
Return a sensible upper bound on the amount of memory which will be
|
required to read the relocations for a section. In practice most
|
required to read the relocations for a section. In practice most
|
targets return the amount of memory required to hold @samp{arelent}
|
targets return the amount of memory required to hold @samp{arelent}
|
pointers for all the relocations plus a trailing @samp{NULL} entry, and
|
pointers for all the relocations plus a trailing @samp{NULL} entry, and
|
store the actual relocation information in BFD private data. This is
|
store the actual relocation information in BFD private data. This is
|
called via @samp{bfd_get_reloc_upper_bound}.
|
called via @samp{bfd_get_reloc_upper_bound}.
|
|
|
@item _canonicalize_reloc
|
@item _canonicalize_reloc
|
Return the relocation information for a section. This is called via
|
Return the relocation information for a section. This is called via
|
@samp{bfd_canonicalize_reloc}. The corresponding field in the target
|
@samp{bfd_canonicalize_reloc}. The corresponding field in the target
|
vector is named @samp{_bfd_canonicalize_reloc}.
|
vector is named @samp{_bfd_canonicalize_reloc}.
|
|
|
@item _bfd_reloc_type_lookup
|
@item _bfd_reloc_type_lookup
|
Given a relocation code, return the corresponding howto structure
|
Given a relocation code, return the corresponding howto structure
|
(@pxref{BFD relocation codes}). This is called via
|
(@pxref{BFD relocation codes}). This is called via
|
@samp{bfd_reloc_type_lookup}. The corresponding field in the target
|
@samp{bfd_reloc_type_lookup}. The corresponding field in the target
|
vector is named @samp{reloc_type_lookup}.
|
vector is named @samp{reloc_type_lookup}.
|
@end table
|
@end table
|
|
|
@node BFD target vector write
|
@node BFD target vector write
|
@subsection Output functions
|
@subsection Output functions
|
@cindex @samp{BFD_JUMP_TABLE_WRITE}
|
@cindex @samp{BFD_JUMP_TABLE_WRITE}
|
|
|
The @samp{BFD_JUMP_TABLE_WRITE} macro is used for functions which deal
|
The @samp{BFD_JUMP_TABLE_WRITE} macro is used for functions which deal
|
with writing out a BFD.
|
with writing out a BFD.
|
|
|
@table @samp
|
@table @samp
|
@item _set_arch_mach
|
@item _set_arch_mach
|
Set the architecture and machine number for a BFD. This is called via
|
Set the architecture and machine number for a BFD. This is called via
|
@samp{bfd_set_arch_mach}. Most targets implement this by calling
|
@samp{bfd_set_arch_mach}. Most targets implement this by calling
|
@samp{bfd_default_set_arch_mach}. The corresponding field in the target
|
@samp{bfd_default_set_arch_mach}. The corresponding field in the target
|
vector is named @samp{_bfd_set_arch_mach}.
|
vector is named @samp{_bfd_set_arch_mach}.
|
|
|
@item _set_section_contents
|
@item _set_section_contents
|
Write out the contents of a section. This is called via
|
Write out the contents of a section. This is called via
|
@samp{bfd_set_section_contents}. The corresponding field in the target
|
@samp{bfd_set_section_contents}. The corresponding field in the target
|
vector is named @samp{_bfd_set_section_contents}.
|
vector is named @samp{_bfd_set_section_contents}.
|
@end table
|
@end table
|
|
|
@node BFD target vector link
|
@node BFD target vector link
|
@subsection Linker functions
|
@subsection Linker functions
|
@cindex @samp{BFD_JUMP_TABLE_LINK}
|
@cindex @samp{BFD_JUMP_TABLE_LINK}
|
|
|
The @samp{BFD_JUMP_TABLE_LINK} macro is used for functions called by the
|
The @samp{BFD_JUMP_TABLE_LINK} macro is used for functions called by the
|
linker.
|
linker.
|
|
|
@table @samp
|
@table @samp
|
@item _sizeof_headers
|
@item _sizeof_headers
|
Return the size of the header information required for a BFD. This is
|
Return the size of the header information required for a BFD. This is
|
used to implement the @samp{SIZEOF_HEADERS} linker script function. It
|
used to implement the @samp{SIZEOF_HEADERS} linker script function. It
|
is normally used to align the first section at an efficient position on
|
is normally used to align the first section at an efficient position on
|
the page. This is called via @samp{bfd_sizeof_headers}. The
|
the page. This is called via @samp{bfd_sizeof_headers}. The
|
corresponding field in the target vector is named
|
corresponding field in the target vector is named
|
@samp{_bfd_sizeof_headers}.
|
@samp{_bfd_sizeof_headers}.
|
|
|
@item _bfd_get_relocated_section_contents
|
@item _bfd_get_relocated_section_contents
|
Read the contents of a section and apply the relocation information.
|
Read the contents of a section and apply the relocation information.
|
This handles both a final link and a relocatable 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
|
case, it adjust the relocation information as well. This is called via
|
@samp{bfd_get_relocated_section_contents}. Most targets implement it by
|
@samp{bfd_get_relocated_section_contents}. Most targets implement it by
|
calling @samp{bfd_generic_get_relocated_section_contents}.
|
calling @samp{bfd_generic_get_relocated_section_contents}.
|
|
|
@item _bfd_relax_section
|
@item _bfd_relax_section
|
Try to use relaxation to shrink the size of a section. This is called
|
Try to use relaxation to shrink the size of a section. This is called
|
by the linker when the @samp{-relax} option is used. This is called via
|
by the linker when the @samp{-relax} option is used. This is called via
|
@samp{bfd_relax_section}. Most targets do not support any sort of
|
@samp{bfd_relax_section}. Most targets do not support any sort of
|
relaxation.
|
relaxation.
|
|
|
@item _bfd_link_hash_table_create
|
@item _bfd_link_hash_table_create
|
Create the symbol hash table to use for the linker. This linker hook
|
Create the symbol hash table to use for the linker. This linker hook
|
permits the backend to control the size and information of the elements
|
permits the backend to control the size and information of the elements
|
in the linker symbol hash table. This is called via
|
in the linker symbol hash table. This is called via
|
@samp{bfd_link_hash_table_create}.
|
@samp{bfd_link_hash_table_create}.
|
|
|
@item _bfd_link_add_symbols
|
@item _bfd_link_add_symbols
|
Given an object file or an archive, add all symbols into the linker
|
Given an object file or an archive, add all symbols into the linker
|
symbol hash table. Use callbacks to the linker to include archive
|
symbol hash table. Use callbacks to the linker to include archive
|
elements in the link. This is called via @samp{bfd_link_add_symbols}.
|
elements in the link. This is called via @samp{bfd_link_add_symbols}.
|
|
|
@item _bfd_final_link
|
@item _bfd_final_link
|
Finish the linking process. The linker calls this hook after all of the
|
Finish the linking process. The linker calls this hook after all of the
|
input files have been read, when it is ready to finish the link and
|
input files have been read, when it is ready to finish the link and
|
generate the output file. This is called via @samp{bfd_final_link}.
|
generate the output file. This is called via @samp{bfd_final_link}.
|
|
|
@item _bfd_link_split_section
|
@item _bfd_link_split_section
|
I don't know what this is for. Nothing seems to call it. The only
|
I don't know what this is for. Nothing seems to call it. The only
|
non-trivial definition is in @file{som.c}.
|
non-trivial definition is in @file{som.c}.
|
@end table
|
@end table
|
|
|
@node BFD target vector dynamic
|
@node BFD target vector dynamic
|
@subsection Dynamic linking information functions
|
@subsection Dynamic linking information functions
|
@cindex @samp{BFD_JUMP_TABLE_DYNAMIC}
|
@cindex @samp{BFD_JUMP_TABLE_DYNAMIC}
|
|
|
The @samp{BFD_JUMP_TABLE_DYNAMIC} macro is used for functions which read
|
The @samp{BFD_JUMP_TABLE_DYNAMIC} macro is used for functions which read
|
dynamic linking information.
|
dynamic linking information.
|
|
|
@table @samp
|
@table @samp
|
@item _get_dynamic_symtab_upper_bound
|
@item _get_dynamic_symtab_upper_bound
|
Return a sensible upper bound on the amount of memory which will be
|
Return a sensible upper bound on the amount of memory which will be
|
required to read the dynamic symbol table. In practice most targets
|
required to read the dynamic symbol table. In practice most targets
|
return the amount of memory required to hold @samp{asymbol} pointers for
|
return the amount of memory required to hold @samp{asymbol} pointers for
|
all the symbols plus a trailing @samp{NULL} entry, and store the actual
|
all the symbols plus a trailing @samp{NULL} entry, and store the actual
|
symbol information in BFD private data. This is called via
|
symbol information in BFD private data. This is called via
|
@samp{bfd_get_dynamic_symtab_upper_bound}. The corresponding field in
|
@samp{bfd_get_dynamic_symtab_upper_bound}. The corresponding field in
|
the target vector is named @samp{_bfd_get_dynamic_symtab_upper_bound}.
|
the target vector is named @samp{_bfd_get_dynamic_symtab_upper_bound}.
|
|
|
@item _canonicalize_dynamic_symtab
|
@item _canonicalize_dynamic_symtab
|
Read the dynamic symbol table. This is called via
|
Read the dynamic symbol table. This is called via
|
@samp{bfd_canonicalize_dynamic_symtab}. The corresponding field in the
|
@samp{bfd_canonicalize_dynamic_symtab}. The corresponding field in the
|
target vector is named @samp{_bfd_canonicalize_dynamic_symtab}.
|
target vector is named @samp{_bfd_canonicalize_dynamic_symtab}.
|
|
|
@item _get_dynamic_reloc_upper_bound
|
@item _get_dynamic_reloc_upper_bound
|
Return a sensible upper bound on the amount of memory which will be
|
Return a sensible upper bound on the amount of memory which will be
|
required to read the dynamic relocations. In practice most targets
|
required to read the dynamic relocations. In practice most targets
|
return the amount of memory required to hold @samp{arelent} pointers for
|
return the amount of memory required to hold @samp{arelent} pointers for
|
all the relocations plus a trailing @samp{NULL} entry, and store the
|
all the relocations plus a trailing @samp{NULL} entry, and store the
|
actual relocation information in BFD private data. This is called via
|
actual relocation information in BFD private data. This is called via
|
@samp{bfd_get_dynamic_reloc_upper_bound}. The corresponding field in
|
@samp{bfd_get_dynamic_reloc_upper_bound}. The corresponding field in
|
the target vector is named @samp{_bfd_get_dynamic_reloc_upper_bound}.
|
the target vector is named @samp{_bfd_get_dynamic_reloc_upper_bound}.
|
|
|
@item _canonicalize_dynamic_reloc
|
@item _canonicalize_dynamic_reloc
|
Read the dynamic relocations. This is called via
|
Read the dynamic relocations. This is called via
|
@samp{bfd_canonicalize_dynamic_reloc}. The corresponding field in the
|
@samp{bfd_canonicalize_dynamic_reloc}. The corresponding field in the
|
target vector is named @samp{_bfd_canonicalize_dynamic_reloc}.
|
target vector is named @samp{_bfd_canonicalize_dynamic_reloc}.
|
@end table
|
@end table
|
|
|
@node BFD generated files
|
@node BFD generated files
|
@section BFD generated files
|
@section BFD generated files
|
@cindex generated files in bfd
|
@cindex generated files in bfd
|
@cindex bfd generated files
|
@cindex bfd generated files
|
|
|
BFD contains several automatically generated files. This section
|
BFD contains several automatically generated files. This section
|
describes them. Some files are created at configure time, when you
|
describes them. Some files are created at configure time, when you
|
configure BFD. Some files are created at make time, when you build
|
configure BFD. Some files are created at make time, when you build
|
BFD. 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
|
you configure with the @samp{--enable-maintainer-mode} option. Some
|
files live in the object directory---the directory from which you run
|
files live in the object directory---the directory from which you run
|
configure---and some live in the source directory. All files that live
|
configure---and some live in the source directory. All files that live
|
in the source directory are checked into the CVS repository.
|
in the source directory are checked into the CVS repository.
|
|
|
@table @file
|
@table @file
|
@item bfd.h
|
@item bfd.h
|
@cindex @file{bfd.h}
|
@cindex @file{bfd.h}
|
@cindex @file{bfd-in3.h}
|
@cindex @file{bfd-in3.h}
|
Lives in the object directory. Created at make time from
|
Lives in the object directory. Created at make time from
|
@file{bfd-in2.h} via @file{bfd-in3.h}. @file{bfd-in3.h} is created at
|
@file{bfd-in2.h} via @file{bfd-in3.h}. @file{bfd-in3.h} is created at
|
configure time from @file{bfd-in2.h}. There are automatic dependencies
|
configure time from @file{bfd-in2.h}. There are automatic dependencies
|
to rebuild @file{bfd-in3.h} and hence @file{bfd.h} if @file{bfd-in2.h}
|
to rebuild @file{bfd-in3.h} and hence @file{bfd.h} if @file{bfd-in2.h}
|
changes, so you can normally ignore @file{bfd-in3.h}, and just think
|
changes, so you can normally ignore @file{bfd-in3.h}, and just think
|
about @file{bfd-in2.h} and @file{bfd.h}.
|
about @file{bfd-in2.h} and @file{bfd.h}.
|
|
|
@file{bfd.h} is built by replacing a few strings in @file{bfd-in2.h}.
|
@file{bfd.h} is built by replacing a few strings in @file{bfd-in2.h}.
|
To see them, search for @samp{@@} in @file{bfd-in2.h}. They mainly
|
To see them, search for @samp{@@} in @file{bfd-in2.h}. They mainly
|
control whether BFD is built for a 32 bit target or a 64 bit target.
|
control whether BFD is built for a 32 bit target or a 64 bit target.
|
|
|
@item bfd-in2.h
|
@item bfd-in2.h
|
@cindex @file{bfd-in2.h}
|
@cindex @file{bfd-in2.h}
|
Lives in the source directory. Created from @file{bfd-in.h} and several
|
Lives in the source directory. Created from @file{bfd-in.h} and several
|
other BFD source files. If you configure with the
|
other BFD source files. If you configure with the
|
@samp{--enable-maintainer-mode} option, @file{bfd-in2.h} is rebuilt
|
@samp{--enable-maintainer-mode} option, @file{bfd-in2.h} is rebuilt
|
automatically when a source file changes.
|
automatically when a source file changes.
|
|
|
@item elf32-target.h
|
@item elf32-target.h
|
@itemx elf64-target.h
|
@itemx elf64-target.h
|
@cindex @file{elf32-target.h}
|
@cindex @file{elf32-target.h}
|
@cindex @file{elf64-target.h}
|
@cindex @file{elf64-target.h}
|
Live in the object directory. Created from @file{elfxx-target.h}.
|
Live in the object directory. Created from @file{elfxx-target.h}.
|
These files are versions of @file{elfxx-target.h} customized for either
|
These files are versions of @file{elfxx-target.h} customized for either
|
a 32 bit ELF target or a 64 bit ELF target.
|
a 32 bit ELF target or a 64 bit ELF target.
|
|
|
@item libbfd.h
|
@item libbfd.h
|
@cindex @file{libbfd.h}
|
@cindex @file{libbfd.h}
|
Lives in the source directory. Created from @file{libbfd-in.h} and
|
Lives in the source directory. Created from @file{libbfd-in.h} and
|
several other BFD source files. If you configure with the
|
several other BFD source files. If you configure with the
|
@samp{--enable-maintainer-mode} option, @file{libbfd.h} is rebuilt
|
@samp{--enable-maintainer-mode} option, @file{libbfd.h} is rebuilt
|
automatically when a source file changes.
|
automatically when a source file changes.
|
|
|
@item libcoff.h
|
@item libcoff.h
|
@cindex @file{libcoff.h}
|
@cindex @file{libcoff.h}
|
Lives in the source directory. Created from @file{libcoff-in.h} and
|
Lives in the source directory. Created from @file{libcoff-in.h} and
|
@file{coffcode.h}. If you configure with the
|
@file{coffcode.h}. If you configure with the
|
@samp{--enable-maintainer-mode} option, @file{libcoff.h} is rebuilt
|
@samp{--enable-maintainer-mode} option, @file{libcoff.h} is rebuilt
|
automatically when a source file changes.
|
automatically when a source file changes.
|
|
|
@item targmatch.h
|
@item targmatch.h
|
@cindex @file{targmatch.h}
|
@cindex @file{targmatch.h}
|
Lives in the object directory. Created at make time from
|
Lives in the object directory. Created at make time from
|
@file{config.bfd}. This file is used to map configuration triplets into
|
@file{config.bfd}. This file is used to map configuration triplets into
|
BFD target vector variable names at run time.
|
BFD target vector variable names at run time.
|
@end table
|
@end table
|
|
|
@node BFD multiple compilations
|
@node BFD multiple compilations
|
@section Files compiled multiple times in BFD
|
@section Files compiled multiple times in BFD
|
Several files in BFD are compiled multiple times. By this I mean that
|
Several files in BFD are compiled multiple times. By this I mean that
|
there are header files which contain function definitions. These header
|
there are header files which contain function definitions. These header
|
files are included by other files, and thus the functions are compiled
|
files are included by other files, and thus the functions are compiled
|
once per file which includes them.
|
once per file which includes them.
|
|
|
Preprocessor macros are used to control the compilation, so that each
|
Preprocessor macros are used to control the compilation, so that each
|
time the files are compiled the resulting functions are slightly
|
time the files are compiled the resulting functions are slightly
|
different. Naturally, if they weren't different, there would be no
|
different. Naturally, if they weren't different, there would be no
|
reason to compile them multiple times.
|
reason to compile them multiple times.
|
|
|
This is a not a particularly good programming technique, and future BFD
|
This is a not a particularly good programming technique, and future BFD
|
work should avoid it.
|
work should avoid it.
|
|
|
@itemize @bullet
|
@itemize @bullet
|
@item
|
@item
|
Since this technique is rarely used, even experienced C programmers find
|
Since this technique is rarely used, even experienced C programmers find
|
it confusing.
|
it confusing.
|
|
|
@item
|
@item
|
It is difficult to debug programs which use BFD, since there is no way
|
It is difficult to debug programs which use BFD, since there is no way
|
to describe which version of a particular function you are looking at.
|
to describe which version of a particular function you are looking at.
|
|
|
@item
|
@item
|
Programs which use BFD wind up incorporating two or more slightly
|
Programs which use BFD wind up incorporating two or more slightly
|
different versions of the same function, which wastes space in the
|
different versions of the same function, which wastes space in the
|
executable.
|
executable.
|
|
|
@item
|
@item
|
This technique is never required nor is it especially efficient. It is
|
This technique is never required nor is it especially efficient. It is
|
always possible to use statically initialized structures holding
|
always possible to use statically initialized structures holding
|
function pointers and magic constants instead.
|
function pointers and magic constants instead.
|
@end itemize
|
@end itemize
|
|
|
The following is a list of the files which are compiled multiple times.
|
The following is a list of the files which are compiled multiple times.
|
|
|
@table @file
|
@table @file
|
@item aout-target.h
|
@item aout-target.h
|
@cindex @file{aout-target.h}
|
@cindex @file{aout-target.h}
|
Describes a few functions and the target vector for a.out targets. This
|
Describes a few functions and the target vector for a.out targets. This
|
is used by individual a.out targets with different definitions of
|
is used by individual a.out targets with different definitions of
|
@samp{N_TXTADDR} and similar a.out macros.
|
@samp{N_TXTADDR} and similar a.out macros.
|
|
|
@item aoutf1.h
|
@item aoutf1.h
|
@cindex @file{aoutf1.h}
|
@cindex @file{aoutf1.h}
|
Implements standard SunOS a.out files. In principle it supports 64 bit
|
Implements standard SunOS a.out files. In principle it supports 64 bit
|
a.out targets based on the preprocessor macro @samp{ARCH_SIZE}, but
|
a.out targets based on the preprocessor macro @samp{ARCH_SIZE}, but
|
since all known a.out targets are 32 bits, this code may or may not
|
since all known a.out targets are 32 bits, this code may or may not
|
work. This file is only included by a few other files, and it is
|
work. This file is only included by a few other files, and it is
|
difficult to justify its existence.
|
difficult to justify its existence.
|
|
|
@item aoutx.h
|
@item aoutx.h
|
@cindex @file{aoutx.h}
|
@cindex @file{aoutx.h}
|
Implements basic a.out support routines. This file can be compiled for
|
Implements basic a.out support routines. This file can be compiled for
|
either 32 or 64 bit support. Since all known a.out targets are 32 bits,
|
either 32 or 64 bit support. Since all known a.out targets are 32 bits,
|
the 64 bit support may or may not work. I believe the original
|
the 64 bit support may or may not work. I believe the original
|
intention was that this file would only be included by @samp{aout32.c}
|
intention was that this file would only be included by @samp{aout32.c}
|
and @samp{aout64.c}, and that other a.out targets would simply refer to
|
and @samp{aout64.c}, and that other a.out targets would simply refer to
|
the functions it defined. Unfortunately, some other a.out targets
|
the functions it defined. Unfortunately, some other a.out targets
|
started including it directly, leading to a somewhat confused state of
|
started including it directly, leading to a somewhat confused state of
|
affairs.
|
affairs.
|
|
|
@item coffcode.h
|
@item coffcode.h
|
@cindex @file{coffcode.h}
|
@cindex @file{coffcode.h}
|
Implements basic COFF support routines. This file is included by every
|
Implements basic COFF support routines. This file is included by every
|
COFF target. It implements code which handles COFF magic numbers as
|
COFF target. It implements code which handles COFF magic numbers as
|
well as various hook functions called by the generic COFF functions in
|
well as various hook functions called by the generic COFF functions in
|
@file{coffgen.c}. This file is controlled by a number of different
|
@file{coffgen.c}. This file is controlled by a number of different
|
macros, and more are added regularly.
|
macros, and more are added regularly.
|
|
|
@item coffswap.h
|
@item coffswap.h
|
@cindex @file{coffswap.h}
|
@cindex @file{coffswap.h}
|
Implements COFF swapping routines. This file is included by
|
Implements COFF swapping routines. This file is included by
|
@file{coffcode.h}, and thus by every COFF target. It implements the
|
@file{coffcode.h}, and thus by every COFF target. It implements the
|
routines which swap COFF structures between internal and external
|
routines which swap COFF structures between internal and external
|
format. The main control for this file is the external structure
|
format. The main control for this file is the external structure
|
definitions in the files in the @file{include/coff} directory. A COFF
|
definitions in the files in the @file{include/coff} directory. A COFF
|
target file will include one of those files before including
|
target file will include one of those files before including
|
@file{coffcode.h} and thus @file{coffswap.h}. There are a few other
|
@file{coffcode.h} and thus @file{coffswap.h}. There are a few other
|
macros which affect @file{coffswap.h} as well, mostly describing whether
|
macros which affect @file{coffswap.h} as well, mostly describing whether
|
certain fields are present in the external structures.
|
certain fields are present in the external structures.
|
|
|
@item ecoffswap.h
|
@item ecoffswap.h
|
@cindex @file{ecoffswap.h}
|
@cindex @file{ecoffswap.h}
|
Implements ECOFF swapping routines. This is like @file{coffswap.h}, but
|
Implements ECOFF swapping routines. This is like @file{coffswap.h}, but
|
for ECOFF. It is included by the ECOFF target files (of which there are
|
for ECOFF. It is included by the ECOFF target files (of which there are
|
only two). The control is the preprocessor macro @samp{ECOFF_32} or
|
only two). The control is the preprocessor macro @samp{ECOFF_32} or
|
@samp{ECOFF_64}.
|
@samp{ECOFF_64}.
|
|
|
@item elfcode.h
|
@item elfcode.h
|
@cindex @file{elfcode.h}
|
@cindex @file{elfcode.h}
|
Implements ELF functions that use external structure definitions. This
|
Implements ELF functions that use external structure definitions. This
|
file is included by two other files: @file{elf32.c} and @file{elf64.c}.
|
file is included by two other files: @file{elf32.c} and @file{elf64.c}.
|
It is controlled by the @samp{ARCH_SIZE} macro which is defined to be
|
It is controlled by the @samp{ARCH_SIZE} macro which is defined to be
|
@samp{32} or @samp{64} before including it. The @samp{NAME} macro is
|
@samp{32} or @samp{64} before including it. The @samp{NAME} macro is
|
used internally to give the functions different names for the two target
|
used internally to give the functions different names for the two target
|
sizes.
|
sizes.
|
|
|
@item elfcore.h
|
@item elfcore.h
|
@cindex @file{elfcore.h}
|
@cindex @file{elfcore.h}
|
Like @file{elfcode.h}, but for functions that are specific to ELF core
|
Like @file{elfcode.h}, but for functions that are specific to ELF core
|
files. This is included only by @file{elfcode.h}.
|
files. This is included only by @file{elfcode.h}.
|
|
|
@item elfxx-target.h
|
@item elfxx-target.h
|
@cindex @file{elfxx-target.h}
|
@cindex @file{elfxx-target.h}
|
This file is the source for the generated files @file{elf32-target.h}
|
This file is the source for the generated files @file{elf32-target.h}
|
and @file{elf64-target.h}, one of which is included by every ELF target.
|
and @file{elf64-target.h}, one of which is included by every ELF target.
|
It defines the ELF target vector.
|
It defines the ELF target vector.
|
|
|
@item freebsd.h
|
@item freebsd.h
|
@cindex @file{freebsd.h}
|
@cindex @file{freebsd.h}
|
Presumably intended to be included by all FreeBSD targets, but in fact
|
Presumably intended to be included by all FreeBSD targets, but in fact
|
there is only one such target, @samp{i386-freebsd}. This defines a
|
there is only one such target, @samp{i386-freebsd}. This defines a
|
function used to set the right magic number for FreeBSD, as well as
|
function used to set the right magic number for FreeBSD, as well as
|
various macros, and includes @file{aout-target.h}.
|
various macros, and includes @file{aout-target.h}.
|
|
|
@item netbsd.h
|
@item netbsd.h
|
@cindex @file{netbsd.h}
|
@cindex @file{netbsd.h}
|
Like @file{freebsd.h}, except that there are several files which include
|
Like @file{freebsd.h}, except that there are several files which include
|
it.
|
it.
|
|
|
@item nlm-target.h
|
@item nlm-target.h
|
@cindex @file{nlm-target.h}
|
@cindex @file{nlm-target.h}
|
Defines the target vector for a standard NLM target.
|
Defines the target vector for a standard NLM target.
|
|
|
@item nlmcode.h
|
@item nlmcode.h
|
@cindex @file{nlmcode.h}
|
@cindex @file{nlmcode.h}
|
Like @file{elfcode.h}, but for NLM targets. This is only included by
|
Like @file{elfcode.h}, but for NLM targets. This is only included by
|
@file{nlm32.c} and @file{nlm64.c}, both of which define the macro
|
@file{nlm32.c} and @file{nlm64.c}, both of which define the macro
|
@samp{ARCH_SIZE} to an appropriate value. There are no 64 bit NLM
|
@samp{ARCH_SIZE} to an appropriate value. There are no 64 bit NLM
|
targets anyhow, so this is sort of useless.
|
targets anyhow, so this is sort of useless.
|
|
|
@item nlmswap.h
|
@item nlmswap.h
|
@cindex @file{nlmswap.h}
|
@cindex @file{nlmswap.h}
|
Like @file{coffswap.h}, but for NLM targets. This is included by each
|
Like @file{coffswap.h}, but for NLM targets. This is included by each
|
NLM target, but I think it winds up compiling to the exact same code for
|
NLM target, but I think it winds up compiling to the exact same code for
|
every target, and as such is fairly useless.
|
every target, and as such is fairly useless.
|
|
|
@item peicode.h
|
@item peicode.h
|
@cindex @file{peicode.h}
|
@cindex @file{peicode.h}
|
Provides swapping routines and other hooks for PE targets.
|
Provides swapping routines and other hooks for PE targets.
|
@file{coffcode.h} will include this rather than @file{coffswap.h} for a
|
@file{coffcode.h} will include this rather than @file{coffswap.h} for a
|
PE target. This defines PE specific versions of the COFF swapping
|
PE target. This defines PE specific versions of the COFF swapping
|
routines, and also defines some macros which control @file{coffcode.h}
|
routines, and also defines some macros which control @file{coffcode.h}
|
itself.
|
itself.
|
@end table
|
@end table
|
|
|
@node BFD relocation handling
|
@node BFD relocation handling
|
@section BFD relocation handling
|
@section BFD relocation handling
|
@cindex bfd relocation handling
|
@cindex bfd relocation handling
|
@cindex relocations in bfd
|
@cindex relocations in bfd
|
|
|
The handling of relocations is one of the more confusing aspects of BFD.
|
The handling of relocations is one of the more confusing aspects of BFD.
|
Relocation handling has been implemented in various different ways, all
|
Relocation handling has been implemented in various different ways, all
|
somewhat incompatible, none perfect.
|
somewhat incompatible, none perfect.
|
|
|
@menu
|
@menu
|
* BFD relocation concepts:: BFD relocation concepts
|
* BFD relocation concepts:: BFD relocation concepts
|
* BFD relocation functions:: BFD relocation functions
|
* BFD relocation functions:: BFD relocation functions
|
* BFD relocation codes:: BFD relocation codes
|
* BFD relocation codes:: BFD relocation codes
|
* BFD relocation future:: BFD relocation future
|
* BFD relocation future:: BFD relocation future
|
@end menu
|
@end menu
|
|
|
@node BFD relocation concepts
|
@node BFD relocation concepts
|
@subsection BFD relocation concepts
|
@subsection BFD relocation concepts
|
|
|
A relocation is an action which the linker must take when linking. It
|
A relocation is an action which the linker must take when linking. It
|
describes a change to the contents of a section. The change is normally
|
describes a change to the contents of a section. The change is normally
|
based on the final value of one or more symbols. Relocations are
|
based on the final value of one or more symbols. Relocations are
|
created by the assembler when it creates an object file.
|
created by the assembler when it creates an object file.
|
|
|
Most relocations are simple. A typical simple relocation is to set 32
|
Most relocations are simple. A typical simple relocation is to set 32
|
bits at a given offset in a section to the value of a symbol. This type
|
bits at a given offset in a section to the value of a symbol. This type
|
of relocation would be generated for code like @code{int *p = &i;} where
|
of relocation would be generated for code like @code{int *p = &i;} where
|
@samp{p} and @samp{i} are global variables. A relocation for the symbol
|
@samp{p} and @samp{i} are global variables. A relocation for the symbol
|
@samp{i} would be generated such that the linker would initialize the
|
@samp{i} would be generated such that the linker would initialize the
|
area of memory which holds the value of @samp{p} to the value of the
|
area of memory which holds the value of @samp{p} to the value of the
|
symbol @samp{i}.
|
symbol @samp{i}.
|
|
|
Slightly more complex relocations may include an addend, which is a
|
Slightly more complex relocations may include an addend, which is a
|
constant to add to the symbol value before using it. In some cases a
|
constant to add to the symbol value before using it. In some cases a
|
relocation will require adding the symbol value to the existing contents
|
relocation will require adding the symbol value to the existing contents
|
of the section in the object file. In others the relocation will simply
|
of the section in the object file. In others the relocation will simply
|
replace the contents of the section with the symbol value. Some
|
replace the contents of the section with the symbol value. Some
|
relocations are PC relative, so that the value to be stored in the
|
relocations are PC relative, so that the value to be stored in the
|
section is the difference between the value of a symbol and the final
|
section is the difference between the value of a symbol and the final
|
address of the section contents.
|
address of the section contents.
|
|
|
In general, relocations can be arbitrarily complex. For example,
|
In general, relocations can be arbitrarily complex. For example,
|
relocations used in dynamic linking systems often require the linker to
|
relocations used in dynamic linking systems often require the linker to
|
allocate space in a different section and use the offset within that
|
allocate space in a different section and use the offset within that
|
section as the value to store. In the IEEE object file format,
|
section as the value to store. In the IEEE object file format,
|
relocations may involve arbitrary expressions.
|
relocations may involve arbitrary expressions.
|
|
|
When doing a relocatable 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
|
anything with a relocation, depending upon the definition of the
|
relocation. Simple relocations generally do not require any special
|
relocation. Simple relocations generally do not require any special
|
action.
|
action.
|
|
|
@node BFD relocation functions
|
@node BFD relocation functions
|
@subsection BFD relocation functions
|
@subsection BFD relocation functions
|
|
|
In BFD, each section has an array of @samp{arelent} structures. Each
|
In BFD, each section has an array of @samp{arelent} structures. Each
|
structure has a pointer to a symbol, an address within the section, an
|
structure has a pointer to a symbol, an address within the section, an
|
addend, and a pointer to a @samp{reloc_howto_struct} structure. The
|
addend, and a pointer to a @samp{reloc_howto_struct} structure. The
|
howto structure has a bunch of fields describing the reloc, including a
|
howto structure has a bunch of fields describing the reloc, including a
|
type field. The type field is specific to the object file format
|
type field. The type field is specific to the object file format
|
backend; none of the generic code in BFD examines it.
|
backend; none of the generic code in BFD examines it.
|
|
|
Originally, the function @samp{bfd_perform_relocation} was supposed to
|
Originally, the function @samp{bfd_perform_relocation} was supposed to
|
handle all relocations. In theory, many relocations would be simple
|
handle all relocations. In theory, many relocations would be simple
|
enough to be described by the fields in the howto structure. For those
|
enough to be described by the fields in the howto structure. For those
|
that weren't, the howto structure included a @samp{special_function}
|
that weren't, the howto structure included a @samp{special_function}
|
field to use as an escape.
|
field to use as an escape.
|
|
|
While this seems plausible, a look at @samp{bfd_perform_relocation}
|
While this seems plausible, a look at @samp{bfd_perform_relocation}
|
shows that it failed. The function has odd special cases. Some of the
|
shows that it failed. The function has odd special cases. Some of the
|
fields in the howto structure, such as @samp{pcrel_offset}, were not
|
fields in the howto structure, such as @samp{pcrel_offset}, were not
|
adequately documented.
|
adequately documented.
|
|
|
The linker uses @samp{bfd_perform_relocation} to do all relocations when
|
The linker uses @samp{bfd_perform_relocation} to do all relocations when
|
the input and output file have different formats (e.g., when generating
|
the input and output file have different formats (e.g., when generating
|
S-records). The generic linker code, which is used by all targets which
|
S-records). The generic linker code, which is used by all targets which
|
do not define their own special purpose linker, uses
|
do not define their own special purpose linker, uses
|
@samp{bfd_get_relocated_section_contents}, which for most targets turns
|
@samp{bfd_get_relocated_section_contents}, which for most targets turns
|
into a call to @samp{bfd_generic_get_relocated_section_contents}, which
|
into a call to @samp{bfd_generic_get_relocated_section_contents}, which
|
calls @samp{bfd_perform_relocation}. So @samp{bfd_perform_relocation}
|
calls @samp{bfd_perform_relocation}. So @samp{bfd_perform_relocation}
|
is still widely used, which makes it difficult to change, since it is
|
is still widely used, which makes it difficult to change, since it is
|
difficult to test all possible cases.
|
difficult to test all possible cases.
|
|
|
The assembler used @samp{bfd_perform_relocation} for a while. This
|
The assembler used @samp{bfd_perform_relocation} for a while. This
|
turned out to be the wrong thing to do, since
|
turned out to be the wrong thing to do, since
|
@samp{bfd_perform_relocation} was written to handle relocations on an
|
@samp{bfd_perform_relocation} was written to handle relocations on an
|
existing object file, while the assembler needed to create relocations
|
existing object file, while the assembler needed to create relocations
|
in a new object file. The assembler was changed to use the new function
|
in a new object file. The assembler was changed to use the new function
|
@samp{bfd_install_relocation} instead, and @samp{bfd_install_relocation}
|
@samp{bfd_install_relocation} instead, and @samp{bfd_install_relocation}
|
was created as a copy of @samp{bfd_perform_relocation}.
|
was created as a copy of @samp{bfd_perform_relocation}.
|
|
|
Unfortunately, the work did not progress any farther, so
|
Unfortunately, the work did not progress any farther, so
|
@samp{bfd_install_relocation} remains a simple copy of
|
@samp{bfd_install_relocation} remains a simple copy of
|
@samp{bfd_perform_relocation}, with all the odd special cases and
|
@samp{bfd_perform_relocation}, with all the odd special cases and
|
confusing code. This again is difficult to change, because again any
|
confusing code. This again is difficult to change, because again any
|
change can affect any assembler target, and so is difficult to test.
|
change can affect any assembler target, and so is difficult to test.
|
|
|
The new linker, when using the same object file format for all input
|
The new linker, when using the same object file format for all input
|
files and the output file, does not convert relocations into
|
files and the output file, does not convert relocations into
|
@samp{arelent} structures, so it can not use
|
@samp{arelent} structures, so it can not use
|
@samp{bfd_perform_relocation} at all. Instead, users of the new linker
|
@samp{bfd_perform_relocation} at all. Instead, users of the new linker
|
are expected to write a @samp{relocate_section} function which will
|
are expected to write a @samp{relocate_section} function which will
|
handle relocations in a target specific fashion.
|
handle relocations in a target specific fashion.
|
|
|
There are two helper functions for target specific relocation:
|
There are two helper functions for target specific relocation:
|
@samp{_bfd_final_link_relocate} and @samp{_bfd_relocate_contents}.
|
@samp{_bfd_final_link_relocate} and @samp{_bfd_relocate_contents}.
|
These functions use a howto structure, but they @emph{do not} use the
|
These functions use a howto structure, but they @emph{do not} use the
|
@samp{special_function} field. Since the functions are normally called
|
@samp{special_function} field. Since the functions are normally called
|
from target specific code, the @samp{special_function} field adds
|
from target specific code, the @samp{special_function} field adds
|
little; any relocations which require special handling can be handled
|
little; any relocations which require special handling can be handled
|
without calling those functions.
|
without calling those functions.
|
|
|
So, if you want to add a new target, or add a new relocation to an
|
So, if you want to add a new target, or add a new relocation to an
|
existing target, you need to do the following:
|
existing target, you need to do the following:
|
|
|
@itemize @bullet
|
@itemize @bullet
|
@item
|
@item
|
Make sure you clearly understand what the contents of the section should
|
Make sure you clearly understand what the contents of the section should
|
look like after assembly, after a relocatable 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
|
link. Make sure you clearly understand the operations the linker must
|
perform during a relocatable link and during a final link.
|
perform during a relocatable link and during a final link.
|
|
|
@item
|
@item
|
Write a howto structure for the relocation. The howto structure is
|
Write a howto structure for the relocation. The howto structure is
|
flexible enough to represent any relocation which should be handled by
|
flexible enough to represent any relocation which should be handled by
|
setting a contiguous bitfield in the destination to the value of a
|
setting a contiguous bitfield in the destination to the value of a
|
symbol, possibly with an addend, possibly adding the symbol value to the
|
symbol, possibly with an addend, possibly adding the symbol value to the
|
value already present in the destination.
|
value already present in the destination.
|
|
|
@item
|
@item
|
Change the assembler to generate your relocation. The assembler will
|
Change the assembler to generate your relocation. The assembler will
|
call @samp{bfd_install_relocation}, so your howto structure has to be
|
call @samp{bfd_install_relocation}, so your howto structure has to be
|
able to handle that. You may need to set the @samp{special_function}
|
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
|
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
|
you write to handle the assembler will also work correctly when doing a
|
relocatable link. For example, see @samp{bfd_elf_generic_reloc}.
|
relocatable link. For example, see @samp{bfd_elf_generic_reloc}.
|
|
|
@item
|
@item
|
Test the assembler. Consider the cases of relocation against an
|
Test the assembler. Consider the cases of relocation against an
|
undefined symbol, a common symbol, a symbol defined in the object file
|
undefined symbol, a common symbol, a symbol defined in the object file
|
in the same section, and a symbol defined in the object file in a
|
in the same section, and a symbol defined in the object file in a
|
different section. These cases may not all be applicable for your
|
different section. These cases may not all be applicable for your
|
reloc.
|
reloc.
|
|
|
@item
|
@item
|
If your target uses the new linker, which is recommended, add any
|
If your target uses the new linker, which is recommended, add any
|
required handling to the target specific relocation function. In simple
|
required handling to the target specific relocation function. In simple
|
cases this will just involve a call to @samp{_bfd_final_link_relocate}
|
cases this will just involve a call to @samp{_bfd_final_link_relocate}
|
or @samp{_bfd_relocate_contents}, depending upon the definition of the
|
or @samp{_bfd_relocate_contents}, depending upon the definition of the
|
relocation and whether the link is relocatable or not.
|
relocation and whether the link is relocatable or not.
|
|
|
@item
|
@item
|
Test the linker. Test the case of a final link. If the relocation can
|
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
|
overflow, use a linker script to force an overflow and make sure the
|
error is reported correctly. Test a relocatable link, whether the
|
error is reported correctly. Test a relocatable link, whether the
|
symbol is defined or undefined in the relocatable output. For both 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
|
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 looked like a common symbol but became a defined
|
symbol, when the symbol is defined in a different object file, and when
|
symbol, when the symbol is defined in a different object file, and when
|
the symbol is defined in the same object file.
|
the symbol is defined in the same object file.
|
|
|
@item
|
@item
|
In order for linking to another object file format, such as S-records,
|
In order for linking to another object file format, such as S-records,
|
to work correctly, @samp{bfd_perform_relocation} has to do the right
|
to work correctly, @samp{bfd_perform_relocation} has to do the right
|
thing for the relocation. You may need to set the
|
thing for the relocation. You may need to set the
|
@samp{special_function} field to handle this correctly. Test this by
|
@samp{special_function} field to handle this correctly. Test this by
|
doing a link in which the output object file format is S-records.
|
doing a link in which the output object file format is S-records.
|
|
|
@item
|
@item
|
Using the linker to generate relocatable 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
|
file format is impossible in the general case, so you generally don't
|
have to worry about that. The GNU linker makes sure to stop that from
|
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.
|
happening when an input file in a different format has relocations.
|
|
|
Linking input files of different object file formats together is quite
|
Linking input files of different object file formats together is quite
|
unusual, but if you're really dedicated you may want to consider testing
|
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
|
this case, both when the output object file format is the same as your
|
format, and when it is different.
|
format, and when it is different.
|
@end itemize
|
@end itemize
|
|
|
@node BFD relocation codes
|
@node BFD relocation codes
|
@subsection BFD relocation codes
|
@subsection BFD relocation codes
|
|
|
BFD has another way of describing relocations besides the howto
|
BFD has another way of describing relocations besides the howto
|
structures described above: the enum @samp{bfd_reloc_code_real_type}.
|
structures described above: the enum @samp{bfd_reloc_code_real_type}.
|
|
|
Every known relocation type can be described as a value in this
|
Every known relocation type can be described as a value in this
|
enumeration. The enumeration contains many target specific relocations,
|
enumeration. The enumeration contains many target specific relocations,
|
but where two or more targets have the same relocation, a single code is
|
but where two or more targets have the same relocation, a single code is
|
used. For example, the single value @samp{BFD_RELOC_32} is used for all
|
used. For example, the single value @samp{BFD_RELOC_32} is used for all
|
simple 32 bit relocation types.
|
simple 32 bit relocation types.
|
|
|
The main purpose of this relocation code is to give the assembler some
|
The main purpose of this relocation code is to give the assembler some
|
mechanism to create @samp{arelent} structures. In order for the
|
mechanism to create @samp{arelent} structures. In order for the
|
assembler to create an @samp{arelent} structure, it has to be able to
|
assembler to create an @samp{arelent} structure, it has to be able to
|
obtain a howto structure. The function @samp{bfd_reloc_type_lookup},
|
obtain a howto structure. The function @samp{bfd_reloc_type_lookup},
|
which simply calls the target vector entry point
|
which simply calls the target vector entry point
|
@samp{reloc_type_lookup}, takes a relocation code and returns a howto
|
@samp{reloc_type_lookup}, takes a relocation code and returns a howto
|
structure.
|
structure.
|
|
|
The function @samp{bfd_get_reloc_code_name} returns the name of a
|
The function @samp{bfd_get_reloc_code_name} returns the name of a
|
relocation code. This is mainly used in error messages.
|
relocation code. This is mainly used in error messages.
|
|
|
Using both howto structures and relocation codes can be somewhat
|
Using both howto structures and relocation codes can be somewhat
|
confusing. There are many processor specific relocation codes.
|
confusing. There are many processor specific relocation codes.
|
However, the relocation is only fully defined by the howto structure.
|
However, the relocation is only fully defined by the howto structure.
|
The same relocation code will map to different howto structures in
|
The same relocation code will map to different howto structures in
|
different object file formats. For example, the addend handling may be
|
different object file formats. For example, the addend handling may be
|
different.
|
different.
|
|
|
Most of the relocation codes are not really general. The assembler can
|
Most of the relocation codes are not really general. The assembler can
|
not use them without already understanding what sorts of relocations can
|
not use them without already understanding what sorts of relocations can
|
be used for a particular target. It might be possible to replace the
|
be used for a particular target. It might be possible to replace the
|
relocation codes with something simpler.
|
relocation codes with something simpler.
|
|
|
@node BFD relocation future
|
@node BFD relocation future
|
@subsection BFD relocation future
|
@subsection BFD relocation future
|
|
|
Clearly the current BFD relocation support is in bad shape. A
|
Clearly the current BFD relocation support is in bad shape. A
|
wholescale rewrite would be very difficult, because it would require
|
wholescale rewrite would be very difficult, because it would require
|
thorough testing of every BFD target. So some sort of incremental
|
thorough testing of every BFD target. So some sort of incremental
|
change is required.
|
change is required.
|
|
|
My vague thoughts on this would involve defining a new, clearly defined,
|
My vague thoughts on this would involve defining a new, clearly defined,
|
howto structure. Some mechanism would be used to determine which type
|
howto structure. Some mechanism would be used to determine which type
|
of howto structure was being used by a particular format.
|
of howto structure was being used by a particular format.
|
|
|
The new howto structure would clearly define the relocation behaviour in
|
The new howto structure would clearly define the relocation behaviour in
|
the case of an assembly, a relocatable 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
|
least one special function would be defined as an escape, and it might
|
make sense to define more.
|
make sense to define more.
|
|
|
One or more generic functions similar to @samp{bfd_perform_relocation}
|
One or more generic functions similar to @samp{bfd_perform_relocation}
|
would be written to handle the new howto structure.
|
would be written to handle the new howto structure.
|
|
|
This should make it possible to write a generic version of the relocate
|
This should make it possible to write a generic version of the relocate
|
section functions used by the new linker. The target specific code
|
section functions used by the new linker. The target specific code
|
would provide some mechanism (a function pointer or an initial
|
would provide some mechanism (a function pointer or an initial
|
conversion) to convert target specific relocations into howto
|
conversion) to convert target specific relocations into howto
|
structures.
|
structures.
|
|
|
Ideally it would be possible to use this generic relocate section
|
Ideally it would be possible to use this generic relocate section
|
function for the generic linker as well. That is, it would replace the
|
function for the generic linker as well. That is, it would replace the
|
@samp{bfd_generic_get_relocated_section_contents} function which is
|
@samp{bfd_generic_get_relocated_section_contents} function which is
|
currently normally used.
|
currently normally used.
|
|
|
For the special case of ELF dynamic linking, more consideration needs to
|
For the special case of ELF dynamic linking, more consideration needs to
|
be given to writing ELF specific but ELF target generic code to handle
|
be given to writing ELF specific but ELF target generic code to handle
|
special relocation types such as GOT and PLT.
|
special relocation types such as GOT and PLT.
|
|
|
@node BFD ELF support
|
@node BFD ELF support
|
@section BFD ELF support
|
@section BFD ELF support
|
@cindex elf support in bfd
|
@cindex elf support in bfd
|
@cindex bfd elf support
|
@cindex bfd elf support
|
|
|
The ELF object file format is defined in two parts: a generic ABI and a
|
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
|
processor specific supplement. The ELF support in BFD is split in a
|
similar fashion. The processor specific support is largely kept within
|
similar fashion. The processor specific support is largely kept within
|
a single file. The generic support is provided by several other files.
|
a single file. The generic support is provided by several other files.
|
The processor specific support provides a set of function pointers and
|
The processor specific support provides a set of function pointers and
|
constants used by the generic support.
|
constants used by the generic support.
|
|
|
@menu
|
@menu
|
* BFD ELF sections and segments:: ELF sections and segments
|
* BFD ELF sections and segments:: ELF sections and segments
|
* BFD ELF generic support:: BFD ELF generic support
|
* BFD ELF generic support:: BFD ELF generic support
|
* BFD ELF processor specific support:: BFD ELF processor specific support
|
* BFD ELF processor specific support:: BFD ELF processor specific support
|
* BFD ELF core files:: BFD ELF core files
|
* BFD ELF core files:: BFD ELF core files
|
* BFD ELF future:: BFD ELF future
|
* BFD ELF future:: BFD ELF future
|
@end menu
|
@end menu
|
|
|
@node BFD ELF sections and segments
|
@node BFD ELF sections and segments
|
@subsection ELF sections and segments
|
@subsection ELF sections and segments
|
|
|
The ELF ABI permits a file to have either sections or segments or both.
|
The ELF ABI permits a file to have either sections or segments or both.
|
Relocatable object files conventionally have only sections.
|
Relocatable object files conventionally have only sections.
|
Executables conventionally have both. Core files conventionally have
|
Executables conventionally have both. Core files conventionally have
|
only program segments.
|
only program segments.
|
|
|
ELF sections are similar to sections in other object file formats: they
|
ELF sections are similar to sections in other object file formats: they
|
have a name, a VMA, file contents, flags, and other miscellaneous
|
have a name, a VMA, file contents, flags, and other miscellaneous
|
information. ELF relocations are stored in sections of a particular
|
information. ELF relocations are stored in sections of a particular
|
type; BFD automatically converts these sections into internal relocation
|
type; BFD automatically converts these sections into internal relocation
|
information.
|
information.
|
|
|
ELF program segments are intended for fast interpretation by a system
|
ELF program segments are intended for fast interpretation by a system
|
loader. They have a type, a VMA, an LMA, file contents, and a couple of
|
loader. They have a type, a VMA, an LMA, file contents, and a couple of
|
other fields. When an ELF executable is run on a Unix system, the
|
other fields. When an ELF executable is run on a Unix system, the
|
system loader will examine the program segments to decide how to load
|
system loader will examine the program segments to decide how to load
|
it. The loader will ignore the section information. Loadable program
|
it. The loader will ignore the section information. Loadable program
|
segments (type @samp{PT_LOAD}) are directly loaded into memory. Other
|
segments (type @samp{PT_LOAD}) are directly loaded into memory. Other
|
program segments are interpreted by the loader, and generally provide
|
program segments are interpreted by the loader, and generally provide
|
dynamic linking information.
|
dynamic linking information.
|
|
|
When an ELF file has both program segments and sections, an ELF program
|
When an ELF file has both program segments and sections, an ELF program
|
segment may encompass one or more ELF sections, in the sense that the
|
segment may encompass one or more ELF sections, in the sense that the
|
portion of the file which corresponds to the program segment may include
|
portion of the file which corresponds to the program segment may include
|
the portions of the file corresponding to one or more sections. When
|
the portions of the file corresponding to one or more sections. When
|
there is more than one section in a loadable program segment, the
|
there is more than one section in a loadable program segment, the
|
relative positions of the section contents in the file must correspond
|
relative positions of the section contents in the file must correspond
|
to the relative positions they should hold when the program segment is
|
to the relative positions they should hold when the program segment is
|
loaded. This requirement should be obvious if you consider that the
|
loaded. This requirement should be obvious if you consider that the
|
system loader will load an entire program segment at a time.
|
system loader will load an entire program segment at a time.
|
|
|
On a system which supports dynamic paging, such as any native Unix
|
On a system which supports dynamic paging, such as any native Unix
|
system, the contents of a loadable program segment must be at the same
|
system, the contents of a loadable program segment must be at the same
|
offset in the file as in memory, modulo the memory page size used on the
|
offset in the file as in memory, modulo the memory page size used on the
|
system. This is because the system loader will map the file into memory
|
system. This is because the system loader will map the file into memory
|
starting at the start of a page. The system loader can easily remap
|
starting at the start of a page. The system loader can easily remap
|
entire pages to the correct load address. However, if the contents of
|
entire pages to the correct load address. However, if the contents of
|
the file were not correctly aligned within the page, the system loader
|
the file were not correctly aligned within the page, the system loader
|
would have to shift the contents around within the page, which is too
|
would have to shift the contents around within the page, which is too
|
expensive. For example, if the LMA of a loadable program segment is
|
expensive. For example, if the LMA of a loadable program segment is
|
@samp{0x40080} and the page size is @samp{0x1000}, then the position of
|
@samp{0x40080} and the page size is @samp{0x1000}, then the position of
|
the segment contents within the file must equal @samp{0x80} modulo
|
the segment contents within the file must equal @samp{0x80} modulo
|
@samp{0x1000}.
|
@samp{0x1000}.
|
|
|
BFD has only a single set of sections. It does not provide any generic
|
BFD has only a single set of sections. It does not provide any generic
|
way to examine both sections and segments. When BFD is used to open an
|
way to examine both sections and segments. When BFD is used to open an
|
object file or executable, the BFD sections will represent ELF sections.
|
object file or executable, the BFD sections will represent ELF sections.
|
When BFD is used to open a core file, the BFD sections will represent
|
When BFD is used to open a core file, the BFD sections will represent
|
ELF program segments.
|
ELF program segments.
|
|
|
When BFD is used to examine an object file or executable, any program
|
When BFD is used to examine an object file or executable, any program
|
segments will be read to set the LMA of the sections. This is because
|
segments will be read to set the LMA of the sections. This is because
|
ELF sections only have a VMA, while ELF program segments have both a VMA
|
ELF sections only have a VMA, while ELF program segments have both a VMA
|
and an LMA. Any program segments will be copied by the
|
and an LMA. Any program segments will be copied by the
|
@samp{copy_private} entry points. They will be printed by the
|
@samp{copy_private} entry points. They will be printed by the
|
@samp{print_private} entry point. Otherwise, the program segments are
|
@samp{print_private} entry point. Otherwise, the program segments are
|
ignored. In particular, programs which use BFD currently have no direct
|
ignored. In particular, programs which use BFD currently have no direct
|
access to the program segments.
|
access to the program segments.
|
|
|
When BFD is used to create an executable, the program segments will be
|
When BFD is used to create an executable, the program segments will be
|
created automatically based on the section information. This is done in
|
created automatically based on the section information. This is done in
|
the function @samp{assign_file_positions_for_segments} in @file{elf.c}.
|
the function @samp{assign_file_positions_for_segments} in @file{elf.c}.
|
This function has been tweaked many times, and probably still has
|
This function has been tweaked many times, and probably still has
|
problems that arise in particular cases.
|
problems that arise in particular cases.
|
|
|
There is a hook which may be used to explicitly define the program
|
There is a hook which may be used to explicitly define the program
|
segments when creating an executable: the @samp{bfd_record_phdr}
|
segments when creating an executable: the @samp{bfd_record_phdr}
|
function in @file{bfd.c}. If this function is called, BFD will not
|
function in @file{bfd.c}. If this function is called, BFD will not
|
create program segments itself, but will only create the program
|
create program segments itself, but will only create the program
|
segments specified by the caller. The linker uses this function to
|
segments specified by the caller. The linker uses this function to
|
implement the @samp{PHDRS} linker script command.
|
implement the @samp{PHDRS} linker script command.
|
|
|
@node BFD ELF generic support
|
@node BFD ELF generic support
|
@subsection BFD ELF generic support
|
@subsection BFD ELF generic support
|
|
|
In general, functions which do not read external data from the ELF file
|
In general, functions which do not read external data from the ELF file
|
are found in @file{elf.c}. They operate on the internal forms of the
|
are found in @file{elf.c}. They operate on the internal forms of the
|
ELF structures, which are defined in @file{include/elf/internal.h}. The
|
ELF structures, which are defined in @file{include/elf/internal.h}. The
|
internal structures are defined in terms of @samp{bfd_vma}, and so may
|
internal structures are defined in terms of @samp{bfd_vma}, and so may
|
be used for both 32 bit and 64 bit ELF targets.
|
be used for both 32 bit and 64 bit ELF targets.
|
|
|
The file @file{elfcode.h} contains functions which operate on the
|
The file @file{elfcode.h} contains functions which operate on the
|
external data. @file{elfcode.h} is compiled twice, once via
|
external data. @file{elfcode.h} is compiled twice, once via
|
@file{elf32.c} with @samp{ARCH_SIZE} defined as @samp{32}, and once via
|
@file{elf32.c} with @samp{ARCH_SIZE} defined as @samp{32}, and once via
|
@file{elf64.c} with @samp{ARCH_SIZE} defined as @samp{64}.
|
@file{elf64.c} with @samp{ARCH_SIZE} defined as @samp{64}.
|
@file{elfcode.h} includes functions to swap the ELF structures in and
|
@file{elfcode.h} includes functions to swap the ELF structures in and
|
out of external form, as well as a few more complex functions.
|
out of external form, as well as a few more complex functions.
|
|
|
Linker support is found in @file{elflink.c}. The
|
Linker support is found in @file{elflink.c}. The
|
linker support is only used if the processor specific file defines
|
linker support is only used if the processor specific file defines
|
@samp{elf_backend_relocate_section}, which is required to relocate the
|
@samp{elf_backend_relocate_section}, which is required to relocate the
|
section contents. If that macro is not defined, the generic linker code
|
section contents. If that macro is not defined, the generic linker code
|
is used, and relocations are handled via @samp{bfd_perform_relocation}.
|
is used, and relocations are handled via @samp{bfd_perform_relocation}.
|
|
|
The core file support is in @file{elfcore.h}, which is compiled twice,
|
The core file support is in @file{elfcore.h}, which is compiled twice,
|
for both 32 and 64 bit support. The more interesting cases of core file
|
for both 32 and 64 bit support. The more interesting cases of core file
|
support only work on a native system which has the @file{sys/procfs.h}
|
support only work on a native system which has the @file{sys/procfs.h}
|
header file. Without that file, the core file support does little more
|
header file. Without that file, the core file support does little more
|
than read the ELF program segments as BFD sections.
|
than read the ELF program segments as BFD sections.
|
|
|
The BFD internal header file @file{elf-bfd.h} is used for communication
|
The BFD internal header file @file{elf-bfd.h} is used for communication
|
among these files and the processor specific files.
|
among these files and the processor specific files.
|
|
|
The default entries for the BFD ELF target vector are found mainly in
|
The default entries for the BFD ELF target vector are found mainly in
|
@file{elf.c}. Some functions are found in @file{elfcode.h}.
|
@file{elf.c}. Some functions are found in @file{elfcode.h}.
|
|
|
The processor specific files may override particular entries in the
|
The processor specific files may override particular entries in the
|
target vector, but most do not, with one exception: the
|
target vector, but most do not, with one exception: the
|
@samp{bfd_reloc_type_lookup} entry point is always processor specific.
|
@samp{bfd_reloc_type_lookup} entry point is always processor specific.
|
|
|
@node BFD ELF processor specific support
|
@node BFD ELF processor specific support
|
@subsection BFD ELF processor specific support
|
@subsection BFD ELF processor specific support
|
|
|
By convention, the processor specific support for a particular processor
|
By convention, the processor specific support for a particular processor
|
will be found in @file{elf@var{nn}-@var{cpu}.c}, where @var{nn} is
|
will be found in @file{elf@var{nn}-@var{cpu}.c}, where @var{nn} is
|
either 32 or 64, and @var{cpu} is the name of the processor.
|
either 32 or 64, and @var{cpu} is the name of the processor.
|
|
|
@menu
|
@menu
|
* BFD ELF processor required:: Required processor specific support
|
* BFD ELF processor required:: Required processor specific support
|
* BFD ELF processor linker:: Processor specific linker support
|
* BFD ELF processor linker:: Processor specific linker support
|
* BFD ELF processor other:: Other processor specific support options
|
* BFD ELF processor other:: Other processor specific support options
|
@end menu
|
@end menu
|
|
|
@node BFD ELF processor required
|
@node BFD ELF processor required
|
@subsubsection Required processor specific support
|
@subsubsection Required processor specific support
|
|
|
When writing a @file{elf@var{nn}-@var{cpu}.c} file, you must do the
|
When writing a @file{elf@var{nn}-@var{cpu}.c} file, you must do the
|
following:
|
following:
|
|
|
@itemize @bullet
|
@itemize @bullet
|
@item
|
@item
|
Define either @samp{TARGET_BIG_SYM} or @samp{TARGET_LITTLE_SYM}, or
|
Define either @samp{TARGET_BIG_SYM} or @samp{TARGET_LITTLE_SYM}, or
|
both, to a unique C name to use for the target vector. This name should
|
both, to a unique C name to use for the target vector. This name should
|
appear in the list of target vectors in @file{targets.c}, and will also
|
appear in the list of target vectors in @file{targets.c}, and will also
|
have to appear in @file{config.bfd} and @file{configure.in}. Define
|
have to appear in @file{config.bfd} and @file{configure.in}. Define
|
@samp{TARGET_BIG_SYM} for a big-endian processor,
|
@samp{TARGET_BIG_SYM} for a big-endian processor,
|
@samp{TARGET_LITTLE_SYM} for a little-endian processor, and define both
|
@samp{TARGET_LITTLE_SYM} for a little-endian processor, and define both
|
for a bi-endian processor.
|
for a bi-endian processor.
|
@item
|
@item
|
Define either @samp{TARGET_BIG_NAME} or @samp{TARGET_LITTLE_NAME}, or
|
Define either @samp{TARGET_BIG_NAME} or @samp{TARGET_LITTLE_NAME}, or
|
both, to a string used as the name of the target vector. This is the
|
both, to a string used as the name of the target vector. This is the
|
name which a user of the BFD tool would use to specify the object file
|
name which a user of the BFD tool would use to specify the object file
|
format. It would normally appear in a linker emulation parameters
|
format. It would normally appear in a linker emulation parameters
|
file.
|
file.
|
@item
|
@item
|
Define @samp{ELF_ARCH} to the BFD architecture (an element of the
|
Define @samp{ELF_ARCH} to the BFD architecture (an element of the
|
@samp{bfd_architecture} enum, typically @samp{bfd_arch_@var{cpu}}).
|
@samp{bfd_architecture} enum, typically @samp{bfd_arch_@var{cpu}}).
|
@item
|
@item
|
Define @samp{ELF_MACHINE_CODE} to the magic number which should appear
|
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,
|
in the @samp{e_machine} field of the ELF header. As of this writing,
|
these magic numbers are assigned by Caldera; 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
|
number for a particular processor, try sending a note to
|
@email{registry@@caldera.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
|
found in @file{include/elf/common.h}; they have names beginning with
|
@samp{EM_}.
|
@samp{EM_}.
|
@item
|
@item
|
Define @samp{ELF_MAXPAGESIZE} to the maximum size of a virtual page in
|
Define @samp{ELF_MAXPAGESIZE} to the maximum size of a virtual page in
|
memory. This can normally be found at the start of chapter 5 in the
|
memory. This can normally be found at the start of chapter 5 in the
|
processor specific supplement. For a processor which will only be used
|
processor specific supplement. For a processor which will only be used
|
in an embedded system, or which has no memory management hardware, this
|
in an embedded system, or which has no memory management hardware, this
|
can simply be @samp{1}.
|
can simply be @samp{1}.
|
@item
|
@item
|
If the format should use @samp{Rel} rather than @samp{Rela} relocations,
|
If the format should use @samp{Rel} rather than @samp{Rela} relocations,
|
define @samp{USE_REL}. This is normally defined in chapter 4 of the
|
define @samp{USE_REL}. This is normally defined in chapter 4 of the
|
processor specific supplement.
|
processor specific supplement.
|
|
|
In the absence of a supplement, it's easier to work with @samp{Rela}
|
In the absence of a supplement, it's easier to work with @samp{Rela}
|
relocations. @samp{Rela} relocations will require more space in object
|
relocations. @samp{Rela} relocations will require more space in object
|
files (but not in executables, except when using dynamic linking).
|
files (but not in executables, except when using dynamic linking).
|
However, this is outweighed by the simplicity of addend handling when
|
However, this is outweighed by the simplicity of addend handling when
|
using @samp{Rela} relocations. With @samp{Rel} relocations, the addend
|
using @samp{Rela} relocations. With @samp{Rel} relocations, the addend
|
must be stored in the section contents, which makes relocatable links
|
must be stored in the section contents, which makes relocatable links
|
more complex.
|
more complex.
|
|
|
For example, consider C code like @code{i = a[1000];} where @samp{a} is
|
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]}
|
a global array. The instructions which load the value of @samp{a[1000]}
|
will most likely use a relocation which refers to the symbol
|
will most likely use a relocation which refers to the symbol
|
representing @samp{a}, with an addend that gives the offset from the
|
representing @samp{a}, with an addend that gives the offset from the
|
start of @samp{a} to element @samp{1000}. When using @samp{Rel}
|
start of @samp{a} to element @samp{1000}. When using @samp{Rel}
|
relocations, that addend must be stored in the instructions themselves.
|
relocations, that addend must be stored in the instructions themselves.
|
If you are adding support for a RISC chip which uses two or more
|
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
|
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.
|
instruction, and will have to be somehow split among the instructions.
|
This makes linking awkward, particularly when doing a relocatable 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
|
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.
|
ELF support does it---but it should be avoided when possible.
|
|
|
It is possible, though somewhat awkward, to support both @samp{Rel} and
|
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
|
@samp{Rela} relocations for a single target; @file{elf64-mips.c} does it
|
by overriding the relocation reading and writing routines.
|
by overriding the relocation reading and writing routines.
|
@item
|
@item
|
Define howto structures for all the relocation types.
|
Define howto structures for all the relocation types.
|
@item
|
@item
|
Define a @samp{bfd_reloc_type_lookup} routine. This must be named
|
Define a @samp{bfd_reloc_type_lookup} routine. This must be named
|
@samp{bfd_elf@var{nn}_bfd_reloc_type_lookup}, and may be either a
|
@samp{bfd_elf@var{nn}_bfd_reloc_type_lookup}, and may be either a
|
function or a macro. It must translate a BFD relocation code into a
|
function or a macro. It must translate a BFD relocation code into a
|
howto structure. This is normally a table lookup or a simple switch.
|
howto structure. This is normally a table lookup or a simple switch.
|
@item
|
@item
|
If using @samp{Rel} relocations, define @samp{elf_info_to_howto_rel}.
|
If using @samp{Rel} relocations, define @samp{elf_info_to_howto_rel}.
|
If using @samp{Rela} relocations, define @samp{elf_info_to_howto}.
|
If using @samp{Rela} relocations, define @samp{elf_info_to_howto}.
|
Either way, this is a macro defined as the name of a function which
|
Either way, this is a macro defined as the name of a function which
|
takes an @samp{arelent} and a @samp{Rel} or @samp{Rela} structure, and
|
takes an @samp{arelent} and a @samp{Rel} or @samp{Rela} structure, and
|
sets the @samp{howto} field of the @samp{arelent} based on the
|
sets the @samp{howto} field of the @samp{arelent} based on the
|
@samp{Rel} or @samp{Rela} structure. This is normally uses
|
@samp{Rel} or @samp{Rela} structure. This is normally uses
|
@samp{ELF@var{nn}_R_TYPE} to get the ELF relocation type and uses it as
|
@samp{ELF@var{nn}_R_TYPE} to get the ELF relocation type and uses it as
|
an index into a table of howto structures.
|
an index into a table of howto structures.
|
@end itemize
|
@end itemize
|
|
|
You must also add the magic number for this processor to the
|
You must also add the magic number for this processor to the
|
@samp{prep_headers} function in @file{elf.c}.
|
@samp{prep_headers} function in @file{elf.c}.
|
|
|
You must also create a header file in the @file{include/elf} directory
|
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
|
called @file{@var{cpu}.h}. This file should define any target specific
|
information which may be needed outside of the BFD code. In particular
|
information which may be needed outside of the BFD code. In particular
|
it should use the @samp{START_RELOC_NUMBERS}, @samp{RELOC_NUMBER},
|
it should use the @samp{START_RELOC_NUMBERS}, @samp{RELOC_NUMBER},
|
@samp{FAKE_RELOC}, @samp{EMPTY_RELOC} and @samp{END_RELOC_NUMBERS}
|
@samp{FAKE_RELOC}, @samp{EMPTY_RELOC} and @samp{END_RELOC_NUMBERS}
|
macros to create a table mapping the number used to identify a
|
macros to create a table mapping the number used to identify a
|
relocation to a name describing that relocation.
|
relocation to a name describing that relocation.
|
|
|
While not a BFD component, you probably also want to make the binutils
|
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
|
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}.
|
code for @code{EM_@var{cpu}} as appropriate in @file{binutils/readelf.c}.
|
|
|
@node BFD ELF processor linker
|
@node BFD ELF processor linker
|
@subsubsection Processor specific linker support
|
@subsubsection Processor specific linker support
|
|
|
The linker will be much more efficient if you define a relocate section
|
The linker will be much more efficient if you define a relocate section
|
function. This will permit BFD to use the ELF specific linker support.
|
function. This will permit BFD to use the ELF specific linker support.
|
|
|
If you do not define a relocate section function, BFD must use the
|
If you do not define a relocate section function, BFD must use the
|
generic linker support, which requires converting all symbols and
|
generic linker support, which requires converting all symbols and
|
relocations into BFD @samp{asymbol} and @samp{arelent} structures. In
|
relocations into BFD @samp{asymbol} and @samp{arelent} structures. In
|
this case, relocations will be handled by calling
|
this case, relocations will be handled by calling
|
@samp{bfd_perform_relocation}, which will use the howto structures you
|
@samp{bfd_perform_relocation}, which will use the howto structures you
|
have defined. @xref{BFD relocation handling}.
|
have defined. @xref{BFD relocation handling}.
|
|
|
In order to support linking into a different object file format, such as
|
In order to support linking into a different object file format, such as
|
S-records, @samp{bfd_perform_relocation} must work correctly with your
|
S-records, @samp{bfd_perform_relocation} must work correctly with your
|
howto structures, so you can't skip that step. However, if you define
|
howto structures, so you can't skip that step. However, if you define
|
the relocate section function, then in the normal case of linking into
|
the relocate section function, then in the normal case of linking into
|
an ELF file the linker will not need to convert symbols and relocations,
|
an ELF file the linker will not need to convert symbols and relocations,
|
and will be much more efficient.
|
and will be much more efficient.
|
|
|
To use a relocation section function, define the macro
|
To use a relocation section function, define the macro
|
@samp{elf_backend_relocate_section} as the name of a function which will
|
@samp{elf_backend_relocate_section} as the name of a function which will
|
take the contents of a section, as well as relocation, symbol, and other
|
take the contents of a section, as well as relocation, symbol, and other
|
information, and modify the section contents according to the relocation
|
information, and modify the section contents according to the relocation
|
information. In simple cases, this is little more than a loop over the
|
information. In simple cases, this is little more than a loop over the
|
relocations which computes the value of each relocation and calls
|
relocations which computes the value of each relocation and calls
|
@samp{_bfd_final_link_relocate}. The function must check for a
|
@samp{_bfd_final_link_relocate}. The function must check for a
|
relocatable 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.
|
than adjust the addend for relocations against a section symbol.
|
|
|
The complex cases generally have to do with dynamic linker support. GOT
|
The complex cases generally have to do with dynamic linker support. GOT
|
and PLT relocations must be handled specially, and the linker normally
|
and PLT relocations must be handled specially, and the linker normally
|
arranges to set up the GOT and PLT sections while handling relocations.
|
arranges to set up the GOT and PLT sections while handling relocations.
|
When generating a shared library, random relocations must normally be
|
When generating a shared library, random relocations must normally be
|
copied into the shared library, or converted to RELATIVE relocations
|
copied into the shared library, or converted to RELATIVE relocations
|
when possible.
|
when possible.
|
|
|
@node BFD ELF processor other
|
@node BFD ELF processor other
|
@subsubsection Other processor specific support options
|
@subsubsection Other processor specific support options
|
|
|
There are many other macros which may be defined in
|
There are many other macros which may be defined in
|
@file{elf@var{nn}-@var{cpu}.c}. These macros may be found in
|
@file{elf@var{nn}-@var{cpu}.c}. These macros may be found in
|
@file{elfxx-target.h}.
|
@file{elfxx-target.h}.
|
|
|
Macros may be used to override some of the generic ELF target vector
|
Macros may be used to override some of the generic ELF target vector
|
functions.
|
functions.
|
|
|
Several processor specific hook functions which may be defined as
|
Several processor specific hook functions which may be defined as
|
macros. These functions are found as function pointers in the
|
macros. These functions are found as function pointers in the
|
@samp{elf_backend_data} structure defined in @file{elf-bfd.h}. In
|
@samp{elf_backend_data} structure defined in @file{elf-bfd.h}. In
|
general, a hook function is set by defining a macro
|
general, a hook function is set by defining a macro
|
@samp{elf_backend_@var{name}}.
|
@samp{elf_backend_@var{name}}.
|
|
|
There are a few processor specific constants which may also be defined.
|
There are a few processor specific constants which may also be defined.
|
These are again found in the @samp{elf_backend_data} structure.
|
These are again found in the @samp{elf_backend_data} structure.
|
|
|
I will not define the various functions and constants here; see the
|
I will not define the various functions and constants here; see the
|
comments in @file{elf-bfd.h}.
|
comments in @file{elf-bfd.h}.
|
|
|
Normally any odd characteristic of a particular ELF processor is handled
|
Normally any odd characteristic of a particular ELF processor is handled
|
via a hook function. For example, the special @samp{SHN_MIPS_SCOMMON}
|
via a hook function. For example, the special @samp{SHN_MIPS_SCOMMON}
|
section number found in MIPS ELF is handled via the hooks
|
section number found in MIPS ELF is handled via the hooks
|
@samp{section_from_bfd_section}, @samp{symbol_processing},
|
@samp{section_from_bfd_section}, @samp{symbol_processing},
|
@samp{add_symbol_hook}, and @samp{output_symbol_hook}.
|
@samp{add_symbol_hook}, and @samp{output_symbol_hook}.
|
|
|
Dynamic linking support, which involves processor specific relocations
|
Dynamic linking support, which involves processor specific relocations
|
requiring special handling, is also implemented via hook functions.
|
requiring special handling, is also implemented via hook functions.
|
|
|
@node BFD ELF core files
|
@node BFD ELF core files
|
@subsection BFD ELF core files
|
@subsection BFD ELF core files
|
@cindex elf core files
|
@cindex elf core files
|
|
|
On native ELF Unix systems, core files are generated without any
|
On native ELF Unix systems, core files are generated without any
|
sections. Instead, they only have program segments.
|
sections. Instead, they only have program segments.
|
|
|
When BFD is used to read an ELF core file, the BFD sections will
|
When BFD is used to read an ELF core file, the BFD sections will
|
actually represent program segments. Since ELF program segments do not
|
actually represent program segments. Since ELF program segments do not
|
have names, BFD will invent names like @samp{segment@var{n}} where
|
have names, BFD will invent names like @samp{segment@var{n}} where
|
@var{n} is a number.
|
@var{n} is a number.
|
|
|
A single ELF program segment may include both an initialized part and an
|
A single ELF program segment may include both an initialized part and an
|
uninitialized part. The size of the initialized part is given by the
|
uninitialized part. The size of the initialized part is given by the
|
@samp{p_filesz} field. The total size of the segment is given by the
|
@samp{p_filesz} field. The total size of the segment is given by the
|
@samp{p_memsz} field. If @samp{p_memsz} is larger than @samp{p_filesz},
|
@samp{p_memsz} field. If @samp{p_memsz} is larger than @samp{p_filesz},
|
then the extra space is uninitialized, or, more precisely, initialized
|
then the extra space is uninitialized, or, more precisely, initialized
|
to zero.
|
to zero.
|
|
|
BFD will represent such a program segment as two different sections.
|
BFD will represent such a program segment as two different sections.
|
The first, named @samp{segment@var{n}a}, will represent the initialized
|
The first, named @samp{segment@var{n}a}, will represent the initialized
|
part of the program segment. The second, named @samp{segment@var{n}b},
|
part of the program segment. The second, named @samp{segment@var{n}b},
|
will represent the uninitialized part.
|
will represent the uninitialized part.
|
|
|
ELF core files store special information such as register values in
|
ELF core files store special information such as register values in
|
program segments with the type @samp{PT_NOTE}. BFD will attempt to
|
program segments with the type @samp{PT_NOTE}. BFD will attempt to
|
interpret the information in these segments, and will create additional
|
interpret the information in these segments, and will create additional
|
sections holding the information. Some of this interpretation requires
|
sections holding the information. Some of this interpretation requires
|
information found in the host header file @file{sys/procfs.h}, and so
|
information found in the host header file @file{sys/procfs.h}, and so
|
will only work when BFD is built on a native system.
|
will only work when BFD is built on a native system.
|
|
|
BFD does not currently provide any way to create an ELF core file. In
|
BFD does not currently provide any way to create an ELF core file. In
|
general, BFD does not provide a way to create core files. The way to
|
general, BFD does not provide a way to create core files. The way to
|
implement this would be to write @samp{bfd_set_format} and
|
implement this would be to write @samp{bfd_set_format} and
|
@samp{bfd_write_contents} routines for the @samp{bfd_core} type; see
|
@samp{bfd_write_contents} routines for the @samp{bfd_core} type; see
|
@ref{BFD target vector format}.
|
@ref{BFD target vector format}.
|
|
|
@node BFD ELF future
|
@node BFD ELF future
|
@subsection BFD ELF future
|
@subsection BFD ELF future
|
|
|
The current dynamic linking support has too much code duplication.
|
The current dynamic linking support has too much code duplication.
|
While each processor has particular differences, much of the dynamic
|
While each processor has particular differences, much of the dynamic
|
linking support is quite similar for each processor. The GOT and PLT
|
linking support is quite similar for each processor. The GOT and PLT
|
are handled in fairly similar ways, the details of -Bsymbolic linking
|
are handled in fairly similar ways, the details of -Bsymbolic linking
|
are generally similar, etc. This code should be reworked to use more
|
are generally similar, etc. This code should be reworked to use more
|
generic functions, eliminating the duplication.
|
generic functions, eliminating the duplication.
|
|
|
Similarly, the relocation handling has too much duplication. Many of
|
Similarly, the relocation handling has too much duplication. Many of
|
the @samp{reloc_type_lookup} and @samp{info_to_howto} functions are
|
the @samp{reloc_type_lookup} and @samp{info_to_howto} functions are
|
quite similar. The relocate section functions are also often quite
|
quite similar. The relocate section functions are also often quite
|
similar, both in the standard linker handling and the dynamic linker
|
similar, both in the standard linker handling and the dynamic linker
|
handling. Many of the COFF processor specific backends share a single
|
handling. Many of the COFF processor specific backends share a single
|
relocate section function (@samp{_bfd_coff_generic_relocate_section}),
|
relocate section function (@samp{_bfd_coff_generic_relocate_section}),
|
and it should be possible to do something like this for the ELF targets
|
and it should be possible to do something like this for the ELF targets
|
as well.
|
as well.
|
|
|
The appearance of the processor specific magic number in
|
The appearance of the processor specific magic number in
|
@samp{prep_headers} in @file{elf.c} is somewhat bogus. It should be
|
@samp{prep_headers} in @file{elf.c} is somewhat bogus. It should be
|
possible to add support for a new processor without changing the generic
|
possible to add support for a new processor without changing the generic
|
support.
|
support.
|
|
|
The processor function hooks and constants are ad hoc and need better
|
The processor function hooks and constants are ad hoc and need better
|
documentation.
|
documentation.
|
|
|
@node BFD glossary
|
@node BFD glossary
|
@section BFD glossary
|
@section BFD glossary
|
@cindex glossary for bfd
|
@cindex glossary for bfd
|
@cindex bfd glossary
|
@cindex bfd glossary
|
|
|
This is a short glossary of some BFD terms.
|
This is a short glossary of some BFD terms.
|
|
|
@table @asis
|
@table @asis
|
@item a.out
|
@item a.out
|
The a.out object file format. The original Unix object file format.
|
The a.out object file format. The original Unix object file format.
|
Still used on SunOS, though not Solaris. Supports only three sections.
|
Still used on SunOS, though not Solaris. Supports only three sections.
|
|
|
@item archive
|
@item archive
|
A collection of object files produced and manipulated by the @samp{ar}
|
A collection of object files produced and manipulated by the @samp{ar}
|
program.
|
program.
|
|
|
@item backend
|
@item backend
|
The implementation within BFD of a particular object file format. The
|
The implementation within BFD of a particular object file format. The
|
set of functions which appear in a particular target vector.
|
set of functions which appear in a particular target vector.
|
|
|
@item BFD
|
@item BFD
|
The BFD library itself. Also, each object file, archive, or executable
|
The BFD library itself. Also, each object file, archive, or executable
|
opened by the BFD library has the type @samp{bfd *}, and is sometimes
|
opened by the BFD library has the type @samp{bfd *}, and is sometimes
|
referred to as a bfd.
|
referred to as a bfd.
|
|
|
@item COFF
|
@item COFF
|
The Common Object File Format. Used on Unix SVR3. Used by some
|
The Common Object File Format. Used on Unix SVR3. Used by some
|
embedded targets, although ELF is normally better.
|
embedded targets, although ELF is normally better.
|
|
|
@item DLL
|
@item DLL
|
A shared library on Windows.
|
A shared library on Windows.
|
|
|
@item dynamic linker
|
@item dynamic linker
|
When a program linked against a shared library is run, the dynamic
|
When a program linked against a shared library is run, the dynamic
|
linker will locate the appropriate shared library and arrange to somehow
|
linker will locate the appropriate shared library and arrange to somehow
|
include it in the running image.
|
include it in the running image.
|
|
|
@item dynamic object
|
@item dynamic object
|
Another name for an ELF shared library.
|
Another name for an ELF shared library.
|
|
|
@item ECOFF
|
@item ECOFF
|
The Extended Common Object File Format. Used on Alpha Digital Unix
|
The Extended Common Object File Format. Used on Alpha Digital Unix
|
(formerly OSF/1), as well as Ultrix and Irix 4. A variant of COFF.
|
(formerly OSF/1), as well as Ultrix and Irix 4. A variant of COFF.
|
|
|
@item ELF
|
@item ELF
|
The Executable and Linking Format. The object file format used on most
|
The Executable and Linking Format. The object file format used on most
|
modern Unix systems, including GNU/Linux, Solaris, Irix, and SVR4. Also
|
modern Unix systems, including GNU/Linux, Solaris, Irix, and SVR4. Also
|
used on many embedded systems.
|
used on many embedded systems.
|
|
|
@item executable
|
@item executable
|
A program, with instructions and symbols, and perhaps dynamic linking
|
A program, with instructions and symbols, and perhaps dynamic linking
|
information. Normally produced by a linker.
|
information. Normally produced by a linker.
|
|
|
@item LMA
|
@item LMA
|
Load Memory Address. This is the address at which a section will be
|
Load Memory Address. This is the address at which a section will be
|
loaded. Compare with VMA, below.
|
loaded. Compare with VMA, below.
|
|
|
@item NLM
|
@item NLM
|
NetWare Loadable Module. Used to describe the format of an object which
|
NetWare Loadable Module. Used to describe the format of an object which
|
be loaded into NetWare, which is some kind of PC based network server
|
be loaded into NetWare, which is some kind of PC based network server
|
program.
|
program.
|
|
|
@item object file
|
@item object file
|
A binary file including machine instructions, symbols, and relocation
|
A binary file including machine instructions, symbols, and relocation
|
information. Normally produced by an assembler.
|
information. Normally produced by an assembler.
|
|
|
@item object file format
|
@item object file format
|
The format of an object file. Typically object files and executables
|
The format of an object file. Typically object files and executables
|
for a particular system are in the same format, although executables
|
for a particular system are in the same format, although executables
|
will not contain any relocation information.
|
will not contain any relocation information.
|
|
|
@item PE
|
@item PE
|
The Portable Executable format. This is the object file format used for
|
The Portable Executable format. This is the object file format used for
|
Windows (specifically, Win32) object files. It is based closely on
|
Windows (specifically, Win32) object files. It is based closely on
|
COFF, but has a few significant differences.
|
COFF, but has a few significant differences.
|
|
|
@item PEI
|
@item PEI
|
The Portable Executable Image format. This is the object file format
|
The Portable Executable Image format. This is the object file format
|
used for Windows (specifically, Win32) executables. It is very similar
|
used for Windows (specifically, Win32) executables. It is very similar
|
to PE, but includes some additional header information.
|
to PE, but includes some additional header information.
|
|
|
@item relocations
|
@item relocations
|
Information used by the linker to adjust section contents. Also called
|
Information used by the linker to adjust section contents. Also called
|
relocs.
|
relocs.
|
|
|
@item section
|
@item section
|
Object files and executable are composed of sections. Sections have
|
Object files and executable are composed of sections. Sections have
|
optional data and optional relocation information.
|
optional data and optional relocation information.
|
|
|
@item shared library
|
@item shared library
|
A library of functions which may be used by many executables without
|
A library of functions which may be used by many executables without
|
actually being linked into each executable. There are several different
|
actually being linked into each executable. There are several different
|
implementations of shared libraries, each having slightly different
|
implementations of shared libraries, each having slightly different
|
features.
|
features.
|
|
|
@item symbol
|
@item symbol
|
Each object file and executable may have a list of symbols, often
|
Each object file and executable may have a list of symbols, often
|
referred to as the symbol table. A symbol is basically a name and an
|
referred to as the symbol table. A symbol is basically a name and an
|
address. There may also be some additional information like the type of
|
address. There may also be some additional information like the type of
|
symbol, although the type of a symbol is normally something simple like
|
symbol, although the type of a symbol is normally something simple like
|
function or object, and should be confused with the more complex C
|
function or object, and should be confused with the more complex C
|
notion of type. Typically every global function and variable in a C
|
notion of type. Typically every global function and variable in a C
|
program will have an associated symbol.
|
program will have an associated symbol.
|
|
|
@item target vector
|
@item target vector
|
A set of functions which implement support for a particular object file
|
A set of functions which implement support for a particular object file
|
format. The @samp{bfd_target} structure.
|
format. The @samp{bfd_target} structure.
|
|
|
@item Win32
|
@item Win32
|
The current Windows API, implemented by Windows 95 and later and Windows
|
The current Windows API, implemented by Windows 95 and later and Windows
|
NT 3.51 and later, but not by Windows 3.1.
|
NT 3.51 and later, but not by Windows 3.1.
|
|
|
@item XCOFF
|
@item XCOFF
|
The eXtended Common Object File Format. Used on AIX. A variant of
|
The eXtended Common Object File Format. Used on AIX. A variant of
|
COFF, with a completely different symbol table implementation.
|
COFF, with a completely different symbol table implementation.
|
|
|
@item VMA
|
@item VMA
|
Virtual Memory Address. This is the address a section will have when
|
Virtual Memory Address. This is the address a section will have when
|
an executable is run. Compare with LMA, above.
|
an executable is run. Compare with LMA, above.
|
@end table
|
@end table
|
|
|
@node Index
|
@node Index
|
@unnumberedsec Index
|
@unnumberedsec Index
|
@printindex cp
|
@printindex cp
|
|
|
@contents
|
@contents
|
@bye
|
@bye
|
|
|
