New documentation style

This commit is contained in:
Steve Chamberlain 1991-12-01 00:39:12 +00:00
parent 93351e91c5
commit 0cda46cff1
8 changed files with 1055 additions and 1062 deletions

View file

@ -20,18 +20,21 @@ Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. */
/*doc* /*doc*
@setfilename archive-info @setfilename archive-info
@section Archives SECTION
Archives
DESCRIPTION
Gumby, you promised to write this bit... Gumby, you promised to write this bit...
Archives are supported in BFD in @code{archive.c}. Archives are supported in BFD in <<archive.c>>.
An archive is represented internally just like another BFD, with a An archive is represented internally just like another BFD,
pointer to a chain of contained BFDs. Archives can be created by with a pointer to a chain of contained BFDs. Archives can be
opening BFDs, linking them together and attaching them as children to created by opening BFDs, linking them together and attaching
another BFD and then closing the parent BFD. them as children to another BFD and then closing the parent
BFD.
*-*/ */
/* Assumes: /* Assumes:
o - all archive elements start on an even boundary, newline padded; o - all archive elements start on an even boundary, newline padded;
@ -84,9 +87,15 @@ _bfd_generic_mkarchive (abfd)
return true; return true;
} }
/*proto* bfd_get_next_mapent /*
FUNCTION
bfd_get_next_mapent
DESCRIPTION
What this does What this does
*; PROTO(symindex, bfd_get_next_mapent, (bfd *, symindex, carsym **));
SYNOPSIS
symindex bfd_get_next_mapent(bfd *, symindex, carsym **);
*/ */
symindex symindex
bfd_get_next_mapent (abfd, prev, entry) bfd_get_next_mapent (abfd, prev, entry)
@ -123,12 +132,17 @@ _bfd_create_empty_archive_element_shell (obfd)
return nbfd; return nbfd;
} }
/*proto* bfd_set_archive_head /*
FUNCTION
bfd_set_archive_head
Used whilst processing archives. Sets the head of the chain of BFDs DESCRIPTION
contained in an archive to @var{new_head}. (see chapter on archives) Used whilst processing archives. Sets the head of the chain of
BFDs contained in an archive to @var{new_head}. (see chapter
on archives)
*; PROTO(boolean, bfd_set_archive_head, (bfd *output, bfd *new_head)); SYNOPSIS
boolean bfd_set_archive_head(bfd *output, bfd *new_head);
*/ */
@ -342,10 +356,15 @@ get_elt_at_filepos (archive, filepos)
return NULL; return NULL;
} }
/*proto* bfd_get_elt_at_index /*
FUNCTION
bfd_get_elt_at_index
DESCRIPTION
Return the sub bfd contained within the archive at archive index n. Return the sub bfd contained within the archive at archive index n.
*; PROTO(bfd *, bfd_get_elt_at_index, (bfd *, int)); SYNOPSIS
bfd *bfd_get_elt_at_index(bfd *, int);
*/ */
bfd * bfd *
@ -359,15 +378,20 @@ bfd_get_elt_at_index (abfd, index)
return result; return result;
} }
/*proto* bfd_openr_next_archived_file /*
Initially provided a BFD containing an archive and NULL, opens a BFD FUNCTION
on the first contained element and returns that. Subsequent calls to bfd_openr_next_archived_file
bfd_openr_next_archived_file should pass the archive and the previous
return value to return a created BFD to the next contained element.
NULL is returned when there are no more.
*; PROTO(bfd*, bfd_openr_next_archived_file, DESCRIPTION
(bfd *archive, bfd *previous)); Initially provided a BFD containing an archive and NULL, opens
a BFD on the first contained element and returns that.
Subsequent calls to bfd_openr_next_archived_file should pass
the archive and the previous return value to return a created
BFD to the next contained element. NULL is returned when there
are no more.
SYNOPSIS
bfd* bfd_openr_next_archived_file(bfd *archive, bfd *previous);
*/ */
@ -1234,7 +1258,7 @@ bsd_write_armap (arch, elength, map, orl_count, stridx)
/* A coff armap looks like : /* A coff armap looks like :
ARMAG lARMAG
struct ar_hdr with name = '/' struct ar_hdr with name = '/'
number of symbols number of symbols
offset of file for symbol 0 offset of file for symbol 0

View file

@ -18,8 +18,11 @@ You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software along with this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. */ Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. */
/*doc* /*
@section Core files SECTION
Core files
DESCRIPTION
Buff output this facinating topic Buff output this facinating topic
*/ */
@ -27,13 +30,17 @@ Buff output this facinating topic
#include "sysdep.h" #include "sysdep.h"
#include "libbfd.h" #include "libbfd.h"
/** Some core file info commands */
/*proto* bfd_core_file_failing_command /*
Returns a read-only string explaining what program was running when FUNCTION
it failed and produced the core file being read bfd_core_file_failing_command
*; PROTO(CONST char *, bfd_core_file_failing_command, (bfd *)); DESCRIPTION
Returns a read-only string explaining what program was running
when it failed and produced the core file being read
SYNOPSIS
CONST char *bfd_core_file_failing_command(bfd *);
*/ */
CONST char * CONST char *
@ -47,12 +54,18 @@ DEFUN(bfd_core_file_failing_command,(abfd),
return BFD_SEND (abfd, _core_file_failing_command, (abfd)); return BFD_SEND (abfd, _core_file_failing_command, (abfd));
} }
/*proto* bfd_core_file_failing_signal /*
Returns the signal number which caused the core dump which generated FUNCTION
the file the BFD is attached to. bfd_core_file_failing_signal
*; PROTO(int, bfd_core_file_failing_signal, (bfd *)); DESCRIPTION
Returns the signal number which caused the core dump which
generated the file the BFD is attached to.
SYNOPSIS
int bfd_core_file_failing_signal(bfd *);
*/ */
int int
bfd_core_file_failing_signal (abfd) bfd_core_file_failing_signal (abfd)
bfd *abfd; bfd *abfd;
@ -65,13 +78,20 @@ bfd_core_file_failing_signal (abfd)
} }
/*proto* core_file_matches_executable_p /*
Returns @code{true} if the core file attached to @var{core_bfd} was FUNCTION
generated by a run of the executable file attached to @var{exec_bfd}, core_file_matches_executable_p
or else @code{false}.
*; PROTO(boolean, core_file_matches_executable_p, DESCRIPTION
(bfd *core_bfd, bfd *exec_bfd)); Returns <<true>> if the core file attached to @var{core_bfd}
was generated by a run of the executable file attached to
@var{exec_bfd}, or else <<false>>.
SYNOPSIS
boolean core_file_matches_executable_p
(bfd *core_bfd, bfd *exec_bfd);
*/ */
boolean boolean
core_file_matches_executable_p (core_bfd, exec_bfd) core_file_matches_executable_p (core_bfd, exec_bfd)
bfd *core_bfd, *exec_bfd; bfd *core_bfd, *exec_bfd;
@ -81,5 +101,6 @@ core_file_matches_executable_p (core_bfd, exec_bfd)
return false; return false;
} }
return BFD_SEND (core_bfd, _core_file_matches_executable_p, (core_bfd, exec_bfd)); return BFD_SEND (core_bfd, _core_file_matches_executable_p,
(core_bfd, exec_bfd));
} }

View file

@ -21,62 +21,67 @@ You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software along with this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. */ Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. */
/*doc* /*
@section Constructors SECTION
Classes in C++ have 'constructors' and 'destructors'. These are Constructors
functions which are called automatically by the language whenever data
of a class is created or destroyed. Class data which is static data
may also be have a type which requires 'construction', the contructor
must be called before the data can be referenced, so the contructor
must be called before the program begins.
The common solution to this problem is for the compiler to call a DESCRIPTION
magic function as the first statement @code{main}. This magic Classes in C++ have 'constructors' and 'destructors'. These
function, (often called @code{__main}) runs around calling the are functions which are called automatically by the language
constructors for all the things needing it. whenever data of a class is created or destroyed. Class data
which is static data may also be have a type which requires
'construction', the contructor must be called before the data
can be referenced, so the contructor must be called before the
program begins.
With COFF the compile has a bargain with the linker et al. All The common solution to this problem is for the compiler to
constructors are given strange names, for example call a magic function as the first statement <<main>>.
@code{__GLOBAL__$I$foo} might be the label of a contructor for the This magic function, (often called <<__main>>) runs around
class @var{foo}. The solution on unfortunate systems (most system V calling the constructors for all the things needing it.
machines) is to perform a partial link on all the .o files, do an
@code{nm} on the result, run @code{awk} or some such over the result
looking for strange @code{__GLOBAL__$} symbols, generate a C program
from this, compile it and link with the partially linked input. This
process is usually called @code{collect}.
Some versions of @code{a.out} use something called the With COFF the compile has a bargain with the linker et al.
@code{set_vector} mechanism. The constructor symbols are output from All constructors are given strange names, for example
the compiler with a special stab code saying that they are <<__GLOBAL__$I$foo>> might be the label of a contructor for
constructors, and the linker can deal with them directly. the class @var{foo}. The solution on unfortunate systems
(most system V machines) is to perform a partial link on all
the .o files, do an <<nm>> on the result, run <<awk>> or some
such over the result looking for strange <<__GLOBAL__$>>
symbols, generate a C program from this, compile it and link
with the partially linked input. This process is usually
called <<collect>>.
BFD allows applications (ie the linker) to deal with constructor Some versions of <<a.out>> use something called the
information independently of their external implimentation by <<set_vector>> mechanism. The constructor symbols are output
providing a set of entry points for the indiviual object back ends to from the compiler with a special stab code saying that they
call which maintains a database of the contructor information. The are constructors, and the linker can deal with them directly.
application can interrogate the database to find out what it wants.
The construction data essential for the linker to be able to perform BFD allows applications (ie the linker) to deal with
its job are: constructor information independently of their external
implimentation by providing a set of entry points for the
indiviual object back ends to call which maintains a database
of the contructor information. The application can
interrogate the database to find out what it wants. The
construction data essential for the linker to be able to
perform its job are:
@itemize @bullet o asymbol
@item asymbol The asymbol of the contructor entry point contains all the
The asymbol of the contructor entry point contains all the information information necessary to call the function.
necessary to call the function.
@item table id
The type of symbol, ie is it a contructor, a destructor or something
else someone dreamed up to make our lives difficult.
@end itemize
This module takes this information and then builds extra sections o table id
attached to the bfds which own the entry points. It creates these The type of symbol, ie is it a contructor, a destructor or
sections as if they were tables of pointers to the entry points, and something else someone dreamed up to make our lives difficult.
builds relocation entries to go with them so that the tables can be
relocated along with the data they reference.
These sections are marked with a special bit (@code{SEC_CONSTRUCTOR}) This module takes this information and then builds extra
which the linker notices and do with what it wants. sections attached to the bfds which own the entry points. It
creates these sections as if they were tables of pointers to
the entry points, and builds relocation entries to go with
them so that the tables can be relocated along with the data
they reference.
These sections are marked with a special bit
(<<SEC_CONSTRUCTOR>>) which the linker notices and do with
what it wants.
*/ */
@ -86,22 +91,23 @@ which the linker notices and do with what it wants.
/*proto-internal* bfd_constructor_entry /*
INTERNAL FUNCTION
bfd_constructor_entry
DESCRIPTION
This function is called with an a symbol describing the This function is called with an a symbol describing the
function to be called, an string which descibes the xtor type, eg function to be called, an string which descibes the xtor type,
something like "CTOR" or "DTOR" would be fine. And the bfd which owns eg something like "CTOR" or "DTOR" would be fine. And the bfd
the function. which owns the function. Its duty is to create a section
called "CTOR" or "DTOR" or whatever if the bfd doesn't already
have one, and grow a relocation table for the entry points as
they accumulate.
It's duty is to create a section called "CTOR" or "DTOR" or whatever SYNOPSIS
if the bfd doesn't already have one, and grow a relocation table for void bfd_constructor_entry(bfd *abfd,
the entry points as they accumulate.
*; PROTO(void, bfd_constructor_entry,
(bfd *abfd,
asymbol **symbol_ptr_ptr, asymbol **symbol_ptr_ptr,
CONST char*type)); CONST char*type);
*/ */

View file

@ -189,147 +189,33 @@ extern bfd *bfd_last_cache;
/* THE FOLLOWING IS EXTRACTED FROM THE SOURCE*/ /* THE FOLLOWING IS EXTRACTED FROM THE SOURCE*/
/*:init.c*/ /*:init.c*/
/* bfd_check_init
This routine is called before any other bfd function using initialized
data is used to ensure that the structures have been initialized.
Soon this function will go away, and the bfd library will assume that
bfd_init has been called.
*/
void EXFUN(bfd_check_init, (void)); void EXFUN(bfd_check_init, (void));
/*
*/
/*:libbfd.c*/ /*:libbfd.c*/
/* bfd_xmalloc bfd_vma EXFUN(bfd_log2, (bfd_vma x));
bfd_xmalloc -- Like malloc, but exit if no more memory.
*/
PROTO(PTR, bfd_xmalloc,( bfd_size_type size));
/*
bfd_write_bigendian_4byte_int
*/
PROTO(void, bfd_write_bigendian_4byte_int,( bfd *abfd, int i));
/*
*i bfd_log2
Return the log base 2 of the value supplied, rounded up. eg an arg
of 1025 would return 11.
*/
PROTO(bfd_vma, bfd_log2,(bfd_vma x));
/*
*/
/*:cache.c*/ /*:cache.c*/
/* BFD_CACHE_MAX_OPEN
The maxiumum number of files which the cache will keep open at one
time.
*/
#define BFD_CACHE_MAX_OPEN 10 #define BFD_CACHE_MAX_OPEN 10
/*
bfd_last_cache
Zero, or a pointer to the topmost BFD on the chain. This is used by
the @code{bfd_cache_lookup} macro in @file{libbfd.h} to determine when
it can avoid a function call.
*/
extern bfd *bfd_last_cache; extern bfd *bfd_last_cache;
/*
bfd_cache_lookup
Checks to see if the required BFD is the same as the last one looked
up. If so then it can use the iostream in the BFD with impunity, since
it can't have changed since the last lookup, otherwise it has to
perform the complicated lookup function
*/
#define bfd_cache_lookup(x) \ #define bfd_cache_lookup(x) \
((x)==bfd_last_cache? \ ((x)==bfd_last_cache? \
(FILE*)(bfd_last_cache->iostream): \ (FILE*)(bfd_last_cache->iostream): \
bfd_cache_lookup_worker(x)) bfd_cache_lookup_worker(x))
void EXFUN(bfd_cache_init , (bfd *));
/* void EXFUN(bfd_cache_close , (bfd *));
FILE* EXFUN(bfd_open_file, (bfd *));
*i bfd_cache_init FILE *EXFUN(bfd_cache_lookup_worker, (bfd *));
Initialize a BFD by putting it on the cache LRU.
*/
PROTO(void, bfd_cache_init, (bfd *));
/*
*i bfd_cache_close
Remove the BFD from the cache. If the attached file is open, then close it too.
*/
PROTO(void, bfd_cache_close, (bfd *));
/*
*i bfd_open_file
Call the OS to open a file for this BFD. Returns the FILE *
(possibly null) that results from this operation. Sets up the
BFD so that future accesses know the file is open. If the FILE *
returned is null, then there is won't have been put in the cache, so
it won't have to be removed from it.
*/
PROTO(FILE *, bfd_open_file, (bfd *));
/*
*i bfd_cache_lookup_worker
Called when the macro @code{bfd_cache_lookup} fails to find a quick
answer. Finds a file descriptor for this BFD. If necessary, it open it.
If there are already more than BFD_CACHE_MAX_OPEN files open, it trys to close
one first, to avoid running out of file descriptors.
*/
PROTO(FILE *, bfd_cache_lookup_worker, (bfd *));
/*
*/
/*:ctor.c*/ /*:ctor.c*/
/* bfd_constructor_entry void EXFUN(bfd_constructor_entry, (bfd *abfd,
This function is called with an a symbol describing the
function to be called, an string which descibes the xtor type, eg
something like "CTOR" or "DTOR" would be fine. And the bfd which owns
the function.
It's duty is to create a section called "CTOR" or "DTOR" or whatever
if the bfd doesn't already have one, and grow a relocation table for
the entry points as they accumulate.
*/
PROTO(void, bfd_constructor_entry,
(bfd *abfd,
asymbol **symbol_ptr_ptr, asymbol **symbol_ptr_ptr,
CONST char*type)); CONST char*type));
/*
*/
/*:reloc.c*/ /*:reloc.c*/
/* bfd_default_reloc_type_lookup CONST struct reloc_howto_struct *EXFUN(bfd_default_reloc_type_lookup
, (CONST struct bfd_arch_info *,
Provides a default relocation lookuperer for any architectue
*/
CONST struct reloc_howto_struct *EXFUN(bfd_default_reloc_type_lookup,
(CONST struct bfd_arch_info *,
bfd_reloc_code_type code)); bfd_reloc_code_type code));
/*
*/
/*:cpu-h8300.c*/ /*:cpu-h8300.c*/
/*:cpu-i960.c*/ /*:cpu-i960.c*/
@ -337,62 +223,13 @@ Provides a default relocation lookuperer for any architectue
/*:cpu-empty.c*/ /*:cpu-empty.c*/
/*:archures.c*/ /*:archures.c*/
/* bfd_default_arch_struct
What bfds are seeded with
*/
extern bfd_arch_info_type bfd_default_arch_struct;
/*
bfd_default_set_arch_mach
Set the architecture and machine type in a bfd. This finds the correct
pointer to structure and inserts it into the arch_info pointer.
*/
boolean EXFUN(bfd_default_set_arch_mach, (bfd *abfd, boolean EXFUN(bfd_default_set_arch_mach, (bfd *abfd,
enum bfd_architecture arch, enum bfd_architecture arch,
unsigned long mach)); unsigned long mach));
void EXFUN(bfd_arch_init, (void));
/*
This routine initializes the architecture dispatch table by calling
all installed architecture packages and getting them to poke around.
*/
PROTO(void, bfd_arch_init,(void));
/*
bfd_arch_linkin
Link the provided arch info structure into the list
*/
void EXFUN(bfd_arch_linkin, (bfd_arch_info_type *)); void EXFUN(bfd_arch_linkin, (bfd_arch_info_type *));
CONST bfd_arch_info_type *EXFUN(bfd_default_compatible
/* , (CONST bfd_arch_info_type *a,
bfd_default_compatible
The default function for testing for compatibility
*/
CONST bfd_arch_info_type *EXFUN(bfd_default_compatible,
(CONST bfd_arch_info_type *a,
CONST bfd_arch_info_type *b)); CONST bfd_arch_info_type *b));
/*
bfd_default_scan
The default function for working out whether this is an architecture
hit and a machine hit
*/
boolean EXFUN(bfd_default_scan, (CONST struct bfd_arch_info *, CONST char *)); boolean EXFUN(bfd_default_scan, (CONST struct bfd_arch_info *, CONST char *));
/*
*/

View file

@ -29,7 +29,32 @@ Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. */
#define obj_relocbase(bfd) (coff_data(bfd)->relocbase) #define obj_relocbase(bfd) (coff_data(bfd)->relocbase)
#define obj_raw_syments(bfd) (coff_data(bfd)->raw_syments) #define obj_raw_syments(bfd) (coff_data(bfd)->raw_syments)
#define obj_convert(bfd) (coff_data(bfd)->conversion_table) #define obj_convert(bfd) (coff_data(bfd)->conversion_table)
#if CFILE_STUFF
#define obj_symbol_slew(bfd) (coff_data(bfd)->symbol_index_slew)
#else
#define obj_symbol_slew(bfd) 0
#endif
#if 0
typedef struct coff_ptr_struct
{
unsigned int offset;
char fix_tag;
char fix_end;
union {
union internal_auxent auxent;
struct internal_syment syment;
} u;
} combined_entry_type;
typedef struct
{
asymbol symbol;
combined_entry_type *native;
struct lineno_cache_entry *lineno;
} coff_symbol_type;
#endif
/* `Tdata' information kept for COFF files. */ /* `Tdata' information kept for COFF files. */
@ -71,73 +96,20 @@ typedef struct coff_tdata
/*THE FOLLOWING IS EXTRACTED FROM THE SOURCE*/ /*THE FOLLOWING IS EXTRACTED FROM THE SOURCE*/
/*:coffcode.h*/ /*:coffcode.h*/
/*
The hidden information for an asymbol is:
*/
typedef struct coff_ptr_struct typedef struct coff_ptr_struct
{ {
/*
Remembers the offset from the first symbol in the file for this
symbol. Generated by @code{coff_renumber_symbols}.
*/
unsigned int offset; unsigned int offset;
/*
Should the tag field of this symbol be renumbered.
Created by @code{coff_pointerize_aux}.
*/
char fix_tag; char fix_tag;
/*
Should the endidx field of this symbol be renumbered.
Created by @code{coff_pointerize_aux}.
*/
char fix_end; char fix_end;
/*
The container for the symbol structure as read and translated from the file.
*/
union { union {
union internal_auxent auxent; union internal_auxent auxent;
struct internal_syment syment; struct internal_syment syment;
} u; } u;
} combined_entry_type; } combined_entry_type;
/*
Each canonical asymbol really looks like this:
*/
typedef struct coff_symbol_struct typedef struct coff_symbol_struct
{ {
/*
The actual symbol which the rest of BFD works with
*/
asymbol symbol; asymbol symbol;
/*
A pointer to the hidden information for this symbol
*/
combined_entry_type *native; combined_entry_type *native;
/*
A pointer to the linenumber information for this symbol
*/
struct lineno_cache_entry *lineno; struct lineno_cache_entry *lineno;
} coff_symbol_type; } coff_symbol_type;
/*
*/

View file

@ -18,162 +18,165 @@ You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software along with this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. */ Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. */
/*doc* /*
@section Relocations SECTION
Relocations
DESCRIPTION
BFD maintains relocations in much the same was as it maintains BFD maintains relocations in much the same was as it maintains
symbols; they are left alone until required, then read in en-mass and symbols; they are left alone until required, then read in
traslated into an internal form. There is a common routine en-mass and traslated into an internal form. There is a common
@code{bfd_perform_relocation} which acts upon the canonical form to to routine <<bfd_perform_relocation>> which acts upon the
the actual fixup. canonical form to to the actual fixup.
Note that relocations are maintained on a per section basis, whilst Note that relocations are maintained on a per section basis,
symbols are maintained on a per BFD basis. whilst symbols are maintained on a per BFD basis.
All a back end has to do to fit the BFD interface is to create as many All a back end has to do to fit the BFD interface is to create
@code{struct reloc_cache_entry} as there are relocations in a as many <<struct reloc_cache_entry>> as there are relocations
particuar section, and fill in the right bits: in a particuar section, and fill in the right bits:
@menu @menu
* typedef arelent:: * typedef arelent::
* reloc handling functions:: * howto manager::
@end menu @end menu
*/ */
#include "sysdep.h"
#include "bfd.h" #include "bfd.h"
#include "sysdep.h"
#include "libbfd.h" #include "libbfd.h"
/*doc /*doc*
@node typedef arelent, Relocations, reloc handling functions, Relocations @node typedef arelent, howto manager, Relocations, Relocations
@section typedef arelent
SUBSECTION
typedef arelent
*/ */
/*proto* bfd_perform_relocation /*
FUNCTION
bfd_perform_relocation
DESCRIPTION
The relocation routine returns as a status an enumerated type: The relocation routine returns as a status an enumerated type:
*+++ .typedef enum bfd_reloc_status {
$typedef enum bfd_reloc_status {
No errors detected No errors detected
$ bfd_reloc_ok, . bfd_reloc_ok,
The relocation was performed, but there was an overflow. The relocation was performed, but there was an overflow.
$ bfd_reloc_overflow, . bfd_reloc_overflow,
The address to relocate was not within the section supplied The address to relocate was not within the section supplied
$ bfd_reloc_outofrange, . bfd_reloc_outofrange,
Used by special functions Used by special functions
$ bfd_reloc_continue, . bfd_reloc_continue,
Unused Unused
$ bfd_reloc_notsupported, . bfd_reloc_notsupported,
Unsupported relocation size requested. Unsupported relocation size requested.
$ bfd_reloc_other, . bfd_reloc_other,
The symbol to relocate against was undefined. The symbol to relocate against was undefined.
$ bfd_reloc_undefined, . bfd_reloc_undefined,
The relocation was performed, but may not be ok - presently generated The relocation was performed, but may not be ok - presently
only when linking i960 coff files with i960 b.out symbols. generated only when linking i960 coff files with i960 b.out symbols.
$ bfd_reloc_dangerous . bfd_reloc_dangerous
$ } . }
$ bfd_reloc_status_enum_type; . bfd_reloc_status_type;
*---
*/ .typedef struct reloc_cache_entry
.{
/*proto*
*+++
$typedef struct reloc_cache_entry
${
A pointer into the canonical table of pointers A pointer into the canonical table of pointers
$ struct symbol_cache_entry **sym_ptr_ptr; . struct symbol_cache_entry **sym_ptr_ptr;
offset in section offset in section
$ rawdata_offset address; . rawdata_offset address;
addend for relocation value addend for relocation value
$ bfd_vma addend; . bfd_vma addend;
if sym is null this is the section if sym is null this is the section
$ struct sec *section; . struct sec *section;
Pointer to how to perform the required relocation Pointer to how to perform the required relocation
$ CONST struct reloc_howto_struct *howto; . CONST struct reloc_howto_struct *howto;
$} arelent; .} arelent;
*---
*/ */
/*doc* /*
@table @code DESCRIPTION
@item sym_ptr_ptr
The symbol table pointer points to a pointer to the symbol associated with the o sym_ptr_ptr
relocation request. This would naturally be the pointer into the table The symbol table pointer points to a pointer to the symbol
returned by the back end's get_symtab action. @xref{Symbols}. The associated with the relocation request. This would naturally
symbol is referenced through a pointer to a pointer so that tools like be the pointer into the table returned by the back end's
the linker can fix up all the symbols of the same name by modifying get_symtab action. @xref{Symbols}. The symbol is referenced
only one pointer. The relocation routine looks in the symbol and uses through a pointer to a pointer so that tools like the linker
the base of the section the symbol is attached to and the value of can fix up all the symbols of the same name by modifying only
the symbol as the initial relocation offset. If the symbol pointer is one pointer. The relocation routine looks in the symbol and
zero, then the section provided is looked up. uses the base of the section the symbol is attached to and the
@item address value of the symbol as the initial relocation offset. If the
The address field gives the offset in bytes from the base of the symbol pointer is zero, then the section provided is looked up.
section data which owns the relocation record to the first byte of
relocatable information. The actual data relocated will be relative to o address
this point - for example, a relocation type which modifies the bottom The address field gives the offset in bytes from the base of
two bytes of a four byte word would not touch the first byte pointed the section data which owns the relocation record to the first
to in a big endian world. byte of relocatable information. The actual data relocated
@item addend will be relative to this point - for example, a relocation
The addend is a value provided by the back end to be added (!) to the type which modifies the bottom two bytes of a four byte word
relocation offset. Its interpretation is dependent upon the howto. would not touch the first byte pointed to in a big endian
For example, on the 68k the code: world. @item addend The addend is a value provided by the back
end to be added (!) to the relocation offset. Its
interpretation is dependent upon the howto. For example, on
the 68k the code:
EXAMPLE
*+
char foo[]; char foo[];
main() main()
{ {
return foo[0x12345678]; return foo[0x12345678];
} }
*-
DESCRIPTION
Could be compiled into: Could be compiled into:
*+ EXAMPLE
linkw fp,#-4 linkw fp,#-4
moveb @@#12345678,d0 moveb @@#12345678,d0
extbl d0 extbl d0
unlk fp unlk fp
rts rts
*-
This could create a reloc pointing to foo, but leave the offset in the data DESCRIPTION
(something like)
*+ This could create a reloc pointing to foo, but leave the
offset in the data (something like)
EXAMPLE
RELOCATION RECORDS FOR [.text]: RELOCATION RECORDS FOR [.text]:
OFFSET TYPE VALUE offset type value
00000006 32 _foo 00000006 32 _foo
00000000 4e56 fffc ; linkw fp,#-4 00000000 4e56 fffc ; linkw fp,#-4
@ -181,54 +184,59 @@ OFFSET TYPE VALUE
0000000a 49c0 ; extbl d0 0000000a 49c0 ; extbl d0
0000000c 4e5e ; unlk fp 0000000c 4e5e ; unlk fp
0000000e 4e75 ; rts 0000000e 4e75 ; rts
*- DESCRIPTION
Using coff and an 88k, some instructions don't have enough space in them to
represent the full address range, and pointers have to be loaded in
two parts. So you'd get something like:
*+ Using coff and an 88k, some instructions don't have enough
space in them to represent the full address range, and
pointers have to be loaded in two parts. So you'd get something like:
EXAMPLE
or.u r13,r0,hi16(_foo+0x12345678) or.u r13,r0,hi16(_foo+0x12345678)
ld.b r2,r13,lo16(_foo+0x12345678) ld.b r2,r13,lo16(_foo+0x12345678)
jmp r1 jmp r1
*-
This whould create two relocs, both pointing to _foo, and with 0x12340000
in their addend field. The data would consist of:
*+ DESCRIPTION
This whould create two relocs, both pointing to _foo, and with
0x12340000 in their addend field. The data would consist of:
EXAMPLE
RELOCATION RECORDS FOR [.text]: RELOCATION RECORDS FOR [.text]:
OFFSET TYPE VALUE offset type value
00000002 HVRT16 _foo+0x12340000 00000002 HVRT16 _foo+0x12340000
00000006 LVRT16 _foo+0x12340000 00000006 LVRT16 _foo+0x12340000
00000000 5da05678 ; or.u r13,r0,0x5678 00000000 5da05678 ; or.u r13,r0,0x5678
00000004 1c4d5678 ; ld.b r2,r13,0x5678 00000004 1c4d5678 ; ld.b r2,r13,0x5678
00000008 f400c001 ; jmp r1 00000008 f400c001 ; jmp r1
*-
The relocation routine digs out the value from the data, adds it to
the addend to get the original offset and then adds the value of _foo.
Note that all 32 bits have to be kept around somewhere, to cope with
carry from bit 15 to bit 16.
On further example is the sparc and the a.out format. The sparc has a DESCRIPTION
similar problem to the 88k, in that some instructions don't have The relocation routine digs out the value from the data, adds
room for an entire offset, but on the sparc the parts are created odd it to the addend to get the original offset and then adds the
sized lumps. The designers of the a.out format chose not to use the value of _foo. Note that all 32 bits have to be kept around
data within the section for storing part of the offset; all the offset somewhere, to cope with carry from bit 15 to bit 16.
is kept within the reloc. Any thing in the data should be ignored.
*+ On further example is the sparc and the a.out format. The
sparc has a similar problem to the 88k, in that some
instructions don't have room for an entire offset, but on the
sparc the parts are created odd sized lumps. The designers of
the a.out format chose not to use the data within the section
for storing part of the offset; all the offset is kept within
the reloc. Any thing in the data should be ignored.
EXAMPLE
save %sp,-112,%sp save %sp,-112,%sp
sethi %hi(_foo+0x12345678),%g2 sethi %hi(_foo+0x12345678),%g2
ldsb [%g2+%lo(_foo+0x12345678)],%i0 ldsb [%g2+%lo(_foo+0x12345678)],%i0
ret ret
restore restore
*-
Both relocs contains a pointer to foo, and the offsets would contain junk.
*+ DESCRIPTION
Both relocs contains a pointer to foo, and the offsets would
contain junk.
EXAMPLE
RELOCATION RECORDS FOR [.text]: RELOCATION RECORDS FOR [.text]:
OFFSET TYPE VALUE offset type value
00000004 HI22 _foo+0x12345678 00000004 HI22 _foo+0x12345678
00000008 LO10 _foo+0x12345678 00000008 LO10 _foo+0x12345678
@ -237,198 +245,214 @@ OFFSET TYPE VALUE
00000008 f048a000 ; ldsb [%g2+%lo(_foo+0)],%i0 00000008 f048a000 ; ldsb [%g2+%lo(_foo+0)],%i0
0000000c 81c7e008 ; ret 0000000c 81c7e008 ; ret
00000010 81e80000 ; restore 00000010 81e80000 ; restore
*-
@item section
The section field is only used when the symbol pointer field is null.
It supplies the section into which the data should be relocated. The
field's main use comes from assemblers which do most of the symbol fixups
themselves; an assembler may take an internal reference to a label,
but since it knows where the label is, it can turn the relocation
request from a symbol lookup into a section relative relocation - the
relocation emitted has no symbol, just a section to relocate against.
I'm not sure what it means when both a symbol pointer an a section DESCRIPTION
pointer are present. Some formats use this sort of mechanism to
describe PIC relocations, but BFD can't to that sort of thing yet. o section
@item howto The section field is only used when the symbol pointer field
The howto field can be imagined as a relocation instruction. It is a is null. It supplies the section into which the data should be
pointer to a struct which contains information on what to do with all relocated. The field's main use comes from assemblers which do
the other information in the reloc record and data section. A back end most of the symbol fixups themselves; an assembler may take an
would normally have a relocation instruction set and turn relocations internal reference to a label, but since it knows where the
into pointers to the correct structure on input - but it would be label is, it can turn the relocation request from a symbol
possible to create each howto field on demand. lookup into a section relative relocation - the relocation
@end table emitted has no symbol, just a section to relocate against. I'm
not sure what it means when both a symbol pointer an a section
pointer are present. Some formats use this sort of mechanism
to describe PIC relocations, but BFD can't to that sort of
thing yet. @item howto The howto field can be imagined as a
relocation instruction. It is a pointer to a struct which
contains information on what to do with all the other
information in the reloc record and data section. A back end
would normally have a relocation instruction set and turn
relocations into pointers to the correct structure on input -
but it would be possible to create each howto field on demand.
*/ */
/*proto* reloc_howto_type /*
The @code{reloc_howto_type} is a structure which contains all the SUBSUBSECTION
<<reloc_howto_type>>
DESCRIPTION
The <<reloc_howto_type>> is a structure which contains all the
information that BFD needs to know to tie up a back end's data. information that BFD needs to know to tie up a back end's data.
*+++ .typedef CONST struct reloc_howto_struct
.{
The type field has mainly a documetary use - the back end can
to what it wants with it, though the normally the back end's
external idea of what a reloc number would be would be stored
in this field. For example, the a PC relative word relocation
in a coff environment would have the type 023 - because that's
what the outside world calls a R_PCRWORD reloc.
$typedef CONST struct reloc_howto_struct . unsigned int type;
${
The type field has mainly a documetary use - the back end can to what
it wants with it, though the normally the back end's external idea of
what a reloc number would be would be stored in this field. For
example, the a PC relative word relocation in a coff environment would
have the type 023 - because that's what the outside world calls a
R_PCRWORD reloc.
$ unsigned int type;
The value the final relocation is shifted right by. This drops The value the final relocation is shifted right by. This drops
unwanted data from the relocation. unwanted data from the relocation.
$ unsigned int rightshift; . unsigned int rightshift;
The size of the item to be relocated - 0, is one byte, 1 is 2 bytes, 3 The size of the item to be relocated - 0, is one byte, 1 is 2
is four bytes. bytes, 3 is four bytes.
$ unsigned int size; . unsigned int size;
Now obsolete Now obsolete
$ unsigned int bitsize; . unsigned int bitsize;
Notes that the relocation is relative to the location in the data Notes that the relocation is relative to the location in the
section of the addend. The relocation function will subtract from the data section of the addend. The relocation function will
relocation value the address of the location being relocated. subtract from the relocation value the address of the location
being relocated.
$ boolean pc_relative; . boolean pc_relative;
Now obsolete Now obsolete
$ unsigned int bitpos; . unsigned int bitpos;
Now obsolete Now obsolete
$ boolean absolute; . boolean absolute;
Causes the relocation routine to return an error if overflow is Causes the relocation routine to return an error if overflow
detected when relocating. is detected when relocating.
$ boolean complain_on_overflow; . boolean complain_on_overflow;
If this field is non null, then the supplied function is called rather If this field is non null, then the supplied function is
than the normal function. This allows really strange relocation called rather than the normal function. This allows really
methods to be accomodated (eg, i960 callj instructions). strange relocation methods to be accomodated (eg, i960 callj
instructions).
$ bfd_reloc_status_enum_type (*special_function)(); . bfd_reloc_status_type (*special_function)();
The textual name of the relocation type. The textual name of the relocation type.
$ char *name; . char *name;
When performing a partial link, some formats must modify the When performing a partial link, some formats must modify the
relocations rather than the data - this flag signals this. relocations rather than the data - this flag signals this.
$ boolean partial_inplace; . boolean partial_inplace;
The src_mask is used to select what parts of the read in data are to The src_mask is used to select what parts of the read in data
be used in the relocation sum. Eg, if this was an 8 bit bit of data are to be used in the relocation sum. Eg, if this was an 8 bit
which we read and relocated, this would be 0x000000ff. When we have bit of data which we read and relocated, this would be
relocs which have an addend, such as sun4 extended relocs, the value 0x000000ff. When we have relocs which have an addend, such as
in the offset part of a relocating field is garbage so we never use sun4 extended relocs, the value in the offset part of a
it. In this case the mask would be 0x00000000. relocating field is garbage so we never use it. In this case
the mask would be 0x00000000.
. bfd_word src_mask;
$ bfd_word src_mask; The dst_mask is what parts of the instruction are replaced
The dst_mask is what parts of the instruction are replaced into the into the instruction. In most cases src_mask == dst_mask,
instruction. In most cases src_mask == dst_mask, except in the above except in the above special case, where dst_mask would be
special case, where dst_mask would be 0x000000ff, and src_mask would 0x000000ff, and src_mask would be 0x00000000.
be 0x00000000. . bfd_word dst_mask;
$ bfd_word dst_mask; When some formats create PC relative instructions, they leave
the value of the pc of the place being relocated in the offset
When some formats create PC relative instructions, they leave the slot of the instruction, so that a PC relative relocation can
value of the pc of the place being relocated in the offset slot of the be made just by adding in an ordinary offset (eg sun3 a.out).
instruction, so that a PC relative relocation can be made just by Some formats leave the displacement part of an instruction
adding in an ordinary offset (eg sun3 a.out). Some formats leave the empty (eg m88k bcs), this flag signals the fact.
displacement part of an instruction empty (eg m88k bcs), this flag . boolean pcrel_offset;
signals the fact. .} reloc_howto_type;
$ boolean pcrel_offset;
$} reloc_howto_type;
*---
*/ */
/*proto* HOWTO /*
FUNCTION
HOWTO
DESCRIPTION
The HOWTO define is horrible and will go away. The HOWTO define is horrible and will go away.
*+
#define HOWTO(C, R,S,B, P, BI, ABS, O, SF, NAME, INPLACE, MASKSRC, MASKDST, PC) \
{(unsigned)C,R,S,B, P, BI, ABS,O,SF,NAME,INPLACE,MASKSRC,MASKDST,PC}
*-
And will be replaced with the totally magic way. But for the moment,
we are compatible, so do it this way..
*+ .#define HOWTO(C, R,S,B, P, BI, ABS, O, SF, NAME, INPLACE, MASKSRC, MASKDST, PC) \
#define NEWHOWTO( FUNCTION, NAME,SIZE,REL,IN) HOWTO(0,0,SIZE,0,REL,0,false,false,FUNCTION, NAME,false,0,0,IN) . {(unsigned)C,R,S,B, P, BI, ABS,O,SF,NAME,INPLACE,MASKSRC,MASKDST,PC}
*-
DESCRIPTION
And will be replaced with the totally magic way. But for the
moment, we are compatible, so do it this way..
.#define NEWHOWTO( FUNCTION, NAME,SIZE,REL,IN) HOWTO(0,0,SIZE,0,REL,0,false,false,FUNCTION, NAME,false,0,0,IN)
.
DESCRIPTION
Helper routine to turn a symbol into a relocation value. Helper routine to turn a symbol into a relocation value.
*+ .#define HOWTO_PREPARE(relocation, symbol) \
. { \
. if (symbol != (asymbol *)NULL) { \
. if (symbol->flags & BSF_FORT_COMM) { \
. relocation = 0; \
. } \
. else { \
. relocation = symbol->value; \
. } \
. } \
. if (symbol->section != (asection *)NULL) { \
. relocation += symbol->section->output_section->vma + \
. symbol->section->output_offset; \
. } \
.}
#define HOWTO_PREPARE(relocation, symbol) \
{ \
if (symbol != (asymbol *)NULL) { \
if (symbol->flags & BSF_FORT_COMM) { \
relocation = 0; \
} \
else { \
relocation = symbol->value; \
} \
} \
if (symbol->section != (asection *)NULL) { \
relocation += symbol->section->output_section->vma + \
symbol->section->output_offset; \
} \
}
*-
*/ */
/*proto* reloc_chain /*
*+ TYPEDEF
typedef unsigned char bfd_byte; reloc_chain
typedef struct relent_chain { DESCRIPTION
arelent relent;
struct relent_chain *next;
} arelent_chain;
*- How relocs are tied together
.typedef unsigned char bfd_byte;
.
.typedef struct relent_chain {
. arelent relent;
. struct relent_chain *next;
.} arelent_chain;
*/ */
/*proto* /*
If an output_bfd is supplied to this function the generated image FUNCTION
will be relocatable, the relocations are copied to the output file bfd_perform_relocation
after they have been changed to reflect the new state of the world.
There are two ways of reflecting the results of partial linkage in an DESCRIPTION
output file; by modifying the output data in place, and by modifying If an output_bfd is supplied to this function the generated
the relocation record. Some native formats (eg basic a.out and basic image will be relocatable, the relocations are copied to the
coff) have no way of specifying an addend in the relocation type, so output file after they have been changed to reflect the new
the addend has to go in the output data. This is no big deal since in state of the world. There are two ways of reflecting the
these formats the output data slot will always be big enough for the results of partial linkage in an output file; by modifying the
addend. Complex reloc types with addends were invented to solve just output data in place, and by modifying the relocation record.
this problem. Some native formats (eg basic a.out and basic coff) have no
*; PROTO(bfd_reloc_status_enum_type, way of specifying an addend in the relocation type, so the
bfd_perform_relocation, addend has to go in the output data. This is no big deal
since in these formats the output data slot will always be big
enough for the addend. Complex reloc types with addends were
invented to solve just this problem.
SYNOPSIS
bfd_reloc_status_type
bfd_perform_relocation
(bfd * abfd, (bfd * abfd,
arelent *reloc_entry, arelent *reloc_entry,
PTR data, PTR data,
asection *input_section, asection *input_section,
bfd *output_bfd)); bfd *output_bfd);
*/ */
bfd_reloc_status_enum_type bfd_reloc_status_type
DEFUN(bfd_perform_relocation,(abfd, DEFUN(bfd_perform_relocation,(abfd,
reloc_entry, reloc_entry,
data, data,
@ -441,7 +465,7 @@ DEFUN(bfd_perform_relocation,(abfd,
bfd *output_bfd) bfd *output_bfd)
{ {
bfd_vma relocation; bfd_vma relocation;
bfd_reloc_status_enum_type flag = bfd_reloc_ok; bfd_reloc_status_type flag = bfd_reloc_ok;
bfd_vma addr = reloc_entry->address ; bfd_vma addr = reloc_entry->address ;
bfd_vma output_base = 0; bfd_vma output_base = 0;
reloc_howto_type *howto = reloc_entry->howto; reloc_howto_type *howto = reloc_entry->howto;
@ -460,7 +484,7 @@ DEFUN(bfd_perform_relocation,(abfd,
} }
if (howto->special_function){ if (howto->special_function){
bfd_reloc_status_enum_type cont; bfd_reloc_status_type cont;
cont = howto->special_function(abfd, cont = howto->special_function(abfd,
reloc_entry, reloc_entry,
symbol, symbol,
@ -671,67 +695,120 @@ DEFUN(bfd_perform_relocation,(abfd,
/*doc* /*
@node howto manager, , typedef arelent, Relocations
SECTION
The howto manager
@section The howto manager DESCRIPTION
When an application wants to create a relocation, but doesn't
know what the target machine might call it, it can find out by
When an application wants to create a relocation, but doesn't know using this bit of code.
what the target machine might call it, it can find out by using this
bit of code.
*/ */
/*proto* bfd_reloc_code_enum_type /*
TYPEDEF
bfd_reloc_code_type
*+++ DESCRIPTION
The insides of a reloc code
$typedef enum .typedef enum bfd_reloc_code_real {
${
16 bits wide, simple reloc 16 bits wide, simple reloc
$ BFD_RELOC_16, . BFD_RELOC_16,
8 bits wide, but used to form an address like 0xffnn 8 bits wide, but used to form an address like 0xffnn
$ BFD_RELOC_8_FFnn, . BFD_RELOC_8_FFnn,
8 bits wide, simple 8 bits wide, simple
$ BFD_RELOC_8, . BFD_RELOC_8,
8 bits wide, pc relative 8 bits wide, pc relative
$ BFD_RELOC_8_PCREL . BFD_RELOC_8_PCREL,
$ } bfd_reloc_code_enum_real_type;
The type of reloc used to build a contructor table - at the
moment probably a 32 bit wide abs address, but the cpu can
choose.
. BFD_RELOC_CTOR
. } bfd_reloc_code_real_type;
*---
*/ */
/*proto* bfd_reloc_type_lookup /*
This routine returns a pointer to a howto struct which when invoked, SECTION
will perform the supplied relocation on data from the architecture bfd_reloc_type_lookup
noted.
[Note] This function will go away. DESCRIPTION
This routine returns a pointer to a howto struct which when
invoked, will perform the supplied relocation on data from the
architecture noted.
*; PROTO(CONST struct reloc_howto_struct *, SYNOPSIS
bfd_reloc_type_lookup, CONST struct reloc_howto_struct *
(CONST bfd_arch_info_struct_type *arch, bfd_reloc_code_enum_type code)); bfd_reloc_type_lookup
(CONST bfd_arch_info_type *arch, bfd_reloc_code_type code);
*/ */
CONST struct reloc_howto_struct * CONST struct reloc_howto_struct *
DEFUN(bfd_reloc_type_lookup,(arch, code), DEFUN(bfd_reloc_type_lookup,(arch, code),
CONST bfd_arch_info_struct_type *arch AND CONST bfd_arch_info_type *arch AND
bfd_reloc_code_enum_type code) bfd_reloc_code_type code)
{ {
return arch->reloc_type_lookup(arch, code); return arch->reloc_type_lookup(arch, code);
} }
static reloc_howto_type bfd_howto_32 =
HOWTO(0, 00,2,32,false,0,false,true,0,"VRT32", false,0xffffffff,0xffffffff,true);
/*
INTERNAL FUNCTION
bfd_default_reloc_type_lookup
DESCRIPTION
Provides a default relocation lookuperer for any architectue
SYNOPSIS
CONST struct reloc_howto_struct *bfd_default_reloc_type_lookup
(CONST struct bfd_arch_info *,
bfd_reloc_code_type code);
*/
CONST struct reloc_howto_struct *
DEFUN(bfd_default_reloc_type_lookup,(arch, code),
CONST struct bfd_arch_info *arch AND
bfd_reloc_code_type code)
{
switch (code)
{
case BFD_RELOC_CTOR:
/* The type of reloc used in a ctor, which will be as wide as the
address - so either a 64, 32, or 16 bitter.. */
switch (arch->bits_per_address) {
case 64:
BFD_FAIL();
case 32:
return &bfd_howto_32;
case 16:
BFD_FAIL();
default:
BFD_FAIL();
}
default:
BFD_FAIL();
}
return (struct reloc_howto_struct *)NULL;
}

View file

@ -18,33 +18,34 @@ You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software along with this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. */ Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. */
/*doc* /*
@section Symbols SECTION
BFD trys to maintain as much symbol information as it can when it Symbols
moves information from file to file. BFD passes information to
applications though the @code{asymbol} structure. When the application DESCRIPTION
requests the symbol table, BFD reads the table in the native form and BFD trys to maintain as much symbol information as it can when
translates parts of it into the internal format. To maintain more than it moves information from file to file. BFD passes information
the infomation passed to applications some targets keep to applications though the <<asymbol>> structure. When the
some information 'behind the sceans', in a structure only the applicationrequests the symbol table, BFD reads the table in
particular back end knows about. For example, the coff back end keeps the native form and translates parts of it into the internal
the original symbol table structure as well as the canonical structure format. To maintain more than the infomation passed to
when a BFD is read in. On output, the coff back end can reconstruct applications some targets keep some information 'behind the
sceans', in a structure only the particular back end knows
about. For example, the coff back end keeps the original
symbol table structure as well as the canonical structure when
a BFD is read in. On output, the coff back end can reconstruct
the output symbol table so that no information is lost, even the output symbol table so that no information is lost, even
information unique to coff which BFD doesn't know or understand. If a information unique to coff which BFD doesn't know or
coff symbol table was read, but was written through an a.out back end, understand. If a coff symbol table was read, but was written
all the coff specific information would be lost. (.. until BFD 2 :). through an a.out back end, all the coff specific information
would be lost. (.. until BFD 2 :). The symbol table of a BFD
The symbol table of a BFD is not necessarily read in until a is not necessarily read in until a canonicalize request is
canonicalize request is made. Then the BFD back end fills in a table made. Then the BFD back end fills in a table provided by the
provided by the application with pointers to the canonical application with pointers to the canonical information. To
information. output symbols, the application provides BFD with a table of
pointers to pointers to <<asymbol>>s. This allows applications
To output symbols, the application provides BFD with a table of like the linker to output a symbol as read, since the 'behind
pointers to pointers to @code{asymbol}s. This allows applications like the sceens' information will be still available.
the linker to output a symbol as read, since the 'behind the sceens'
information will be still available.
@menu @menu
* Reading Symbols:: * Reading Symbols::
* Writing Symbols:: * Writing Symbols::
@ -53,12 +54,16 @@ information will be still available.
@end menu @end menu
@node Reading Symbols, Writing Symbols, Symbols, Symbols @node Reading Symbols, Writing Symbols, Symbols, Symbols
@subsection Reading Symbols SUBSECTION
There are two stages to reading a symbol table from a BFD; allocating Reading Symbols
storage, and the actual reading process. This is an excerpt from an
appliction which reads the symbol table: DESCRIPTION
There are two stages to reading a symbol table from a BFD;
allocating storage, and the actual reading process. This is an
excerpt from an appliction which reads the symbol table:
EXAMPLE
*+
unsigned int storage_needed; unsigned int storage_needed;
asymbol **symbol_table; asymbol **symbol_table;
unsigned int number_of_symbols; unsigned int number_of_symbols;
@ -77,25 +82,29 @@ appliction which reads the symbol table:
for (i = 0; i < number_of_symbols; i++) { for (i = 0; i < number_of_symbols; i++) {
process_symbol (symbol_table[i]); process_symbol (symbol_table[i]);
} }
*-
All storage for the symbols themselves is in an obstack connected to DESCRIPTION
the BFD, and is freed when the BFD is closed.
All storage for the symbols themselves is in an obstack
connected to the BFD, and is freed when the BFD is closed.
@node Writing Symbols, typedef asymbol, Reading Symbols, Symbols @node Writing Symbols, typedef asymbol, Reading Symbols, Symbols
@subsection Writing Symbols SUBSECTION
Writing of a symbol table is automatic when a BFD open for writing Writing Symbols
is closed. The application attaches a vector of pointers to pointers to symbols
to the BFD being written, and fills in the symbol count. The close and
cleanup code reads through the table provided and performs all the
necessary operations. The outputing code must always be provided with
an 'owned' symbol; one which has come from another BFD, or one which
has been created using @code{bfd_make_empty_symbol}.
An example showing the creation of a symbol table with only one DESCRIPTION
element: Writing of a symbol table is automatic when a BFD open for
writing is closed. The application attaches a vector of
pointers to pointers to symbols to the BFD being written, and
fills in the symbol count. The close and cleanup code reads
through the table provided and performs all the necessary
operations. The outputing code must always be provided with an
'owned' symbol; one which has come from another BFD, or one
which has been created using <<bfd_make_empty_symbol>>. An
example showing the creation of a symbol table with only one element:
*+ EXAMPLE
#include "bfd.h" #include "bfd.h"
main() main()
{ {
@ -123,12 +132,13 @@ nm foo
00012345 A dummy_symbol 00012345 A dummy_symbol
*- DESCRIPTION
Many formats cannot represent arbitary symbol information; for Many formats cannot represent arbitary symbol information; for
instance the @code{a.out} object format does not allow an arbitary instance the <<a.out>> object format does not allow an
number of sections. A symbol pointing to a section which is not one of arbitary number of sections. A symbol pointing to a section
@code{.text}, @code{.data} or @code{.bss} cannot be described. which is not one of <<.text>>, <<.data>> or <<.bss>> cannot
be described.
*/ */
@ -136,130 +146,131 @@ number of sections. A symbol pointing to a section which is not one of
@node typedef asymbol, symbol handling functions, Writing Symbols, Symbols @node typedef asymbol, symbol handling functions, Writing Symbols, Symbols
*/ */
/*proto* /*
@subsection typedef asymbol TYPEDEF
An @code{asymbol} has the form: typedef asymbol
*+++ DESCRIPTION
An <<asymbol>> has the form:
$typedef struct symbol_cache_entry .typedef struct symbol_cache_entry
${ .{
A pointer to the BFD which owns the symbol. This information is A pointer to the BFD which owns the symbol. This information
necessary so that a back end can work out what additional (invisible to is necessary so that a back end can work out what additional
the application writer) information is carried with the symbol. (invisible to the application writer) information is carried
with the symbol.
$ struct _bfd *the_bfd; . struct _bfd *the_bfd;
The text of the symbol. The name is left alone, and not copied - the The text of the symbol. The name is left alone, and not copied - the
application may not alter it. application may not alter it.
$ CONST char *name; . CONST char *name;
The value of the symbol. The value of the symbol.
$ symvalue value; . symvalue value;
Attributes of a symbol: Attributes of a symbol:
$#define BSF_NO_FLAGS 0x00 .#define BSF_NO_FLAGS 0x00
The symbol has local scope; @code{static} in @code{C}. The value is The symbol has local scope; <<static>> in <<C>>. The value is
the offset into the section of the data. the offset into the section of the data.
$#define BSF_LOCAL 0x01 .#define BSF_LOCAL 0x01
The symbol has global scope; initialized data in @code{C}. The value The symbol has global scope; initialized data in <<C>>. The value
is the offset into the section of the data. is the offset into the section of the data.
$#define BSF_GLOBAL 0x02 .#define BSF_GLOBAL 0x02
Obsolete Obsolete
$#define BSF_IMPORT 0x04 .#define BSF_IMPORT 0x04
The symbol has global scope, and is exported. The value is the offset The symbol has global scope, and is exported. The value is the offset
into the section of the data. into the section of the data.
$#define BSF_EXPORT 0x08 .#define BSF_EXPORT 0x08
The symbol is undefined. @code{extern} in @code{C}. The value has no meaning. The symbol is undefined. <<extern>> in <<C>>. The value has no meaning.
$#define BSF_UNDEFINED 0x10 .#define BSF_UNDEFINED 0x10
The symbol is common, initialized to zero; default in @code{C}. The The symbol is common, initialized to zero; default in <<C>>. The
value is the size of the object in bytes. value is the size of the object in bytes.
$#define BSF_FORT_COMM 0x20 .#define BSF_FORT_COMM 0x20
A normal @code{C} symbol would be one of: A normal <<C>> symbol would be one of:
@code{BSF_LOCAL}, @code{BSF_FORT_COMM}, @code{BSF_UNDEFINED} or @code{BSF_EXPORT|BSD_GLOBAL} <<BSF_LOCAL>>, <<BSF_FORT_COMM>>, <<BSF_UNDEFINED>> or <<BSF_EXPORT|BSD_GLOBAL>>
The symbol is a debugging record. The value has an arbitary meaning. The symbol is a debugging record. The value has an arbitary meaning.
$#define BSF_DEBUGGING 0x40 .#define BSF_DEBUGGING 0x40
The symbol has no section attached, any value is the actual value and The symbol has no section attached, any value is the actual value and
is not a relative offset to a section. is not a relative offset to a section.
$#define BSF_ABSOLUTE 0x80 .#define BSF_ABSOLUTE 0x80
Used by the linker Used by the linker
$#define BSF_KEEP 0x10000 .#define BSF_KEEP 0x10000
$#define BSF_KEEP_G 0x80000 .#define BSF_KEEP_G 0x80000
Unused Unused
$#define BSF_WEAK 0x100000 .#define BSF_WEAK 0x100000
$#define BSF_CTOR 0x200000 .#define BSF_CTOR 0x200000
$#define BSF_FAKE 0x400000 .#define BSF_FAKE 0x400000
The symbol used to be a common symbol, but now it is allocated. The symbol used to be a common symbol, but now it is allocated.
$#define BSF_OLD_COMMON 0x800000 .#define BSF_OLD_COMMON 0x800000
The default value for common data. The default value for common data.
$#define BFD_FORT_COMM_DEFAULT_VALUE 0 .#define BFD_FORT_COMM_DEFAULT_VALUE 0
In some files the type of a symbol sometimes alters its location In some files the type of a symbol sometimes alters its location
in an output file - ie in coff a @code{ISFCN} symbol which is also @code{C_EXT} in an output file - ie in coff a <<ISFCN>> symbol which is also <<C_EXT>>
symbol appears where it was declared and not at the end of a section. symbol appears where it was declared and not at the end of a section.
This bit is set by the target BFD part to convey this information. This bit is set by the target BFD part to convey this information.
$#define BSF_NOT_AT_END 0x40000 .#define BSF_NOT_AT_END 0x40000
Signal that the symbol is the label of constructor section. Signal that the symbol is the label of constructor section.
$#define BSF_CONSTRUCTOR 0x1000000 .#define BSF_CONSTRUCTOR 0x1000000
Signal that the symbol is a warning symbol. If the symbol is a warning Signal that the symbol is a warning symbol. If the symbol is a warning
symbol, then the value field (I know this is tacky) will point to the symbol, then the value field (I know this is tacky) will point to the
asymbol which when referenced will cause the warning. asymbol which when referenced will cause the warning.
$#define BSF_WARNING 0x2000000 .#define BSF_WARNING 0x2000000
Signal that the symbol is indirect. The value of the symbol is a Signal that the symbol is indirect. The value of the symbol is a
pointer to an undefined asymbol which contains the name to use pointer to an undefined asymbol which contains the name to use
instead. instead.
$#define BSF_INDIRECT 0x4000000 .#define BSF_INDIRECT 0x4000000
$ flagword flags; . flagword flags;
A pointer to the section to which this symbol is relative, or 0 if the A pointer to the section to which this symbol is relative, or 0 if the
symbol is absolute or undefined. Note that it is not sufficient to set symbol is absolute or undefined. Note that it is not sufficient to set
this location to 0 to mark a symbol as absolute - the flag this location to 0 to mark a symbol as absolute - the flag
@code{BSF_ABSOLUTE} must be set also. <<BSF_ABSOLUTE>> must be set also.
$ struct sec *section; . struct sec *section;
Back end special data. This is being phased out in favour of making Back end special data. This is being phased out in favour of making
this a union. this a union.
$ PTR udata; . PTR udata;
$} asymbol; .} asymbol;
*---
*/ */
@ -268,44 +279,57 @@ $} asymbol;
#include "libbfd.h" #include "libbfd.h"
#include "stab.gnu.h" #include "stab.gnu.h"
/*doc* /*
@node symbol handling functions, , typedef asymbol, Symbols @node symbol handling functions, , typedef asymbol, Symbols
@subsection Symbol Handling Functions SUBSECTION
Symbol Handling Functions
*/ */
/*proto* get_symtab_upper_bound /*
Returns the number of bytes required in a vector of pointers to FUNCTION
@code{asymbols} for all the symbols in the supplied BFD, including a get_symtab_upper_bound
terminal NULL pointer. If there are no symbols in the BFD, then 0 is
returned. DESCRIPTION
*+ Returns the number of bytes required in a vector of pointers
#define get_symtab_upper_bound(abfd) \ to <<asymbols>> for all the symbols in the supplied BFD,
BFD_SEND (abfd, _get_symtab_upper_bound, (abfd)) including a terminal NULL pointer. If there are no symbols in
*- the BFD, then 0 is returned.
.#define get_symtab_upper_bound(abfd) \
. BFD_SEND (abfd, _get_symtab_upper_bound, (abfd))
*/ */
/*proto* bfd_canonicalize_symtab /*
Supplied a BFD and a pointer to an uninitialized vector of pointers. FUNCTION
This reads in the symbols from the BFD, and fills in the table with bfd_canonicalize_symtab
pointers to the symbols, and a trailing NULL. The routine returns the
actual number of symbol pointers not including the NULL.
*+ DESCRIPTION
#define bfd_canonicalize_symtab(abfd, location) \ Supplied a BFD and a pointer to an uninitialized vector of
BFD_SEND (abfd, _bfd_canonicalize_symtab,\ pointers. This reads in the symbols from the BFD, and fills in
(abfd, location)) the table with pointers to the symbols, and a trailing NULL.
The routine returns the actual number of symbol pointers not
including the NULL.
.#define bfd_canonicalize_symtab(abfd, location) \
. BFD_SEND (abfd, _bfd_canonicalize_symtab,\
. (abfd, location))
*-
*/ */
/*proto* bfd_set_symtab /*
Provided a table of pointers to symbols and a count, writes to the FUNCTION
output BFD the symbols when closed. bfd_set_symtab
*; PROTO(boolean, bfd_set_symtab, (bfd *, asymbol **, unsigned int )); DESCRIPTION
Provided a table of pointers to symbols and a count, writes to
the output BFD the symbols when closed.
SYNOPSIS
boolean bfd_set_symtab (bfd *, asymbol **, unsigned int );
*/ */
boolean boolean
@ -324,10 +348,15 @@ bfd_set_symtab (abfd, location, symcount)
return true; return true;
} }
/*proto* bfd_print_symbol_vandf /*
FUNCTION
bfd_print_symbol_vandf
DESCRIPTION
Prints the value and flags of the symbol supplied to the stream file. Prints the value and flags of the symbol supplied to the stream file.
*; PROTO(void, bfd_print_symbol_vandf, (PTR file, asymbol *symbol)); SYNOPSIS
void bfd_print_symbol_vandf(PTR file, asymbol *symbol);
*/ */
void void
DEFUN(bfd_print_symbol_vandf,(file, symbol), DEFUN(bfd_print_symbol_vandf,(file, symbol),
@ -358,24 +387,33 @@ asymbol *symbol)
} }
/*proto* bfd_make_empty_symbol /*
This function creates a new @code{asymbol} structure for the BFD, and FUNCTION
returns a pointer to it. bfd_make_empty_symbol
This routine is necessary, since each back end has private information DESCRIPTION
surrounding the @code{asymbol}. Building your own @code{asymbol} and This function creates a new <<asymbol>> structure for the BFD,
pointing to it will not create the private information, and will cause and returns a pointer to it.
problems later on.
*+ This routine is necessary, since each back end has private
#define bfd_make_empty_symbol(abfd) \ information surrounding the <<asymbol>>. Building your own
BFD_SEND (abfd, _bfd_make_empty_symbol, (abfd)) <<asymbol>> and pointing to it will not create the private
*- information, and will cause problems later on.
.#define bfd_make_empty_symbol(abfd) \
. BFD_SEND (abfd, _bfd_make_empty_symbol, (abfd))
*/ */
/*proto* bfd_decode_symclass /*
Return a lower-case character corresponding to the symbol class of symbol. FUNCTION
bfd_decode_symclass
*; PROTO(int, bfd_decode_symclass, (asymbol *symbol)); DESCRIPTION
Return a lower-case character corresponding to the symbol
class of symbol.
SYNOPSIS
int bfd_decode_symclass(asymbol *symbol);
*/ */
int int
DEFUN(bfd_decode_symclass,(symbol), DEFUN(bfd_decode_symclass,(symbol),

View file

@ -24,302 +24,309 @@ Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. */
#include "sysdep.h" #include "sysdep.h"
#include "libbfd.h" #include "libbfd.h"
/*doc* /*
@section Targets SECTION
Each port of BFD to a different machine requries the creation of a Targets
target back end. All the back end provides to the root part of BFD is
a structure containing pointers to functions which perform certain low
level operations on files. BFD translates the applications's requests
through a pointer into calls to the back end routines.
When a file is opened with @code{bfd_openr}, its format and target are DESCRIPTION
unknown. BFD uses various mechanisms to determine how to interpret the Each port of BFD to a different machine requries the creation
file. The operations performed are: of a target back end. All the back end provides to the root
@itemize @bullet part of BFD is a structure containing pointers to functions
@item which perform certain low level operations on files. BFD
First a BFD is created by calling the internal routine translates the applications's requests through a pointer into
@code{new_bfd}, then @code{bfd_find_target} is called with the target calls to the back end routines.
string supplied to @code{bfd_openr} and the new BFD pointer.
@item
If a null target string was provided to
@code{bfd_find_target}, it looks up the environment variable
@code{GNUTARGET} and uses that as the target string.
@item
If the target string is still NULL, or the target string
is @code{default}, then the first item in the target vector is used as
the target type. @xref{bfd_target}.
@item
Otherwise, the elements in the target vector are
inspected one by one, until a match on target name is found. When
found, that is used.
@item
Otherwise the error @code{invalid_target} is returned to
@code{bfd_openr}.
@item
@code{bfd_openr} attempts to open the file using
@code{bfd_open_file}, and returns the BFD.
@end itemize
Once the BFD has been opened and the target selected, the file format
may be determined. This is done by calling @code{bfd_check_format} on
the BFD with a suggested format. The routine returns @code{true} when
the application guesses right.
When a file is opened with <<bfd_openr>>, its format and
target are unknown. BFD uses various mechanisms to determine
how to interpret the file. The operations performed are:
o First a BFD is created by calling the internal routine
<<new_bfd>>, then <<bfd_find_target>> is called with the
target string supplied to <<bfd_openr>> and the new BFD pointer.
o If a null target string was provided to <<bfd_find_target>>,
it looks up the environment variable <<GNUTARGET>> and uses
that as the target string.
o If the target string is still NULL, or the target string is
<<default>>, then the first item in the target vector is used
as the target type. @xref{bfd_target}.
o Otherwise, the elements in the target vector are inspected
one by one, until a match on target name is found. When found,
that is used.
o Otherwise the error <<invalid_target>> is returned to
<<bfd_openr>>.
o <<bfd_openr>> attempts to open the file using
<<bfd_open_file>>, and returns the BFD.
Once the BFD has been opened and the target selected, the file
format may be determined. This is done by calling
<<bfd_check_format>> on the BFD with a suggested format. The
routine returns <<true>> when the application guesses right.
@menu @menu
* bfd_target:: * bfd_target::
@end menu @end menu
*/ */
/*proto* bfd_target /*
@node bfd_target, , Targets, Targets @node bfd_target, , Targets, Targets
@subsection bfd_target
This structure contains everything that BFD knows about a target.
It includes things like its byte order, name, what routines to call
to do various operations, etc.
Every BFD points to a target structure with its "xvec" member. SUBSECTION
bfd_target
DESCRIPTION
This structure contains everything that BFD knows about a
target. It includes things like its byte order, name, what
routines to call to do various operations, etc.
Every BFD points to a target structure with its <<xvec>>
member.
Shortcut for declaring fields which are prototyped function
pointers, while avoiding anguish on compilers that don't
support protos.
.#define SDEF(ret, name, arglist) \
. PROTO(ret,(*name),arglist)
.#define SDEF_FMT(ret, name, arglist) \
. PROTO(ret,(*name[bfd_type_end]),arglist)
These macros are used to dispatch to functions through the
bfd_target vector. They are used in a number of macros further
down in @file{bfd.h}, and are also used when calling various
routines by hand inside the BFD implementation. The "arglist"
argument must be parenthesized; it contains all the arguments
to the called function.
Shortcut for declaring fields which are prototyped function pointers, .#define BFD_SEND(bfd, message, arglist) \
while avoiding anguish on compilers that don't support protos. . ((*((bfd)->xvec->message)) arglist)
$#define SDEF(ret, name, arglist) \
$ PROTO(ret,(*name),arglist)
$#define SDEF_FMT(ret, name, arglist) \
$ PROTO(ret,(*name[bfd_type_end]),arglist)
These macros are used to dispatch to functions through the bfd_target
vector. They are used in a number of macros further down in @file{bfd.h}, and
are also used when calling various routines by hand inside the BFD
implementation. The "arglist" argument must be parenthesized; it
contains all the arguments to the called function.
$#define BFD_SEND(bfd, message, arglist) \
$ ((*((bfd)->xvec->message)) arglist)
For operations which index on the BFD format For operations which index on the BFD format
$#define BFD_SEND_FMT(bfd, message, arglist) \ .#define BFD_SEND_FMT(bfd, message, arglist) \
$ (((bfd)->xvec->message[(int)((bfd)->format)]) arglist) . (((bfd)->xvec->message[(int)((bfd)->format)]) arglist)
This is the struct which defines the type of BFD this is. The This is the struct which defines the type of BFD this is. The
"xvec" member of the struct @code{bfd} itself points here. Each module <<xvec>> member of the struct <<bfd>> itself points here. Each
that implements access to a different target under BFD, defines module that implements access to a different target under BFD,
one of these. defines one of these.
FIXME, these names should be rationalised with the names of the
entry points which call them. Too bad we can't have one macro to
define them both!
*+++ FIXME, these names should be rationalised with the names of
the entry points which call them. Too bad we can't have one
macro to define them both!
$typedef struct bfd_target .typedef struct bfd_target
${ .{
identifies the kind of target, eg SunOS4, Ultrix, etc identifies the kind of target, eg SunOS4, Ultrix, etc
$ char *name; . char *name;
The "flavour" of a back end is a general indication about the contents The "flavour" of a back end is a general indication about the contents
of a file. of a file.
$ enum target_flavour { . enum target_flavour {
$ bfd_target_unknown_flavour, . bfd_target_unknown_flavour,
$ bfd_target_aout_flavour, . bfd_target_aout_flavour,
$ bfd_target_coff_flavour, . bfd_target_coff_flavour,
$ bfd_target_elf_flavour, . bfd_target_elf_flavour,
$ bfd_target_ieee_flavour, . bfd_target_ieee_flavour,
$ bfd_target_oasys_flavour, . bfd_target_oasys_flavour,
$ bfd_target_srec_flavour} flavour; . bfd_target_srec_flavour} flavour;
The order of bytes within the data area of a file. The order of bytes within the data area of a file.
$ boolean byteorder_big_p; . boolean byteorder_big_p;
The order of bytes within the header parts of a file. The order of bytes within the header parts of a file.
$ boolean header_byteorder_big_p; . boolean header_byteorder_big_p;
This is a mask of all the flags which an executable may have set - This is a mask of all the flags which an executable may have set -
from the set @code{NO_FLAGS}, @code{HAS_RELOC}, ...@code{D_PAGED}. from the set <<NO_FLAGS>>, <<HAS_RELOC>>, ...<<D_PAGED>>.
$ flagword object_flags; . flagword object_flags;
This is a mask of all the flags which a section may have set - from This is a mask of all the flags which a section may have set - from
the set @code{SEC_NO_FLAGS}, @code{SEC_ALLOC}, ...@code{SET_NEVER_LOAD}. the set <<SEC_NO_FLAGS>>, <<SEC_ALLOC>>, ...<<SET_NEVER_LOAD>>.
$ flagword section_flags; . flagword section_flags;
The pad character for filenames within an archive header. The pad character for filenames within an archive header.
$ char ar_pad_char; . char ar_pad_char;
The maximum number of characters in an archive header. The maximum number of characters in an archive header.
$ unsigned short ar_max_namelen; . unsigned short ar_max_namelen;
The minimum alignment restriction for any section. The minimum alignment restriction for any section.
$ unsigned int align_power_min; . unsigned int align_power_min;
Entries for byte swapping for data. These are different to the other Entries for byte swapping for data. These are different to the other
entry points, since they don't take BFD as first arg. Certain other handlers entry points, since they don't take BFD as first arg. Certain other handlers
could do the same. could do the same.
$ SDEF (bfd_vma, bfd_getx64, (bfd_byte *)); . SDEF (bfd_vma, bfd_getx64, (bfd_byte *));
$ SDEF (void, bfd_putx64, (bfd_vma, bfd_byte *)); . SDEF (void, bfd_putx64, (bfd_vma, bfd_byte *));
$ SDEF (bfd_vma, bfd_getx32, (bfd_byte *)); . SDEF (bfd_vma, bfd_getx32, (bfd_byte *));
$ SDEF (void, bfd_putx32, (bfd_vma, bfd_byte *)); . SDEF (void, bfd_putx32, (bfd_vma, bfd_byte *));
$ SDEF (bfd_vma, bfd_getx16, (bfd_byte *)); . SDEF (bfd_vma, bfd_getx16, (bfd_byte *));
$ SDEF (void, bfd_putx16, (bfd_vma, bfd_byte *)); . SDEF (void, bfd_putx16, (bfd_vma, bfd_byte *));
Byte swapping for the headers Byte swapping for the headers
$ SDEF (bfd_vma, bfd_h_getx64, (bfd_byte *)); . SDEF (bfd_vma, bfd_h_getx64, (bfd_byte *));
$ SDEF (void, bfd_h_putx64, (bfd_vma, bfd_byte *)); . SDEF (void, bfd_h_putx64, (bfd_vma, bfd_byte *));
$ SDEF (bfd_vma, bfd_h_getx32, (bfd_byte *)); . SDEF (bfd_vma, bfd_h_getx32, (bfd_byte *));
$ SDEF (void, bfd_h_putx32, (bfd_vma, bfd_byte *)); . SDEF (void, bfd_h_putx32, (bfd_vma, bfd_byte *));
$ SDEF (bfd_vma, bfd_h_getx16, (bfd_byte *)); . SDEF (bfd_vma, bfd_h_getx16, (bfd_byte *));
$ SDEF (void, bfd_h_putx16, (bfd_vma, bfd_byte *)); . SDEF (void, bfd_h_putx16, (bfd_vma, bfd_byte *));
Format dependent routines, these turn into vectors of entry points Format dependent routines, these turn into vectors of entry points
within the target vector structure; one for each format to check. within the target vector structure; one for each format to check.
Check the format of a file being read. Return bfd_target * or zero. Check the format of a file being read. Return bfd_target * or zero.
$ SDEF_FMT (struct bfd_target *, _bfd_check_format, (bfd *)); . SDEF_FMT (struct bfd_target *, _bfd_check_format, (bfd *));
Set the format of a file being written. Set the format of a file being written.
$ SDEF_FMT (boolean, _bfd_set_format, (bfd *)); . SDEF_FMT (boolean, _bfd_set_format, (bfd *));
Write cached information into a file being written, at bfd_close. Write cached information into a file being written, at bfd_close.
$ SDEF_FMT (boolean, _bfd_write_contents, (bfd *)); . SDEF_FMT (boolean, _bfd_write_contents, (bfd *));
The following functions are defined in @code{JUMP_TABLE}. The idea is The following functions are defined in <<JUMP_TABLE>>. The idea is
that the back end writer of @code{foo} names all the routines that the back end writer of <<foo>> names all the routines
@code{foo_}@var{entry_point}, @code{JUMP_TABLE} will built the entries <<foo_>>@var{entry_point}, <<JUMP_TABLE>> will built the entries
in this structure in the right order. in this structure in the right order.
Core file entry points Core file entry points
$ SDEF (char *, _core_file_failing_command, (bfd *)); . SDEF (char *, _core_file_failing_command, (bfd *));
$ SDEF (int, _core_file_failing_signal, (bfd *)); . SDEF (int, _core_file_failing_signal, (bfd *));
$ SDEF (boolean, _core_file_matches_executable_p, (bfd *, bfd *)); . SDEF (boolean, _core_file_matches_executable_p, (bfd *, bfd *));
Archive entry points Archive entry points
$ SDEF (boolean, _bfd_slurp_armap, (bfd *)); . SDEF (boolean, _bfd_slurp_armap, (bfd *));
$ SDEF (boolean, _bfd_slurp_extended_name_table, (bfd *)); . SDEF (boolean, _bfd_slurp_extended_name_table, (bfd *));
$ SDEF (void, _bfd_truncate_arname, (bfd *, CONST char *, char *)); . SDEF (void, _bfd_truncate_arname, (bfd *, CONST char *, char *));
$ SDEF (boolean, write_armap, (bfd *arch, . SDEF (boolean, write_armap, (bfd *arch,
$ unsigned int elength, . unsigned int elength,
$ struct orl *map, . struct orl *map,
$ unsigned int orl_count, . unsigned int orl_count,
$ int stridx)); . int stridx));
Standard stuff. Standard stuff.
$ SDEF (boolean, _close_and_cleanup, (bfd *)); . SDEF (boolean, _close_and_cleanup, (bfd *));
$ SDEF (boolean, _bfd_set_section_contents, (bfd *, sec_ptr, PTR, . SDEF (boolean, _bfd_set_section_contents, (bfd *, sec_ptr, PTR,
$ file_ptr, bfd_size_type)); . file_ptr, bfd_size_type));
$ SDEF (boolean, _bfd_get_section_contents, (bfd *, sec_ptr, PTR, . SDEF (boolean, _bfd_get_section_contents, (bfd *, sec_ptr, PTR,
$ file_ptr, bfd_size_type)); . file_ptr, bfd_size_type));
$ SDEF (boolean, _new_section_hook, (bfd *, sec_ptr)); . SDEF (boolean, _new_section_hook, (bfd *, sec_ptr));
Symbols and reloctions Symbols and reloctions
$ SDEF (unsigned int, _get_symtab_upper_bound, (bfd *)); . SDEF (unsigned int, _get_symtab_upper_bound, (bfd *));
$ SDEF (unsigned int, _bfd_canonicalize_symtab, . SDEF (unsigned int, _bfd_canonicalize_symtab,
$ (bfd *, struct symbol_cache_entry **)); . (bfd *, struct symbol_cache_entry **));
$ SDEF (unsigned int, _get_reloc_upper_bound, (bfd *, sec_ptr)); . SDEF (unsigned int, _get_reloc_upper_bound, (bfd *, sec_ptr));
$ SDEF (unsigned int, _bfd_canonicalize_reloc, (bfd *, sec_ptr, arelent **, . SDEF (unsigned int, _bfd_canonicalize_reloc, (bfd *, sec_ptr, arelent **,
$ struct symbol_cache_entry**)); . struct symbol_cache_entry**));
$ SDEF (struct symbol_cache_entry *, _bfd_make_empty_symbol, (bfd *)); . SDEF (struct symbol_cache_entry *, _bfd_make_empty_symbol, (bfd *));
$ SDEF (void, _bfd_print_symbol, (bfd *, PTR, struct symbol_cache_entry *, . SDEF (void, _bfd_print_symbol, (bfd *, PTR, struct symbol_cache_entry *,
$ bfd_print_symbol_type)); . bfd_print_symbol_type));
$#define bfd_print_symbol(b,p,s,e) BFD_SEND(b, _bfd_print_symbol, (b,p,s,e)) .#define bfd_print_symbol(b,p,s,e) BFD_SEND(b, _bfd_print_symbol, (b,p,s,e))
$ SDEF (alent *, _get_lineno, (bfd *, struct symbol_cache_entry *)); . SDEF (alent *, _get_lineno, (bfd *, struct symbol_cache_entry *));
$ .
$ SDEF (boolean, _bfd_set_arch_mach, (bfd *, enum bfd_architecture, . SDEF (boolean, _bfd_set_arch_mach, (bfd *, enum bfd_architecture,
$ unsigned long)); . unsigned long));
$ .
$ SDEF (bfd *, openr_next_archived_file, (bfd *arch, bfd *prev)); . SDEF (bfd *, openr_next_archived_file, (bfd *arch, bfd *prev));
$ SDEF (boolean, _bfd_find_nearest_line, . SDEF (boolean, _bfd_find_nearest_line,
$ (bfd *abfd, struct sec *section, . (bfd *abfd, struct sec *section,
$ struct symbol_cache_entry **symbols,bfd_vma offset, . struct symbol_cache_entry **symbols,bfd_vma offset,
$ CONST char **file, CONST char **func, unsigned int *line)); . CONST char **file, CONST char **func, unsigned int *line));
$ SDEF (int, _bfd_stat_arch_elt, (bfd *, struct stat *)); . SDEF (int, _bfd_stat_arch_elt, (bfd *, struct stat *));
$ .
$ SDEF (int, _bfd_sizeof_headers, (bfd *, boolean)); . SDEF (int, _bfd_sizeof_headers, (bfd *, boolean));
$ .
$ SDEF (void, _bfd_debug_info_start, (bfd *)); . SDEF (void, _bfd_debug_info_start, (bfd *));
$ SDEF (void, _bfd_debug_info_end, (bfd *)); . SDEF (void, _bfd_debug_info_end, (bfd *));
$ SDEF (void, _bfd_debug_info_accumulate, (bfd *, struct sec *)); . SDEF (void, _bfd_debug_info_accumulate, (bfd *, struct sec *));
Special entry points for gdb to swap in coff symbol table parts Special entry points for gdb to swap in coff symbol table parts
$ SDEF(void, _bfd_coff_swap_aux_in,( . SDEF(void, _bfd_coff_swap_aux_in,(
$ bfd *abfd , . bfd *abfd ,
$ PTR ext, . PTR ext,
$ int type, . int type,
$ int class , . int class ,
$ PTR in)); . PTR in));
$ .
$ SDEF(void, _bfd_coff_swap_sym_in,( . SDEF(void, _bfd_coff_swap_sym_in,(
$ bfd *abfd , . bfd *abfd ,
$ PTR ext, . PTR ext,
$ PTR in)); . PTR in));
$ .
$ SDEF(void, _bfd_coff_swap_lineno_in, ( . SDEF(void, _bfd_coff_swap_lineno_in, (
$ bfd *abfd, . bfd *abfd,
$ PTR ext, . PTR ext,
$ PTR in)); . PTR in));
$ .
Special entry points for gas to swap coff parts Special entry points for gas to swap coff parts
$ SDEF(unsigned int, _bfd_coff_swap_aux_out,( . SDEF(unsigned int, _bfd_coff_swap_aux_out,(
$ bfd *abfd, . bfd *abfd,
$ PTR in, . PTR in,
$ int type, . int type,
$ int class, . int class,
$ PTR ext)); . PTR ext));
$ .
$ SDEF(unsigned int, _bfd_coff_swap_sym_out,( . SDEF(unsigned int, _bfd_coff_swap_sym_out,(
$ bfd *abfd, . bfd *abfd,
$ PTR in, . PTR in,
$ PTR ext)); . PTR ext));
$ .
$ SDEF(unsigned int, _bfd_coff_swap_lineno_out,( . SDEF(unsigned int, _bfd_coff_swap_lineno_out,(
$ bfd *abfd, . bfd *abfd,
$ PTR in, . PTR in,
$ PTR ext)); . PTR ext));
$ .
$ SDEF(unsigned int, _bfd_coff_swap_reloc_out,( . SDEF(unsigned int, _bfd_coff_swap_reloc_out,(
$ bfd *abfd, . bfd *abfd,
$ PTR src, . PTR src,
$ PTR dst)); . PTR dst));
$ .
$ SDEF(unsigned int, _bfd_coff_swap_filehdr_out,( . SDEF(unsigned int, _bfd_coff_swap_filehdr_out,(
$ bfd *abfd, . bfd *abfd,
$ PTR in, . PTR in,
$ PTR out)); . PTR out));
$ .
$ SDEF(unsigned int, _bfd_coff_swap_aouthdr_out,( . SDEF(unsigned int, _bfd_coff_swap_aouthdr_out,(
$ bfd *abfd, . bfd *abfd,
$ PTR in, . PTR in,
$ PTR out)); . PTR out));
$ .
$ SDEF(unsigned int, _bfd_coff_swap_scnhdr_out,( . SDEF(unsigned int, _bfd_coff_swap_scnhdr_out,(
$ bfd *abfd, . bfd *abfd,
$ PTR in, . PTR in,
$ PTR out)); . PTR out));
$ .
$} bfd_target; .} bfd_target;
*---
*/ */
@ -519,19 +526,24 @@ bfd_target *default_vector[] = {
/*proto* /*
*i bfd_find_target FUNCTION
bfd_find_target
DESCRIPTION
Returns a pointer to the transfer vector for the object target Returns a pointer to the transfer vector for the object target
named target_name. If target_name is NULL, chooses the one in the named target_name. If target_name is NULL, chooses the one in
environment variable GNUTARGET; if that is null or not defined then the environment variable GNUTARGET; if that is null or not
the first entry in the target list is chosen. Passing in the defined thenthe first entry in the target list is chosen.
string "default" or setting the environment variable to "default" Passing in the string "default" or setting the environment
will cause the first entry in the target list to be returned, variable to "default" will cause the first entry in the target
and "target_defaulted" will be set in the BFD. This causes list to be returned, and "target_defaulted" will be set in the
@code{bfd_check_format} to loop over all the targets to find the one BFD. This causes <<bfd_check_format>> to loop over all the
that matches the file being read. targets to find the one that matches the file being read.
*; PROTO(bfd_target *, bfd_find_target,(CONST char *, bfd *));
*-*/ SYNOPSIS
bfd_target *bfd_find_target(CONST char *, bfd *);
*/
bfd_target * bfd_target *
DEFUN(bfd_find_target,(target_name, abfd), DEFUN(bfd_find_target,(target_name, abfd),
@ -561,13 +573,19 @@ DEFUN(bfd_find_target,(target_name, abfd),
} }
/*proto* /*
*i bfd_target_list FUNCTION
This function returns a freshly malloced NULL-terminated vector of the bfd_target_list
names of all the valid BFD targets. Do not modify the names
*; PROTO(CONST char **,bfd_target_list,());
*-*/ DESCRIPTION
This function returns a freshly malloced NULL-terminated
vector of the names of all the valid BFD targets. Do not
modify the names
SYNOPSIS
CONST char **bfd_target_list();
*/
CONST char ** CONST char **
DEFUN_VOID(bfd_target_list) DEFUN_VOID(bfd_target_list)