bfd.texinfo

早期freebsd实现

language.

@emph{Information can be lost during canonicalization.} The BFD
internal canonical form of the external formats is not exhaustive; there
are structures in input formats for which there is no direct
representation internally.  This means that the BFD back ends
cannot maintain all possible data richness through the transformation
between external to internal and back to external formats.

This limitation is only a problem when an application reads one
format and writes another.  Each BFD back end is responsible for
maintaining as much data as possible, and the internal BFD
canonical form has structures which are opaque to the BFD core,
and exported only to the back ends. When a file is read in one format,
the canonical form is generated for BFD and the application. At the
same time, the back end saves away any information which may otherwise
be lost. If the data is then written back in the same format, the back
end routine will be able to use the canonical form provided by the
BFD core as well as the information it prepared earlier.  Since
there is a great deal of commonality between back ends, this mechanism
is very useful. There is no information lost for this reason when
linking or copying big endian COFF to little endian COFF, or @code{a.out} to
@code{b.out}.  When a mixture of formats is linked, the information is
only lost from the files whose format differs from the destination.

@node Mechanism,  , BFD information loss, What BFD Version 1 Can Do
@subsection Mechanism 
The greatest potential for loss of information is when there is least
overlap between the information provided by the source format, that
stored by the canonical format, and the information needed by the
destination format. A brief description of the canonical form may help
you appreciate what kinds of data you can count on preserving across
conversions.
@cindex BFD canonical format
@cindex internal object-file format

@table @emph
@item files
Information on target machine architecture, particular implementation
and format type are stored on a per-file basis. Other information
includes a demand pageable bit and a write protected bit.  Note that
information like Unix magic numbers is not stored here---only the magic
numbers' meaning, so a @code{ZMAGIC} file would have both the demand
pageable bit and the write protected text bit set.  The byte order of
the target is stored on a per-file basis, so that big- and little-endian
object files may be linked with one another.
@c FIXME: generalize above from "link"?

@item sections
Each section in the input file contains the name of the section, the
original address in the object file, various flags, size and alignment
information and pointers into other BFD data structures.

@item symbols
Each symbol contains a pointer to the object file which originally
defined it, its name, its value, and various flag bits.  When a
BFD back end reads in a symbol table, the back end relocates all
symbols to make them relative to the base of the section where they were
defined.  This ensures that each symbol points to its containing
section.  Each symbol also has a varying amount of hidden data to contain
private data for the BFD back end.  Since the symbol points to the
original file, the private data format for that symbol is accessible.
@code{gld} can operate on a collection of symbols of wildly different
formats without problems.

Normal global and simple local symbols are maintained on output, so an
output file (no matter its format) will retain symbols pointing to
functions and to global, static, and common variables.  Some symbol
information is not worth retaining; in @code{a.out} type information is
stored in the symbol table as long symbol names.  This information would
be useless to most COFF debuggers; the linker has command line switches
to allow users to throw it away.

There is one word of type information within the symbol, so if the
format supports symbol type information within symbols (for example COFF,
IEEE, Oasys) and the type is simple enough to fit within one word
(nearly everything but aggregates) the information will be preserved.

@item relocation level
Each canonical BFD relocation record contains a pointer to the symbol to
relocate to, the offset of the data to relocate, the section the data
is in and a pointer to a relocation type descriptor. Relocation is
performed effectively by message passing through the relocation type
descriptor and symbol pointer. It allows relocations to be performed
on output data using a relocation method only available in one of the
input formats. For instance, Oasys provides a byte relocation format.
A relocation record requesting this relocation type would point
indirectly to a routine to perform this, so the relocation may be
performed on a byte being written to a COFF file, even though 68k COFF
has no such relocation type.

@item line numbers
Object formats can contain, for debugging purposes, some form of mapping
between symbols, source line numbers, and addresses in the output file.
These addresses have to be relocated along with the symbol information.
Each symbol with an associated list of line number records points to the
first record of the list.  The head of a line number list consists of a
pointer to the symbol, which allows divination of the address of the
function whose line number is being described. The rest of the list is
made up of pairs: offsets into the section and line numbers. Any format
which can simply derive this information can pass it successfully
between formats (COFF, IEEE and Oasys).
@end table

@c FIXME: what is this line about?  Do we want introductory remarks 
@c FIXME... on back ends?  commented out for now.
@c What is a backend


@node BFD front end, BFD back end, Overview, Top
@chapter BFD front end
@include  bfd.texi

@menu
* Memory Usage::
* Initialization::
* Sections::
* Symbols::
* Archives::
* Formats::
* Relocations::
* Core Files::
* Targets::
* Architectures::
* Opening and Closing::
* Constructors::
* Internal::
* File Caching::
@end menu

@node Memory Usage, Initialization, BFD front end, BFD front end
@section Memory Usage
BFD keeps all its internal structures in obstacks. There is one obstack
per open BFD file, into which the current state is stored. When a BFD is
closed, the obstack is deleted, and so everything which has been
allocated by libbfd for the closing file will be thrown away.

BFD will not free anything created by an application, but pointers into
@code{bfd} structures will be invalidated on a @code{bfd_close}; for example,
after a @code{bfd_close} the vector passed to
@code{bfd_canonicalize_symtab} will still be around, since it has been
allocated by the application, but the data that it pointed to will be
lost.

The general rule is not to close a BFD until all operations dependent
upon data from the BFD have been completed, or all the data from within
the file has been copied. To help with the management of memory, there is a function
(@code{bfd_alloc_size}) which returns the number of bytes in obstacks
associated with the supplied BFD. This could be used to select the
greediest open BFD, close it to reclaim the memory, perform some
operation and reopen the BFD again, to get a fresh copy of the data structures.

@node Initialization, Sections, Memory Usage, BFD front end
@include  init.texi

@node Sections, Symbols, Initialization, BFD front end
@include  section.texi

@node Symbols, Archives, Sections, BFD front end
@include  syms.texi

@node Archives, Formats, Symbols, BFD front end
@include  archive.texi

@node Formats, Relocations, Archives, BFD front end
@include  format.texi

@node Relocations, Core Files, Formats, BFD front end
@include  reloc.texi

@node Core Files, Targets, Relocations, BFD front end
@include  core.texi

@node Targets, Architectures, Core Files, BFD front end
@include  targets.texi

@node Architectures, Opening and Closing, Targets, BFD front end
@include  archures.texi

@node Opening and Closing, Constructors, Architectures, BFD front end
@include  opncls.texi

@node Constructors, Internal, Opening and Closing, BFD front end
@include  ctor.texi

@node Internal, File Caching, Constructors, BFD front end
@include  libbfd.texi

@node File Caching,  , Internal, BFD front end
@include  cache.texi

@node BFD back end, Index, BFD front end, Top
@chapter BFD back end
@menu
* What to put where::
* aout ::	a.out backends
* coff ::	coff backends
@ignore
* oasys ::	oasys backends
* ieee ::	ieee backend
* srecord ::	s-record backend
@end ignore
@end menu
@node What to Put Where, aout, BFD back end, BFD back end
All of BFD lives in one directory.

@node aout, coff, What to Put Where, BFD back end
@include  aoutx.texi

@node coff,  , aout, BFD back end
@include  coffcode.texi

@node Index,  , BFD back end, Top
@unnumbered Index
@printindex cp

@tex
% I think something like @colophon should be in texinfo.  In the
% meantime:
\long\def\colophon{\hbox to0pt{}\vfill
\centerline{The body of this manual is set in}
\centerline{\fontname\tenrm,}
\centerline{with headings in {\bf\fontname\tenbf}}
\centerline{and examples in {\tt\fontname\tentt}.}
\centerline{{\it\fontname\tenit\/} and}
\centerline{{\sl\fontname\tensl\/}}
\centerline{are used for emphasis.}\vfill}
\page\colophon
% Blame: [e-mail], 28mar91.
@end tex

@contents
@bye