include elf doc

bfd/doc/ChangeLog

@@ -1,3 +1,11 @@
+Mon Aug  9 16:27:30 1993  Ken Raeburn  (raeburn@cambridge.cygnus.com)
+
+	* bfd.texinfo (BFD back end): New section on ELF, includes
+	elf.texi and elfcode.texi.
+	* Makefile.in (DOCFILES): Include elf.texi, elfcode.texi.
+	(SRCDOC): Include elfcode.h, elf.c.
+	(elf.texi, elfcode.texi): New intermediate targets.
+
 Thu Jun 24 13:48:13 1993  David J. Mackenzie  (djm@thepub.cygnus.com)
 
 	* Makefile.in (.c.o, chew.o): Put CFLAGS last.

bfd/doc/bfd.texinfo

@@ -20,7 +20,7 @@
 @ifinfo
 @format
 START-INFO-DIR-ENTRY
-* Bfd: (bfd).			The Binary File Descriptor library.
+* Bfd::                         The Binary File Descriptor library.
 END-INFO-DIR-ENTRY
 @end format
 @end ifinfo
@@ -150,9 +150,9 @@ different object file formats: IEEE-695, Oasys, Srecords, a.out and 68k
 coff.
 
 BFD was first implemented by members of Cygnus Support; Steve
-Chamberlain (@file{sac@@cygnus.com}), John Gilmore
+Chamberlain (@code{sac@@cygnus.com}), John Gilmore
-(@file{gnu@@cygnus.com}), K.  Richard Pixley (@file{rich@@cygnus.com})
+(@code{gnu@@cygnus.com}), K.  Richard Pixley (@code{rich@@cygnus.com})
-and David Henkel-Wallace (@file{gumby@@cygnus.com}).
+and David Henkel-Wallace (@code{gumby@@cygnus.com}).
 
 
 
@@ -165,9 +165,9 @@ BFD provides a common interface to the parts of an object file
 for a calling application. 
 
 When an application sucessfully opens a target file (object, archive, or
-whatever) a pointer to an internal structure is returned. This pointer
+whatever), a pointer to an internal structure is returned. This pointer
 points to a structure called @code{bfd}, described in
-@file{include/bfd.h}.  Our convention is to call this pointer a BFD, and
+@file{bfd.h}.  Our convention is to call this pointer a BFD, and
 instances of it within code @code{abfd}.  All operations on
 the target object file are applied as methods to the BFD.  The mapping is
 defined within @code{bfd.h} in a set of macros, all beginning
@@ -189,163 +189,31 @@ bfd *abfd;
 @c @end cartouche
 @end lisp
 
-The abstraction used within BFD is that an object file has a header,
+The abstraction used within BFD is that an object file has:
-a number of sections containing raw data, a set of relocations, and some
+
-symbol information. Also, BFDs opened for archives have the
+@itemize @bullet
-additional attribute of an index and contain subordinate BFDs. This approach is
+@item
-fine for a.out and coff, but loses efficiency when applied to formats
+a header,
-such as S-records and IEEE-695. 
+@item
+a number of sections containing raw data (@pxref{Sections}),
+@item
+a set of relocations (@pxref{Relocations}), and
+@item
+some symbol information (@pxref{Symbols}).
+@end itemize
+@noindent
+Also, BFDs opened for archives have the additional attribute of an index
+and contain subordinate BFDs. This approach is fine for a.out and coff,
+but loses efficiency when applied to formats such as S-records and
+IEEE-695.
 
 @node What BFD Version 2 Can Do,  , How It Works, Overview
 @section What BFD Version 2 Can Do
-As different information from the the object files is required,
+@include bfdsumm.texi
-BFD reads from different sections of the file and processes them.
-For example, a very common operation for the linker is processing symbol
-tables.  Each BFD back end provides a routine for converting
-between the object file's representation of symbols and an internal
-canonical format. When the linker asks for the symbol table of an object
-file, it calls through the memory pointer to a routine from the
-relevant BFD back end which reads and converts the table into a canonical
-form.  The linker then operates upon the canonical form. When the link is
-finished and the linker writes the output file's symbol table,
-another BFD back end routine is called to take the newly
-created symbol table and convert it into the chosen output format.
-
-@menu
-* BFD information loss::	Information Loss
-* Mechanism::			Mechanism 
-@end menu
-
-@node BFD information loss, Mechanism, What BFD Version 2 Can Do, What BFD Version 2 Can Do
-@subsection Information Loss
-@emph{Some information is lost due to the nature of the file format.} The output targets
-supported by BFD do not provide identical facilities, and
-information which can be described in one form has nowhere to go in
-another format. One example of this is alignment information in
-@code{b.out}. There is nowhere in an @code{a.out} format file to store
-alignment information on the contained data, so when a file is linked
-from @code{b.out} and an @code{a.out} image is produced, alignment
-information will not propagate to the output file. (The linker will
-still use the alignment information internally, so the link is performed
-correctly).
-
-Another example is COFF section names. COFF files may contain an
-unlimited number of sections, each one with a textual section name. If
-the target of the link is a format which does not have many sections (e.g.,
-@code{a.out}) or has sections without names (e.g., the Oasys format), the
-link cannot be done simply. You can circumvent this problem by
-describing the desired input-to-output section mapping with the linker command
-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,
-there is no information lost 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 2 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 used with one another.
-
-@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 (if any), 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 68k 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
+@include bfd.texi
 
 @menu
 * Memory Usage::
@@ -432,6 +300,7 @@ structures.
 * What to Put Where::
 * aout ::	a.out backends
 * coff ::	coff backends
+* elf  ::	elf backends
 @ignore
 * oasys ::	oasys backends
 * ieee ::	ieee backend
@@ -444,9 +313,13 @@ 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
+@node coff, elf, aout, BFD back end
 @include  coffcode.texi
 
+@node elf,  , coff, BFD back end
+@include  elf.texi
+@include  elfcode.texi
+
 @node Index,  , BFD back end, Top
 @unnumbered Index
 @printindex cp
@@ -468,5 +341,3 @@ All of BFD lives in one directory.
 
 @contents
 @bye
-
-