* bfdint.texi: New file.
* Makefile.am (noinst_TEXINFOS): New variable. * Makefile.in: Rebuild.
This commit is contained in:
Ian Lance Taylor
parent
240f5c9faa
commit
c91a48dd42
@ -26,6 +26,7 @@ Things-to-keep:
|
||||
Makefile.am
|
||||
Makefile.in
|
||||
bfd.texinfo
|
||||
bfdint.texi
|
||||
bfdsumm.texi
|
||||
chew.c
|
||||
makefile.vms
|
||||
|
||||
399
bfd/doc/bfdint.texi
Normal file
399
bfd/doc/bfdint.texi
Normal file
@ -0,0 +1,399 @@
|
||||
\input texinfo
|
||||
@setfilename bfdint.info
|
||||
@node Top
|
||||
@top BFD Internals
|
||||
@raisesections
|
||||
@cindex bfd internals
|
||||
|
||||
This document describes some BFD internal information which may be
|
||||
helpful when working on BFD. It is very incomplete.
|
||||
|
||||
This document is not updated regularly, and may be out of date. It was
|
||||
last modified on $Date$.
|
||||
|
||||
The initial version of this document was written by Ian Lance Taylor
|
||||
@email{ian@@cygnus.com}.
|
||||
|
||||
@menu
|
||||
* BFD glossary:: BFD glossary
|
||||
* BFD guidelines:: BFD programming guidelines
|
||||
* BFD generated files:: BFD generated files
|
||||
* BFD multiple compilations:: Files compiled multiple times in BFD
|
||||
* Index:: Index
|
||||
@end menu
|
||||
|
||||
@node BFD glossary
|
||||
@section BFD glossary
|
||||
@cindex glossary for bfd
|
||||
@cindex bfd glossary
|
||||
|
||||
This is a short glossary of some BFD terms.
|
||||
|
||||
@table @asis
|
||||
@item a.out
|
||||
The a.out object file format. The original Unix object file format.
|
||||
Still used on SunOS, though not Solaris. Supports only three sections.
|
||||
|
||||
@item archive
|
||||
A collection of object files produced and manipulated by the @samp{ar}
|
||||
program.
|
||||
|
||||
@item BFD
|
||||
The BFD library itself. Also, each object file, archive, or exectable
|
||||
opened by the BFD library has the type @samp{bfd *}, and is sometimes
|
||||
referred to as a bfd.
|
||||
|
||||
@item COFF
|
||||
The Common Object File Format. Used on Unix SVR3. Used by some
|
||||
embedded targets, although ELF is normally better.
|
||||
|
||||
@item DLL
|
||||
A shared library on Windows.
|
||||
|
||||
@item dynamic linker
|
||||
When a program linked against a shared library is run, the dynamic
|
||||
linker will locate the appropriate shared library and arrange to somehow
|
||||
include it in the running image.
|
||||
|
||||
@item dynamic object
|
||||
Another name for an ELF shared library.
|
||||
|
||||
@item ECOFF
|
||||
The Extended Common Object File Format. Used on Alpha Digital Unix
|
||||
(formerly OSF/1), as well as Ultrix and Irix 4. A variant of COFF.
|
||||
|
||||
@item ELF
|
||||
The Executable and Linking Format. The object file format used on most
|
||||
modern Unix systems, including GNU/Linux, Solaris, Irix, and SVR4. Also
|
||||
used on many embedded systems.
|
||||
|
||||
@item executable
|
||||
A program, with instructions and symbols, and perhaps dynamic linking
|
||||
information. Normally produced by a linker.
|
||||
|
||||
@item NLM
|
||||
NetWare Loadable Module. Used to describe the format of an object which
|
||||
be loaded into NetWare, which is some kind of PC based network server
|
||||
program.
|
||||
|
||||
@item object file
|
||||
A binary file including machine instructions, symbols, and relocation
|
||||
information. Normally produced by an assembler.
|
||||
|
||||
@item object file format
|
||||
The format of an object file. Typically object files and executables
|
||||
for a particular system are in the same format, although executables
|
||||
will not contain any relocation information.
|
||||
|
||||
@item PE
|
||||
The Portable Executable format. This is the object file format used for
|
||||
Windows (specifically, Win32) object files. It is based closely on
|
||||
COFF, but has a few significant differences.
|
||||
|
||||
@item PEI
|
||||
The Portable Executable Image format. This is the object file format
|
||||
used for Windows (specifically, Win32) executables. It is very similar
|
||||
to PE, but includes some additional header information.
|
||||
|
||||
@item relocations
|
||||
Information used by the linker to adjust section contents.
|
||||
|
||||
@item section
|
||||
Object files and executable are composed of sections. Sections have
|
||||
optional data and optional relocation information.
|
||||
|
||||
@item shared library
|
||||
A library of functions which may be used by many executables without
|
||||
actually being linked into each executable. There are several different
|
||||
implementations of shared libraries, each having slightly different
|
||||
features.
|
||||
|
||||
@item symbol
|
||||
Each object file and executable may have a list of symbols, often
|
||||
referred to as the symbol table. A symbol is basically a name and an
|
||||
address. There may also be some additional information like the type of
|
||||
symbol, although the type of a symbol is normally something simple like
|
||||
function or object, and should be confused with the more complex C
|
||||
notion of type. Typically every global function and variable in a C
|
||||
program will have an associated symbol.
|
||||
|
||||
@item Win32
|
||||
The current Windows API, implemented by Windows 95 and later and Windows
|
||||
NT 3.51 and later, but not by Windows 3.1.
|
||||
|
||||
@item XCOFF
|
||||
The eXtended Common Object File Format. Used on AIX. A variant of
|
||||
COFF, with a completely different symbol table implementation.
|
||||
@end table
|
||||
|
||||
@node BFD guidelines
|
||||
@section BFD programming guidelines
|
||||
@cindex bfd programming guidelines
|
||||
@cindex programming guidelines for bfd
|
||||
@cindex guidelines, bfd programming
|
||||
|
||||
There is a lot of poorly written and confusing code in BFD. New BFD
|
||||
code should be written to a higher standard. Merely because some BFD
|
||||
code is written in a particular manner does not mean that you should
|
||||
emulate it.
|
||||
|
||||
Here are some general BFD programming guidelines:
|
||||
|
||||
@itemize @bullet
|
||||
@item
|
||||
Avoid global variables. We ideally want BFD to be fully reentrant, so
|
||||
that it can be used in multiple threads. All uses of global or static
|
||||
variables interfere with that. Initialized constant variables are OK,
|
||||
and they should be explicitly marked with const. Instead of global
|
||||
variables, use data attached to a BFD or to a linker hash table.
|
||||
|
||||
@item
|
||||
All externally visible functions should have names which start with
|
||||
@samp{bfd_}. All such functions should be declared in some header file,
|
||||
typically @file{bfd.h}. See, for example, the various declarations near
|
||||
the end of @file{bfd-in.h}, which mostly declare functions required by
|
||||
specific linker emulations.
|
||||
|
||||
@item
|
||||
All functions which need to be visible from one file to another within
|
||||
BFD, but should not be visible outside of BFD, should start with
|
||||
@samp{_bfd_}. Although external names beginning with @samp{_} are
|
||||
prohibited by the ANSI standard, in practice this usage will always
|
||||
work, and it is required by the GNU coding standards.
|
||||
|
||||
@item
|
||||
Always remember that people can compile using --enable-targets to build
|
||||
several, or all, targets at once. It must be possible to link together
|
||||
the files for all targets.
|
||||
|
||||
@item
|
||||
BFD code should compile with few or no warnings using @samp{gcc -Wall}.
|
||||
Some warnings are OK, like the absence of certain function declarations
|
||||
which may or may not be declared in system header files. Warnings about
|
||||
ambiguous expressions and the like should always be fixed.
|
||||
@end itemize
|
||||
|
||||
@node BFD generated files
|
||||
@section BFD generated files
|
||||
@cindex generated files in bfd
|
||||
@cindex bfd generated files
|
||||
|
||||
BFD contains several automatically generated files. This section
|
||||
describes them. Some files are created at configure time, when you
|
||||
configure BFD. Some files are created at make time, when you build
|
||||
time. Some files are automatically rebuilt at make time, but only if
|
||||
you configure with the @samp{--enable-maintainer-mode} option. Some
|
||||
files live in the object directory---the directory from which you run
|
||||
configure---and some live in the source directory. All files that live
|
||||
in the source directory are checked into the CVS repository.
|
||||
|
||||
@table @file
|
||||
@item bfd.h
|
||||
@cindex @file{bfd.h}
|
||||
@cindex @file{bfd-in3.h}
|
||||
Lives in the object directory. Created at make time from
|
||||
@file{bfd-in2.h} via @file{bfd-in3.h}. @file{bfd-in3.h} is created at
|
||||
configure time from @file{bfd-in2.h}. There are automatic dependencies
|
||||
to rebuild @file{bfd-in3.h} and hence @file{bfd.h} if @file{bfd-in2.h}
|
||||
changes, so you can normally ignore @file{bfd-in3.h}, and just think
|
||||
about @file{bfd-in2.h} and @file{bfd.h}.
|
||||
|
||||
@file{bfd.h} is built by replacing a few strings in @file{bfd-in2.h}.
|
||||
To see them, search for @samp{@@} in @file{bfd-in2.h}. They mainly
|
||||
control whether BFD is built for a 32 bit target or a 64 bit target.
|
||||
|
||||
@item bfd-in2.h
|
||||
@cindex @file{bfd-in2.h}
|
||||
Lives in the source directory. Created from @file{bfd-in.h} and several
|
||||
other BFD source files. If you configure with the
|
||||
@samp{--enable-maintainer-mode} option, @file{bfd-in2.h} is rebuilt
|
||||
automatically when a source file changes.
|
||||
|
||||
@item elf32-target.h
|
||||
@itemx elf64-target.h
|
||||
@cindex @file{elf32-target.h}
|
||||
@cindex @file{elf64-target.h}
|
||||
Live in the object directory. Created from @file{elfxx-target.h}.
|
||||
These files are versions of @file{elfxx-target.h} customized for either
|
||||
a 32 bit ELF target or a 64 bit ELF target.
|
||||
|
||||
@item libbfd.h
|
||||
@cindex @file{libbfd.h}
|
||||
Lives in the source directory. Created from @file{libbfd-in.h} and
|
||||
several other BFD source files. If you configure with the
|
||||
@samp{--enable-maintainer-mode} option, @file{libbfd.h} is rebuilt
|
||||
automatically when a source file changes.
|
||||
|
||||
@item libcoff.h
|
||||
@cindex @file{libcoff.h}
|
||||
Lives in the source directory. Created from @file{libcoff-in.h} and
|
||||
@file{coffcode.h}. If you configure with the
|
||||
@samp{--enable-maintainer-mode} option, @file{libcoff.h} is rebuilt
|
||||
automatically when a source file changes.
|
||||
|
||||
@item targmatch.h
|
||||
@cindex @file{targmatch.h}
|
||||
Lives in the object directory. Created at make time from
|
||||
@file{config.bfd}. This file is used to map configuration triplets into
|
||||
BFD target vector variable names at run time.
|
||||
@end table
|
||||
|
||||
@node BFD multiple compilations
|
||||
@section Files compiled multiple times in BFD
|
||||
Several files in BFD are compiled multiple times. By this I mean that
|
||||
there are header files which contain function definitions. These header
|
||||
filesare included by other files, and thus the functions are compiled
|
||||
once per file which includes them.
|
||||
|
||||
Preprocessor macros are used to control the compilation, so that each
|
||||
time the files are compiled the resulting functions are slightly
|
||||
different. Naturally, if they weren't different, there would be no
|
||||
reason to compile them multiple times.
|
||||
|
||||
This is a not a particularly good programming technique, and future BFD
|
||||
work should avoid it.
|
||||
|
||||
@itemize @bullet
|
||||
@item
|
||||
Since this technique is rarely used, even experienced C programmers find
|
||||
it confusing.
|
||||
|
||||
@item
|
||||
It is difficult to debug programs which use BFD, since there is no way
|
||||
to describe which version of a particular function you are looking at.
|
||||
|
||||
@item
|
||||
Programs which use BFD wind up incorporating two or more slightly
|
||||
different versions of the same function, which wastes space in the
|
||||
executable.
|
||||
|
||||
@item
|
||||
This technique is never required nor is it especially efficient. It is
|
||||
always possible to use statically initialized structures holding
|
||||
function pointers and magic constants instead.
|
||||
@end itemize
|
||||
|
||||
The following a list of the files which are compiled multiple times.
|
||||
|
||||
@table @file
|
||||
@item aout-target.h
|
||||
@cindex @file{aout-target.h}
|
||||
Describes a few functions and the target vector for a.out targets. This
|
||||
is used by individual a.out targets with different definitions of
|
||||
@samp{N_TXTADDR} and similar a.out macros.
|
||||
|
||||
@item aoutf1.h
|
||||
@cindex @file{aoutf1.h}
|
||||
Implements standard SunOS a.out files. In principle it supports 64 bit
|
||||
a.out targets based on the preprocessor macro @samp{ARCH_SIZE}, but
|
||||
since all known a.out targets are 32 bits, this code may or may not
|
||||
work. This file is only included by a few other files, and it is
|
||||
difficult to justify its existence.
|
||||
|
||||
@item aoutx.h
|
||||
@cindex @file{aoutx.h}
|
||||
Implements basic a.out support routines. This file can be compiled for
|
||||
either 32 or 64 bit support. Since all known a.out targets are 32 bits,
|
||||
the 64 bit support may or may not work. I believe the original
|
||||
intention was that this file would only be included by @samp{aout32.c}
|
||||
and @samp{aout64.c}, and that other a.out targets would simply refer to
|
||||
the functions it defined. Unfortunately, some other a.out targets
|
||||
started including it directly, leading to a somewhat confused state of
|
||||
affairs.
|
||||
|
||||
@item coffcode.h
|
||||
@cindex @file{coffcode.h}
|
||||
Implements basic COFF support routines. This file is included by every
|
||||
COFF target. It implements code which handles COFF magic numbers as
|
||||
well as various hook functions called by the generic COFF functions in
|
||||
@file{coffgen.c}. This file is controlled by a number of different
|
||||
macros, and more are added regularly.
|
||||
|
||||
@item coffswap.h
|
||||
@cindex @file{coffswap.h}
|
||||
Implements COFF swapping routines. This file is included by
|
||||
@file{coffcode.h}, and thus by every COFF target. It implements the
|
||||
routines which swap COFF structures between internal and external
|
||||
format. The main control for this file is the external structure
|
||||
definitions in the files in the @file{include/coff} directory. A COFF
|
||||
target file will include one of those files before including
|
||||
@file{coffcode.h} and thus @file{coffswap.h}. There are a few other
|
||||
macros which affect @file{coffswap.h} as well, mostly describing whether
|
||||
certain fields are present in the external structures.
|
||||
|
||||
@item ecoffswap.h
|
||||
@cindex @file{ecoffswap.h}
|
||||
Implements ECOFF swapping routines. This is like @file{coffswap.h}, but
|
||||
for ECOFF. It is included by the ECOFF target files (of which there are
|
||||
only two). The control is the preprocessor macro @samp{ECOFF_32} or
|
||||
@samp{ECOFF_64}.
|
||||
|
||||
@item elfcode.h
|
||||
@cindex @file{elfcode.h}
|
||||
Implements ELF functions that use external structure definitions. This
|
||||
file is included by two other files: @file{elf32.c} and @file{elf64.c}.
|
||||
It is controlled by the @samp{ARCH_SIZE} macro which is defined to be
|
||||
@samp{32} or @samp{64} before including it. The @samp{NAME} macro is
|
||||
used internally to give the functions different names for the two target
|
||||
sizes.
|
||||
|
||||
@item elfcore.h
|
||||
@cindex @file{elfcore.h}
|
||||
Like @file{elfcode.h}, but for functions that are specific to ELF core
|
||||
files. This is included only by @file{elfcode.h}.
|
||||
|
||||
@item elflink.h
|
||||
@cindex @file{elflink.h}
|
||||
Like @file{elfcode.h}, but for functions used by the ELF linker. This
|
||||
is included only by @file{elfcode.h}.
|
||||
|
||||
@item elfxx-target.h
|
||||
@cindex @file{elfxx-target.h}
|
||||
This file is the source for the generated files @file{elf32-target.h}
|
||||
and @file{elf64-target.h}, one of which is included by every ELF target.
|
||||
It defines the ELF target vector.
|
||||
|
||||
@item freebsd.h
|
||||
@cindex @file{freebsd.h}
|
||||
Presumably intended to be included by all FreeBSD targets, but in fact
|
||||
there is only one such target, @samp{i386-freebsd}. This defines a
|
||||
function used to set the right magic number for FreeBSD, as well as
|
||||
various macros, and includes @file{aout-target.h}.
|
||||
|
||||
@item netbsd.h
|
||||
@cindex @file{netbsd.h}
|
||||
Like @file{freebsd.h}, except that there are several files which include
|
||||
it.
|
||||
|
||||
@item nlm-target.h
|
||||
@cindex @file{nlm-target.h}
|
||||
Defines the target vector for a standard NLM target.
|
||||
|
||||
@item nlmcode.h
|
||||
@cindex @file{nlmcode.h}
|
||||
Like @file{elfcode.h}, but for NLM targets. This is only included by
|
||||
@file{nlm32.c} and @file{nlm64.c}, both of which define the macro
|
||||
@samp{ARCH_SIZE} to an appropriate value. There are no 64 bit NLM
|
||||
targets anyhow, so this is sort of useless.
|
||||
|
||||
@item nlmswap.h
|
||||
@cindex @file{nlmswap.h}
|
||||
Like @file{coffswap.h}, but for NLM targets. This is included by each
|
||||
NLM target, but I think it winds up compiling to the exact same code for
|
||||
every target, and as such is fairly useless.
|
||||
|
||||
@item peicode.h
|
||||
@cindex @file{peicode.h}
|
||||
Provides swapping routines and other hooks for PE targets.
|
||||
@file{coffcode.h} will include this rather than @file{coffswap.h} for a
|
||||
PE target. This defines PE specific versions of the COFF swapping
|
||||
routines, and also defines some macros which control @file{coffcode.h}
|
||||
itself.
|
||||
@end table
|
||||
|
||||
@node Index
|
||||
@unnumberedsec Index
|
||||
@printindex cp
|
||||
|
||||
@contents
|
||||
@bye
|
||||
Loading…
Reference in New Issue
Block a user