mirror of
https://github.com/espressif/binutils-gdb.git
synced 2025-06-20 01:50:24 +08:00
Even more documentation
This commit is contained in:
Steve Chamberlain
309
bfd/bfd.c
309
bfd/bfd.c
@ -20,142 +20,143 @@ Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. */
|
|||||||
|
|
||||||
/* $Id$ */
|
/* $Id$ */
|
||||||
|
|
||||||
/*proto*
|
/*
|
||||||
@section @code{typedef bfd}
|
SECTION
|
||||||
|
<<typedef bfd>>
|
||||||
|
|
||||||
A BFD is has type @code{bfd}; objects of this type are the cornerstone
|
DESCRIPTION
|
||||||
of any application using @code{libbfd}. References though the BFD and
|
A BFD is has type <<bfd>>; objects of this type are the
|
||||||
to data in the BFD give the entire BFD functionality.
|
cornerstone of any application using <<libbfd>>. References
|
||||||
|
though the BFD and to data in the BFD give the entire BFD
|
||||||
|
functionality.
|
||||||
|
|
||||||
Here is the struct used to define the type @code{bfd}. This contains
|
Here is the struct used to define the type <<bfd>>. This
|
||||||
the major data about the file, and contains pointers to the rest of
|
contains he major data about the file, and contains pointers
|
||||||
the data.
|
to the rest of the data.
|
||||||
|
|
||||||
*+++
|
.struct _bfd
|
||||||
|
.{
|
||||||
|
The filename the application opened the BFD with.
|
||||||
|
|
||||||
$struct _bfd
|
. CONST char *filename;
|
||||||
${
|
|
||||||
The filename the application opened the BFD with.
|
|
||||||
|
|
||||||
$ CONST char *filename;
|
A pointer to the target jump table.
|
||||||
|
|
||||||
A pointer to the target jump table.
|
. struct bfd_target *xvec;
|
||||||
|
|
||||||
$ struct bfd_target *xvec;
|
To avoid dragging too many header files into every file that
|
||||||
|
includes @file{bfd.h}, IOSTREAM has been declared as a "char
|
||||||
|
*", and MTIME as a "long". Their correct types, to which they
|
||||||
|
are cast when used, are "FILE *" and "time_t". The iostream
|
||||||
|
is the result of an fopen on the filename.
|
||||||
|
|
||||||
|
. char *iostream;
|
||||||
To avoid dragging too many header files into every file that
|
|
||||||
includes @file{bfd.h}, IOSTREAM has been declared as a "char *", and MTIME
|
|
||||||
as a "long". Their correct types, to which they are cast when used,
|
|
||||||
are "FILE *" and "time_t".
|
|
||||||
|
|
||||||
The iostream is the result of an fopen on the filename.
|
|
||||||
|
|
||||||
$ char *iostream;
|
|
||||||
|
|
||||||
Is the file being cached @xref{File Caching}.
|
Is the file being cached @xref{File Caching}.
|
||||||
|
|
||||||
$ boolean cacheable;
|
. boolean cacheable;
|
||||||
|
|
||||||
Marks whether there was a default target specified when the BFD was
|
Marks whether there was a default target specified when the
|
||||||
opened. This is used to select what matching algorithm to use to chose
|
BFD was opened. This is used to select what matching algorithm
|
||||||
the back end.
|
to use to chose the back end.
|
||||||
|
|
||||||
$ boolean target_defaulted;
|
. boolean target_defaulted;
|
||||||
|
|
||||||
The caching routines use these to maintain a least-recently-used list of
|
The caching routines use these to maintain a
|
||||||
BFDs (@pxref{File Caching}).
|
least-recently-used list of BFDs (@pxref{File Caching}).
|
||||||
|
|
||||||
$ struct _bfd *lru_prev, *lru_next;
|
. struct _bfd *lru_prev, *lru_next;
|
||||||
|
|
||||||
When a file is closed by the caching routines, BFD retains state
|
When a file is closed by the caching routines, BFD retains
|
||||||
information on the file here:
|
state information on the file here:
|
||||||
|
|
||||||
$ file_ptr where;
|
. file_ptr where;
|
||||||
|
|
||||||
and here:
|
and here:
|
||||||
|
|
||||||
$ boolean opened_once;
|
. boolean opened_once;
|
||||||
|
|
||||||
|
. boolean mtime_set;
|
||||||
|
|
||||||
$ boolean mtime_set;
|
|
||||||
File modified time
|
File modified time
|
||||||
|
|
||||||
$ long mtime;
|
. long mtime;
|
||||||
|
|
||||||
Reserved for an unimplemented file locking extension.
|
Reserved for an unimplemented file locking extension.
|
||||||
|
|
||||||
$int ifd;
|
. int ifd;
|
||||||
|
|
||||||
The format which belongs to the BFD.
|
The format which belongs to the BFD.
|
||||||
|
|
||||||
$ bfd_format format;
|
. bfd_format format;
|
||||||
|
|
||||||
The direction the BFD was opened with
|
The direction the BFD was opened with
|
||||||
|
|
||||||
$ enum bfd_direction {no_direction = 0,
|
. enum bfd_direction {no_direction = 0,
|
||||||
$ read_direction = 1,
|
. read_direction = 1,
|
||||||
$ write_direction = 2,
|
. write_direction = 2,
|
||||||
$ both_direction = 3} direction;
|
. both_direction = 3} direction;
|
||||||
|
|
||||||
Format_specific flags
|
Format_specific flags
|
||||||
|
|
||||||
$ flagword flags;
|
. flagword flags;
|
||||||
|
|
||||||
Currently my_archive is tested before adding origin to anything. I
|
Currently my_archive is tested before adding origin to
|
||||||
believe that this can become always an add of origin, with origin set
|
anything. I believe that this can become always an add of
|
||||||
to 0 for non archive files.
|
origin, with origin set to 0 for non archive files.
|
||||||
|
|
||||||
$ file_ptr origin;
|
. file_ptr origin;
|
||||||
|
|
||||||
Remember when output has begun, to stop strange things happening.
|
Remember when output has begun, to stop strange things happening.
|
||||||
|
|
||||||
$ boolean output_has_begun;
|
. boolean output_has_begun;
|
||||||
|
|
||||||
Pointer to linked list of sections
|
Pointer to linked list of sections
|
||||||
|
|
||||||
$ struct sec *sections;
|
. struct sec *sections;
|
||||||
|
|
||||||
The number of sections
|
The number of sections
|
||||||
|
|
||||||
$ unsigned int section_count;
|
. unsigned int section_count;
|
||||||
|
|
||||||
Stuff only useful for object files:
|
Stuff only useful for object files:
|
||||||
The start address.
|
The start address.
|
||||||
|
|
||||||
$ bfd_vma start_address;
|
. bfd_vma start_address;
|
||||||
Used for input and output
|
|
||||||
|
|
||||||
$ unsigned int symcount;
|
Used for input and output
|
||||||
Symbol table for output BFD
|
|
||||||
|
|
||||||
$ struct symbol_cache_entry **outsymbols;
|
. unsigned int symcount;
|
||||||
|
|
||||||
Pointer to structure which contains architecture information
|
Symbol table for output BFD
|
||||||
|
|
||||||
$ struct bfd_arch_info *arch_info;
|
. struct symbol_cache_entry **outsymbols;
|
||||||
|
|
||||||
Stuff only useful for archives:
|
Pointer to structure which contains architecture information
|
||||||
|
|
||||||
$ PTR arelt_data;
|
. struct bfd_arch_info *arch_info;
|
||||||
$ struct _bfd *my_archive;
|
|
||||||
$ struct _bfd *next;
|
|
||||||
$ struct _bfd *archive_head;
|
|
||||||
$ boolean has_armap;
|
|
||||||
|
|
||||||
Used by the back end to hold private data.
|
Stuff only useful for archives:
|
||||||
|
|
||||||
$ PTR tdata;
|
. PTR arelt_data;
|
||||||
|
. struct _bfd *my_archive;
|
||||||
|
. struct _bfd *next;
|
||||||
|
. struct _bfd *archive_head;
|
||||||
|
. boolean has_armap;
|
||||||
|
|
||||||
Used by the application to hold private data
|
Used by the back end to hold private data.
|
||||||
|
|
||||||
$ PTR usrdata;
|
. PTR tdata;
|
||||||
|
|
||||||
Where all the allocated stuff under this BFD goes (@pxref{Memory Usage}).
|
Used by the application to hold private data
|
||||||
|
|
||||||
$ struct obstack memory;
|
. PTR usrdata;
|
||||||
$};
|
|
||||||
|
|
||||||
*---
|
Where all the allocated stuff under this BFD goes
|
||||||
|
(@pxref{Memory Usage}).
|
||||||
|
|
||||||
|
. struct obstack memory;
|
||||||
|
.};
|
||||||
|
|
||||||
*/
|
*/
|
||||||
#include "bfd.h"
|
#include "bfd.h"
|
||||||
@ -338,12 +339,19 @@ int line;
|
|||||||
}
|
}
|
||||||
|
|
||||||
|
|
||||||
/*proto* bfd_set_start_address
|
/*
|
||||||
|
FUNCTION
|
||||||
|
bfd_set_start_address
|
||||||
|
|
||||||
Marks the entry point of an output BFD. Returns @code{true} on
|
DESCRIPTION
|
||||||
success, @code{false} otherwise.
|
|
||||||
|
|
||||||
*; PROTO(boolean, bfd_set_start_address,(bfd *, bfd_vma));
|
Marks the entry point of an output BFD.
|
||||||
|
|
||||||
|
RETURNS
|
||||||
|
Returns <<true>> on success, <<false>> otherwise.
|
||||||
|
|
||||||
|
SYNOPSIS
|
||||||
|
boolean bfd_set_start_address(bfd *, bfd_vma);
|
||||||
*/
|
*/
|
||||||
|
|
||||||
boolean
|
boolean
|
||||||
@ -356,14 +364,18 @@ bfd_vma vma;
|
|||||||
}
|
}
|
||||||
|
|
||||||
|
|
||||||
/*proto* bfd_get_mtime
|
/*
|
||||||
|
FUNCTION
|
||||||
|
bfd_get_mtime
|
||||||
|
|
||||||
Return cached file modification time (e.g. as read from archive header
|
DESCRIPTION
|
||||||
for archive members, or from file system if we have been called
|
Return cached file modification time (e.g. as read from
|
||||||
before); else determine modify time, cache it, and return it.
|
archive header for archive members, or from file system if we
|
||||||
|
have been called before); else determine modify time, cache
|
||||||
*; PROTO(long, bfd_get_mtime, (bfd *));
|
it, and return it.
|
||||||
|
|
||||||
|
SYNOPSIS
|
||||||
|
long bfd_get_mtime(bfd *);
|
||||||
*/
|
*/
|
||||||
|
|
||||||
long
|
long
|
||||||
@ -385,63 +397,64 @@ bfd_get_mtime (abfd)
|
|||||||
return abfd->mtime;
|
return abfd->mtime;
|
||||||
}
|
}
|
||||||
|
|
||||||
/*proto* stuff
|
/*
|
||||||
|
FUNCTION
|
||||||
|
stuff
|
||||||
|
|
||||||
*+
|
DESCRIPTION
|
||||||
|
stuff which should be documented
|
||||||
#define bfd_sizeof_headers(abfd, reloc) \
|
|
||||||
BFD_SEND (abfd, _bfd_sizeof_headers, (abfd, reloc))
|
|
||||||
|
|
||||||
#define bfd_find_nearest_line(abfd, section, symbols, offset, filename_ptr, func, line_ptr) \
|
|
||||||
BFD_SEND (abfd, _bfd_find_nearest_line, (abfd, section, symbols, offset, filename_ptr, func, line_ptr))
|
|
||||||
|
|
||||||
#define bfd_debug_info_start(abfd) \
|
|
||||||
BFD_SEND (abfd, _bfd_debug_info_start, (abfd))
|
|
||||||
|
|
||||||
#define bfd_debug_info_end(abfd) \
|
|
||||||
BFD_SEND (abfd, _bfd_debug_info_end, (abfd))
|
|
||||||
|
|
||||||
#define bfd_debug_info_accumulate(abfd, section) \
|
|
||||||
BFD_SEND (abfd, _bfd_debug_info_accumulate, (abfd, section))
|
|
||||||
|
|
||||||
#define bfd_stat_arch_elt(abfd, stat) \
|
|
||||||
BFD_SEND (abfd, _bfd_stat_arch_elt,(abfd, stat))
|
|
||||||
|
|
||||||
#define bfd_coff_swap_aux_in(a,e,t,c,i) \
|
|
||||||
BFD_SEND (a, _bfd_coff_swap_aux_in, (a,e,t,c,i))
|
|
||||||
|
|
||||||
#define bfd_coff_swap_sym_in(a,e,i) \
|
|
||||||
BFD_SEND (a, _bfd_coff_swap_sym_in, (a,e,i))
|
|
||||||
|
|
||||||
#define bfd_coff_swap_lineno_in(a,e,i) \
|
|
||||||
BFD_SEND ( a, _bfd_coff_swap_lineno_in, (a,e,i))
|
|
||||||
|
|
||||||
#define bfd_set_arch_mach(abfd, arch, mach)\
|
|
||||||
BFD_SEND ( abfd, _bfd_set_arch_mach, (abfd, arch, mach))
|
|
||||||
|
|
||||||
#define bfd_coff_swap_reloc_out(abfd, i, o) \
|
|
||||||
BFD_SEND (abfd, _bfd_coff_swap_reloc_out, (abfd, i, o))
|
|
||||||
|
|
||||||
#define bfd_coff_swap_lineno_out(abfd, i, o) \
|
|
||||||
BFD_SEND (abfd, _bfd_coff_swap_lineno_out, (abfd, i, o))
|
|
||||||
|
|
||||||
#define bfd_coff_swap_aux_out(abfd, i, t,c,o) \
|
|
||||||
BFD_SEND (abfd, _bfd_coff_swap_aux_out, (abfd, i,t,c, o))
|
|
||||||
|
|
||||||
#define bfd_coff_swap_sym_out(abfd, i,o) \
|
|
||||||
BFD_SEND (abfd, _bfd_coff_swap_sym_out, (abfd, i, o))
|
|
||||||
|
|
||||||
#define bfd_coff_swap_scnhdr_out(abfd, i,o) \
|
|
||||||
BFD_SEND (abfd, _bfd_coff_swap_scnhdr_out, (abfd, i, o))
|
|
||||||
|
|
||||||
#define bfd_coff_swap_filehdr_out(abfd, i,o) \
|
|
||||||
BFD_SEND (abfd, _bfd_coff_swap_filehdr_out, (abfd, i, o))
|
|
||||||
|
|
||||||
#define bfd_coff_swap_aouthdr_out(abfd, i,o) \
|
|
||||||
BFD_SEND (abfd, _bfd_coff_swap_aouthdr_out, (abfd, i, o))
|
|
||||||
|
|
||||||
*-
|
|
||||||
|
|
||||||
|
.#define bfd_sizeof_headers(abfd, reloc) \
|
||||||
|
. BFD_SEND (abfd, _bfd_sizeof_headers, (abfd, reloc))
|
||||||
|
.
|
||||||
|
.#define bfd_find_nearest_line(abfd, section, symbols, offset, filename_ptr, func, line_ptr) \
|
||||||
|
. BFD_SEND (abfd, _bfd_find_nearest_line, (abfd, section, symbols, offset, filename_ptr, func, line_ptr))
|
||||||
|
.
|
||||||
|
.#define bfd_debug_info_start(abfd) \
|
||||||
|
. BFD_SEND (abfd, _bfd_debug_info_start, (abfd))
|
||||||
|
.
|
||||||
|
.#define bfd_debug_info_end(abfd) \
|
||||||
|
. BFD_SEND (abfd, _bfd_debug_info_end, (abfd))
|
||||||
|
.
|
||||||
|
.#define bfd_debug_info_accumulate(abfd, section) \
|
||||||
|
. BFD_SEND (abfd, _bfd_debug_info_accumulate, (abfd, section))
|
||||||
|
.
|
||||||
|
.#define bfd_stat_arch_elt(abfd, stat) \
|
||||||
|
. BFD_SEND (abfd, _bfd_stat_arch_elt,(abfd, stat))
|
||||||
|
.
|
||||||
|
.#define bfd_coff_swap_aux_in(a,e,t,c,i) \
|
||||||
|
. BFD_SEND (a, _bfd_coff_swap_aux_in, (a,e,t,c,i))
|
||||||
|
.
|
||||||
|
.#define bfd_coff_swap_sym_in(a,e,i) \
|
||||||
|
. BFD_SEND (a, _bfd_coff_swap_sym_in, (a,e,i))
|
||||||
|
.
|
||||||
|
.#define bfd_coff_swap_lineno_in(a,e,i) \
|
||||||
|
. BFD_SEND ( a, _bfd_coff_swap_lineno_in, (a,e,i))
|
||||||
|
.
|
||||||
|
.#define bfd_set_arch_mach(abfd, arch, mach)\
|
||||||
|
. BFD_SEND ( abfd, _bfd_set_arch_mach, (abfd, arch, mach))
|
||||||
|
.
|
||||||
|
.#define bfd_coff_swap_reloc_out(abfd, i, o) \
|
||||||
|
. BFD_SEND (abfd, _bfd_coff_swap_reloc_out, (abfd, i, o))
|
||||||
|
.
|
||||||
|
.#define bfd_coff_swap_lineno_out(abfd, i, o) \
|
||||||
|
. BFD_SEND (abfd, _bfd_coff_swap_lineno_out, (abfd, i, o))
|
||||||
|
.
|
||||||
|
.#define bfd_coff_swap_aux_out(abfd, i, t,c,o) \
|
||||||
|
. BFD_SEND (abfd, _bfd_coff_swap_aux_out, (abfd, i,t,c, o))
|
||||||
|
.
|
||||||
|
.#define bfd_coff_swap_sym_out(abfd, i,o) \
|
||||||
|
. BFD_SEND (abfd, _bfd_coff_swap_sym_out, (abfd, i, o))
|
||||||
|
.
|
||||||
|
.#define bfd_coff_swap_scnhdr_out(abfd, i,o) \
|
||||||
|
. BFD_SEND (abfd, _bfd_coff_swap_scnhdr_out, (abfd, i, o))
|
||||||
|
.
|
||||||
|
.#define bfd_coff_swap_filehdr_out(abfd, i,o) \
|
||||||
|
. BFD_SEND (abfd, _bfd_coff_swap_filehdr_out, (abfd, i, o))
|
||||||
|
.
|
||||||
|
.#define bfd_coff_swap_aouthdr_out(abfd, i,o) \
|
||||||
|
. BFD_SEND (abfd, _bfd_coff_swap_aouthdr_out, (abfd, i, o))
|
||||||
|
.
|
||||||
*/
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user