diff options
Diffstat (limited to 'bfd')
| -rw-r--r-- | bfd/doc/.Sanitize | 1 | ||||
| -rw-r--r-- | bfd/doc/Makefile.in | 19 | ||||
| -rw-r--r-- | bfd/doc/bfdsumm.texi | 148 |
3 files changed, 161 insertions, 7 deletions
diff --git a/bfd/doc/.Sanitize b/bfd/doc/.Sanitize index 22e475a..1ab6cfc 100644 --- a/bfd/doc/.Sanitize +++ b/bfd/doc/.Sanitize @@ -25,6 +25,7 @@ Things-to-keep: Makefile.in bfd.texinfo +bfdsumm.texi configure.in chew.c proto.str diff --git a/bfd/doc/Makefile.in b/bfd/doc/Makefile.in index a2bc308..9fdf078 100644 --- a/bfd/doc/Makefile.in +++ b/bfd/doc/Makefile.in @@ -61,7 +61,7 @@ CC_FOR_BUILD = $(CC) ### .c.o: - $(CC) $(CFLAGS) -c $(H_CFLAGS) -I.. -I$(srcdir)/.. -I$(srcdir)/../../include $< + $(CC) -c -I.. -I$(srcdir)/.. -I$(srcdir)/../../include $(H_CFLAGS) $(CFLAGS) $< # main GDB source directory @@ -123,13 +123,17 @@ install-info: info docs: $(MKDOC) protos bfd.info bfd.dvi bfd.ps $(MKDOC): chew.o - $(CC_FOR_BUILD) $(CFLAGS) -o $(MKDOC) $(H_CFLAGS) chew.o $(LOADLIBES) + $(CC_FOR_BUILD) -o $(MKDOC) chew.o $(LOADLIBES) $(LDFLAGS) chew.o: chew.c - $(CC_FOR_BUILD) $(CFLAGS) -c $(H_CFLAGS) -I.. -I$(srcdir)/.. -I$(srcdir)/../../include $(srcdir)/chew.c + $(CC_FOR_BUILD) -c -I.. -I$(srcdir)/.. -I$(srcdir)/../../include $(H_CFLAGS) $(CFLAGS) $(srcdir)/chew.c protos: libbfd.h libcoff.h bfd.h + +# We can't replace these rules with an implicit rule, because +# makes without VPATH support couldn't find the .h files in `..'. + aoutx.texi: $(MKDOC) $(srcdir)/../aoutx.h $(srcdir)/doc.str $(MKDOC) -f $(srcdir)/doc.str <$(srcdir)/../aoutx.h >aoutx.texi @@ -201,6 +205,7 @@ libbfd.h: $(srcdir)/../libbfd-in.h \ $(MKDOC) -i -f $(srcdir)/proto.str < $(srcdir)/../cpu-h8300.c >>libbfd.h $(MKDOC) -i -f $(srcdir)/proto.str < $(srcdir)/../cpu-i960.c >>libbfd.h $(MKDOC) -i -f $(srcdir)/proto.str < $(srcdir)/../archures.c >>libbfd.h + $(MKDOC) -i -f $(srcdir)/proto.str < $(srcdir)/../elf.c >>libbfd.h $(MKDOC) -i -f $(srcdir)/proto.str < $(srcdir)/../elfcode.h >>libbfd.h libcoff.h: $(srcdir)/../libcoff-in.h \ @@ -256,16 +261,16 @@ distclean: clean realclean: clean rm -f Makefile config.status -bfd.info: $(DOCFILES) bfd.texinfo +bfd.info: $(DOCFILES) bfdsumm.texi bfd.texinfo $(MAKEINFO) -o bfd.info $(srcdir)/bfd.texinfo -bfd.dvi: $(DOCFILES) bfd.texinfo +bfd.dvi: $(DOCFILES) bfdsumm.texi bfd.texinfo $(TEXI2DVI) $(srcdir)/bfd.texinfo bfd.ps: bfd.dvi dvips bfd -o - -quickdoc: $(DOCFILES) bfd.texinfo + +quickdoc: $(DOCFILES) bfdsumm.texi bfd.texinfo TEXINPUTS=${TEXIDIR}:.:$$TEXINPUTS tex bfd.texinfo stage1: force diff --git a/bfd/doc/bfdsumm.texi b/bfd/doc/bfdsumm.texi new file mode 100644 index 0000000..844531a --- /dev/null +++ b/bfd/doc/bfdsumm.texi @@ -0,0 +1,148 @@ +@c This summary of BFD is shared by the BFD and LD docs. +When an object file is opened, BFD subroutines automatically determine +the format of the input object file. They then build a descriptor in +memory with pointers to routines that will be used to access elements of +the object file's data structures. + +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 a memory pointer to the 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 +* Canonical format:: The BFD canonical object-file format +@end menu + +@node BFD information loss +@subsection Information Loss + +@emph{Information can be lost during output.} The output formats +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 Canonical format +@subsection The BFD canonical object-file format + +The greatest potential for loss of information occurs when there is the least +overlap between the information provided by the source format, that +stored by the canonical format, and that needed by the +destination format. A brief description of the canonical form may help +you understand which kinds of data you can count on preserving across +conversions. +@cindex BFD canonical format +@cindex internal object-file format + +@table @emph +@item files +Information stored on a per-file basis includes target machine +architecture, particular implementation format type, a demand pageable +bit, and a write protected bit. 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 +section's original address in the object file, size and alignment +information, various flags, and pointers into other BFD data +structures. + +@item symbols +Each symbol contains a pointer to the information for 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, it relocates all +symbols to make them relative to the base of the section where they were +defined. Doing this ensures that each symbol points to its containing +section. Each symbol also has a varying amount of hidden 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{ld} 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 by passing messages through the relocation type +descriptor and the symbol pointer. Therefore, relocations can be performed +on output data using a relocation method that is 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 finding out 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 |