Tue Apr 28 12:16:57 1998 Jason Molenda ([email protected])

[binutils.git] / bfd / doc / bfdint.texi

\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