From e5c5fbca679679672ac8b07788f5ba23f39ccde0 Mon Sep 17 00:00:00 2001 From: Ken Raeburn Date: Mon, 9 Aug 1993 20:31:30 +0000 Subject: [PATCH] include elf doc --- bfd/doc/ChangeLog | 8 ++ bfd/doc/bfd.texinfo | 191 +++++++------------------------------------- 2 files changed, 39 insertions(+), 160 deletions(-) diff --git a/bfd/doc/ChangeLog b/bfd/doc/ChangeLog index 0296e3d037..1595068d5a 100644 --- a/bfd/doc/ChangeLog +++ b/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. diff --git a/bfd/doc/bfd.texinfo b/bfd/doc/bfd.texinfo index 90eb98c0c4..d2622e0404 100644 --- a/bfd/doc/bfd.texinfo +++ b/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 -(@file{gnu@@cygnus.com}), K. Richard Pixley (@file{rich@@cygnus.com}) -and David Henkel-Wallace (@file{gumby@@cygnus.com}). +Chamberlain (@code{sac@@cygnus.com}), John Gilmore +(@code{gnu@@cygnus.com}), K. Richard Pixley (@code{rich@@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, -a number of sections containing raw data, a set of relocations, and some -symbol information. 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. +The abstraction used within BFD is that an object file has: + +@itemize @bullet +@item +a header, +@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, -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 - +@include bfdsumm.texi @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 - -