Toolchain/binutils-gdb
1
0
Fork 0
forked from Imagelibrary/binutils-gdb
Code Pull Requests Activity

Add generated files.

Browse Source
This commit is contained in:
Phil Blundell
2000-05-29 14:08:54 +00:00
parent b01819b086
commit 8beeaa5b89
82 changed files with 67595 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
Makefile.in
View File

@@ -711,7 +711,6 @@ INSTALL_MODULES = \
install-shellutils \
install-sim \
install-tar \
install-texinfo \
install-textutils \
install-tgas \
install-time \

211
bfd/doc/aoutx.texi Normal file
View File

@@ -0,0 +1,211 @@
@section a.out backends
@strong{Description}@*
BFD supports a number of different flavours of a.out format,
though the major differences are only the sizes of the
structures on disk, and the shape of the relocation
information.
The support is split into a basic support file @file{aoutx.h}
and other files which derive functions from the base. One
derivation file is @file{aoutf1.h} (for a.out flavour 1), and
adds to the basic a.out functions support for sun3, sun4, 386
and 29k a.out files, to create a target jump vector for a
specific target.
This information is further split out into more specific files
for each machine, including @file{sunos.c} for sun3 and sun4,
@file{newsos3.c} for the Sony NEWS, and @file{demo64.c} for a
demonstration of a 64 bit a.out format.
The base file @file{aoutx.h} defines general mechanisms for
reading and writing records to and from disk and various
other methods which BFD requires. It is included by
@file{aout32.c} and @file{aout64.c} to form the names
@code{aout_32_swap_exec_header_in}, @code{aout_64_swap_exec_header_in}, etc.
As an example, this is what goes on to make the back end for a
sun4, from @file{aout32.c}:
@example
#define ARCH_SIZE 32
#include "aoutx.h"
@end example
Which exports names:
@example
...
aout_32_canonicalize_reloc
aout_32_find_nearest_line
aout_32_get_lineno
aout_32_get_reloc_upper_bound
...
@end example
from @file{sunos.c}:
@example
#define TARGET_NAME "a.out-sunos-big"
#define VECNAME sunos_big_vec
#include "aoutf1.h"
@end example
requires all the names from @file{aout32.c}, and produces the jump vector
@example
sunos_big_vec
@end example
The file @file{host-aout.c} is a special case. It is for a large set
of hosts that use ``more or less standard'' a.out files, and
for which cross-debugging is not interesting. It uses the
standard 32-bit a.out support routines, but determines the
file offsets and addresses of the text, data, and BSS
sections, the machine architecture and machine type, and the
entry point address, in a host-dependent manner. Once these
values have been determined, generic code is used to handle
the object file.
When porting it to run on a new system, you must supply:
@example
HOST_PAGE_SIZE
HOST_SEGMENT_SIZE
HOST_MACHINE_ARCH (optional)
HOST_MACHINE_MACHINE (optional)
HOST_TEXT_START_ADDR
HOST_STACK_END_ADDR
@end example
in the file @file{../include/sys/h-@var{XXX}.h} (for your host). These
values, plus the structures and macros defined in @file{a.out.h} on
your host system, will produce a BFD target that will access
ordinary a.out files on your host. To configure a new machine
to use @file{host-aout.c}, specify:
@example
TDEFAULTS = -DDEFAULT_VECTOR=host_aout_big_vec
TDEPFILES= host-aout.o trad-core.o
@end example
in the @file{config/@var{XXX}.mt} file, and modify @file{configure.in}
to use the
@file{@var{XXX}.mt} file (by setting "@code{bfd_target=XXX}") when your
configuration is selected.
@subsection Relocations
@strong{Description}@*
The file @file{aoutx.h} provides for both the @emph{standard}
and @emph{extended} forms of a.out relocation records.
The standard records contain only an
address, a symbol index, and a type field. The extended records
(used on 29ks and sparcs) also have a full integer for an
addend.
@subsection Internal entry points
@strong{Description}@*
@file{aoutx.h} exports several routines for accessing the
contents of an a.out file, which are gathered and exported in
turn by various format specific files (eg sunos.c).
@findex aout_@var{size}_swap_exec_header_in
@subsubsection @code{aout_@var{size}_swap_exec_header_in}
@strong{Synopsis}
@example
void aout_@var{size}_swap_exec_header_in,
(bfd *abfd,
struct external_exec *raw_bytes,
struct internal_exec *execp);
@end example
@strong{Description}@*
Swap the information in an executable header @var{raw_bytes} taken
from a raw byte stream memory image into the internal exec header
structure @var{execp}.
@findex aout_@var{size}_swap_exec_header_out
@subsubsection @code{aout_@var{size}_swap_exec_header_out}
@strong{Synopsis}
@example
void aout_@var{size}_swap_exec_header_out
(bfd *abfd,
struct internal_exec *execp,
struct external_exec *raw_bytes);
@end example
@strong{Description}@*
Swap the information in an internal exec header structure
@var{execp} into the buffer @var{raw_bytes} ready for writing to disk.
@findex aout_@var{size}_some_aout_object_p
@subsubsection @code{aout_@var{size}_some_aout_object_p}
@strong{Synopsis}
@example
const bfd_target *aout_@var{size}_some_aout_object_p
(bfd *abfd,
const bfd_target *(*callback_to_real_object_p)());
@end example
@strong{Description}@*
Some a.out variant thinks that the file open in @var{abfd}
checking is an a.out file. Do some more checking, and set up
for access if it really is. Call back to the calling
environment's "finish up" function just before returning, to
handle any last-minute setup.
@findex aout_@var{size}_mkobject
@subsubsection @code{aout_@var{size}_mkobject}
@strong{Synopsis}
@example
boolean aout_@var{size}_mkobject, (bfd *abfd);
@end example
@strong{Description}@*
Initialize BFD @var{abfd} for use with a.out files.
@findex aout_@var{size}_machine_type
@subsubsection @code{aout_@var{size}_machine_type}
@strong{Synopsis}
@example
enum machine_type aout_@var{size}_machine_type
(enum bfd_architecture arch,
unsigned long machine));
@end example
@strong{Description}@*
Keep track of machine architecture and machine type for
a.out's. Return the @code{machine_type} for a particular
architecture and machine, or @code{M_UNKNOWN} if that exact architecture
and machine can't be represented in a.out format.
If the architecture is understood, machine type 0 (default)
is always understood.
@findex aout_@var{size}_set_arch_mach
@subsubsection @code{aout_@var{size}_set_arch_mach}
@strong{Synopsis}
@example
boolean aout_@var{size}_set_arch_mach,
(bfd *,
enum bfd_architecture arch,
unsigned long machine));
@end example
@strong{Description}@*
Set the architecture and the machine of the BFD @var{abfd} to the
values @var{arch} and @var{machine}. Verify that @var{abfd}'s format
can support the architecture required.
@findex aout_@var{size}_new_section_hook
@subsubsection @code{aout_@var{size}_new_section_hook}
@strong{Synopsis}
@example
boolean aout_@var{size}_new_section_hook,
(bfd *abfd,
asection *newsect));
@end example
@strong{Description}@*
Called by the BFD in response to a @code{bfd_make_section}
request.

95
bfd/doc/archive.texi Normal file
View File

@@ -0,0 +1,95 @@
@section Archives
@strong{Description}@*
An archive (or library) is just another BFD. It has a symbol
table, although there's not much a user program will do with it.
The big difference between an archive BFD and an ordinary BFD
is that the archive doesn't have sections. Instead it has a
chain of BFDs that are considered its contents. These BFDs can
be manipulated like any other. The BFDs contained in an
archive opened for reading will all be opened for reading. You
may put either input or output BFDs into an archive opened for
output; they will be handled correctly when the archive is closed.
Use @code{bfd_openr_next_archived_file} to step through
the contents of an archive opened for input. You don't
have to read the entire archive if you don't want
to! Read it until you find what you want.
Archive contents of output BFDs are chained through the
@code{next} pointer in a BFD. The first one is findable through
the @code{archive_head} slot of the archive. Set it with
@code{bfd_set_archive_head} (q.v.). A given BFD may be in only one
open output archive at a time.
As expected, the BFD archive code is more general than the
archive code of any given environment. BFD archives may
contain files of different formats (e.g., a.out and coff) and
even different architectures. You may even place archives
recursively into archives!
This can cause unexpected confusion, since some archive
formats are more expressive than others. For instance, Intel
COFF archives can preserve long filenames; SunOS a.out archives
cannot. If you move a file from the first to the second
format and back again, the filename may be truncated.
Likewise, different a.out environments have different
conventions as to how they truncate filenames, whether they
preserve directory names in filenames, etc. When
interoperating with native tools, be sure your files are
homogeneous.
Beware: most of these formats do not react well to the
presence of spaces in filenames. We do the best we can, but
can't always handle this case due to restrictions in the format of
archives. Many Unix utilities are braindead in regards to
spaces and such in filenames anyway, so this shouldn't be much
of a restriction.
Archives are supported in BFD in @code{archive.c}.
@findex bfd_get_next_mapent
@subsubsection @code{bfd_get_next_mapent}
@strong{Synopsis}
@example
symindex bfd_get_next_mapent(bfd *abfd, symindex previous, carsym **sym);
@end example
@strong{Description}@*
Step through archive @var{abfd}'s symbol table (if it
has one). Successively update @var{sym} with the next symbol's
information, returning that symbol's (internal) index into the
symbol table.
Supply @code{BFD_NO_MORE_SYMBOLS} as the @var{previous} entry to get
the first one; returns @code{BFD_NO_MORE_SYMBOLS} when you've already
got the last one.
A @code{carsym} is a canonical archive symbol. The only
user-visible element is its name, a null-terminated string.
@findex bfd_set_archive_head
@subsubsection @code{bfd_set_archive_head}
@strong{Synopsis}
@example
boolean bfd_set_archive_head(bfd *output, bfd *new_head);
@end example
@strong{Description}@*
Set the head of the chain of
BFDs contained in the archive @var{output} to @var{new_head}.
@findex bfd_openr_next_archived_file
@subsubsection @code{bfd_openr_next_archived_file}
@strong{Synopsis}
@example
bfd *bfd_openr_next_archived_file(bfd *archive, bfd *previous);
@end example
@strong{Description}@*
Provided a BFD, @var{archive}, containing an archive and NULL, open
an input BFD on the first contained element and returns that.
Subsequent calls should pass
the archive and the previous return value to return a created
BFD to the next contained element. NULL is returned when there
are no more.

409
bfd/doc/archures.texi Normal file
View File

@@ -0,0 +1,409 @@
@section Architectures
BFD keeps one atom in a BFD describing the
architecture of the data attached to the BFD: a pointer to a
@code{bfd_arch_info_type}.
Pointers to structures can be requested independently of a BFD
so that an architecture's information can be interrogated
without access to an open BFD.
The architecture information is provided by each architecture package.
The set of default architectures is selected by the macro
@code{SELECT_ARCHITECTURES}. This is normally set up in the
@file{config/@var{target}.mt} file of your choice. If the name is not
defined, then all the architectures supported are included.
When BFD starts up, all the architectures are called with an
initialize method. It is up to the architecture back end to
insert as many items into the list of architectures as it wants to;
generally this would be one for each machine and one for the
default case (an item with a machine field of 0).
BFD's idea of an architecture is implemented in @file{archures.c}.
@subsection bfd_architecture
@strong{Description}@*
This enum gives the object file's CPU architecture, in a
global sense---i.e., what processor family does it belong to?
Another field indicates which processor within
the family is in use. The machine gives a number which
distinguishes different versions of the architecture,
containing, for example, 2 and 3 for Intel i960 KA and i960 KB,
and 68020 and 68030 for Motorola 68020 and 68030.
@example
enum bfd_architecture
@{
bfd_arch_unknown, /* File arch not known */
bfd_arch_obscure, /* Arch known, not one of these */
bfd_arch_m68k, /* Motorola 68xxx */
#define bfd_mach_m68000 1
#define bfd_mach_m68008 2
#define bfd_mach_m68010 3
#define bfd_mach_m68020 4
#define bfd_mach_m68030 5
#define bfd_mach_m68040 6
#define bfd_mach_m68060 7
#define bfd_mach_cpu32 8
bfd_arch_vax, /* DEC Vax */
bfd_arch_i960, /* Intel 960 */
/* The order of the following is important.
lower number indicates a machine type that
only accepts a subset of the instructions
available to machines with higher numbers.
The exception is the "ca", which is
incompatible with all other machines except
"core". */
#define bfd_mach_i960_core 1
#define bfd_mach_i960_ka_sa 2
#define bfd_mach_i960_kb_sb 3
#define bfd_mach_i960_mc 4
#define bfd_mach_i960_xa 5
#define bfd_mach_i960_ca 6
#define bfd_mach_i960_jx 7
#define bfd_mach_i960_hx 8
bfd_arch_a29k, /* AMD 29000 */
bfd_arch_sparc, /* SPARC */
#define bfd_mach_sparc 1
/* The difference between v8plus and v9 is that v9 is a true 64 bit env. */
#define bfd_mach_sparc_sparclet 2
#define bfd_mach_sparc_sparclite 3
#define bfd_mach_sparc_v8plus 4
#define bfd_mach_sparc_v8plusa 5 /* with ultrasparc add'ns */
#define bfd_mach_sparc_sparclite_le 6
#define bfd_mach_sparc_v9 7
#define bfd_mach_sparc_v9a 8 /* with ultrasparc add'ns */
/* Nonzero if MACH has the v9 instruction set. */
#define bfd_mach_sparc_v9_p(mach) \
((mach) >= bfd_mach_sparc_v8plus && (mach) <= bfd_mach_sparc_v9a)
bfd_arch_mips, /* MIPS Rxxxx */
#define bfd_mach_mips3000 3000
#define bfd_mach_mips3900 3900
#define bfd_mach_mips4000 4000
#define bfd_mach_mips4010 4010
#define bfd_mach_mips4100 4100
#define bfd_mach_mips4111 4111
#define bfd_mach_mips4300 4300
#define bfd_mach_mips4400 4400
#define bfd_mach_mips4600 4600
#define bfd_mach_mips4650 4650
#define bfd_mach_mips5000 5000
#define bfd_mach_mips6000 6000
#define bfd_mach_mips8000 8000
#define bfd_mach_mips10000 10000
#define bfd_mach_mips16 16
bfd_arch_i386, /* Intel 386 */
#define bfd_mach_i386_i386 0
#define bfd_mach_i386_i8086 1
#define bfd_mach_i386_i386_intel_syntax 2
bfd_arch_we32k, /* AT&T WE32xxx */
bfd_arch_tahoe, /* CCI/Harris Tahoe */
bfd_arch_i860, /* Intel 860 */
bfd_arch_i370, /* IBM 360/370 Mainframes */
bfd_arch_romp, /* IBM ROMP PC/RT */
bfd_arch_alliant, /* Alliant */
bfd_arch_convex, /* Convex */
bfd_arch_m88k, /* Motorola 88xxx */
bfd_arch_pyramid, /* Pyramid Technology */
bfd_arch_h8300, /* Hitachi H8/300 */
#define bfd_mach_h8300 1
#define bfd_mach_h8300h 2
#define bfd_mach_h8300s 3
bfd_arch_powerpc, /* PowerPC */
bfd_arch_rs6000, /* IBM RS/6000 */
bfd_arch_hppa, /* HP PA RISC */
bfd_arch_d10v, /* Mitsubishi D10V */
#define bfd_mach_d10v 0
#define bfd_mach_d10v_ts2 2
#define bfd_mach_d10v_ts3 3
bfd_arch_d30v, /* Mitsubishi D30V */
bfd_arch_z8k, /* Zilog Z8000 */
#define bfd_mach_z8001 1
#define bfd_mach_z8002 2
bfd_arch_h8500, /* Hitachi H8/500 */
bfd_arch_sh, /* Hitachi SH */
#define bfd_mach_sh 0
#define bfd_mach_sh2 0x20
#define bfd_mach_sh_dsp 0x2d
#define bfd_mach_sh3 0x30
#define bfd_mach_sh3_dsp 0x3d
#define bfd_mach_sh3e 0x3e
#define bfd_mach_sh4 0x40
bfd_arch_alpha, /* Dec Alpha */
#define bfd_mach_alpha_ev4 0x10
#define bfd_mach_alpha_ev5 0x20
#define bfd_mach_alpha_ev6 0x30
bfd_arch_arm, /* Advanced Risc Machines ARM */
#define bfd_mach_arm_2 1
#define bfd_mach_arm_2a 2
#define bfd_mach_arm_3 3
#define bfd_mach_arm_3M 4
#define bfd_mach_arm_4 5
#define bfd_mach_arm_4T 6
#define bfd_mach_arm_5 7
#define bfd_mach_arm_5T 8
bfd_arch_ns32k, /* National Semiconductors ns32000 */
bfd_arch_w65, /* WDC 65816 */
bfd_arch_tic30, /* Texas Instruments TMS320C30 */
bfd_arch_tic80, /* TI TMS320c80 (MVP) */
bfd_arch_v850, /* NEC V850 */
#define bfd_mach_v850 0
#define bfd_mach_v850e 'E'
#define bfd_mach_v850ea 'A'
bfd_arch_arc, /* Argonaut RISC Core */
#define bfd_mach_arc_base 0
bfd_arch_m32r, /* Mitsubishi M32R/D */
#define bfd_mach_m32r 0 /* backwards compatibility */
#define bfd_mach_m32rx 'x'
bfd_arch_mn10200, /* Matsushita MN10200 */
bfd_arch_mn10300, /* Matsushita MN10300 */
#define bfd_mach_mn10300 300
#define bfd_mach_am33 330
bfd_arch_fr30,
#define bfd_mach_fr30 0x46523330
bfd_arch_mcore,
bfd_arch_pj,
bfd_arch_avr, /* Atmel AVR microcontrollers */
#define bfd_mach_avr1 1
#define bfd_mach_avr2 2
#define bfd_mach_avr3 3
#define bfd_mach_avr4 4
bfd_arch_last
@};
@end example
@subsection bfd_arch_info
@strong{Description}@*
This structure contains information on architectures for use
within BFD.
@example
typedef struct bfd_arch_info
@{
int bits_per_word;
int bits_per_address;
int bits_per_byte;
enum bfd_architecture arch;
unsigned long mach;
const char *arch_name;
const char *printable_name;
unsigned int section_align_power;
/* true if this is the default machine for the architecture */
boolean the_default;
const struct bfd_arch_info * (*compatible)
PARAMS ((const struct bfd_arch_info *a,
const struct bfd_arch_info *b));
boolean (*scan) PARAMS ((const struct bfd_arch_info *, const char *));
const struct bfd_arch_info *next;
@} bfd_arch_info_type;
@end example
@findex bfd_printable_name
@subsubsection @code{bfd_printable_name}
@strong{Synopsis}
@example
const char *bfd_printable_name(bfd *abfd);
@end example
@strong{Description}@*
Return a printable string representing the architecture and machine
from the pointer to the architecture info structure.
@findex bfd_scan_arch
@subsubsection @code{bfd_scan_arch}
@strong{Synopsis}
@example
const bfd_arch_info_type *bfd_scan_arch(const char *string);
@end example
@strong{Description}@*
Figure out if BFD supports any cpu which could be described with
the name @var{string}. Return a pointer to an @code{arch_info}
structure if a machine is found, otherwise NULL.
@findex bfd_arch_list
@subsubsection @code{bfd_arch_list}
@strong{Synopsis}
@example
const char **bfd_arch_list(void);
@end example
@strong{Description}@*
Return a freshly malloced NULL-terminated vector of the names
of all the valid BFD architectures. Do not modify the names.
@findex bfd_arch_get_compatible
@subsubsection @code{bfd_arch_get_compatible}
@strong{Synopsis}
@example
const bfd_arch_info_type *bfd_arch_get_compatible(
const bfd *abfd,
const bfd *bbfd);
@end example
@strong{Description}@*
Determine whether two BFDs'
architectures and machine types are compatible. Calculates
the lowest common denominator between the two architectures
and machine types implied by the BFDs and returns a pointer to
an @code{arch_info} structure describing the compatible machine.
@findex bfd_default_arch_struct
@subsubsection @code{bfd_default_arch_struct}
@strong{Description}@*
The @code{bfd_default_arch_struct} is an item of
@code{bfd_arch_info_type} which has been initialized to a fairly
generic state. A BFD starts life by pointing to this
structure, until the correct back end has determined the real
architecture of the file.
@example
extern const bfd_arch_info_type bfd_default_arch_struct;
@end example
@findex bfd_set_arch_info
@subsubsection @code{bfd_set_arch_info}
@strong{Synopsis}
@example
void bfd_set_arch_info(bfd *abfd, const bfd_arch_info_type *arg);
@end example
@strong{Description}@*
Set the architecture info of @var{abfd} to @var{arg}.
@findex bfd_default_set_arch_mach
@subsubsection @code{bfd_default_set_arch_mach}
@strong{Synopsis}
@example
boolean bfd_default_set_arch_mach(bfd *abfd,
enum bfd_architecture arch,
unsigned long mach);
@end example
@strong{Description}@*
Set the architecture and machine type in BFD @var{abfd}
to @var{arch} and @var{mach}. Find the correct
pointer to a structure and insert it into the @code{arch_info}
pointer.
@findex bfd_get_arch
@subsubsection @code{bfd_get_arch}
@strong{Synopsis}
@example
enum bfd_architecture bfd_get_arch(bfd *abfd);
@end example
@strong{Description}@*
Return the enumerated type which describes the BFD @var{abfd}'s
architecture.
@findex bfd_get_mach
@subsubsection @code{bfd_get_mach}
@strong{Synopsis}
@example
unsigned long bfd_get_mach(bfd *abfd);
@end example
@strong{Description}@*
Return the long type which describes the BFD @var{abfd}'s
machine.
@findex bfd_arch_bits_per_byte
@subsubsection @code{bfd_arch_bits_per_byte}
@strong{Synopsis}
@example
unsigned int bfd_arch_bits_per_byte(bfd *abfd);
@end example
@strong{Description}@*
Return the number of bits in one of the BFD @var{abfd}'s
architecture's bytes.
@findex bfd_arch_bits_per_address
@subsubsection @code{bfd_arch_bits_per_address}
@strong{Synopsis}
@example
unsigned int bfd_arch_bits_per_address(bfd *abfd);
@end example
@strong{Description}@*
Return the number of bits in one of the BFD @var{abfd}'s
architecture's addresses.
@findex bfd_default_compatible
@subsubsection @code{bfd_default_compatible}
@strong{Synopsis}
@example
const bfd_arch_info_type *bfd_default_compatible
(const bfd_arch_info_type *a,
const bfd_arch_info_type *b);
@end example
@strong{Description}@*
The default function for testing for compatibility.
@findex bfd_default_scan
@subsubsection @code{bfd_default_scan}
@strong{Synopsis}
@example
boolean bfd_default_scan(const struct bfd_arch_info *info, const char *string);
@end example
@strong{Description}@*
The default function for working out whether this is an
architecture hit and a machine hit.
@findex bfd_get_arch_info
@subsubsection @code{bfd_get_arch_info}
@strong{Synopsis}
@example
const bfd_arch_info_type * bfd_get_arch_info(bfd *abfd);
@end example
@strong{Description}@*
Return the architecture info struct in @var{abfd}.
@findex bfd_lookup_arch
@subsubsection @code{bfd_lookup_arch}
@strong{Synopsis}
@example
const bfd_arch_info_type *bfd_lookup_arch
(enum bfd_architecture
arch,
unsigned long machine);
@end example
@strong{Description}@*
Look for the architecure info structure which matches the
arguments @var{arch} and @var{machine}. A machine of 0 matches the
machine/architecture structure which marks itself as the
default.
@findex bfd_printable_arch_mach
@subsubsection @code{bfd_printable_arch_mach}
@strong{Synopsis}
@example
const char *bfd_printable_arch_mach
(enum bfd_architecture arch, unsigned long machine);
@end example
@strong{Description}@*
Return a printable string representing the architecture and
machine type.
This routine is depreciated.
@findex bfd_octets_per_byte
@subsubsection @code{bfd_octets_per_byte}
@strong{Synopsis}
@example
unsigned int bfd_octets_per_byte(bfd *abfd);
@end example
@strong{Description}@*
Return the number of octets (8-bit quantities) per target byte
(minimum addressable unit). In most cases, this will be one, but some
DSP targets have 16, 32, or even 48 bits per byte.
@findex bfd_arch_mach_octets_per_byte
@subsubsection @code{bfd_arch_mach_octets_per_byte}
@strong{Synopsis}
@example
unsigned int bfd_arch_mach_octets_per_byte(enum bfd_architecture arch,
unsigned long machine);
@end example
@strong{Description}@*
See bfd_octets_per_byte.
This routine is provided for those cases where a bfd * is not
available

95
bfd/doc/bfd.info Normal file
View File

@@ -0,0 +1,95 @@
This is bfd.info, produced by makeinfo version 4.0 from bfd.texinfo.
START-INFO-DIR-ENTRY
* Bfd: (bfd). The Binary File Descriptor library.
END-INFO-DIR-ENTRY
This file documents the BFD library.
Copyright (C) 1991 Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.
Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, subject to the
terms of the GNU General Public License, which includes the provision
that the entire resulting derived work is distributed under the terms
of a permission notice identical to this one.
Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions.

Indirect:
bfd.info-1: 916
bfd.info-2: 37727
bfd.info-3: 81566
bfd.info-4: 126215
bfd.info-5: 175891
bfd.info-6: 205826
bfd.info-7: 233431

Tag Table:
(Indirect)
Node: Top916
Node: Overview1181
Node: History2231
Node: How It Works3172
Node: What BFD Version 2 Can Do4710
Node: BFD information loss6024
Node: Canonical format8547
Node: BFD front end12908
Node: Memory Usage31825
Node: Initialization33048
Node: Sections33425
Node: Section Input33903
Node: Section Output35259
Node: typedef asection37727
Node: section prototypes53227
Node: Symbols59441
Node: Reading Symbols61031
Node: Writing Symbols62205
Node: Mini Symbols63895
Node: typedef asymbol64860
Node: symbol handling functions70089
Node: Archives74418
Node: Formats78036
Node: Relocations80846
Node: typedef arelent81566
Node: howto manager97725
Node: Core Files123231
Node: Targets124252
Node: bfd_target126215
Node: Architectures145125
Node: Opening and Closing158434
Node: Internal162831
Node: File Caching168829
Node: Linker Functions171607
Node: Creating a Linker Hash Table173273
Node: Adding Symbols to the Hash Table175001
Node: Differing file formats175891
Node: Adding symbols from an object file177624
Node: Adding symbols from an archive179760
Node: Performing the Final Link182159
Node: Information provided by the linker183390
Node: Relocating the section contents184526
Node: Writing the symbol table186263
Node: Hash Tables188857
Node: Creating and Freeing a Hash Table190048
Node: Looking Up or Entering a String191205
Node: Traversing a Hash Table192447
Node: Deriving a New Hash Table Type193225
Node: Define the Derived Structures194280
Node: Write the Derived Creation Routine195346
Node: Write Other Derived Routines198045
Node: BFD back ends199345
Node: What to Put Where199564
Node: aout199702
Node: coff205826
Node: elf232598
Node: Index233431

End Tag Table

1017
bfd/doc/bfd.info-1 Normal file
View File

File diff suppressed because it is too large Load Diff

1187
bfd/doc/bfd.info-2 Normal file
View File

File diff suppressed because it is too large Load Diff

1297
bfd/doc/bfd.info-3 Normal file
View File

File diff suppressed because it is too large Load Diff

1292
bfd/doc/bfd.info-4 Normal file
View File

File diff suppressed because it is too large Load Diff

736
bfd/doc/bfd.info-5 Normal file
View File

@@ -0,0 +1,736 @@
This is bfd.info, produced by makeinfo version 4.0 from bfd.texinfo.
START-INFO-DIR-ENTRY
* Bfd: (bfd). The Binary File Descriptor library.
END-INFO-DIR-ENTRY
This file documents the BFD library.
Copyright (C) 1991 Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.
Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, subject to the
terms of the GNU General Public License, which includes the provision
that the entire resulting derived work is distributed under the terms
of a permission notice identical to this one.
Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions.

File: bfd.info, Node: Differing file formats, Next: Adding symbols from an object file, Prev: Adding Symbols to the Hash Table, Up: Adding Symbols to the Hash Table
Differing file formats
......................
Normally all the files involved in a link will be of the same
format, but it is also possible to link together different format
object files, and the back end must support that. The
`_bfd_link_add_symbols' entry point is called via the target vector of
the file to be added. This has an important consequence: the function
may not assume that the hash table is the type created by the
corresponding `_bfd_link_hash_table_create' vector. All the
`_bfd_link_add_symbols' function can assume about the hash table is
that it is derived from `struct bfd_link_hash_table'.
Sometimes the `_bfd_link_add_symbols' function must store some
information in the hash table entry to be used by the `_bfd_final_link'
function. In such a case the `creator' field of the hash table must be
checked to make sure that the hash table was created by an object file
of the same format.
The `_bfd_final_link' routine must be prepared to handle a hash
entry without any extra information added by the
`_bfd_link_add_symbols' function. A hash entry without extra
information will also occur when the linker script directs the linker
to create a symbol. Note that, regardless of how a hash table entry is
added, all the fields will be initialized to some sort of null value by
the hash table entry initialization function.
See `ecoff_link_add_externals' for an example of how to check the
`creator' field before saving information (in this case, the ECOFF
external symbol debugging information) in a hash table entry.

File: bfd.info, Node: Adding symbols from an object file, Next: Adding symbols from an archive, Prev: Differing file formats, Up: Adding Symbols to the Hash Table
Adding symbols from an object file
..................................
When the `_bfd_link_add_symbols' routine is passed an object file,
it must add all externally visible symbols in that object file to the
hash table. The actual work of adding the symbol to the hash table is
normally handled by the function `_bfd_generic_link_add_one_symbol'.
The `_bfd_link_add_symbols' routine is responsible for reading all the
symbols from the object file and passing the correct information to
`_bfd_generic_link_add_one_symbol'.
The `_bfd_link_add_symbols' routine should not use
`bfd_canonicalize_symtab' to read the symbols. The point of providing
this routine is to avoid the overhead of converting the symbols into
generic `asymbol' structures.
`_bfd_generic_link_add_one_symbol' handles the details of combining
common symbols, warning about multiple definitions, and so forth. It
takes arguments which describe the symbol to add, notably symbol flags,
a section, and an offset. The symbol flags include such things as
`BSF_WEAK' or `BSF_INDIRECT'. The section is a section in the object
file, or something like `bfd_und_section_ptr' for an undefined symbol
or `bfd_com_section_ptr' for a common symbol.
If the `_bfd_final_link' routine is also going to need to read the
symbol information, the `_bfd_link_add_symbols' routine should save it
somewhere attached to the object file BFD. However, the information
should only be saved if the `keep_memory' field of the `info' argument
is true, so that the `-no-keep-memory' linker switch is effective.
The a.out function which adds symbols from an object file is
`aout_link_add_object_symbols', and most of the interesting work is in
`aout_link_add_symbols'. The latter saves pointers to the hash tables
entries created by `_bfd_generic_link_add_one_symbol' indexed by symbol
number, so that the `_bfd_final_link' routine does not have to call the
hash table lookup routine to locate the entry.

File: bfd.info, Node: Adding symbols from an archive, Prev: Adding symbols from an object file, Up: Adding Symbols to the Hash Table
Adding symbols from an archive
..............................
When the `_bfd_link_add_symbols' routine is passed an archive, it
must look through the symbols defined by the archive and decide which
elements of the archive should be included in the link. For each such
element it must call the `add_archive_element' linker callback, and it
must add the symbols from the object file to the linker hash table.
In most cases the work of looking through the symbols in the archive
should be done by the `_bfd_generic_link_add_archive_symbols' function.
This function builds a hash table from the archive symbol table and
looks through the list of undefined symbols to see which elements
should be included. `_bfd_generic_link_add_archive_symbols' is passed
a function to call to make the final decision about adding an archive
element to the link and to do the actual work of adding the symbols to
the linker hash table.
The function passed to `_bfd_generic_link_add_archive_symbols' must
read the symbols of the archive element and decide whether the archive
element should be included in the link. If the element is to be
included, the `add_archive_element' linker callback routine must be
called with the element as an argument, and the elements symbols must
be added to the linker hash table just as though the element had itself
been passed to the `_bfd_link_add_symbols' function.
When the a.out `_bfd_link_add_symbols' function receives an archive,
it calls `_bfd_generic_link_add_archive_symbols' passing
`aout_link_check_archive_element' as the function argument.
`aout_link_check_archive_element' calls `aout_link_check_ar_symbols'.
If the latter decides to add the element (an element is only added if
it provides a real, non-common, definition for a previously undefined
or common symbol) it calls the `add_archive_element' callback and then
`aout_link_check_archive_element' calls `aout_link_add_symbols' to
actually add the symbols to the linker hash table.
The ECOFF back end is unusual in that it does not normally call
`_bfd_generic_link_add_archive_symbols', because ECOFF archives already
contain a hash table of symbols. The ECOFF back end searches the
archive itself to avoid the overhead of creating a new hash table.

File: bfd.info, Node: Performing the Final Link, Prev: Adding Symbols to the Hash Table, Up: Linker Functions
Performing the final link
-------------------------
When all the input files have been processed, the linker calls the
`_bfd_final_link' entry point of the output BFD. This routine is
responsible for producing the final output file, which has several
aspects. It must relocate the contents of the input sections and copy
the data into the output sections. It must build an output symbol
table including any local symbols from the input files and the global
symbols from the hash table. When producing relocateable output, it
must modify the input relocs and write them into the output file.
There may also be object format dependent work to be done.
The linker will also call the `write_object_contents' entry point
when the BFD is closed. The two entry points must work together in
order to produce the correct output file.
The details of how this works are inevitably dependent upon the
specific object file format. The a.out `_bfd_final_link' routine is
`NAME(aout,final_link)'.
* Menu:
* Information provided by the linker::
* Relocating the section contents::
* Writing the symbol table::

File: bfd.info, Node: Information provided by the linker, Next: Relocating the section contents, Prev: Performing the Final Link, Up: Performing the Final Link
Information provided by the linker
..................................
Before the linker calls the `_bfd_final_link' entry point, it sets
up some data structures for the function to use.
The `input_bfds' field of the `bfd_link_info' structure will point
to a list of all the input files included in the link. These files are
linked through the `link_next' field of the `bfd' structure.
Each section in the output file will have a list of `link_order'
structures attached to the `link_order_head' field (the `link_order'
structure is defined in `bfdlink.h'). These structures describe how to
create the contents of the output section in terms of the contents of
various input sections, fill constants, and, eventually, other types of
information. They also describe relocs that must be created by the BFD
backend, but do not correspond to any input file; this is used to
support -Ur, which builds constructors while generating a relocateable
object file.

File: bfd.info, Node: Relocating the section contents, Next: Writing the symbol table, Prev: Information provided by the linker, Up: Performing the Final Link
Relocating the section contents
...............................
The `_bfd_final_link' function should look through the `link_order'
structures attached to each section of the output file. Each
`link_order' structure should either be handled specially, or it should
be passed to the function `_bfd_default_link_order' which will do the
right thing (`_bfd_default_link_order' is defined in `linker.c').
For efficiency, a `link_order' of type `bfd_indirect_link_order'
whose associated section belongs to a BFD of the same format as the
output BFD must be handled specially. This type of `link_order'
describes part of an output section in terms of a section belonging to
one of the input files. The `_bfd_final_link' function should read the
contents of the section and any associated relocs, apply the relocs to
the section contents, and write out the modified section contents. If
performing a relocateable link, the relocs themselves must also be
modified and written out.
The functions `_bfd_relocate_contents' and
`_bfd_final_link_relocate' provide some general support for performing
the actual relocations, notably overflow checking. Their arguments
include information about the symbol the relocation is against and a
`reloc_howto_type' argument which describes the relocation to perform.
These functions are defined in `reloc.c'.
The a.out function which handles reading, relocating, and writing
section contents is `aout_link_input_section'. The actual relocation
is done in `aout_link_input_section_std' and
`aout_link_input_section_ext'.

File: bfd.info, Node: Writing the symbol table, Prev: Relocating the section contents, Up: Performing the Final Link
Writing the symbol table
........................
The `_bfd_final_link' function must gather all the symbols in the
input files and write them out. It must also write out all the symbols
in the global hash table. This must be controlled by the `strip' and
`discard' fields of the `bfd_link_info' structure.
The local symbols of the input files will not have been entered into
the linker hash table. The `_bfd_final_link' routine must consider
each input file and include the symbols in the output file. It may be
convenient to do this when looking through the `link_order' structures,
or it may be done by stepping through the `input_bfds' list.
The `_bfd_final_link' routine must also traverse the global hash
table to gather all the externally visible symbols. It is possible
that most of the externally visible symbols may be written out when
considering the symbols of each input file, but it is still necessary
to traverse the hash table since the linker script may have defined
some symbols that are not in any of the input files.
The `strip' field of the `bfd_link_info' structure controls which
symbols are written out. The possible values are listed in
`bfdlink.h'. If the value is `strip_some', then the `keep_hash' field
of the `bfd_link_info' structure is a hash table of symbols to keep;
each symbol should be looked up in this hash table, and only symbols
which are present should be included in the output file.
If the `strip' field of the `bfd_link_info' structure permits local
symbols to be written out, the `discard' field is used to further
controls which local symbols are included in the output file. If the
value is `discard_l', then all local symbols which begin with a certain
prefix are discarded; this is controlled by the
`bfd_is_local_label_name' entry point.
The a.out backend handles symbols by calling
`aout_link_write_symbols' on each input BFD and then traversing the
global hash table with the function `aout_link_write_other_symbol'. It
builds a string table while writing out the symbols, which is written
to the output file at the end of `NAME(aout,final_link)'.
`bfd_link_split_section'
........................
*Synopsis*
boolean bfd_link_split_section(bfd *abfd, asection *sec);
*Description*
Return nonzero if SEC should be split during a reloceatable or final
link.
#define bfd_link_split_section(abfd, sec) \
BFD_SEND (abfd, _bfd_link_split_section, (abfd, sec))

File: bfd.info, Node: Hash Tables, Prev: Linker Functions, Up: BFD front end
Hash Tables
===========
BFD provides a simple set of hash table functions. Routines are
provided to initialize a hash table, to free a hash table, to look up a
string in a hash table and optionally create an entry for it, and to
traverse a hash table. There is currently no routine to delete an
string from a hash table.
The basic hash table does not permit any data to be stored with a
string. However, a hash table is designed to present a base class from
which other types of hash tables may be derived. These derived types
may store additional information with the string. Hash tables were
implemented in this way, rather than simply providing a data pointer in
a hash table entry, because they were designed for use by the linker
back ends. The linker may create thousands of hash table entries, and
the overhead of allocating private data and storing and following
pointers becomes noticeable.
The basic hash table code is in `hash.c'.
* Menu:
* Creating and Freeing a Hash Table::
* Looking Up or Entering a String::
* Traversing a Hash Table::
* Deriving a New Hash Table Type::

File: bfd.info, Node: Creating and Freeing a Hash Table, Next: Looking Up or Entering a String, Prev: Hash Tables, Up: Hash Tables
Creating and freeing a hash table
---------------------------------
To create a hash table, create an instance of a `struct
bfd_hash_table' (defined in `bfd.h') and call `bfd_hash_table_init' (if
you know approximately how many entries you will need, the function
`bfd_hash_table_init_n', which takes a SIZE argument, may be used).
`bfd_hash_table_init' returns `false' if some sort of error occurs.
The function `bfd_hash_table_init' take as an argument a function to
use to create new entries. For a basic hash table, use the function
`bfd_hash_newfunc'. *Note Deriving a New Hash Table Type::, for why
you would want to use a different value for this argument.
`bfd_hash_table_init' will create an objalloc which will be used to
allocate new entries. You may allocate memory on this objalloc using
`bfd_hash_allocate'.
Use `bfd_hash_table_free' to free up all the memory that has been
allocated for a hash table. This will not free up the `struct
bfd_hash_table' itself, which you must provide.

File: bfd.info, Node: Looking Up or Entering a String, Next: Traversing a Hash Table, Prev: Creating and Freeing a Hash Table, Up: Hash Tables
Looking up or entering a string
-------------------------------
The function `bfd_hash_lookup' is used both to look up a string in
the hash table and to create a new entry.
If the CREATE argument is `false', `bfd_hash_lookup' will look up a
string. If the string is found, it will returns a pointer to a `struct
bfd_hash_entry'. If the string is not found in the table
`bfd_hash_lookup' will return `NULL'. You should not modify any of the
fields in the returns `struct bfd_hash_entry'.
If the CREATE argument is `true', the string will be entered into
the hash table if it is not already there. Either way a pointer to a
`struct bfd_hash_entry' will be returned, either to the existing
structure or to a newly created one. In this case, a `NULL' return
means that an error occurred.
If the CREATE argument is `true', and a new entry is created, the
COPY argument is used to decide whether to copy the string onto the
hash table objalloc or not. If COPY is passed as `false', you must be
careful not to deallocate or modify the string as long as the hash table
exists.

File: bfd.info, Node: Traversing a Hash Table, Next: Deriving a New Hash Table Type, Prev: Looking Up or Entering a String, Up: Hash Tables
Traversing a hash table
-----------------------
The function `bfd_hash_traverse' may be used to traverse a hash
table, calling a function on each element. The traversal is done in a
random order.
`bfd_hash_traverse' takes as arguments a function and a generic
`void *' pointer. The function is called with a hash table entry (a
`struct bfd_hash_entry *') and the generic pointer passed to
`bfd_hash_traverse'. The function must return a `boolean' value, which
indicates whether to continue traversing the hash table. If the
function returns `false', `bfd_hash_traverse' will stop the traversal
and return immediately.

File: bfd.info, Node: Deriving a New Hash Table Type, Prev: Traversing a Hash Table, Up: Hash Tables
Deriving a new hash table type
------------------------------
Many uses of hash tables want to store additional information which
each entry in the hash table. Some also find it convenient to store
additional information with the hash table itself. This may be done
using a derived hash table.
Since C is not an object oriented language, creating a derived hash
table requires sticking together some boilerplate routines with a few
differences specific to the type of hash table you want to create.
An example of a derived hash table is the linker hash table. The
structures for this are defined in `bfdlink.h'. The functions are in
`linker.c'.
You may also derive a hash table from an already derived hash table.
For example, the a.out linker backend code uses a hash table derived
from the linker hash table.
* Menu:
* Define the Derived Structures::
* Write the Derived Creation Routine::
* Write Other Derived Routines::

File: bfd.info, Node: Define the Derived Structures, Next: Write the Derived Creation Routine, Prev: Deriving a New Hash Table Type, Up: Deriving a New Hash Table Type
Define the derived structures
.............................
You must define a structure for an entry in the hash table, and a
structure for the hash table itself.
The first field in the structure for an entry in the hash table must
be of the type used for an entry in the hash table you are deriving
from. If you are deriving from a basic hash table this is `struct
bfd_hash_entry', which is defined in `bfd.h'. The first field in the
structure for the hash table itself must be of the type of the hash
table you are deriving from itself. If you are deriving from a basic
hash table, this is `struct bfd_hash_table'.
For example, the linker hash table defines `struct
bfd_link_hash_entry' (in `bfdlink.h'). The first field, `root', is of
type `struct bfd_hash_entry'. Similarly, the first field in `struct
bfd_link_hash_table', `table', is of type `struct bfd_hash_table'.

File: bfd.info, Node: Write the Derived Creation Routine, Next: Write Other Derived Routines, Prev: Define the Derived Structures, Up: Deriving a New Hash Table Type
Write the derived creation routine
..................................
You must write a routine which will create and initialize an entry
in the hash table. This routine is passed as the function argument to
`bfd_hash_table_init'.
In order to permit other hash tables to be derived from the hash
table you are creating, this routine must be written in a standard way.
The first argument to the creation routine is a pointer to a hash
table entry. This may be `NULL', in which case the routine should
allocate the right amount of space. Otherwise the space has already
been allocated by a hash table type derived from this one.
After allocating space, the creation routine must call the creation
routine of the hash table type it is derived from, passing in a pointer
to the space it just allocated. This will initialize any fields used
by the base hash table.
Finally the creation routine must initialize any local fields for
the new hash table type.
Here is a boilerplate example of a creation routine. FUNCTION_NAME
is the name of the routine. ENTRY_TYPE is the type of an entry in the
hash table you are creating. BASE_NEWFUNC is the name of the creation
routine of the hash table type your hash table is derived from.
struct bfd_hash_entry *
FUNCTION_NAME (entry, table, string)
struct bfd_hash_entry *entry;
struct bfd_hash_table *table;
const char *string;
{
struct ENTRY_TYPE *ret = (ENTRY_TYPE *) entry;
/* Allocate the structure if it has not already been allocated by a
derived class. */
if (ret == (ENTRY_TYPE *) NULL)
{
ret = ((ENTRY_TYPE *)
bfd_hash_allocate (table, sizeof (ENTRY_TYPE)));
if (ret == (ENTRY_TYPE *) NULL)
return NULL;
}
/* Call the allocation method of the base class. */
ret = ((ENTRY_TYPE *)
BASE_NEWFUNC ((struct bfd_hash_entry *) ret, table, string));
/* Initialize the local fields here. */
return (struct bfd_hash_entry *) ret;
}
*Description*
The creation routine for the linker hash table, which is in `linker.c',
looks just like this example. FUNCTION_NAME is
`_bfd_link_hash_newfunc'. ENTRY_TYPE is `struct bfd_link_hash_entry'.
BASE_NEWFUNC is `bfd_hash_newfunc', the creation routine for a basic
hash table.
`_bfd_link_hash_newfunc' also initializes the local fields in a
linker hash table entry: `type', `written' and `next'.

File: bfd.info, Node: Write Other Derived Routines, Prev: Write the Derived Creation Routine, Up: Deriving a New Hash Table Type
Write other derived routines
............................
You will want to write other routines for your new hash table, as
well.
You will want an initialization routine which calls the
initialization routine of the hash table you are deriving from and
initializes any other local fields. For the linker hash table, this is
`_bfd_link_hash_table_init' in `linker.c'.
You will want a lookup routine which calls the lookup routine of the
hash table you are deriving from and casts the result. The linker hash
table uses `bfd_link_hash_lookup' in `linker.c' (this actually takes an
additional argument which it uses to decide how to return the looked up
value).
You may want a traversal routine. This should just call the
traversal routine of the hash table you are deriving from with
appropriate casts. The linker hash table uses `bfd_link_hash_traverse'
in `linker.c'.
These routines may simply be defined as macros. For example, the
a.out backend linker hash table, which is derived from the linker hash
table, uses macros for the lookup and traversal routines. These are
`aout_link_hash_lookup' and `aout_link_hash_traverse' in aoutx.h.

File: bfd.info, Node: BFD back ends, Next: Index, Prev: BFD front end, Up: Top
BFD back ends
*************
* Menu:
* What to Put Where::
* aout :: a.out backends
* coff :: coff backends
* elf :: elf backends

File: bfd.info, Node: What to Put Where, Next: aout, Prev: BFD back ends, Up: BFD back ends
All of BFD lives in one directory.

File: bfd.info, Node: aout, Next: coff, Prev: What to Put Where, Up: BFD back ends
a.out backends
==============
*Description*
BFD supports a number of different flavours of a.out format, though the
major differences are only the sizes of the structures on disk, and the
shape of the relocation information.
The support is split into a basic support file `aoutx.h' and other
files which derive functions from the base. One derivation file is
`aoutf1.h' (for a.out flavour 1), and adds to the basic a.out functions
support for sun3, sun4, 386 and 29k a.out files, to create a target
jump vector for a specific target.
This information is further split out into more specific files for
each machine, including `sunos.c' for sun3 and sun4, `newsos3.c' for
the Sony NEWS, and `demo64.c' for a demonstration of a 64 bit a.out
format.
The base file `aoutx.h' defines general mechanisms for reading and
writing records to and from disk and various other methods which BFD
requires. It is included by `aout32.c' and `aout64.c' to form the names
`aout_32_swap_exec_header_in', `aout_64_swap_exec_header_in', etc.
As an example, this is what goes on to make the back end for a sun4,
from `aout32.c':
#define ARCH_SIZE 32
#include "aoutx.h"
Which exports names:
...
aout_32_canonicalize_reloc
aout_32_find_nearest_line
aout_32_get_lineno
aout_32_get_reloc_upper_bound
...
from `sunos.c':
#define TARGET_NAME "a.out-sunos-big"
#define VECNAME sunos_big_vec
#include "aoutf1.h"
requires all the names from `aout32.c', and produces the jump vector
sunos_big_vec
The file `host-aout.c' is a special case. It is for a large set of
hosts that use "more or less standard" a.out files, and for which
cross-debugging is not interesting. It uses the standard 32-bit a.out
support routines, but determines the file offsets and addresses of the
text, data, and BSS sections, the machine architecture and machine
type, and the entry point address, in a host-dependent manner. Once
these values have been determined, generic code is used to handle the
object file.
When porting it to run on a new system, you must supply:
HOST_PAGE_SIZE
HOST_SEGMENT_SIZE
HOST_MACHINE_ARCH (optional)
HOST_MACHINE_MACHINE (optional)
HOST_TEXT_START_ADDR
HOST_STACK_END_ADDR
in the file `../include/sys/h-XXX.h' (for your host). These values,
plus the structures and macros defined in `a.out.h' on your host
system, will produce a BFD target that will access ordinary a.out files
on your host. To configure a new machine to use `host-aout.c', specify:
TDEFAULTS = -DDEFAULT_VECTOR=host_aout_big_vec
TDEPFILES= host-aout.o trad-core.o
in the `config/XXX.mt' file, and modify `configure.in' to use the
`XXX.mt' file (by setting "`bfd_target=XXX'") when your configuration
is selected.
Relocations
-----------
*Description*
The file `aoutx.h' provides for both the _standard_ and _extended_
forms of a.out relocation records.
The standard records contain only an address, a symbol index, and a
type field. The extended records (used on 29ks and sparcs) also have a
full integer for an addend.
Internal entry points
---------------------
*Description*
`aoutx.h' exports several routines for accessing the contents of an
a.out file, which are gathered and exported in turn by various format
specific files (eg sunos.c).
`aout_SIZE_swap_exec_header_in'
...............................
*Synopsis*
void aout_SIZE_swap_exec_header_in,
(bfd *abfd,
struct external_exec *raw_bytes,
struct internal_exec *execp);
*Description*
Swap the information in an executable header RAW_BYTES taken from a raw
byte stream memory image into the internal exec header structure EXECP.
`aout_SIZE_swap_exec_header_out'
................................
*Synopsis*
void aout_SIZE_swap_exec_header_out
(bfd *abfd,
struct internal_exec *execp,
struct external_exec *raw_bytes);
*Description*
Swap the information in an internal exec header structure EXECP into
the buffer RAW_BYTES ready for writing to disk.
`aout_SIZE_some_aout_object_p'
..............................
*Synopsis*
const bfd_target *aout_SIZE_some_aout_object_p
(bfd *abfd,
const bfd_target *(*callback_to_real_object_p)());
*Description*
Some a.out variant thinks that the file open in ABFD checking is an
a.out file. Do some more checking, and set up for access if it really
is. Call back to the calling environment's "finish up" function just
before returning, to handle any last-minute setup.
`aout_SIZE_mkobject'
....................
*Synopsis*
boolean aout_SIZE_mkobject, (bfd *abfd);
*Description*
Initialize BFD ABFD for use with a.out files.
`aout_SIZE_machine_type'
........................
*Synopsis*
enum machine_type aout_SIZE_machine_type
(enum bfd_architecture arch,
unsigned long machine));
*Description*
Keep track of machine architecture and machine type for a.out's. Return
the `machine_type' for a particular architecture and machine, or
`M_UNKNOWN' if that exact architecture and machine can't be represented
in a.out format.
If the architecture is understood, machine type 0 (default) is
always understood.
`aout_SIZE_set_arch_mach'
.........................
*Synopsis*
boolean aout_SIZE_set_arch_mach,
(bfd *,
enum bfd_architecture arch,
unsigned long machine));
*Description*
Set the architecture and the machine of the BFD ABFD to the values ARCH
and MACHINE. Verify that ABFD's format can support the architecture
required.
`aout_SIZE_new_section_hook'
............................
*Synopsis*
boolean aout_SIZE_new_section_hook,
(bfd *abfd,
asection *newsect));
*Description*
Called by the BFD in response to a `bfd_make_section' request.

683
bfd/doc/bfd.info-6 Normal file
View File

@@ -0,0 +1,683 @@
This is bfd.info, produced by makeinfo version 4.0 from bfd.texinfo.
START-INFO-DIR-ENTRY
* Bfd: (bfd). The Binary File Descriptor library.
END-INFO-DIR-ENTRY
This file documents the BFD library.
Copyright (C) 1991 Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.
Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, subject to the
terms of the GNU General Public License, which includes the provision
that the entire resulting derived work is distributed under the terms
of a permission notice identical to this one.
Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions.

File: bfd.info, Node: coff, Next: elf, Prev: aout, Up: BFD back ends
coff backends
=============
BFD supports a number of different flavours of coff format. The
major differences between formats are the sizes and alignments of
fields in structures on disk, and the occasional extra field.
Coff in all its varieties is implemented with a few common files and
a number of implementation specific files. For example, The 88k bcs
coff format is implemented in the file `coff-m88k.c'. This file
`#include's `coff/m88k.h' which defines the external structure of the
coff format for the 88k, and `coff/internal.h' which defines the
internal structure. `coff-m88k.c' also defines the relocations used by
the 88k format *Note Relocations::.
The Intel i960 processor version of coff is implemented in
`coff-i960.c'. This file has the same structure as `coff-m88k.c',
except that it includes `coff/i960.h' rather than `coff-m88k.h'.
Porting to a new version of coff
--------------------------------
The recommended method is to select from the existing
implementations the version of coff which is most like the one you want
to use. For example, we'll say that i386 coff is the one you select,
and that your coff flavour is called foo. Copy `i386coff.c' to
`foocoff.c', copy `../include/coff/i386.h' to `../include/coff/foo.h',
and add the lines to `targets.c' and `Makefile.in' so that your new
back end is used. Alter the shapes of the structures in
`../include/coff/foo.h' so that they match what you need. You will
probably also have to add `#ifdef's to the code in `coff/internal.h' and
`coffcode.h' if your version of coff is too wild.
You can verify that your new BFD backend works quite simply by
building `objdump' from the `binutils' directory, and making sure that
its version of what's going on and your host system's idea (assuming it
has the pretty standard coff dump utility, usually called `att-dump' or
just `dump') are the same. Then clean up your code, and send what
you've done to Cygnus. Then your stuff will be in the next release, and
you won't have to keep integrating it.
How the coff backend works
--------------------------
File layout
...........
The Coff backend is split into generic routines that are applicable
to any Coff target and routines that are specific to a particular
target. The target-specific routines are further split into ones which
are basically the same for all Coff targets except that they use the
external symbol format or use different values for certain constants.
The generic routines are in `coffgen.c'. These routines work for
any Coff target. They use some hooks into the target specific code;
the hooks are in a `bfd_coff_backend_data' structure, one of which
exists for each target.
The essentially similar target-specific routines are in
`coffcode.h'. This header file includes executable C code. The
various Coff targets first include the appropriate Coff header file,
make any special defines that are needed, and then include `coffcode.h'.
Some of the Coff targets then also have additional routines in the
target source file itself.
For example, `coff-i960.c' includes `coff/internal.h' and
`coff/i960.h'. It then defines a few constants, such as `I960', and
includes `coffcode.h'. Since the i960 has complex relocation types,
`coff-i960.c' also includes some code to manipulate the i960 relocs.
This code is not in `coffcode.h' because it would not be used by any
other target.
Bit twiddling
.............
Each flavour of coff supported in BFD has its own header file
describing the external layout of the structures. There is also an
internal description of the coff layout, in `coff/internal.h'. A major
function of the coff backend is swapping the bytes and twiddling the
bits to translate the external form of the structures into the normal
internal form. This is all performed in the `bfd_swap'_thing_direction
routines. Some elements are different sizes between different versions
of coff; it is the duty of the coff version specific include file to
override the definitions of various packing routines in `coffcode.h'.
E.g., the size of line number entry in coff is sometimes 16 bits, and
sometimes 32 bits. `#define'ing `PUT_LNSZ_LNNO' and `GET_LNSZ_LNNO'
will select the correct one. No doubt, some day someone will find a
version of coff which has a varying field size not catered to at the
moment. To port BFD, that person will have to add more `#defines'.
Three of the bit twiddling routines are exported to `gdb';
`coff_swap_aux_in', `coff_swap_sym_in' and `coff_swap_lineno_in'. `GDB'
reads the symbol table on its own, but uses BFD to fix things up. More
of the bit twiddlers are exported for `gas'; `coff_swap_aux_out',
`coff_swap_sym_out', `coff_swap_lineno_out', `coff_swap_reloc_out',
`coff_swap_filehdr_out', `coff_swap_aouthdr_out',
`coff_swap_scnhdr_out'. `Gas' currently keeps track of all the symbol
table and reloc drudgery itself, thereby saving the internal BFD
overhead, but uses BFD to swap things on the way out, making cross
ports much safer. Doing so also allows BFD (and thus the linker) to
use the same header files as `gas', which makes one avenue to disaster
disappear.
Symbol reading
..............
The simple canonical form for symbols used by BFD is not rich enough
to keep all the information available in a coff symbol table. The back
end gets around this problem by keeping the original symbol table
around, "behind the scenes".
When a symbol table is requested (through a call to
`bfd_canonicalize_symtab'), a request gets through to
`coff_get_normalized_symtab'. This reads the symbol table from the coff
file and swaps all the structures inside into the internal form. It
also fixes up all the pointers in the table (represented in the file by
offsets from the first symbol in the table) into physical pointers to
elements in the new internal table. This involves some work since the
meanings of fields change depending upon context: a field that is a
pointer to another structure in the symbol table at one moment may be
the size in bytes of a structure at the next. Another pass is made
over the table. All symbols which mark file names (`C_FILE' symbols)
are modified so that the internal string points to the value in the
auxent (the real filename) rather than the normal text associated with
the symbol (`".file"').
At this time the symbol names are moved around. Coff stores all
symbols less than nine characters long physically within the symbol
table; longer strings are kept at the end of the file in the string
table. This pass moves all strings into memory and replaces them with
pointers to the strings.
The symbol table is massaged once again, this time to create the
canonical table used by the BFD application. Each symbol is inspected
in turn, and a decision made (using the `sclass' field) about the
various flags to set in the `asymbol'. *Note Symbols::. The generated
canonical table shares strings with the hidden internal symbol table.
Any linenumbers are read from the coff file too, and attached to the
symbols which own the functions the linenumbers belong to.
Symbol writing
..............
Writing a symbol to a coff file which didn't come from a coff file
will lose any debugging information. The `asymbol' structure remembers
the BFD from which the symbol was taken, and on output the back end
makes sure that the same destination target as source target is present.
When the symbols have come from a coff file then all the debugging
information is preserved.
Symbol tables are provided for writing to the back end in a vector
of pointers to pointers. This allows applications like the linker to
accumulate and output large symbol tables without having to do too much
byte copying.
This function runs through the provided symbol table and patches
each symbol marked as a file place holder (`C_FILE') to point to the
next file place holder in the list. It also marks each `offset' field
in the list with the offset from the first symbol of the current symbol.
Another function of this procedure is to turn the canonical value
form of BFD into the form used by coff. Internally, BFD expects symbol
values to be offsets from a section base; so a symbol physically at
0x120, but in a section starting at 0x100, would have the value 0x20.
Coff expects symbols to contain their final value, so symbols have
their values changed at this point to reflect their sum with their
owning section. This transformation uses the `output_section' field of
the `asymbol''s `asection' *Note Sections::.
* `coff_mangle_symbols'
This routine runs though the provided symbol table and uses the
offsets generated by the previous pass and the pointers generated when
the symbol table was read in to create the structured hierachy required
by coff. It changes each pointer to a symbol into the index into the
symbol table of the asymbol.
* `coff_write_symbols'
This routine runs through the symbol table and patches up the
symbols from their internal form into the coff way, calls the bit
twiddlers, and writes out the table to the file.
`coff_symbol_type'
..................
*Description*
The hidden information for an `asymbol' is described in a
`combined_entry_type':
typedef struct coff_ptr_struct
{
/* Remembers the offset from the first symbol in the file for
this symbol. Generated by coff_renumber_symbols. */
unsigned int offset;
/* Should the value of this symbol be renumbered. Used for
XCOFF C_BSTAT symbols. Set by coff_slurp_symbol_table. */
unsigned int fix_value : 1;
/* Should the tag field of this symbol be renumbered.
Created by coff_pointerize_aux. */
unsigned int fix_tag : 1;
/* Should the endidx field of this symbol be renumbered.
Created by coff_pointerize_aux. */
unsigned int fix_end : 1;
/* Should the x_csect.x_scnlen field be renumbered.
Created by coff_pointerize_aux. */
unsigned int fix_scnlen : 1;
/* Fix up an XCOFF C_BINCL/C_EINCL symbol. The value is the
index into the line number entries. Set by
coff_slurp_symbol_table. */
unsigned int fix_line : 1;
/* The container for the symbol structure as read and translated
from the file. */
union {
union internal_auxent auxent;
struct internal_syment syment;
} u;
} combined_entry_type;
/* Each canonical asymbol really looks like this: */
typedef struct coff_symbol_struct
{
/* The actual symbol which the rest of BFD works with */
asymbol symbol;
/* A pointer to the hidden information for this symbol */
combined_entry_type *native;
/* A pointer to the linenumber information for this symbol */
struct lineno_cache_entry *lineno;
/* Have the line numbers been relocated yet ? */
boolean done_lineno;
} coff_symbol_type;
`bfd_coff_backend_data'
.......................
/* COFF symbol classifications. */
enum coff_symbol_classification
{
/* Global symbol. */
COFF_SYMBOL_GLOBAL,
/* Common symbol. */
COFF_SYMBOL_COMMON,
/* Undefined symbol. */
COFF_SYMBOL_UNDEFINED,
/* Local symbol. */
COFF_SYMBOL_LOCAL,
/* PE section symbol. */
COFF_SYMBOL_PE_SECTION
};
Special entry points for gdb to swap in coff symbol table parts:
typedef struct
{
void (*_bfd_coff_swap_aux_in) PARAMS ((
bfd *abfd,
PTR ext,
int type,
int class,
int indaux,
int numaux,
PTR in));
void (*_bfd_coff_swap_sym_in) PARAMS ((
bfd *abfd ,
PTR ext,
PTR in));
void (*_bfd_coff_swap_lineno_in) PARAMS ((
bfd *abfd,
PTR ext,
PTR in));
Special entry points for gas to swap out coff parts:
unsigned int (*_bfd_coff_swap_aux_out) PARAMS ((
bfd *abfd,
PTR in,
int type,
int class,
int indaux,
int numaux,
PTR ext));
unsigned int (*_bfd_coff_swap_sym_out) PARAMS ((
bfd *abfd,
PTR in,
PTR ext));
unsigned int (*_bfd_coff_swap_lineno_out) PARAMS ((
bfd *abfd,
PTR in,
PTR ext));
unsigned int (*_bfd_coff_swap_reloc_out) PARAMS ((
bfd *abfd,
PTR src,
PTR dst));
unsigned int (*_bfd_coff_swap_filehdr_out) PARAMS ((
bfd *abfd,
PTR in,
PTR out));
unsigned int (*_bfd_coff_swap_aouthdr_out) PARAMS ((
bfd *abfd,
PTR in,
PTR out));
unsigned int (*_bfd_coff_swap_scnhdr_out) PARAMS ((
bfd *abfd,
PTR in,
PTR out));
Special entry points for generic COFF routines to call target
dependent COFF routines:
unsigned int _bfd_filhsz;
unsigned int _bfd_aoutsz;
unsigned int _bfd_scnhsz;
unsigned int _bfd_symesz;
unsigned int _bfd_auxesz;
unsigned int _bfd_relsz;
unsigned int _bfd_linesz;
unsigned int _bfd_filnmlen;
boolean _bfd_coff_long_filenames;
boolean _bfd_coff_long_section_names;
unsigned int _bfd_coff_default_section_alignment_power;
void (*_bfd_coff_swap_filehdr_in) PARAMS ((
bfd *abfd,
PTR ext,
PTR in));
void (*_bfd_coff_swap_aouthdr_in) PARAMS ((
bfd *abfd,
PTR ext,
PTR in));
void (*_bfd_coff_swap_scnhdr_in) PARAMS ((
bfd *abfd,
PTR ext,
PTR in));
void (*_bfd_coff_swap_reloc_in) PARAMS ((
bfd *abfd,
PTR ext,
PTR in));
boolean (*_bfd_coff_bad_format_hook) PARAMS ((
bfd *abfd,
PTR internal_filehdr));
boolean (*_bfd_coff_set_arch_mach_hook) PARAMS ((
bfd *abfd,
PTR internal_filehdr));
PTR (*_bfd_coff_mkobject_hook) PARAMS ((
bfd *abfd,
PTR internal_filehdr,
PTR internal_aouthdr));
flagword (*_bfd_styp_to_sec_flags_hook) PARAMS ((
bfd *abfd,
PTR internal_scnhdr,
const char *name,
asection *section));
void (*_bfd_set_alignment_hook) PARAMS ((
bfd *abfd,
asection *sec,
PTR internal_scnhdr));
boolean (*_bfd_coff_slurp_symbol_table) PARAMS ((
bfd *abfd));
boolean (*_bfd_coff_symname_in_debug) PARAMS ((
bfd *abfd,
struct internal_syment *sym));
boolean (*_bfd_coff_pointerize_aux_hook) PARAMS ((
bfd *abfd,
combined_entry_type *table_base,
combined_entry_type *symbol,
unsigned int indaux,
combined_entry_type *aux));
boolean (*_bfd_coff_print_aux) PARAMS ((
bfd *abfd,
FILE *file,
combined_entry_type *table_base,
combined_entry_type *symbol,
combined_entry_type *aux,
unsigned int indaux));
void (*_bfd_coff_reloc16_extra_cases) PARAMS ((
bfd *abfd,
struct bfd_link_info *link_info,
struct bfd_link_order *link_order,
arelent *reloc,
bfd_byte *data,
unsigned int *src_ptr,
unsigned int *dst_ptr));
int (*_bfd_coff_reloc16_estimate) PARAMS ((
bfd *abfd,
asection *input_section,
arelent *r,
unsigned int shrink,
struct bfd_link_info *link_info));
enum coff_symbol_classification (*_bfd_coff_classify_symbol) PARAMS ((
bfd *abfd,
struct internal_syment *));
boolean (*_bfd_coff_compute_section_file_positions) PARAMS ((
bfd *abfd));
boolean (*_bfd_coff_start_final_link) PARAMS ((
bfd *output_bfd,
struct bfd_link_info *info));
boolean (*_bfd_coff_relocate_section) PARAMS ((
bfd *output_bfd,
struct bfd_link_info *info,
bfd *input_bfd,
asection *input_section,
bfd_byte *contents,
struct internal_reloc *relocs,
struct internal_syment *syms,
asection **sections));
reloc_howto_type *(*_bfd_coff_rtype_to_howto) PARAMS ((
bfd *abfd,
asection *sec,
struct internal_reloc *rel,
struct coff_link_hash_entry *h,
struct internal_syment *sym,
bfd_vma *addendp));
boolean (*_bfd_coff_adjust_symndx) PARAMS ((
bfd *obfd,
struct bfd_link_info *info,
bfd *ibfd,
asection *sec,
struct internal_reloc *reloc,
boolean *adjustedp));
boolean (*_bfd_coff_link_add_one_symbol) PARAMS ((
struct bfd_link_info *info,
bfd *abfd,
const char *name,
flagword flags,
asection *section,
bfd_vma value,
const char *string,
boolean copy,
boolean collect,
struct bfd_link_hash_entry **hashp));
boolean (*_bfd_coff_link_output_has_begun) PARAMS ((
bfd * abfd,
struct coff_final_link_info * pfinfo));
boolean (*_bfd_coff_final_link_postscript) PARAMS ((
bfd * abfd,
struct coff_final_link_info * pfinfo));
} bfd_coff_backend_data;
#define coff_backend_info(abfd) ((bfd_coff_backend_data *) (abfd)->xvec->backend_data)
#define bfd_coff_swap_aux_in(a,e,t,c,ind,num,i) \
((coff_backend_info (a)->_bfd_coff_swap_aux_in) (a,e,t,c,ind,num,i))
#define bfd_coff_swap_sym_in(a,e,i) \
((coff_backend_info (a)->_bfd_coff_swap_sym_in) (a,e,i))
#define bfd_coff_swap_lineno_in(a,e,i) \
((coff_backend_info ( a)->_bfd_coff_swap_lineno_in) (a,e,i))
#define bfd_coff_swap_reloc_out(abfd, i, o) \
((coff_backend_info (abfd)->_bfd_coff_swap_reloc_out) (abfd, i, o))
#define bfd_coff_swap_lineno_out(abfd, i, o) \
((coff_backend_info (abfd)->_bfd_coff_swap_lineno_out) (abfd, i, o))
#define bfd_coff_swap_aux_out(a,i,t,c,ind,num,o) \
((coff_backend_info (a)->_bfd_coff_swap_aux_out) (a,i,t,c,ind,num,o))
#define bfd_coff_swap_sym_out(abfd, i,o) \
((coff_backend_info (abfd)->_bfd_coff_swap_sym_out) (abfd, i, o))
#define bfd_coff_swap_scnhdr_out(abfd, i,o) \
((coff_backend_info (abfd)->_bfd_coff_swap_scnhdr_out) (abfd, i, o))
#define bfd_coff_swap_filehdr_out(abfd, i,o) \
((coff_backend_info (abfd)->_bfd_coff_swap_filehdr_out) (abfd, i, o))
#define bfd_coff_swap_aouthdr_out(abfd, i,o) \
((coff_backend_info (abfd)->_bfd_coff_swap_aouthdr_out) (abfd, i, o))
#define bfd_coff_filhsz(abfd) (coff_backend_info (abfd)->_bfd_filhsz)
#define bfd_coff_aoutsz(abfd) (coff_backend_info (abfd)->_bfd_aoutsz)
#define bfd_coff_scnhsz(abfd) (coff_backend_info (abfd)->_bfd_scnhsz)
#define bfd_coff_symesz(abfd) (coff_backend_info (abfd)->_bfd_symesz)
#define bfd_coff_auxesz(abfd) (coff_backend_info (abfd)->_bfd_auxesz)
#define bfd_coff_relsz(abfd) (coff_backend_info (abfd)->_bfd_relsz)
#define bfd_coff_linesz(abfd) (coff_backend_info (abfd)->_bfd_linesz)
#define bfd_coff_filnmlen(abfd) (coff_backend_info (abfd)->_bfd_filnmlen)
#define bfd_coff_long_filenames(abfd) (coff_backend_info (abfd)->_bfd_coff_long_filenames)
#define bfd_coff_long_section_names(abfd) \
(coff_backend_info (abfd)->_bfd_coff_long_section_names)
#define bfd_coff_default_section_alignment_power(abfd) \
(coff_backend_info (abfd)->_bfd_coff_default_section_alignment_power)
#define bfd_coff_swap_filehdr_in(abfd, i,o) \
((coff_backend_info (abfd)->_bfd_coff_swap_filehdr_in) (abfd, i, o))
#define bfd_coff_swap_aouthdr_in(abfd, i,o) \
((coff_backend_info (abfd)->_bfd_coff_swap_aouthdr_in) (abfd, i, o))
#define bfd_coff_swap_scnhdr_in(abfd, i,o) \
((coff_backend_info (abfd)->_bfd_coff_swap_scnhdr_in) (abfd, i, o))
#define bfd_coff_swap_reloc_in(abfd, i, o) \
((coff_backend_info (abfd)->_bfd_coff_swap_reloc_in) (abfd, i, o))
#define bfd_coff_bad_format_hook(abfd, filehdr) \
((coff_backend_info (abfd)->_bfd_coff_bad_format_hook) (abfd, filehdr))
#define bfd_coff_set_arch_mach_hook(abfd, filehdr)\
((coff_backend_info (abfd)->_bfd_coff_set_arch_mach_hook) (abfd, filehdr))
#define bfd_coff_mkobject_hook(abfd, filehdr, aouthdr)\
((coff_backend_info (abfd)->_bfd_coff_mkobject_hook) (abfd, filehdr, aouthdr))
#define bfd_coff_styp_to_sec_flags_hook(abfd, scnhdr, name, section)\
((coff_backend_info (abfd)->_bfd_styp_to_sec_flags_hook)\
(abfd, scnhdr, name, section))
#define bfd_coff_set_alignment_hook(abfd, sec, scnhdr)\
((coff_backend_info (abfd)->_bfd_set_alignment_hook) (abfd, sec, scnhdr))
#define bfd_coff_slurp_symbol_table(abfd)\
((coff_backend_info (abfd)->_bfd_coff_slurp_symbol_table) (abfd))
#define bfd_coff_symname_in_debug(abfd, sym)\
((coff_backend_info (abfd)->_bfd_coff_symname_in_debug) (abfd, sym))
#define bfd_coff_print_aux(abfd, file, base, symbol, aux, indaux)\
((coff_backend_info (abfd)->_bfd_coff_print_aux)\
(abfd, file, base, symbol, aux, indaux))
#define bfd_coff_reloc16_extra_cases(abfd, link_info, link_order, reloc, data, src_ptr, dst_ptr)\
((coff_backend_info (abfd)->_bfd_coff_reloc16_extra_cases)\
(abfd, link_info, link_order, reloc, data, src_ptr, dst_ptr))
#define bfd_coff_reloc16_estimate(abfd, section, reloc, shrink, link_info)\
((coff_backend_info (abfd)->_bfd_coff_reloc16_estimate)\
(abfd, section, reloc, shrink, link_info))
#define bfd_coff_classify_symbol(abfd, sym)\
((coff_backend_info (abfd)->_bfd_coff_classify_symbol)\
(abfd, sym))
#define bfd_coff_compute_section_file_positions(abfd)\
((coff_backend_info (abfd)->_bfd_coff_compute_section_file_positions)\
(abfd))
#define bfd_coff_start_final_link(obfd, info)\
((coff_backend_info (obfd)->_bfd_coff_start_final_link)\
(obfd, info))
#define bfd_coff_relocate_section(obfd,info,ibfd,o,con,rel,isyms,secs)\
((coff_backend_info (ibfd)->_bfd_coff_relocate_section)\
(obfd, info, ibfd, o, con, rel, isyms, secs))
#define bfd_coff_rtype_to_howto(abfd, sec, rel, h, sym, addendp)\
((coff_backend_info (abfd)->_bfd_coff_rtype_to_howto)\
(abfd, sec, rel, h, sym, addendp))
#define bfd_coff_adjust_symndx(obfd, info, ibfd, sec, rel, adjustedp)\
((coff_backend_info (abfd)->_bfd_coff_adjust_symndx)\
(obfd, info, ibfd, sec, rel, adjustedp))
#define bfd_coff_link_add_one_symbol(info,abfd,name,flags,section,value,string,cp,coll,hashp)\
((coff_backend_info (abfd)->_bfd_coff_link_add_one_symbol)\
(info, abfd, name, flags, section, value, string, cp, coll, hashp))
#define bfd_coff_link_output_has_begun(a,p) \
((coff_backend_info (a)->_bfd_coff_link_output_has_begun) (a,p))
#define bfd_coff_final_link_postscript(a,p) \
((coff_backend_info (a)->_bfd_coff_final_link_postscript) (a,p))
Writing relocations
...................
To write relocations, the back end steps though the canonical
relocation table and create an `internal_reloc'. The symbol index to
use is removed from the `offset' field in the symbol table supplied.
The address comes directly from the sum of the section base address and
the relocation offset; the type is dug directly from the howto field.
Then the `internal_reloc' is swapped into the shape of an
`external_reloc' and written out to disk.
Reading linenumbers
...................
Creating the linenumber table is done by reading in the entire coff
linenumber table, and creating another table for internal use.
A coff linenumber table is structured so that each function is
marked as having a line number of 0. Each line within the function is
an offset from the first line in the function. The base of the line
number information for the table is stored in the symbol associated
with the function.
Note: The PE format uses line number 0 for a flag indicating a new
source file.
The information is copied from the external to the internal table,
and each symbol which marks a function is marked by pointing its...
How does this work ?
Reading relocations
...................
Coff relocations are easily transformed into the internal BFD form
(`arelent').
Reading a coff relocation table is done in the following stages:
* Read the entire coff relocation table into memory.
* Process each relocation in turn; first swap it from the external
to the internal form.
* Turn the symbol referenced in the relocation's symbol index into a
pointer into the canonical symbol table. This table is the same
as the one returned by a call to `bfd_canonicalize_symtab'. The
back end will call that routine and save the result if a
canonicalization hasn't been done.
* The reloc index is turned into a pointer to a howto structure, in
a back end specific way. For instance, the 386 and 960 use the
`r_type' to directly produce an index into a howto table vector;
the 88k subtracts a number from the `r_type' field and creates an
addend field.

File: bfd.info, Node: elf, Prev: coff, Up: BFD back ends
ELF backends
============
BFD support for ELF formats is being worked on. Currently, the best
supported back ends are for sparc and i386 (running svr4 or Solaris 2).
Documentation of the internals of the support code still needs to be
written. The code is changing quickly enough that we haven't bothered
yet.
`bfd_elf_find_section'
......................
*Synopsis*
struct elf_internal_shdr *bfd_elf_find_section (bfd *abfd, char *name);
*Description*
Helper functions for GDB to locate the string tables. Since BFD hides
string tables from callers, GDB needs to use an internal hook to find
them. Sun's .stabstr, in particular, isn't even pointed to by the
.stab section, so ordinary mechanisms wouldn't work to find it, even if
we had some.

491
bfd/doc/bfd.info-7 Normal file
View File

@@ -0,0 +1,491 @@
This is bfd.info, produced by makeinfo version 4.0 from bfd.texinfo.
START-INFO-DIR-ENTRY
* Bfd: (bfd). The Binary File Descriptor library.
END-INFO-DIR-ENTRY
This file documents the BFD library.
Copyright (C) 1991 Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.
Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, subject to the
terms of the GNU General Public License, which includes the provision
that the entire resulting derived work is distributed under the terms
of a permission notice identical to this one.
Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions.

File: bfd.info, Node: Index, Prev: BFD back ends, Up: Top
Index
*****
* Menu:
* _bfd_final_link_relocate: Relocating the section contents.
* _bfd_generic_link_add_archive_symbols: Adding symbols from an archive.
* _bfd_generic_link_add_one_symbol: Adding symbols from an object file.
* _bfd_link_add_symbols in target vector: Adding Symbols to the Hash Table.
* _bfd_link_final_link in target vector: Performing the Final Link.
* _bfd_link_hash_table_create in target vector: Creating a Linker Hash Table.
* _bfd_relocate_contents: Relocating the section contents.
* _bfd_strip_section_from_output: section prototypes.
* aout_SIZE_machine_type: aout.
* aout_SIZE_mkobject: aout.
* aout_SIZE_new_section_hook: aout.
* aout_SIZE_set_arch_mach: aout.
* aout_SIZE_some_aout_object_p: aout.
* aout_SIZE_swap_exec_header_in: aout.
* aout_SIZE_swap_exec_header_out: aout.
* arelent_chain: typedef arelent.
* BFD: Overview.
* BFD canonical format: Canonical format.
* bfd_alloc: Opening and Closing.
* bfd_arch_bits_per_address: Architectures.
* bfd_arch_bits_per_byte: Architectures.
* bfd_arch_get_compatible: Architectures.
* bfd_arch_list: Architectures.
* bfd_arch_mach_octets_per_byte: Architectures.
* bfd_cache_close: File Caching.
* bfd_cache_init: File Caching.
* bfd_cache_lookup: File Caching.
* bfd_cache_lookup_worker: File Caching.
* BFD_CACHE_MAX_OPEN macro: File Caching.
* bfd_canonicalize_reloc: BFD front end.
* bfd_canonicalize_symtab: symbol handling functions.
* bfd_check_format: Formats.
* bfd_check_format_matches: Formats.
* bfd_check_overflow: typedef arelent.
* bfd_close: Opening and Closing.
* bfd_close_all_done: Opening and Closing.
* bfd_coff_backend_data: coff.
* bfd_copy_private_bfd_data: BFD front end.
* bfd_copy_private_section_data: section prototypes.
* bfd_copy_private_symbol_data: symbol handling functions.
* bfd_core_file_failing_command: Core Files.
* bfd_core_file_failing_signal: Core Files.
* bfd_create: Opening and Closing.
* bfd_decode_symclass: symbol handling functions.
* bfd_default_arch_struct: Architectures.
* bfd_default_compatible: Architectures.
* bfd_default_reloc_type_lookup: howto manager.
* bfd_default_scan: Architectures.
* bfd_default_set_arch_mach: Architectures.
* bfd_elf_find_section: elf.
* bfd_errmsg: BFD front end.
* bfd_fdopenr: Opening and Closing.
* bfd_find_target: bfd_target.
* bfd_format_string: Formats.
* bfd_generic_gc_sections: howto manager.
* bfd_generic_get_relocated_section_contents: howto manager.
* bfd_generic_relax_section: howto manager.
* bfd_get_arch: Architectures.
* bfd_get_arch_info: Architectures.
* bfd_get_error: BFD front end.
* bfd_get_error_handler: BFD front end.
* bfd_get_gp_size: BFD front end.
* bfd_get_mach: Architectures.
* bfd_get_mtime: BFD front end.
* bfd_get_next_mapent: Archives.
* bfd_get_reloc_code_name: howto manager.
* bfd_get_reloc_size: typedef arelent.
* bfd_get_reloc_upper_bound: BFD front end.
* bfd_get_section_by_name: section prototypes.
* bfd_get_section_contents: section prototypes.
* bfd_get_size <1>: Internal.
* bfd_get_size: BFD front end.
* bfd_get_symtab_upper_bound: symbol handling functions.
* bfd_h_put_size: Internal.
* bfd_hash_allocate: Creating and Freeing a Hash Table.
* bfd_hash_lookup: Looking Up or Entering a String.
* bfd_hash_newfunc: Creating and Freeing a Hash Table.
* bfd_hash_table_free: Creating and Freeing a Hash Table.
* bfd_hash_table_init: Creating and Freeing a Hash Table.
* bfd_hash_table_init_n: Creating and Freeing a Hash Table.
* bfd_hash_traverse: Traversing a Hash Table.
* bfd_init: Initialization.
* bfd_install_relocation: typedef arelent.
* bfd_is_local_label: symbol handling functions.
* bfd_is_local_label_name: symbol handling functions.
* bfd_is_undefined_symclass: symbol handling functions.
* bfd_last_cache: File Caching.
* bfd_link_split_section: Writing the symbol table.
* bfd_log2: Internal.
* bfd_lookup_arch: Architectures.
* bfd_make_debug_symbol: symbol handling functions.
* bfd_make_empty_symbol: symbol handling functions.
* bfd_make_readable: Opening and Closing.
* bfd_make_section: section prototypes.
* bfd_make_section_anyway: section prototypes.
* bfd_make_section_old_way: section prototypes.
* bfd_make_writable: Opening and Closing.
* bfd_map_over_sections: section prototypes.
* bfd_merge_private_bfd_data: BFD front end.
* bfd_octets_per_byte: Architectures.
* bfd_open_file: File Caching.
* bfd_openr: Opening and Closing.
* bfd_openr_next_archived_file: Archives.
* bfd_openstreamr: Opening and Closing.
* bfd_openw: Opening and Closing.
* bfd_perform_relocation: typedef arelent.
* bfd_perror: BFD front end.
* bfd_print_symbol_vandf: symbol handling functions.
* bfd_printable_arch_mach: Architectures.
* bfd_printable_name: Architectures.
* bfd_put_size: Internal.
* BFD_RELOC_12_PCREL: howto manager.
* BFD_RELOC_14: howto manager.
* BFD_RELOC_16: howto manager.
* BFD_RELOC_16_BASEREL: howto manager.
* BFD_RELOC_16_GOT_PCREL: howto manager.
* BFD_RELOC_16_GOTOFF: howto manager.
* BFD_RELOC_16_PCREL: howto manager.
* BFD_RELOC_16_PCREL_S2: howto manager.
* BFD_RELOC_16_PLT_PCREL: howto manager.
* BFD_RELOC_16_PLTOFF: howto manager.
* BFD_RELOC_23_PCREL_S2: howto manager.
* BFD_RELOC_24: howto manager.
* BFD_RELOC_24_PCREL: howto manager.
* BFD_RELOC_24_PLT_PCREL: howto manager.
* BFD_RELOC_26: howto manager.
* BFD_RELOC_32: howto manager.
* BFD_RELOC_32_BASEREL: howto manager.
* BFD_RELOC_32_GOT_PCREL: howto manager.
* BFD_RELOC_32_GOTOFF: howto manager.
* BFD_RELOC_32_PCREL: howto manager.
* BFD_RELOC_32_PCREL_S2: howto manager.
* BFD_RELOC_32_PLT_PCREL: howto manager.
* BFD_RELOC_32_PLTOFF: howto manager.
* BFD_RELOC_386_COPY: howto manager.
* BFD_RELOC_386_GLOB_DAT: howto manager.
* BFD_RELOC_386_GOT32: howto manager.
* BFD_RELOC_386_GOTOFF: howto manager.
* BFD_RELOC_386_GOTPC: howto manager.
* BFD_RELOC_386_JUMP_SLOT: howto manager.
* BFD_RELOC_386_PLT32: howto manager.
* BFD_RELOC_386_RELATIVE: howto manager.
* BFD_RELOC_64: howto manager.
* BFD_RELOC_64_PCREL: howto manager.
* BFD_RELOC_68K_GLOB_DAT: howto manager.
* BFD_RELOC_68K_JMP_SLOT: howto manager.
* BFD_RELOC_68K_RELATIVE: howto manager.
* BFD_RELOC_8: howto manager.
* BFD_RELOC_8_BASEREL: howto manager.
* BFD_RELOC_8_FFnn: howto manager.
* BFD_RELOC_8_GOT_PCREL: howto manager.
* BFD_RELOC_8_GOTOFF: howto manager.
* BFD_RELOC_8_PCREL: howto manager.
* BFD_RELOC_8_PLT_PCREL: howto manager.
* BFD_RELOC_8_PLTOFF: howto manager.
* BFD_RELOC_ALPHA_CODEADDR: howto manager.
* BFD_RELOC_ALPHA_ELF_LITERAL: howto manager.
* BFD_RELOC_ALPHA_GPDISP: howto manager.
* BFD_RELOC_ALPHA_GPDISP_HI16: howto manager.
* BFD_RELOC_ALPHA_GPDISP_LO16: howto manager.
* BFD_RELOC_ALPHA_HINT: howto manager.
* BFD_RELOC_ALPHA_LINKAGE: howto manager.
* BFD_RELOC_ALPHA_LITERAL: howto manager.
* BFD_RELOC_ALPHA_LITUSE: howto manager.
* BFD_RELOC_ALPHA_USER_GPDISP: howto manager.
* BFD_RELOC_ALPHA_USER_GPRELHIGH: howto manager.
* BFD_RELOC_ALPHA_USER_GPRELLOW: howto manager.
* BFD_RELOC_ALPHA_USER_LITERAL: howto manager.
* BFD_RELOC_ALPHA_USER_LITUSE_BASE: howto manager.
* BFD_RELOC_ALPHA_USER_LITUSE_BYTOFF: howto manager.
* BFD_RELOC_ALPHA_USER_LITUSE_JSR: howto manager.
* BFD_RELOC_ARC_B22_PCREL: howto manager.
* BFD_RELOC_ARC_B26: howto manager.
* BFD_RELOC_ARM_ADR_IMM: howto manager.
* BFD_RELOC_ARM_ADRL_IMMEDIATE: howto manager.
* BFD_RELOC_ARM_COPY: howto manager.
* BFD_RELOC_ARM_CP_OFF_IMM: howto manager.
* BFD_RELOC_ARM_GLOB_DAT: howto manager.
* BFD_RELOC_ARM_GOT12: howto manager.
* BFD_RELOC_ARM_GOT32: howto manager.
* BFD_RELOC_ARM_GOTOFF: howto manager.
* BFD_RELOC_ARM_GOTPC: howto manager.
* BFD_RELOC_ARM_HWLITERAL: howto manager.
* BFD_RELOC_ARM_IMMEDIATE: howto manager.
* BFD_RELOC_ARM_IN_POOL: howto manager.
* BFD_RELOC_ARM_JUMP_SLOT: howto manager.
* BFD_RELOC_ARM_LDR_IMM: howto manager.
* BFD_RELOC_ARM_LITERAL: howto manager.
* BFD_RELOC_ARM_MULTI: howto manager.
* BFD_RELOC_ARM_OFFSET_IMM: howto manager.
* BFD_RELOC_ARM_OFFSET_IMM8: howto manager.
* BFD_RELOC_ARM_PCREL_BRANCH: howto manager.
* BFD_RELOC_ARM_PLT32: howto manager.
* BFD_RELOC_ARM_RELATIVE: howto manager.
* BFD_RELOC_ARM_SHIFT_IMM: howto manager.
* BFD_RELOC_ARM_SWI: howto manager.
* BFD_RELOC_ARM_THUMB_ADD: howto manager.
* BFD_RELOC_ARM_THUMB_IMM: howto manager.
* BFD_RELOC_ARM_THUMB_OFFSET: howto manager.
* BFD_RELOC_ARM_THUMB_SHIFT: howto manager.
* BFD_RELOC_AVR_13_PCREL: howto manager.
* BFD_RELOC_AVR_16_PM: howto manager.
* BFD_RELOC_AVR_7_PCREL: howto manager.
* BFD_RELOC_AVR_CALL: howto manager.
* BFD_RELOC_AVR_HH8_LDI: howto manager.
* BFD_RELOC_AVR_HH8_LDI_NEG: howto manager.
* BFD_RELOC_AVR_HH8_LDI_PM: howto manager.
* BFD_RELOC_AVR_HH8_LDI_PM_NEG: howto manager.
* BFD_RELOC_AVR_HI8_LDI: howto manager.
* BFD_RELOC_AVR_HI8_LDI_NEG: howto manager.
* BFD_RELOC_AVR_HI8_LDI_PM: howto manager.
* BFD_RELOC_AVR_HI8_LDI_PM_NEG: howto manager.
* BFD_RELOC_AVR_LO8_LDI: howto manager.
* BFD_RELOC_AVR_LO8_LDI_NEG: howto manager.
* BFD_RELOC_AVR_LO8_LDI_PM: howto manager.
* BFD_RELOC_AVR_LO8_LDI_PM_NEG: howto manager.
* bfd_reloc_code_type: howto manager.
* BFD_RELOC_CTOR: howto manager.
* BFD_RELOC_D10V_10_PCREL_L: howto manager.
* BFD_RELOC_D10V_10_PCREL_R: howto manager.
* BFD_RELOC_D10V_18: howto manager.
* BFD_RELOC_D10V_18_PCREL: howto manager.
* BFD_RELOC_D30V_15: howto manager.
* BFD_RELOC_D30V_15_PCREL: howto manager.
* BFD_RELOC_D30V_15_PCREL_R: howto manager.
* BFD_RELOC_D30V_21: howto manager.
* BFD_RELOC_D30V_21_PCREL: howto manager.
* BFD_RELOC_D30V_21_PCREL_R: howto manager.
* BFD_RELOC_D30V_32: howto manager.
* BFD_RELOC_D30V_32_PCREL: howto manager.
* BFD_RELOC_D30V_6: howto manager.
* BFD_RELOC_D30V_9_PCREL: howto manager.
* BFD_RELOC_D30V_9_PCREL_R: howto manager.
* BFD_RELOC_FR30_10_IN_8: howto manager.
* BFD_RELOC_FR30_12_PCREL: howto manager.
* BFD_RELOC_FR30_20: howto manager.
* BFD_RELOC_FR30_48: howto manager.
* BFD_RELOC_FR30_6_IN_4: howto manager.
* BFD_RELOC_FR30_8_IN_8: howto manager.
* BFD_RELOC_FR30_9_IN_8: howto manager.
* BFD_RELOC_FR30_9_PCREL: howto manager.
* BFD_RELOC_GPREL16: howto manager.
* BFD_RELOC_GPREL32: howto manager.
* BFD_RELOC_HI16: howto manager.
* BFD_RELOC_HI16_BASEREL: howto manager.
* BFD_RELOC_HI16_GOTOFF: howto manager.
* BFD_RELOC_HI16_PLTOFF: howto manager.
* BFD_RELOC_HI16_S: howto manager.
* BFD_RELOC_HI16_S_BASEREL: howto manager.
* BFD_RELOC_HI16_S_GOTOFF: howto manager.
* BFD_RELOC_HI16_S_PLTOFF: howto manager.
* BFD_RELOC_HI22: howto manager.
* BFD_RELOC_I370_D12: howto manager.
* BFD_RELOC_I960_CALLJ: howto manager.
* BFD_RELOC_LO10: howto manager.
* BFD_RELOC_LO16: howto manager.
* BFD_RELOC_LO16_BASEREL: howto manager.
* BFD_RELOC_LO16_GOTOFF: howto manager.
* BFD_RELOC_LO16_PLTOFF: howto manager.
* BFD_RELOC_M32R_10_PCREL: howto manager.
* BFD_RELOC_M32R_18_PCREL: howto manager.
* BFD_RELOC_M32R_24: howto manager.
* BFD_RELOC_M32R_26_PCREL: howto manager.
* BFD_RELOC_M32R_HI16_SLO: howto manager.
* BFD_RELOC_M32R_HI16_ULO: howto manager.
* BFD_RELOC_M32R_LO16: howto manager.
* BFD_RELOC_M32R_SDA16: howto manager.
* BFD_RELOC_MCORE_PCREL_32: howto manager.
* BFD_RELOC_MCORE_PCREL_IMM11BY2: howto manager.
* BFD_RELOC_MCORE_PCREL_IMM4BY2: howto manager.
* BFD_RELOC_MCORE_PCREL_IMM8BY4: howto manager.
* BFD_RELOC_MCORE_PCREL_JSR_IMM11BY2: howto manager.
* BFD_RELOC_MCORE_RVA: howto manager.
* BFD_RELOC_MIPS16_GPREL: howto manager.
* BFD_RELOC_MIPS16_JMP: howto manager.
* BFD_RELOC_MIPS_CALL16: howto manager.
* BFD_RELOC_MIPS_CALL_HI16: howto manager.
* BFD_RELOC_MIPS_CALL_LO16: howto manager.
* BFD_RELOC_MIPS_GOT16: howto manager.
* BFD_RELOC_MIPS_GOT_DISP: howto manager.
* BFD_RELOC_MIPS_GOT_HI16: howto manager.
* BFD_RELOC_MIPS_GOT_LO16: howto manager.
* BFD_RELOC_MIPS_GOT_OFST: howto manager.
* BFD_RELOC_MIPS_GOT_PAGE: howto manager.
* BFD_RELOC_MIPS_GPREL: howto manager.
* BFD_RELOC_MIPS_GPREL32: howto manager.
* BFD_RELOC_MIPS_JMP: howto manager.
* BFD_RELOC_MIPS_LITERAL: howto manager.
* BFD_RELOC_MIPS_SUB: howto manager.
* BFD_RELOC_MN10300_16_PCREL: howto manager.
* BFD_RELOC_MN10300_32_PCREL: howto manager.
* BFD_RELOC_NONE: howto manager.
* BFD_RELOC_NS32K_DISP_16: howto manager.
* BFD_RELOC_NS32K_DISP_16_PCREL: howto manager.
* BFD_RELOC_NS32K_DISP_32: howto manager.
* BFD_RELOC_NS32K_DISP_32_PCREL: howto manager.
* BFD_RELOC_NS32K_DISP_8: howto manager.
* BFD_RELOC_NS32K_DISP_8_PCREL: howto manager.
* BFD_RELOC_NS32K_IMM_16: howto manager.
* BFD_RELOC_NS32K_IMM_16_PCREL: howto manager.
* BFD_RELOC_NS32K_IMM_32: howto manager.
* BFD_RELOC_NS32K_IMM_32_PCREL: howto manager.
* BFD_RELOC_NS32K_IMM_8: howto manager.
* BFD_RELOC_NS32K_IMM_8_PCREL: howto manager.
* BFD_RELOC_PCREL_HI16_S: howto manager.
* BFD_RELOC_PCREL_LO16: howto manager.
* BFD_RELOC_PJ_CODE_DIR16: howto manager.
* BFD_RELOC_PJ_CODE_DIR32: howto manager.
* BFD_RELOC_PJ_CODE_HI16: howto manager.
* BFD_RELOC_PJ_CODE_LO16: howto manager.
* BFD_RELOC_PJ_CODE_REL16: howto manager.
* BFD_RELOC_PJ_CODE_REL32: howto manager.
* BFD_RELOC_PPC_B16: howto manager.
* BFD_RELOC_PPC_B16_BRNTAKEN: howto manager.
* BFD_RELOC_PPC_B16_BRTAKEN: howto manager.
* BFD_RELOC_PPC_B26: howto manager.
* BFD_RELOC_PPC_BA16: howto manager.
* BFD_RELOC_PPC_BA16_BRNTAKEN: howto manager.
* BFD_RELOC_PPC_BA16_BRTAKEN: howto manager.
* BFD_RELOC_PPC_BA26: howto manager.
* BFD_RELOC_PPC_COPY: howto manager.
* BFD_RELOC_PPC_EMB_BIT_FLD: howto manager.
* BFD_RELOC_PPC_EMB_MRKREF: howto manager.
* BFD_RELOC_PPC_EMB_NADDR16: howto manager.
* BFD_RELOC_PPC_EMB_NADDR16_HA: howto manager.
* BFD_RELOC_PPC_EMB_NADDR16_HI: howto manager.
* BFD_RELOC_PPC_EMB_NADDR16_LO: howto manager.
* BFD_RELOC_PPC_EMB_NADDR32: howto manager.
* BFD_RELOC_PPC_EMB_RELSDA: howto manager.
* BFD_RELOC_PPC_EMB_RELSEC16: howto manager.
* BFD_RELOC_PPC_EMB_RELST_HA: howto manager.
* BFD_RELOC_PPC_EMB_RELST_HI: howto manager.
* BFD_RELOC_PPC_EMB_RELST_LO: howto manager.
* BFD_RELOC_PPC_EMB_SDA21: howto manager.
* BFD_RELOC_PPC_EMB_SDA2I16: howto manager.
* BFD_RELOC_PPC_EMB_SDA2REL: howto manager.
* BFD_RELOC_PPC_EMB_SDAI16: howto manager.
* BFD_RELOC_PPC_GLOB_DAT: howto manager.
* BFD_RELOC_PPC_JMP_SLOT: howto manager.
* BFD_RELOC_PPC_LOCAL24PC: howto manager.
* BFD_RELOC_PPC_RELATIVE: howto manager.
* BFD_RELOC_PPC_TOC16: howto manager.
* BFD_RELOC_RVA: howto manager.
* BFD_RELOC_SH_ALIGN: howto manager.
* BFD_RELOC_SH_CODE: howto manager.
* BFD_RELOC_SH_COUNT: howto manager.
* BFD_RELOC_SH_DATA: howto manager.
* BFD_RELOC_SH_IMM4: howto manager.
* BFD_RELOC_SH_IMM4BY2: howto manager.
* BFD_RELOC_SH_IMM4BY4: howto manager.
* BFD_RELOC_SH_IMM8: howto manager.
* BFD_RELOC_SH_IMM8BY2: howto manager.
* BFD_RELOC_SH_IMM8BY4: howto manager.
* BFD_RELOC_SH_LABEL: howto manager.
* BFD_RELOC_SH_PCDISP12BY2: howto manager.
* BFD_RELOC_SH_PCDISP8BY2: howto manager.
* BFD_RELOC_SH_PCRELIMM8BY2: howto manager.
* BFD_RELOC_SH_PCRELIMM8BY4: howto manager.
* BFD_RELOC_SH_SWITCH16: howto manager.
* BFD_RELOC_SH_SWITCH32: howto manager.
* BFD_RELOC_SH_USES: howto manager.
* BFD_RELOC_SPARC13: howto manager.
* BFD_RELOC_SPARC22: howto manager.
* BFD_RELOC_SPARC_10: howto manager.
* BFD_RELOC_SPARC_11: howto manager.
* BFD_RELOC_SPARC_5: howto manager.
* BFD_RELOC_SPARC_6: howto manager.
* BFD_RELOC_SPARC_64: howto manager.
* BFD_RELOC_SPARC_7: howto manager.
* BFD_RELOC_SPARC_BASE13: howto manager.
* BFD_RELOC_SPARC_BASE22: howto manager.
* BFD_RELOC_SPARC_COPY: howto manager.
* BFD_RELOC_SPARC_DISP64: howto manager.
* BFD_RELOC_SPARC_GLOB_DAT: howto manager.
* BFD_RELOC_SPARC_GOT10: howto manager.
* BFD_RELOC_SPARC_GOT13: howto manager.
* BFD_RELOC_SPARC_GOT22: howto manager.
* BFD_RELOC_SPARC_H44: howto manager.
* BFD_RELOC_SPARC_HH22: howto manager.
* BFD_RELOC_SPARC_HIX22: howto manager.
* BFD_RELOC_SPARC_HM10: howto manager.
* BFD_RELOC_SPARC_JMP_SLOT: howto manager.
* BFD_RELOC_SPARC_L44: howto manager.
* BFD_RELOC_SPARC_LM22: howto manager.
* BFD_RELOC_SPARC_LOX10: howto manager.
* BFD_RELOC_SPARC_M44: howto manager.
* BFD_RELOC_SPARC_OLO10: howto manager.
* BFD_RELOC_SPARC_PC10: howto manager.
* BFD_RELOC_SPARC_PC22: howto manager.
* BFD_RELOC_SPARC_PC_HH22: howto manager.
* BFD_RELOC_SPARC_PC_HM10: howto manager.
* BFD_RELOC_SPARC_PC_LM22: howto manager.
* BFD_RELOC_SPARC_PLT64: howto manager.
* BFD_RELOC_SPARC_REGISTER: howto manager.
* BFD_RELOC_SPARC_RELATIVE: howto manager.
* BFD_RELOC_SPARC_REV32: howto manager.
* BFD_RELOC_SPARC_UA32: howto manager.
* BFD_RELOC_SPARC_WDISP16: howto manager.
* BFD_RELOC_SPARC_WDISP19: howto manager.
* BFD_RELOC_SPARC_WDISP22: howto manager.
* BFD_RELOC_SPARC_WPLT30: howto manager.
* BFD_RELOC_THUMB_PCREL_BRANCH12: howto manager.
* BFD_RELOC_THUMB_PCREL_BRANCH23: howto manager.
* BFD_RELOC_THUMB_PCREL_BRANCH9: howto manager.
* BFD_RELOC_TIC30_LDP: howto manager.
* bfd_reloc_type_lookup: howto manager.
* BFD_RELOC_V850_22_PCREL: howto manager.
* BFD_RELOC_V850_9_PCREL: howto manager.
* BFD_RELOC_V850_CALLT_16_16_OFFSET: howto manager.
* BFD_RELOC_V850_CALLT_6_7_OFFSET: howto manager.
* BFD_RELOC_V850_SDA_15_16_OFFSET: howto manager.
* BFD_RELOC_V850_SDA_16_16_OFFSET: howto manager.
* BFD_RELOC_V850_SDA_16_16_SPLIT_OFFSET: howto manager.
* BFD_RELOC_V850_TDA_16_16_OFFSET: howto manager.
* BFD_RELOC_V850_TDA_4_4_OFFSET: howto manager.
* BFD_RELOC_V850_TDA_4_5_OFFSET: howto manager.
* BFD_RELOC_V850_TDA_6_8_OFFSET: howto manager.
* BFD_RELOC_V850_TDA_7_7_OFFSET: howto manager.
* BFD_RELOC_V850_TDA_7_8_OFFSET: howto manager.
* BFD_RELOC_V850_ZDA_15_16_OFFSET: howto manager.
* BFD_RELOC_V850_ZDA_16_16_OFFSET: howto manager.
* BFD_RELOC_V850_ZDA_16_16_SPLIT_OFFSET: howto manager.
* BFD_RELOC_VTABLE_ENTRY: howto manager.
* BFD_RELOC_VTABLE_INHERIT: howto manager.
* bfd_scan_arch: Architectures.
* bfd_scan_vma: BFD front end.
* bfd_seach_for_target: bfd_target.
* bfd_set_arch_info: Architectures.
* bfd_set_archive_head: Archives.
* bfd_set_default_target: bfd_target.
* bfd_set_error: BFD front end.
* bfd_set_error_handler: BFD front end.
* bfd_set_error_program_name: BFD front end.
* bfd_set_file_flags: BFD front end.
* bfd_set_format: Formats.
* bfd_set_gp_size: BFD front end.
* bfd_set_private_flags: BFD front end.
* bfd_set_reloc: BFD front end.
* bfd_set_section_contents: section prototypes.
* bfd_set_section_flags: section prototypes.
* bfd_set_section_size: section prototypes.
* bfd_set_start_address: BFD front end.
* bfd_set_symtab: symbol handling functions.
* bfd_symbol_info: symbol handling functions.
* bfd_target_list: bfd_target.
* bfd_write_bigendian_4byte_int: Internal.
* coff_symbol_type: coff.
* core_file_matches_executable_p: Core Files.
* Hash tables: Hash Tables.
* internal object-file format: Canonical format.
* Linker: Linker Functions.
* stuff: BFD front end.
* target vector (_bfd_final_link): Performing the Final Link.
* target vector (_bfd_link_add_symbols): Adding Symbols to the Hash Table.
* target vector (_bfd_link_hash_table_create): Creating a Linker Hash Table.
* The HOWTO Macro: typedef arelent.
* what is it?: Overview.

601
bfd/doc/bfdt.texi Normal file
View File

@@ -0,0 +1,601 @@
@section @code{typedef bfd}
A BFD has type @code{bfd}; objects of this type are the
cornerstone of any application using BFD. Using BFD
consists of making references though the BFD and to data in the BFD.
Here is the structure that defines the type @code{bfd}. It
contains the major data about the file and pointers
to the rest of the data.
@example
struct _bfd
@{
/* The filename the application opened the BFD with. */
CONST char *filename;
/* A pointer to the target jump table. */
const struct bfd_target *xvec;
/* To avoid dragging too many header files into every file that
includes `@code{bfd.h}', IOSTREAM has been declared as a "char
*", and MTIME as a "long". Their correct types, to which they
are cast when used, are "FILE *" and "time_t". The iostream
is the result of an fopen on the filename. However, if the
BFD_IN_MEMORY flag is set, then iostream is actually a pointer
to a bfd_in_memory struct. */
PTR iostream;
/* Is the file descriptor being cached? That is, can it be closed as
needed, and re-opened when accessed later? */
boolean cacheable;
/* Marks whether there was a default target specified when the
BFD was opened. This is used to select which matching algorithm
to use to choose the back end. */
boolean target_defaulted;
/* The caching routines use these to maintain a
least-recently-used list of BFDs */
struct _bfd *lru_prev, *lru_next;
/* When a file is closed by the caching routines, BFD retains
state information on the file here: */
file_ptr where;
/* and here: (``once'' means at least once) */
boolean opened_once;
/* Set if we have a locally maintained mtime value, rather than
getting it from the file each time: */
boolean mtime_set;
/* File modified time, if mtime_set is true: */
long mtime;
/* Reserved for an unimplemented file locking extension.*/
int ifd;
/* The format which belongs to the BFD. (object, core, etc.) */
bfd_format format;
/* The direction the BFD was opened with*/
enum bfd_direction @{no_direction = 0,
read_direction = 1,
write_direction = 2,
both_direction = 3@} direction;
/* Format_specific flags*/
flagword flags;
/* Currently my_archive is tested before adding origin to
anything. I believe that this can become always an add of
origin, with origin set to 0 for non archive files. */
file_ptr origin;
/* Remember when output has begun, to stop strange things
from happening. */
boolean output_has_begun;
/* Pointer to linked list of sections*/
struct sec *sections;
/* The number of sections */
unsigned int section_count;
/* Stuff only useful for object files:
The start address. */
bfd_vma start_address;
/* Used for input and output*/
unsigned int symcount;
/* Symbol table for output BFD (with symcount entries) */
struct symbol_cache_entry **outsymbols;
/* Pointer to structure which contains architecture information*/
const struct bfd_arch_info *arch_info;
/* Stuff only useful for archives:*/
PTR arelt_data;
struct _bfd *my_archive; /* The containing archive BFD. */
struct _bfd *next; /* The next BFD in the archive. */
struct _bfd *archive_head; /* The first BFD in the archive. */
boolean has_armap;
/* A chain of BFD structures involved in a link. */
struct _bfd *link_next;
/* A field used by _bfd_generic_link_add_archive_symbols. This will
be used only for archive elements. */
int archive_pass;
/* Used by the back end to hold private data. */
union
@{
struct aout_data_struct *aout_data;
struct artdata *aout_ar_data;
struct _oasys_data *oasys_obj_data;
struct _oasys_ar_data *oasys_ar_data;
struct coff_tdata *coff_obj_data;
struct pe_tdata *pe_obj_data;
struct xcoff_tdata *xcoff_obj_data;
struct ecoff_tdata *ecoff_obj_data;
struct ieee_data_struct *ieee_data;
struct ieee_ar_data_struct *ieee_ar_data;
struct srec_data_struct *srec_data;
struct ihex_data_struct *ihex_data;
struct tekhex_data_struct *tekhex_data;
struct elf_obj_tdata *elf_obj_data;
struct nlm_obj_tdata *nlm_obj_data;
struct bout_data_struct *bout_data;
struct sun_core_struct *sun_core_data;
struct sco5_core_struct *sco5_core_data;
struct trad_core_struct *trad_core_data;
struct som_data_struct *som_data;
struct hpux_core_struct *hpux_core_data;
struct hppabsd_core_struct *hppabsd_core_data;
struct sgi_core_struct *sgi_core_data;
struct lynx_core_struct *lynx_core_data;
struct osf_core_struct *osf_core_data;
struct cisco_core_struct *cisco_core_data;
struct versados_data_struct *versados_data;
struct netbsd_core_struct *netbsd_core_data;
PTR any;
@} tdata;
/* Used by the application to hold private data*/
PTR usrdata;
/* Where all the allocated stuff under this BFD goes. This is a
struct objalloc *, but we use PTR to avoid requiring the inclusion of
objalloc.h. */
PTR memory;
@};
@end example
@section Error reporting
Most BFD functions return nonzero on success (check their
individual documentation for precise semantics). On an error,
they call @code{bfd_set_error} to set an error condition that callers
can check by calling @code{bfd_get_error}.
If that returns @code{bfd_error_system_call}, then check
@code{errno}.
The easiest way to report a BFD error to the user is to
use @code{bfd_perror}.
@subsection Type @code{bfd_error_type}
The values returned by @code{bfd_get_error} are defined by the
enumerated type @code{bfd_error_type}.
@example
typedef enum bfd_error
@{
bfd_error_no_error = 0,
bfd_error_system_call,
bfd_error_invalid_target,
bfd_error_wrong_format,
bfd_error_invalid_operation,
bfd_error_no_memory,
bfd_error_no_symbols,
bfd_error_no_armap,
bfd_error_no_more_archived_files,
bfd_error_malformed_archive,
bfd_error_file_not_recognized,
bfd_error_file_ambiguously_recognized,
bfd_error_no_contents,
bfd_error_nonrepresentable_section,
bfd_error_no_debug_section,
bfd_error_bad_value,
bfd_error_file_truncated,
bfd_error_file_too_big,
bfd_error_invalid_error_code
@} bfd_error_type;
@end example
@findex bfd_get_error
@subsubsection @code{bfd_get_error}
@strong{Synopsis}
@example
bfd_error_type bfd_get_error (void);
@end example
@strong{Description}@*
Return the current BFD error condition.
@findex bfd_set_error
@subsubsection @code{bfd_set_error}
@strong{Synopsis}
@example
void bfd_set_error (bfd_error_type error_tag);
@end example
@strong{Description}@*
Set the BFD error condition to be @var{error_tag}.
@findex bfd_errmsg
@subsubsection @code{bfd_errmsg}
@strong{Synopsis}
@example
CONST char *bfd_errmsg (bfd_error_type error_tag);
@end example
@strong{Description}@*
Return a string describing the error @var{error_tag}, or
the system error if @var{error_tag} is @code{bfd_error_system_call}.
@findex bfd_perror
@subsubsection @code{bfd_perror}
@strong{Synopsis}
@example
void bfd_perror (CONST char *message);
@end example
@strong{Description}@*
Print to the standard error stream a string describing the
last BFD error that occurred, or the last system error if
the last BFD error was a system call failure. If @var{message}
is non-NULL and non-empty, the error string printed is preceded
by @var{message}, a colon, and a space. It is followed by a newline.
@subsection BFD error handler
Some BFD functions want to print messages describing the
problem. They call a BFD error handler function. This
function may be overriden by the program.
The BFD error handler acts like printf.
@example
typedef void (*bfd_error_handler_type) PARAMS ((const char *, ...));
@end example
@findex bfd_set_error_handler
@subsubsection @code{bfd_set_error_handler}
@strong{Synopsis}
@example
bfd_error_handler_type bfd_set_error_handler (bfd_error_handler_type);
@end example
@strong{Description}@*
Set the BFD error handler function. Returns the previous
function.
@findex bfd_set_error_program_name
@subsubsection @code{bfd_set_error_program_name}
@strong{Synopsis}
@example
void bfd_set_error_program_name (const char *);
@end example
@strong{Description}@*
Set the program name to use when printing a BFD error. This
is printed before the error message followed by a colon and
space. The string must not be changed after it is passed to
this function.
@findex bfd_get_error_handler
@subsubsection @code{bfd_get_error_handler}
@strong{Synopsis}
@example
bfd_error_handler_type bfd_get_error_handler (void);
@end example
@strong{Description}@*
Return the BFD error handler function.
@section Symbols
@findex bfd_get_reloc_upper_bound
@subsubsection @code{bfd_get_reloc_upper_bound}
@strong{Synopsis}
@example
long bfd_get_reloc_upper_bound(bfd *abfd, asection *sect);
@end example
@strong{Description}@*
Return the number of bytes required to store the
relocation information associated with section @var{sect}
attached to bfd @var{abfd}. If an error occurs, return -1.
@findex bfd_canonicalize_reloc
@subsubsection @code{bfd_canonicalize_reloc}
@strong{Synopsis}
@example
long bfd_canonicalize_reloc
(bfd *abfd,
asection *sec,
arelent **loc,
asymbol **syms);
@end example
@strong{Description}@*
Call the back end associated with the open BFD
@var{abfd} and translate the external form of the relocation
information attached to @var{sec} into the internal canonical
form. Place the table into memory at @var{loc}, which has
been preallocated, usually by a call to
@code{bfd_get_reloc_upper_bound}. Returns the number of relocs, or
-1 on error.
The @var{syms} table is also needed for horrible internal magic
reasons.
@findex bfd_set_reloc
@subsubsection @code{bfd_set_reloc}
@strong{Synopsis}
@example
void bfd_set_reloc
(bfd *abfd, asection *sec, arelent **rel, unsigned int count)
@end example
@strong{Description}@*
Set the relocation pointer and count within
section @var{sec} to the values @var{rel} and @var{count}.
The argument @var{abfd} is ignored.
@findex bfd_set_file_flags
@subsubsection @code{bfd_set_file_flags}
@strong{Synopsis}
@example
boolean bfd_set_file_flags(bfd *abfd, flagword flags);
@end example
@strong{Description}@*
Set the flag word in the BFD @var{abfd} to the value @var{flags}.
Possible errors are:
@itemize @bullet
@item
@code{bfd_error_wrong_format} - The target bfd was not of object format.
@item
@code{bfd_error_invalid_operation} - The target bfd was open for reading.
@item
@code{bfd_error_invalid_operation} -
The flag word contained a bit which was not applicable to the
type of file. E.g., an attempt was made to set the @code{D_PAGED} bit
on a BFD format which does not support demand paging.
@end itemize
@findex bfd_set_start_address
@subsubsection @code{bfd_set_start_address}
@strong{Synopsis}
@example
boolean bfd_set_start_address(bfd *abfd, bfd_vma vma);
@end example
@strong{Description}@*
Make @var{vma} the entry point of output BFD @var{abfd}.
@strong{Returns}@*
Returns @code{true} on success, @code{false} otherwise.
@findex bfd_get_mtime
@subsubsection @code{bfd_get_mtime}
@strong{Synopsis}
@example
long bfd_get_mtime(bfd *abfd);
@end example
@strong{Description}@*
Return the file modification time (as read from the file system, or
from the archive header for archive members).
@findex bfd_get_size
@subsubsection @code{bfd_get_size}
@strong{Synopsis}
@example
long bfd_get_size(bfd *abfd);
@end example
@strong{Description}@*
Return the file size (as read from file system) for the file
associated with BFD @var{abfd}.
The initial motivation for, and use of, this routine is not
so we can get the exact size of the object the BFD applies to, since
that might not be generally possible (archive members for example).
It would be ideal if someone could eventually modify
it so that such results were guaranteed.
Instead, we want to ask questions like "is this NNN byte sized
object I'm about to try read from file offset YYY reasonable?"
As as example of where we might do this, some object formats
use string tables for which the first @code{sizeof(long)} bytes of the
table contain the size of the table itself, including the size bytes.
If an application tries to read what it thinks is one of these
string tables, without some way to validate the size, and for
some reason the size is wrong (byte swapping error, wrong location
for the string table, etc.), the only clue is likely to be a read
error when it tries to read the table, or a "virtual memory
exhausted" error when it tries to allocate 15 bazillon bytes
of space for the 15 bazillon byte table it is about to read.
This function at least allows us to answer the quesion, "is the
size reasonable?".
@findex bfd_get_gp_size
@subsubsection @code{bfd_get_gp_size}
@strong{Synopsis}
@example
int bfd_get_gp_size(bfd *abfd);
@end example
@strong{Description}@*
Return the maximum size of objects to be optimized using the GP
register under MIPS ECOFF. This is typically set by the @code{-G}
argument to the compiler, assembler or linker.
@findex bfd_set_gp_size
@subsubsection @code{bfd_set_gp_size}
@strong{Synopsis}
@example
void bfd_set_gp_size(bfd *abfd, int i);
@end example
@strong{Description}@*
Set the maximum size of objects to be optimized using the GP
register under ECOFF or MIPS ELF. This is typically set by
the @code{-G} argument to the compiler, assembler or linker.
@findex bfd_scan_vma
@subsubsection @code{bfd_scan_vma}
@strong{Synopsis}
@example
bfd_vma bfd_scan_vma(CONST char *string, CONST char **end, int base);
@end example
@strong{Description}@*
Convert, like @code{strtoul}, a numerical expression
@var{string} into a @code{bfd_vma} integer, and return that integer.
(Though without as many bells and whistles as @code{strtoul}.)
The expression is assumed to be unsigned (i.e., positive).
If given a @var{base}, it is used as the base for conversion.
A base of 0 causes the function to interpret the string
in hex if a leading "0x" or "0X" is found, otherwise
in octal if a leading zero is found, otherwise in decimal.
Overflow is not detected.
@findex bfd_copy_private_bfd_data
@subsubsection @code{bfd_copy_private_bfd_data}
@strong{Synopsis}
@example
boolean bfd_copy_private_bfd_data(bfd *ibfd, bfd *obfd);
@end example
@strong{Description}@*
Copy private BFD information from the BFD @var{ibfd} to the
the BFD @var{obfd}. Return @code{true} on success, @code{false} on error.
Possible error returns are:
@itemize @bullet
@item
@code{bfd_error_no_memory} -
Not enough memory exists to create private data for @var{obfd}.
@end itemize
@example
#define bfd_copy_private_bfd_data(ibfd, obfd) \
BFD_SEND (obfd, _bfd_copy_private_bfd_data, \
(ibfd, obfd))
@end example
@findex bfd_merge_private_bfd_data
@subsubsection @code{bfd_merge_private_bfd_data}
@strong{Synopsis}
@example
boolean bfd_merge_private_bfd_data(bfd *ibfd, bfd *obfd);
@end example
@strong{Description}@*
Merge private BFD information from the BFD @var{ibfd} to the
the output file BFD @var{obfd} when linking. Return @code{true}
on success, @code{false} on error. Possible error returns are:
@itemize @bullet
@item
@code{bfd_error_no_memory} -
Not enough memory exists to create private data for @var{obfd}.
@end itemize
@example
#define bfd_merge_private_bfd_data(ibfd, obfd) \
BFD_SEND (obfd, _bfd_merge_private_bfd_data, \
(ibfd, obfd))
@end example
@findex bfd_set_private_flags
@subsubsection @code{bfd_set_private_flags}
@strong{Synopsis}
@example
boolean bfd_set_private_flags(bfd *abfd, flagword flags);
@end example
@strong{Description}@*
Set private BFD flag information in the BFD @var{abfd}.
Return @code{true} on success, @code{false} on error. Possible error
returns are:
@itemize @bullet
@item
@code{bfd_error_no_memory} -
Not enough memory exists to create private data for @var{obfd}.
@end itemize
@example
#define bfd_set_private_flags(abfd, flags) \
BFD_SEND (abfd, _bfd_set_private_flags, \
(abfd, flags))
@end example
@findex stuff
@subsubsection @code{stuff}
@strong{Description}@*
Stuff which should be documented:
@example
#define bfd_sizeof_headers(abfd, reloc) \
BFD_SEND (abfd, _bfd_sizeof_headers, (abfd, reloc))
#define bfd_find_nearest_line(abfd, sec, syms, off, file, func, line) \
BFD_SEND (abfd, _bfd_find_nearest_line, (abfd, sec, syms, off, file, func, line))
/* Do these three do anything useful at all, for any back end? */
#define bfd_debug_info_start(abfd) \
BFD_SEND (abfd, _bfd_debug_info_start, (abfd))
#define bfd_debug_info_end(abfd) \
BFD_SEND (abfd, _bfd_debug_info_end, (abfd))
#define bfd_debug_info_accumulate(abfd, section) \
BFD_SEND (abfd, _bfd_debug_info_accumulate, (abfd, section))
#define bfd_stat_arch_elt(abfd, stat) \
BFD_SEND (abfd, _bfd_stat_arch_elt,(abfd, stat))
#define bfd_update_armap_timestamp(abfd) \
BFD_SEND (abfd, _bfd_update_armap_timestamp, (abfd))
#define bfd_set_arch_mach(abfd, arch, mach)\
BFD_SEND ( abfd, _bfd_set_arch_mach, (abfd, arch, mach))
#define bfd_relax_section(abfd, section, link_info, again) \
BFD_SEND (abfd, _bfd_relax_section, (abfd, section, link_info, again))
#define bfd_gc_sections(abfd, link_info) \
BFD_SEND (abfd, _bfd_gc_sections, (abfd, link_info))
#define bfd_link_hash_table_create(abfd) \
BFD_SEND (abfd, _bfd_link_hash_table_create, (abfd))
#define bfd_link_add_symbols(abfd, info) \
BFD_SEND (abfd, _bfd_link_add_symbols, (abfd, info))
#define bfd_final_link(abfd, info) \
BFD_SEND (abfd, _bfd_final_link, (abfd, info))
#define bfd_free_cached_info(abfd) \
BFD_SEND (abfd, _bfd_free_cached_info, (abfd))
#define bfd_get_dynamic_symtab_upper_bound(abfd) \
BFD_SEND (abfd, _bfd_get_dynamic_symtab_upper_bound, (abfd))
#define bfd_print_private_bfd_data(abfd, file)\
BFD_SEND (abfd, _bfd_print_private_bfd_data, (abfd, file))
#define bfd_canonicalize_dynamic_symtab(abfd, asymbols) \
BFD_SEND (abfd, _bfd_canonicalize_dynamic_symtab, (abfd, asymbols))
#define bfd_get_dynamic_reloc_upper_bound(abfd) \
BFD_SEND (abfd, _bfd_get_dynamic_reloc_upper_bound, (abfd))
#define bfd_canonicalize_dynamic_reloc(abfd, arels, asyms) \
BFD_SEND (abfd, _bfd_canonicalize_dynamic_reloc, (abfd, arels, asyms))
extern bfd_byte *bfd_get_relocated_section_contents
PARAMS ((bfd *, struct bfd_link_info *,
struct bfd_link_order *, bfd_byte *,
boolean, asymbol **));
@end example

95
bfd/doc/cache.texi Normal file
View File

@@ -0,0 +1,95 @@
@section File caching
The file caching mechanism is embedded within BFD and allows
the application to open as many BFDs as it wants without
regard to the underlying operating system's file descriptor
limit (often as low as 20 open files). The module in
@code{cache.c} maintains a least recently used list of
@code{BFD_CACHE_MAX_OPEN} files, and exports the name
@code{bfd_cache_lookup}, which runs around and makes sure that
the required BFD is open. If not, then it chooses a file to
close, closes it and opens the one wanted, returning its file
handle.
@findex BFD_CACHE_MAX_OPEN macro
@subsubsection @code{BFD_CACHE_MAX_OPEN macro}
@strong{Description}@*
The maximum number of files which the cache will keep open at
one time.
@example
#define BFD_CACHE_MAX_OPEN 10
@end example
@findex bfd_last_cache
@subsubsection @code{bfd_last_cache}
@strong{Synopsis}
@example
extern bfd *bfd_last_cache;
@end example
@strong{Description}@*
Zero, or a pointer to the topmost BFD on the chain. This is
used by the @code{bfd_cache_lookup} macro in @file{libbfd.h} to
determine when it can avoid a function call.
@findex bfd_cache_lookup
@subsubsection @code{bfd_cache_lookup}
@strong{Description}@*
Check to see if the required BFD is the same as the last one
looked up. If so, then it can use the stream in the BFD with
impunity, since it can't have changed since the last lookup;
otherwise, it has to perform the complicated lookup function.
@example
#define bfd_cache_lookup(x) \
((x)==bfd_last_cache? \
(FILE*)(bfd_last_cache->iostream): \
bfd_cache_lookup_worker(x))
@end example
@findex bfd_cache_init
@subsubsection @code{bfd_cache_init}
@strong{Synopsis}
@example
boolean bfd_cache_init (bfd *abfd);
@end example
@strong{Description}@*
Add a newly opened BFD to the cache.
@findex bfd_cache_close
@subsubsection @code{bfd_cache_close}
@strong{Synopsis}
@example
boolean bfd_cache_close (bfd *abfd);
@end example
@strong{Description}@*
Remove the BFD @var{abfd} from the cache. If the attached file is open,
then close it too.
@strong{Returns}@*
@code{false} is returned if closing the file fails, @code{true} is
returned if all is well.
@findex bfd_open_file
@subsubsection @code{bfd_open_file}
@strong{Synopsis}
@example
FILE* bfd_open_file(bfd *abfd);
@end example
@strong{Description}@*
Call the OS to open a file for @var{abfd}. Return the @code{FILE *}
(possibly @code{NULL}) that results from this operation. Set up the
BFD so that future accesses know the file is open. If the @code{FILE *}
returned is @code{NULL}, then it won't have been put in the
cache, so it won't have to be removed from it.
@findex bfd_cache_lookup_worker
@subsubsection @code{bfd_cache_lookup_worker}
@strong{Synopsis}
@example
FILE *bfd_cache_lookup_worker(bfd *abfd);
@end example
@strong{Description}@*
Called when the macro @code{bfd_cache_lookup} fails to find a
quick answer. Find a file descriptor for @var{abfd}. If
necessary, it open it. If there are already more than
@code{BFD_CACHE_MAX_OPEN} files open, it tries to close one first, to
avoid running out of file descriptors.

666
bfd/doc/coffcode.texi Normal file
View File

@@ -0,0 +1,666 @@
@section coff backends
BFD supports a number of different flavours of coff format.
The major differences between formats are the sizes and
alignments of fields in structures on disk, and the occasional
extra field.
Coff in all its varieties is implemented with a few common
files and a number of implementation specific files. For
example, The 88k bcs coff format is implemented in the file
@file{coff-m88k.c}. This file @code{#include}s
@file{coff/m88k.h} which defines the external structure of the
coff format for the 88k, and @file{coff/internal.h} which
defines the internal structure. @file{coff-m88k.c} also
defines the relocations used by the 88k format
@xref{Relocations}.
The Intel i960 processor version of coff is implemented in
@file{coff-i960.c}. This file has the same structure as
@file{coff-m88k.c}, except that it includes @file{coff/i960.h}
rather than @file{coff-m88k.h}.
@subsection Porting to a new version of coff
The recommended method is to select from the existing
implementations the version of coff which is most like the one
you want to use. For example, we'll say that i386 coff is
the one you select, and that your coff flavour is called foo.
Copy @file{i386coff.c} to @file{foocoff.c}, copy
@file{../include/coff/i386.h} to @file{../include/coff/foo.h},
and add the lines to @file{targets.c} and @file{Makefile.in}
so that your new back end is used. Alter the shapes of the
structures in @file{../include/coff/foo.h} so that they match
what you need. You will probably also have to add
@code{#ifdef}s to the code in @file{coff/internal.h} and
@file{coffcode.h} if your version of coff is too wild.
You can verify that your new BFD backend works quite simply by
building @file{objdump} from the @file{binutils} directory,
and making sure that its version of what's going on and your
host system's idea (assuming it has the pretty standard coff
dump utility, usually called @code{att-dump} or just
@code{dump}) are the same. Then clean up your code, and send
what you've done to Cygnus. Then your stuff will be in the
next release, and you won't have to keep integrating it.
@subsection How the coff backend works
@subsubsection File layout
The Coff backend is split into generic routines that are
applicable to any Coff target and routines that are specific
to a particular target. The target-specific routines are
further split into ones which are basically the same for all
Coff targets except that they use the external symbol format
or use different values for certain constants.
The generic routines are in @file{coffgen.c}. These routines
work for any Coff target. They use some hooks into the target
specific code; the hooks are in a @code{bfd_coff_backend_data}
structure, one of which exists for each target.
The essentially similar target-specific routines are in
@file{coffcode.h}. This header file includes executable C code.
The various Coff targets first include the appropriate Coff
header file, make any special defines that are needed, and
then include @file{coffcode.h}.
Some of the Coff targets then also have additional routines in
the target source file itself.
For example, @file{coff-i960.c} includes
@file{coff/internal.h} and @file{coff/i960.h}. It then
defines a few constants, such as @code{I960}, and includes
@file{coffcode.h}. Since the i960 has complex relocation
types, @file{coff-i960.c} also includes some code to
manipulate the i960 relocs. This code is not in
@file{coffcode.h} because it would not be used by any other
target.
@subsubsection Bit twiddling
Each flavour of coff supported in BFD has its own header file
describing the external layout of the structures. There is also
an internal description of the coff layout, in
@file{coff/internal.h}. A major function of the
coff backend is swapping the bytes and twiddling the bits to
translate the external form of the structures into the normal
internal form. This is all performed in the
@code{bfd_swap}_@i{thing}_@i{direction} routines. Some
elements are different sizes between different versions of
coff; it is the duty of the coff version specific include file
to override the definitions of various packing routines in
@file{coffcode.h}. E.g., the size of line number entry in coff is
sometimes 16 bits, and sometimes 32 bits. @code{#define}ing
@code{PUT_LNSZ_LNNO} and @code{GET_LNSZ_LNNO} will select the
correct one. No doubt, some day someone will find a version of
coff which has a varying field size not catered to at the
moment. To port BFD, that person will have to add more @code{#defines}.
Three of the bit twiddling routines are exported to
@code{gdb}; @code{coff_swap_aux_in}, @code{coff_swap_sym_in}
and @code{coff_swap_lineno_in}. @code{GDB} reads the symbol
table on its own, but uses BFD to fix things up. More of the
bit twiddlers are exported for @code{gas};
@code{coff_swap_aux_out}, @code{coff_swap_sym_out},
@code{coff_swap_lineno_out}, @code{coff_swap_reloc_out},
@code{coff_swap_filehdr_out}, @code{coff_swap_aouthdr_out},
@code{coff_swap_scnhdr_out}. @code{Gas} currently keeps track
of all the symbol table and reloc drudgery itself, thereby
saving the internal BFD overhead, but uses BFD to swap things
on the way out, making cross ports much safer. Doing so also
allows BFD (and thus the linker) to use the same header files
as @code{gas}, which makes one avenue to disaster disappear.
@subsubsection Symbol reading
The simple canonical form for symbols used by BFD is not rich
enough to keep all the information available in a coff symbol
table. The back end gets around this problem by keeping the original
symbol table around, "behind the scenes".
When a symbol table is requested (through a call to
@code{bfd_canonicalize_symtab}), a request gets through to
@code{coff_get_normalized_symtab}. This reads the symbol table from
the coff file and swaps all the structures inside into the
internal form. It also fixes up all the pointers in the table
(represented in the file by offsets from the first symbol in
the table) into physical pointers to elements in the new
internal table. This involves some work since the meanings of
fields change depending upon context: a field that is a
pointer to another structure in the symbol table at one moment
may be the size in bytes of a structure at the next. Another
pass is made over the table. All symbols which mark file names
(@code{C_FILE} symbols) are modified so that the internal
string points to the value in the auxent (the real filename)
rather than the normal text associated with the symbol
(@code{".file"}).
At this time the symbol names are moved around. Coff stores
all symbols less than nine characters long physically
within the symbol table; longer strings are kept at the end of
the file in the string table. This pass moves all strings
into memory and replaces them with pointers to the strings.
The symbol table is massaged once again, this time to create
the canonical table used by the BFD application. Each symbol
is inspected in turn, and a decision made (using the
@code{sclass} field) about the various flags to set in the
@code{asymbol}. @xref{Symbols}. The generated canonical table
shares strings with the hidden internal symbol table.
Any linenumbers are read from the coff file too, and attached
to the symbols which own the functions the linenumbers belong to.
@subsubsection Symbol writing
Writing a symbol to a coff file which didn't come from a coff
file will lose any debugging information. The @code{asymbol}
structure remembers the BFD from which the symbol was taken, and on
output the back end makes sure that the same destination target as
source target is present.
When the symbols have come from a coff file then all the
debugging information is preserved.
Symbol tables are provided for writing to the back end in a
vector of pointers to pointers. This allows applications like
the linker to accumulate and output large symbol tables
without having to do too much byte copying.
This function runs through the provided symbol table and
patches each symbol marked as a file place holder
(@code{C_FILE}) to point to the next file place holder in the
list. It also marks each @code{offset} field in the list with
the offset from the first symbol of the current symbol.
Another function of this procedure is to turn the canonical
value form of BFD into the form used by coff. Internally, BFD
expects symbol values to be offsets from a section base; so a
symbol physically at 0x120, but in a section starting at
0x100, would have the value 0x20. Coff expects symbols to
contain their final value, so symbols have their values
changed at this point to reflect their sum with their owning
section. This transformation uses the
@code{output_section} field of the @code{asymbol}'s
@code{asection} @xref{Sections}.
@itemize @bullet
@item
@code{coff_mangle_symbols}
@end itemize
This routine runs though the provided symbol table and uses
the offsets generated by the previous pass and the pointers
generated when the symbol table was read in to create the
structured hierachy required by coff. It changes each pointer
to a symbol into the index into the symbol table of the asymbol.
@itemize @bullet
@item
@code{coff_write_symbols}
@end itemize
This routine runs through the symbol table and patches up the
symbols from their internal form into the coff way, calls the
bit twiddlers, and writes out the table to the file.
@findex coff_symbol_type
@subsubsection @code{coff_symbol_type}
@strong{Description}@*
The hidden information for an @code{asymbol} is described in a
@code{combined_entry_type}:
@example
typedef struct coff_ptr_struct
@{
/* Remembers the offset from the first symbol in the file for
this symbol. Generated by coff_renumber_symbols. */
unsigned int offset;
/* Should the value of this symbol be renumbered. Used for
XCOFF C_BSTAT symbols. Set by coff_slurp_symbol_table. */
unsigned int fix_value : 1;
/* Should the tag field of this symbol be renumbered.
Created by coff_pointerize_aux. */
unsigned int fix_tag : 1;
/* Should the endidx field of this symbol be renumbered.
Created by coff_pointerize_aux. */
unsigned int fix_end : 1;
/* Should the x_csect.x_scnlen field be renumbered.
Created by coff_pointerize_aux. */
unsigned int fix_scnlen : 1;
/* Fix up an XCOFF C_BINCL/C_EINCL symbol. The value is the
index into the line number entries. Set by
coff_slurp_symbol_table. */
unsigned int fix_line : 1;
/* The container for the symbol structure as read and translated
from the file. */
union @{
union internal_auxent auxent;
struct internal_syment syment;
@} u;
@} combined_entry_type;
/* Each canonical asymbol really looks like this: */
typedef struct coff_symbol_struct
@{
/* The actual symbol which the rest of BFD works with */
asymbol symbol;
/* A pointer to the hidden information for this symbol */
combined_entry_type *native;
/* A pointer to the linenumber information for this symbol */
struct lineno_cache_entry *lineno;
/* Have the line numbers been relocated yet ? */
boolean done_lineno;
@} coff_symbol_type;
@end example
@findex bfd_coff_backend_data
@subsubsection @code{bfd_coff_backend_data}
@example
/* COFF symbol classifications. */
enum coff_symbol_classification
@{
/* Global symbol. */
COFF_SYMBOL_GLOBAL,
/* Common symbol. */
COFF_SYMBOL_COMMON,
/* Undefined symbol. */
COFF_SYMBOL_UNDEFINED,
/* Local symbol. */
COFF_SYMBOL_LOCAL,
/* PE section symbol. */
COFF_SYMBOL_PE_SECTION
@};
@end example
Special entry points for gdb to swap in coff symbol table parts:
@example
typedef struct
@{
void (*_bfd_coff_swap_aux_in) PARAMS ((
bfd *abfd,
PTR ext,
int type,
int class,
int indaux,
int numaux,
PTR in));
void (*_bfd_coff_swap_sym_in) PARAMS ((
bfd *abfd ,
PTR ext,
PTR in));
void (*_bfd_coff_swap_lineno_in) PARAMS ((
bfd *abfd,
PTR ext,
PTR in));
@end example
Special entry points for gas to swap out coff parts:
@example
unsigned int (*_bfd_coff_swap_aux_out) PARAMS ((
bfd *abfd,
PTR in,
int type,
int class,
int indaux,
int numaux,
PTR ext));
unsigned int (*_bfd_coff_swap_sym_out) PARAMS ((
bfd *abfd,
PTR in,
PTR ext));
unsigned int (*_bfd_coff_swap_lineno_out) PARAMS ((
bfd *abfd,
PTR in,
PTR ext));
unsigned int (*_bfd_coff_swap_reloc_out) PARAMS ((
bfd *abfd,
PTR src,
PTR dst));
unsigned int (*_bfd_coff_swap_filehdr_out) PARAMS ((
bfd *abfd,
PTR in,
PTR out));
unsigned int (*_bfd_coff_swap_aouthdr_out) PARAMS ((
bfd *abfd,
PTR in,
PTR out));
unsigned int (*_bfd_coff_swap_scnhdr_out) PARAMS ((
bfd *abfd,
PTR in,
PTR out));
@end example
Special entry points for generic COFF routines to call target
dependent COFF routines:
@example
unsigned int _bfd_filhsz;
unsigned int _bfd_aoutsz;
unsigned int _bfd_scnhsz;
unsigned int _bfd_symesz;
unsigned int _bfd_auxesz;
unsigned int _bfd_relsz;
unsigned int _bfd_linesz;
unsigned int _bfd_filnmlen;
boolean _bfd_coff_long_filenames;
boolean _bfd_coff_long_section_names;
unsigned int _bfd_coff_default_section_alignment_power;
void (*_bfd_coff_swap_filehdr_in) PARAMS ((
bfd *abfd,
PTR ext,
PTR in));
void (*_bfd_coff_swap_aouthdr_in) PARAMS ((
bfd *abfd,
PTR ext,
PTR in));
void (*_bfd_coff_swap_scnhdr_in) PARAMS ((
bfd *abfd,
PTR ext,
PTR in));
void (*_bfd_coff_swap_reloc_in) PARAMS ((
bfd *abfd,
PTR ext,
PTR in));
boolean (*_bfd_coff_bad_format_hook) PARAMS ((
bfd *abfd,
PTR internal_filehdr));
boolean (*_bfd_coff_set_arch_mach_hook) PARAMS ((
bfd *abfd,
PTR internal_filehdr));
PTR (*_bfd_coff_mkobject_hook) PARAMS ((
bfd *abfd,
PTR internal_filehdr,
PTR internal_aouthdr));
flagword (*_bfd_styp_to_sec_flags_hook) PARAMS ((
bfd *abfd,
PTR internal_scnhdr,
const char *name,
asection *section));
void (*_bfd_set_alignment_hook) PARAMS ((
bfd *abfd,
asection *sec,
PTR internal_scnhdr));
boolean (*_bfd_coff_slurp_symbol_table) PARAMS ((
bfd *abfd));
boolean (*_bfd_coff_symname_in_debug) PARAMS ((
bfd *abfd,
struct internal_syment *sym));
boolean (*_bfd_coff_pointerize_aux_hook) PARAMS ((
bfd *abfd,
combined_entry_type *table_base,
combined_entry_type *symbol,
unsigned int indaux,
combined_entry_type *aux));
boolean (*_bfd_coff_print_aux) PARAMS ((
bfd *abfd,
FILE *file,
combined_entry_type *table_base,
combined_entry_type *symbol,
combined_entry_type *aux,
unsigned int indaux));
void (*_bfd_coff_reloc16_extra_cases) PARAMS ((
bfd *abfd,
struct bfd_link_info *link_info,
struct bfd_link_order *link_order,
arelent *reloc,
bfd_byte *data,
unsigned int *src_ptr,
unsigned int *dst_ptr));
int (*_bfd_coff_reloc16_estimate) PARAMS ((
bfd *abfd,
asection *input_section,
arelent *r,
unsigned int shrink,
struct bfd_link_info *link_info));
enum coff_symbol_classification (*_bfd_coff_classify_symbol) PARAMS ((
bfd *abfd,
struct internal_syment *));
boolean (*_bfd_coff_compute_section_file_positions) PARAMS ((
bfd *abfd));
boolean (*_bfd_coff_start_final_link) PARAMS ((
bfd *output_bfd,
struct bfd_link_info *info));
boolean (*_bfd_coff_relocate_section) PARAMS ((
bfd *output_bfd,
struct bfd_link_info *info,
bfd *input_bfd,
asection *input_section,
bfd_byte *contents,
struct internal_reloc *relocs,
struct internal_syment *syms,
asection **sections));
reloc_howto_type *(*_bfd_coff_rtype_to_howto) PARAMS ((
bfd *abfd,
asection *sec,
struct internal_reloc *rel,
struct coff_link_hash_entry *h,
struct internal_syment *sym,
bfd_vma *addendp));
boolean (*_bfd_coff_adjust_symndx) PARAMS ((
bfd *obfd,
struct bfd_link_info *info,
bfd *ibfd,
asection *sec,
struct internal_reloc *reloc,
boolean *adjustedp));
boolean (*_bfd_coff_link_add_one_symbol) PARAMS ((
struct bfd_link_info *info,
bfd *abfd,
const char *name,
flagword flags,
asection *section,
bfd_vma value,
const char *string,
boolean copy,
boolean collect,
struct bfd_link_hash_entry **hashp));
boolean (*_bfd_coff_link_output_has_begun) PARAMS ((
bfd * abfd,
struct coff_final_link_info * pfinfo));
boolean (*_bfd_coff_final_link_postscript) PARAMS ((
bfd * abfd,
struct coff_final_link_info * pfinfo));
@} bfd_coff_backend_data;
#define coff_backend_info(abfd) ((bfd_coff_backend_data *) (abfd)->xvec->backend_data)
#define bfd_coff_swap_aux_in(a,e,t,c,ind,num,i) \
((coff_backend_info (a)->_bfd_coff_swap_aux_in) (a,e,t,c,ind,num,i))
#define bfd_coff_swap_sym_in(a,e,i) \
((coff_backend_info (a)->_bfd_coff_swap_sym_in) (a,e,i))
#define bfd_coff_swap_lineno_in(a,e,i) \
((coff_backend_info ( a)->_bfd_coff_swap_lineno_in) (a,e,i))
#define bfd_coff_swap_reloc_out(abfd, i, o) \
((coff_backend_info (abfd)->_bfd_coff_swap_reloc_out) (abfd, i, o))
#define bfd_coff_swap_lineno_out(abfd, i, o) \
((coff_backend_info (abfd)->_bfd_coff_swap_lineno_out) (abfd, i, o))
#define bfd_coff_swap_aux_out(a,i,t,c,ind,num,o) \
((coff_backend_info (a)->_bfd_coff_swap_aux_out) (a,i,t,c,ind,num,o))
#define bfd_coff_swap_sym_out(abfd, i,o) \
((coff_backend_info (abfd)->_bfd_coff_swap_sym_out) (abfd, i, o))
#define bfd_coff_swap_scnhdr_out(abfd, i,o) \
((coff_backend_info (abfd)->_bfd_coff_swap_scnhdr_out) (abfd, i, o))
#define bfd_coff_swap_filehdr_out(abfd, i,o) \
((coff_backend_info (abfd)->_bfd_coff_swap_filehdr_out) (abfd, i, o))
#define bfd_coff_swap_aouthdr_out(abfd, i,o) \
((coff_backend_info (abfd)->_bfd_coff_swap_aouthdr_out) (abfd, i, o))
#define bfd_coff_filhsz(abfd) (coff_backend_info (abfd)->_bfd_filhsz)
#define bfd_coff_aoutsz(abfd) (coff_backend_info (abfd)->_bfd_aoutsz)
#define bfd_coff_scnhsz(abfd) (coff_backend_info (abfd)->_bfd_scnhsz)
#define bfd_coff_symesz(abfd) (coff_backend_info (abfd)->_bfd_symesz)
#define bfd_coff_auxesz(abfd) (coff_backend_info (abfd)->_bfd_auxesz)
#define bfd_coff_relsz(abfd) (coff_backend_info (abfd)->_bfd_relsz)
#define bfd_coff_linesz(abfd) (coff_backend_info (abfd)->_bfd_linesz)
#define bfd_coff_filnmlen(abfd) (coff_backend_info (abfd)->_bfd_filnmlen)
#define bfd_coff_long_filenames(abfd) (coff_backend_info (abfd)->_bfd_coff_long_filenames)
#define bfd_coff_long_section_names(abfd) \
(coff_backend_info (abfd)->_bfd_coff_long_section_names)
#define bfd_coff_default_section_alignment_power(abfd) \
(coff_backend_info (abfd)->_bfd_coff_default_section_alignment_power)
#define bfd_coff_swap_filehdr_in(abfd, i,o) \
((coff_backend_info (abfd)->_bfd_coff_swap_filehdr_in) (abfd, i, o))
#define bfd_coff_swap_aouthdr_in(abfd, i,o) \
((coff_backend_info (abfd)->_bfd_coff_swap_aouthdr_in) (abfd, i, o))
#define bfd_coff_swap_scnhdr_in(abfd, i,o) \
((coff_backend_info (abfd)->_bfd_coff_swap_scnhdr_in) (abfd, i, o))
#define bfd_coff_swap_reloc_in(abfd, i, o) \
((coff_backend_info (abfd)->_bfd_coff_swap_reloc_in) (abfd, i, o))
#define bfd_coff_bad_format_hook(abfd, filehdr) \
((coff_backend_info (abfd)->_bfd_coff_bad_format_hook) (abfd, filehdr))
#define bfd_coff_set_arch_mach_hook(abfd, filehdr)\
((coff_backend_info (abfd)->_bfd_coff_set_arch_mach_hook) (abfd, filehdr))
#define bfd_coff_mkobject_hook(abfd, filehdr, aouthdr)\
((coff_backend_info (abfd)->_bfd_coff_mkobject_hook) (abfd, filehdr, aouthdr))
#define bfd_coff_styp_to_sec_flags_hook(abfd, scnhdr, name, section)\
((coff_backend_info (abfd)->_bfd_styp_to_sec_flags_hook)\
(abfd, scnhdr, name, section))
#define bfd_coff_set_alignment_hook(abfd, sec, scnhdr)\
((coff_backend_info (abfd)->_bfd_set_alignment_hook) (abfd, sec, scnhdr))
#define bfd_coff_slurp_symbol_table(abfd)\
((coff_backend_info (abfd)->_bfd_coff_slurp_symbol_table) (abfd))
#define bfd_coff_symname_in_debug(abfd, sym)\
((coff_backend_info (abfd)->_bfd_coff_symname_in_debug) (abfd, sym))
#define bfd_coff_print_aux(abfd, file, base, symbol, aux, indaux)\
((coff_backend_info (abfd)->_bfd_coff_print_aux)\
(abfd, file, base, symbol, aux, indaux))
#define bfd_coff_reloc16_extra_cases(abfd, link_info, link_order, reloc, data, src_ptr, dst_ptr)\
((coff_backend_info (abfd)->_bfd_coff_reloc16_extra_cases)\
(abfd, link_info, link_order, reloc, data, src_ptr, dst_ptr))
#define bfd_coff_reloc16_estimate(abfd, section, reloc, shrink, link_info)\
((coff_backend_info (abfd)->_bfd_coff_reloc16_estimate)\
(abfd, section, reloc, shrink, link_info))
#define bfd_coff_classify_symbol(abfd, sym)\
((coff_backend_info (abfd)->_bfd_coff_classify_symbol)\
(abfd, sym))
#define bfd_coff_compute_section_file_positions(abfd)\
((coff_backend_info (abfd)->_bfd_coff_compute_section_file_positions)\
(abfd))
#define bfd_coff_start_final_link(obfd, info)\
((coff_backend_info (obfd)->_bfd_coff_start_final_link)\
(obfd, info))
#define bfd_coff_relocate_section(obfd,info,ibfd,o,con,rel,isyms,secs)\
((coff_backend_info (ibfd)->_bfd_coff_relocate_section)\
(obfd, info, ibfd, o, con, rel, isyms, secs))
#define bfd_coff_rtype_to_howto(abfd, sec, rel, h, sym, addendp)\
((coff_backend_info (abfd)->_bfd_coff_rtype_to_howto)\
(abfd, sec, rel, h, sym, addendp))
#define bfd_coff_adjust_symndx(obfd, info, ibfd, sec, rel, adjustedp)\
((coff_backend_info (abfd)->_bfd_coff_adjust_symndx)\
(obfd, info, ibfd, sec, rel, adjustedp))
#define bfd_coff_link_add_one_symbol(info,abfd,name,flags,section,value,string,cp,coll,hashp)\
((coff_backend_info (abfd)->_bfd_coff_link_add_one_symbol)\
(info, abfd, name, flags, section, value, string, cp, coll, hashp))
#define bfd_coff_link_output_has_begun(a,p) \
((coff_backend_info (a)->_bfd_coff_link_output_has_begun) (a,p))
#define bfd_coff_final_link_postscript(a,p) \
((coff_backend_info (a)->_bfd_coff_final_link_postscript) (a,p))
@end example
@subsubsection Writing relocations
To write relocations, the back end steps though the
canonical relocation table and create an
@code{internal_reloc}. The symbol index to use is removed from
the @code{offset} field in the symbol table supplied. The
address comes directly from the sum of the section base
address and the relocation offset; the type is dug directly
from the howto field. Then the @code{internal_reloc} is
swapped into the shape of an @code{external_reloc} and written
out to disk.
@subsubsection Reading linenumbers
Creating the linenumber table is done by reading in the entire
coff linenumber table, and creating another table for internal use.
A coff linenumber table is structured so that each function
is marked as having a line number of 0. Each line within the
function is an offset from the first line in the function. The
base of the line number information for the table is stored in
the symbol associated with the function.
Note: The PE format uses line number 0 for a flag indicating a
new source file.
The information is copied from the external to the internal
table, and each symbol which marks a function is marked by
pointing its...
How does this work ?
@subsubsection Reading relocations
Coff relocations are easily transformed into the internal BFD form
(@code{arelent}).
Reading a coff relocation table is done in the following stages:
@itemize @bullet
@item
Read the entire coff relocation table into memory.
@item
Process each relocation in turn; first swap it from the
external to the internal form.
@item
Turn the symbol referenced in the relocation's symbol index
into a pointer into the canonical symbol table.
This table is the same as the one returned by a call to
@code{bfd_canonicalize_symtab}. The back end will call that
routine and save the result if a canonicalization hasn't been done.
@item
The reloc index is turned into a pointer to a howto
structure, in a back end specific way. For instance, the 386
and 960 use the @code{r_type} to directly produce an index
into a howto table vector; the 88k subtracts a number from the
@code{r_type} field and creates an addend field.
@end itemize

38
bfd/doc/core.texi Normal file
View File

@@ -0,0 +1,38 @@
@section Core files
@strong{Description}@*
These are functions pertaining to core files.
@findex bfd_core_file_failing_command
@subsubsection @code{bfd_core_file_failing_command}
@strong{Synopsis}
@example
CONST char *bfd_core_file_failing_command(bfd *abfd);
@end example
@strong{Description}@*
Return a read-only string explaining which program was running
when it failed and produced the core file @var{abfd}.
@findex bfd_core_file_failing_signal
@subsubsection @code{bfd_core_file_failing_signal}
@strong{Synopsis}
@example
int bfd_core_file_failing_signal(bfd *abfd);
@end example
@strong{Description}@*
Returns the signal number which caused the core dump which
generated the file the BFD @var{abfd} is attached to.
@findex core_file_matches_executable_p
@subsubsection @code{core_file_matches_executable_p}
@strong{Synopsis}
@example
boolean core_file_matches_executable_p
(bfd *core_bfd, bfd *exec_bfd);
@end example
@strong{Description}@*
Return @code{true} if the core file attached to @var{core_bfd}
was generated by a run of the executable file attached to
@var{exec_bfd}, @code{false} otherwise.

22
bfd/doc/elf.texi Normal file
View File

@@ -0,0 +1,22 @@
@section ELF backends
BFD support for ELF formats is being worked on.
Currently, the best supported back ends are for sparc and i386
(running svr4 or Solaris 2).
Documentation of the internals of the support code still needs
to be written. The code is changing quickly enough that we
haven't bothered yet.
@findex bfd_elf_find_section
@subsubsection @code{bfd_elf_find_section}
@strong{Synopsis}
@example
struct elf_internal_shdr *bfd_elf_find_section (bfd *abfd, char *name);
@end example
@strong{Description}@*
Helper functions for GDB to locate the string tables.
Since BFD hides string tables from callers, GDB needs to use an
internal hook to find them. Sun's .stabstr, in particular,
isn't even pointed to by the .stab section, so ordinary
mechanisms wouldn't work to find it, even if we had some.

0
bfd/doc/elfcode.texi Normal file
View File

108
bfd/doc/format.texi Normal file
View File

@@ -0,0 +1,108 @@
@section File formats
A format is a BFD concept of high level file contents type. The
formats supported by BFD are:
@itemize @bullet
@item
@code{bfd_object}
@end itemize
The BFD may contain data, symbols, relocations and debug info.
@itemize @bullet
@item
@code{bfd_archive}
@end itemize
The BFD contains other BFDs and an optional index.
@itemize @bullet
@item
@code{bfd_core}
@end itemize
The BFD contains the result of an executable core dump.
@findex bfd_check_format
@subsubsection @code{bfd_check_format}
@strong{Synopsis}
@example
boolean bfd_check_format(bfd *abfd, bfd_format format);
@end example
@strong{Description}@*
Verify if the file attached to the BFD @var{abfd} is compatible
with the format @var{format} (i.e., one of @code{bfd_object},
@code{bfd_archive} or @code{bfd_core}).
If the BFD has been set to a specific target before the
call, only the named target and format combination is
checked. If the target has not been set, or has been set to
@code{default}, then all the known target backends is
interrogated to determine a match. If the default target
matches, it is used. If not, exactly one target must recognize
the file, or an error results.
The function returns @code{true} on success, otherwise @code{false}
with one of the following error codes:
@itemize @bullet
@item
@code{bfd_error_invalid_operation} -
if @code{format} is not one of @code{bfd_object}, @code{bfd_archive} or
@code{bfd_core}.
@item
@code{bfd_error_system_call} -
if an error occured during a read - even some file mismatches
can cause bfd_error_system_calls.
@item
@code{file_not_recognised} -
none of the backends recognised the file format.
@item
@code{bfd_error_file_ambiguously_recognized} -
more than one backend recognised the file format.
@end itemize
@findex bfd_check_format_matches
@subsubsection @code{bfd_check_format_matches}
@strong{Synopsis}
@example
boolean bfd_check_format_matches(bfd *abfd, bfd_format format, char ***matching);
@end example
@strong{Description}@*
Like @code{bfd_check_format}, except when it returns false with
@code{bfd_errno} set to @code{bfd_error_file_ambiguously_recognized}. In that
case, if @var{matching} is not NULL, it will be filled in with
a NULL-terminated list of the names of the formats that matched,
allocated with @code{malloc}.
Then the user may choose a format and try again.
When done with the list that @var{matching} points to, the caller
should free it.
@findex bfd_set_format
@subsubsection @code{bfd_set_format}
@strong{Synopsis}
@example
boolean bfd_set_format(bfd *abfd, bfd_format format);
@end example
@strong{Description}@*
This function sets the file format of the BFD @var{abfd} to the
format @var{format}. If the target set in the BFD does not
support the format requested, the format is invalid, or the BFD
is not open for writing, then an error occurs.
@findex bfd_format_string
@subsubsection @code{bfd_format_string}
@strong{Synopsis}
@example
CONST char *bfd_format_string(bfd_format format);
@end example
@strong{Description}@*
Return a pointer to a const string
@code{invalid}, @code{object}, @code{archive}, @code{core}, or @code{unknown},
depending upon the value of @var{format}.

245
bfd/doc/hash.texi Normal file
View File

@@ -0,0 +1,245 @@
@section Hash Tables
@cindex Hash tables
BFD provides a simple set of hash table functions. Routines
are provided to initialize a hash table, to free a hash table,
to look up a string in a hash table and optionally create an
entry for it, and to traverse a hash table. There is
currently no routine to delete an string from a hash table.
The basic hash table does not permit any data to be stored
with a string. However, a hash table is designed to present a
base class from which other types of hash tables may be
derived. These derived types may store additional information
with the string. Hash tables were implemented in this way,
rather than simply providing a data pointer in a hash table
entry, because they were designed for use by the linker back
ends. The linker may create thousands of hash table entries,
and the overhead of allocating private data and storing and
following pointers becomes noticeable.
The basic hash table code is in @code{hash.c}.
@menu
* Creating and Freeing a Hash Table::
* Looking Up or Entering a String::
* Traversing a Hash Table::
* Deriving a New Hash Table Type::
@end menu
@node Creating and Freeing a Hash Table, Looking Up or Entering a String, Hash Tables, Hash Tables
@subsection Creating and freeing a hash table
@findex bfd_hash_table_init
@findex bfd_hash_table_init_n
To create a hash table, create an instance of a @code{struct
bfd_hash_table} (defined in @code{bfd.h}) and call
@code{bfd_hash_table_init} (if you know approximately how many
entries you will need, the function @code{bfd_hash_table_init_n},
which takes a @var{size} argument, may be used).
@code{bfd_hash_table_init} returns @code{false} if some sort of
error occurs.
@findex bfd_hash_newfunc
The function @code{bfd_hash_table_init} take as an argument a
function to use to create new entries. For a basic hash
table, use the function @code{bfd_hash_newfunc}. @xref{Deriving
a New Hash Table Type}, for why you would want to use a
different value for this argument.
@findex bfd_hash_allocate
@code{bfd_hash_table_init} will create an objalloc which will be
used to allocate new entries. You may allocate memory on this
objalloc using @code{bfd_hash_allocate}.
@findex bfd_hash_table_free
Use @code{bfd_hash_table_free} to free up all the memory that has
been allocated for a hash table. This will not free up the
@code{struct bfd_hash_table} itself, which you must provide.
@node Looking Up or Entering a String, Traversing a Hash Table, Creating and Freeing a Hash Table, Hash Tables
@subsection Looking up or entering a string
@findex bfd_hash_lookup
The function @code{bfd_hash_lookup} is used both to look up a
string in the hash table and to create a new entry.
If the @var{create} argument is @code{false}, @code{bfd_hash_lookup}
will look up a string. If the string is found, it will
returns a pointer to a @code{struct bfd_hash_entry}. If the
string is not found in the table @code{bfd_hash_lookup} will
return @code{NULL}. You should not modify any of the fields in
the returns @code{struct bfd_hash_entry}.
If the @var{create} argument is @code{true}, the string will be
entered into the hash table if it is not already there.
Either way a pointer to a @code{struct bfd_hash_entry} will be
returned, either to the existing structure or to a newly
created one. In this case, a @code{NULL} return means that an
error occurred.
If the @var{create} argument is @code{true}, and a new entry is
created, the @var{copy} argument is used to decide whether to
copy the string onto the hash table objalloc or not. If
@var{copy} is passed as @code{false}, you must be careful not to
deallocate or modify the string as long as the hash table
exists.
@node Traversing a Hash Table, Deriving a New Hash Table Type, Looking Up or Entering a String, Hash Tables
@subsection Traversing a hash table
@findex bfd_hash_traverse
The function @code{bfd_hash_traverse} may be used to traverse a
hash table, calling a function on each element. The traversal
is done in a random order.
@code{bfd_hash_traverse} takes as arguments a function and a
generic @code{void *} pointer. The function is called with a
hash table entry (a @code{struct bfd_hash_entry *}) and the
generic pointer passed to @code{bfd_hash_traverse}. The function
must return a @code{boolean} value, which indicates whether to
continue traversing the hash table. If the function returns
@code{false}, @code{bfd_hash_traverse} will stop the traversal and
return immediately.
@node Deriving a New Hash Table Type, , Traversing a Hash Table, Hash Tables
@subsection Deriving a new hash table type
Many uses of hash tables want to store additional information
which each entry in the hash table. Some also find it
convenient to store additional information with the hash table
itself. This may be done using a derived hash table.
Since C is not an object oriented language, creating a derived
hash table requires sticking together some boilerplate
routines with a few differences specific to the type of hash
table you want to create.
An example of a derived hash table is the linker hash table.
The structures for this are defined in @code{bfdlink.h}. The
functions are in @code{linker.c}.
You may also derive a hash table from an already derived hash
table. For example, the a.out linker backend code uses a hash
table derived from the linker hash table.
@menu
* Define the Derived Structures::
* Write the Derived Creation Routine::
* Write Other Derived Routines::
@end menu
@node Define the Derived Structures, Write the Derived Creation Routine, Deriving a New Hash Table Type, Deriving a New Hash Table Type
@subsubsection Define the derived structures
You must define a structure for an entry in the hash table,
and a structure for the hash table itself.
The first field in the structure for an entry in the hash
table must be of the type used for an entry in the hash table
you are deriving from. If you are deriving from a basic hash
table this is @code{struct bfd_hash_entry}, which is defined in
@code{bfd.h}. The first field in the structure for the hash
table itself must be of the type of the hash table you are
deriving from itself. If you are deriving from a basic hash
table, this is @code{struct bfd_hash_table}.
For example, the linker hash table defines @code{struct
bfd_link_hash_entry} (in @code{bfdlink.h}). The first field,
@code{root}, is of type @code{struct bfd_hash_entry}. Similarly,
the first field in @code{struct bfd_link_hash_table}, @code{table},
is of type @code{struct bfd_hash_table}.
@node Write the Derived Creation Routine, Write Other Derived Routines, Define the Derived Structures, Deriving a New Hash Table Type
@subsubsection Write the derived creation routine
You must write a routine which will create and initialize an
entry in the hash table. This routine is passed as the
function argument to @code{bfd_hash_table_init}.
In order to permit other hash tables to be derived from the
hash table you are creating, this routine must be written in a
standard way.
The first argument to the creation routine is a pointer to a
hash table entry. This may be @code{NULL}, in which case the
routine should allocate the right amount of space. Otherwise
the space has already been allocated by a hash table type
derived from this one.
After allocating space, the creation routine must call the
creation routine of the hash table type it is derived from,
passing in a pointer to the space it just allocated. This
will initialize any fields used by the base hash table.
Finally the creation routine must initialize any local fields
for the new hash table type.
Here is a boilerplate example of a creation routine.
@var{function_name} is the name of the routine.
@var{entry_type} is the type of an entry in the hash table you
are creating. @var{base_newfunc} is the name of the creation
routine of the hash table type your hash table is derived
from.
@example
struct bfd_hash_entry *
@var{function_name} (entry, table, string)
struct bfd_hash_entry *entry;
struct bfd_hash_table *table;
const char *string;
@{
struct @var{entry_type} *ret = (@var{entry_type} *) entry;
/* Allocate the structure if it has not already been allocated by a
derived class. */
if (ret == (@var{entry_type} *) NULL)
@{
ret = ((@var{entry_type} *)
bfd_hash_allocate (table, sizeof (@var{entry_type})));
if (ret == (@var{entry_type} *) NULL)
return NULL;
@}
/* Call the allocation method of the base class. */
ret = ((@var{entry_type} *)
@var{base_newfunc} ((struct bfd_hash_entry *) ret, table, string));
/* Initialize the local fields here. */
return (struct bfd_hash_entry *) ret;
@}
@end example
@strong{Description}@*
The creation routine for the linker hash table, which is in
@code{linker.c}, looks just like this example.
@var{function_name} is @code{_bfd_link_hash_newfunc}.
@var{entry_type} is @code{struct bfd_link_hash_entry}.
@var{base_newfunc} is @code{bfd_hash_newfunc}, the creation
routine for a basic hash table.
@code{_bfd_link_hash_newfunc} also initializes the local fields
in a linker hash table entry: @code{type}, @code{written} and
@code{next}.
@node Write Other Derived Routines, , Write the Derived Creation Routine, Deriving a New Hash Table Type
@subsubsection Write other derived routines
You will want to write other routines for your new hash table,
as well.
You will want an initialization routine which calls the
initialization routine of the hash table you are deriving from
and initializes any other local fields. For the linker hash
table, this is @code{_bfd_link_hash_table_init} in @code{linker.c}.
You will want a lookup routine which calls the lookup routine
of the hash table you are deriving from and casts the result.
The linker hash table uses @code{bfd_link_hash_lookup} in
@code{linker.c} (this actually takes an additional argument which
it uses to decide how to return the looked up value).
You may want a traversal routine. This should just call the
traversal routine of the hash table you are deriving from with
appropriate casts. The linker hash table uses
@code{bfd_link_hash_traverse} in @code{linker.c}.
These routines may simply be defined as macros. For example,
the a.out backend linker hash table, which is derived from the
linker hash table, uses macros for the lookup and traversal
routines. These are @code{aout_link_hash_lookup} and
@code{aout_link_hash_traverse} in aoutx.h.

13
bfd/doc/init.texi Normal file
View File

@@ -0,0 +1,13 @@
@section Initialization
These are the functions that handle initializing a BFD.
@findex bfd_init
@subsubsection @code{bfd_init}
@strong{Synopsis}
@example
void bfd_init(void);
@end example
@strong{Description}@*
This routine must be called before any other BFD function to
initialize magical internal data structures.

156
bfd/doc/libbfd.texi Normal file
View File

@@ -0,0 +1,156 @@
@section Internal functions
@strong{Description}@*
These routines are used within BFD.
They are not intended for export, but are documented here for
completeness.
@findex bfd_write_bigendian_4byte_int
@subsubsection @code{bfd_write_bigendian_4byte_int}
@strong{Synopsis}
@example
void bfd_write_bigendian_4byte_int(bfd *abfd, int i);
@end example
@strong{Description}@*
Write a 4 byte integer @var{i} to the output BFD @var{abfd}, in big
endian order regardless of what else is going on. This is useful in
archives.
@findex bfd_put_size
@subsubsection @code{bfd_put_size}
@findex bfd_get_size
@subsubsection @code{bfd_get_size}
@strong{Description}@*
These macros as used for reading and writing raw data in
sections; each access (except for bytes) is vectored through
the target format of the BFD and mangled accordingly. The
mangling performs any necessary endian translations and
removes alignment restrictions. Note that types accepted and
returned by these macros are identical so they can be swapped
around in macros---for example, @file{libaout.h} defines @code{GET_WORD}
to either @code{bfd_get_32} or @code{bfd_get_64}.
In the put routines, @var{val} must be a @code{bfd_vma}. If we are on a
system without prototypes, the caller is responsible for making
sure that is true, with a cast if necessary. We don't cast
them in the macro definitions because that would prevent @code{lint}
or @code{gcc -Wall} from detecting sins such as passing a pointer.
To detect calling these with less than a @code{bfd_vma}, use
@code{gcc -Wconversion} on a host with 64 bit @code{bfd_vma}'s.
@example
/* Byte swapping macros for user section data. */
#define bfd_put_8(abfd, val, ptr) \
((void) (*((unsigned char *)(ptr)) = (unsigned char)(val)))
#define bfd_put_signed_8 \
bfd_put_8
#define bfd_get_8(abfd, ptr) \
(*(unsigned char *)(ptr))
#define bfd_get_signed_8(abfd, ptr) \
((*(unsigned char *)(ptr) ^ 0x80) - 0x80)
#define bfd_put_16(abfd, val, ptr) \
BFD_SEND(abfd, bfd_putx16, ((val),(ptr)))
#define bfd_put_signed_16 \
bfd_put_16
#define bfd_get_16(abfd, ptr) \
BFD_SEND(abfd, bfd_getx16, (ptr))
#define bfd_get_signed_16(abfd, ptr) \
BFD_SEND (abfd, bfd_getx_signed_16, (ptr))
#define bfd_put_32(abfd, val, ptr) \
BFD_SEND(abfd, bfd_putx32, ((val),(ptr)))
#define bfd_put_signed_32 \
bfd_put_32
#define bfd_get_32(abfd, ptr) \
BFD_SEND(abfd, bfd_getx32, (ptr))
#define bfd_get_signed_32(abfd, ptr) \
BFD_SEND(abfd, bfd_getx_signed_32, (ptr))
#define bfd_put_64(abfd, val, ptr) \
BFD_SEND(abfd, bfd_putx64, ((val), (ptr)))
#define bfd_put_signed_64 \
bfd_put_64
#define bfd_get_64(abfd, ptr) \
BFD_SEND(abfd, bfd_getx64, (ptr))
#define bfd_get_signed_64(abfd, ptr) \
BFD_SEND(abfd, bfd_getx_signed_64, (ptr))
#define bfd_get(bits, abfd, ptr) \
((bits) == 8 ? bfd_get_8 (abfd, ptr) \
: (bits) == 16 ? bfd_get_16 (abfd, ptr) \
: (bits) == 32 ? bfd_get_32 (abfd, ptr) \
: (bits) == 64 ? bfd_get_64 (abfd, ptr) \
: (abort (), (bfd_vma) - 1))
#define bfd_put(bits, abfd, val, ptr) \
((bits) == 8 ? bfd_put_8 (abfd, val, ptr) \
: (bits) == 16 ? bfd_put_16 (abfd, val, ptr) \
: (bits) == 32 ? bfd_put_32 (abfd, val, ptr) \
: (bits) == 64 ? bfd_put_64 (abfd, val, ptr) \
: (abort (), (void) 0))
@end example
@findex bfd_h_put_size
@subsubsection @code{bfd_h_put_size}
@strong{Description}@*
These macros have the same function as their @code{bfd_get_x}
bretheren, except that they are used for removing information
for the header records of object files. Believe it or not,
some object files keep their header records in big endian
order and their data in little endian order.
@example
/* Byte swapping macros for file header data. */
#define bfd_h_put_8(abfd, val, ptr) \
bfd_put_8 (abfd, val, ptr)
#define bfd_h_put_signed_8(abfd, val, ptr) \
bfd_put_8 (abfd, val, ptr)
#define bfd_h_get_8(abfd, ptr) \
bfd_get_8 (abfd, ptr)
#define bfd_h_get_signed_8(abfd, ptr) \
bfd_get_signed_8 (abfd, ptr)
#define bfd_h_put_16(abfd, val, ptr) \
BFD_SEND(abfd, bfd_h_putx16,(val,ptr))
#define bfd_h_put_signed_16 \
bfd_h_put_16
#define bfd_h_get_16(abfd, ptr) \
BFD_SEND(abfd, bfd_h_getx16,(ptr))
#define bfd_h_get_signed_16(abfd, ptr) \
BFD_SEND(abfd, bfd_h_getx_signed_16, (ptr))
#define bfd_h_put_32(abfd, val, ptr) \
BFD_SEND(abfd, bfd_h_putx32,(val,ptr))
#define bfd_h_put_signed_32 \
bfd_h_put_32
#define bfd_h_get_32(abfd, ptr) \
BFD_SEND(abfd, bfd_h_getx32,(ptr))
#define bfd_h_get_signed_32(abfd, ptr) \
BFD_SEND(abfd, bfd_h_getx_signed_32, (ptr))
#define bfd_h_put_64(abfd, val, ptr) \
BFD_SEND(abfd, bfd_h_putx64,(val, ptr))
#define bfd_h_put_signed_64 \
bfd_h_put_64
#define bfd_h_get_64(abfd, ptr) \
BFD_SEND(abfd, bfd_h_getx64,(ptr))
#define bfd_h_get_signed_64(abfd, ptr) \
BFD_SEND(abfd, bfd_h_getx_signed_64, (ptr))
@end example
@findex bfd_log2
@subsubsection @code{bfd_log2}
@strong{Synopsis}
@example
unsigned int bfd_log2(bfd_vma x);
@end example
@strong{Description}@*
Return the log base 2 of the value supplied, rounded up. E.g., an
@var{x} of 1025 returns 11.

365
bfd/doc/linker.texi Normal file
View File

@@ -0,0 +1,365 @@
@section Linker Functions
@cindex Linker
The linker uses three special entry points in the BFD target
vector. It is not necessary to write special routines for
these entry points when creating a new BFD back end, since
generic versions are provided. However, writing them can
speed up linking and make it use significantly less runtime
memory.
The first routine creates a hash table used by the other
routines. The second routine adds the symbols from an object
file to the hash table. The third routine takes all the
object files and links them together to create the output
file. These routines are designed so that the linker proper
does not need to know anything about the symbols in the object
files that it is linking. The linker merely arranges the
sections as directed by the linker script and lets BFD handle
the details of symbols and relocs.
The second routine and third routines are passed a pointer to
a @code{struct bfd_link_info} structure (defined in
@code{bfdlink.h}) which holds information relevant to the link,
including the linker hash table (which was created by the
first routine) and a set of callback functions to the linker
proper.
The generic linker routines are in @code{linker.c}, and use the
header file @code{genlink.h}. As of this writing, the only back
ends which have implemented versions of these routines are
a.out (in @code{aoutx.h}) and ECOFF (in @code{ecoff.c}). The a.out
routines are used as examples throughout this section.
@menu
* Creating a Linker Hash Table::
* Adding Symbols to the Hash Table::
* Performing the Final Link::
@end menu
@node Creating a Linker Hash Table, Adding Symbols to the Hash Table, Linker Functions, Linker Functions
@subsection Creating a linker hash table
@cindex _bfd_link_hash_table_create in target vector
@cindex target vector (_bfd_link_hash_table_create)
The linker routines must create a hash table, which must be
derived from @code{struct bfd_link_hash_table} described in
@code{bfdlink.c}. @xref{Hash Tables}, for information on how to
create a derived hash table. This entry point is called using
the target vector of the linker output file.
The @code{_bfd_link_hash_table_create} entry point must allocate
and initialize an instance of the desired hash table. If the
back end does not require any additional information to be
stored with the entries in the hash table, the entry point may
simply create a @code{struct bfd_link_hash_table}. Most likely,
however, some additional information will be needed.
For example, with each entry in the hash table the a.out
linker keeps the index the symbol has in the final output file
(this index number is used so that when doing a relocateable
link the symbol index used in the output file can be quickly
filled in when copying over a reloc). The a.out linker code
defines the required structures and functions for a hash table
derived from @code{struct bfd_link_hash_table}. The a.out linker
hash table is created by the function
@code{NAME(aout,link_hash_table_create)}; it simply allocates
space for the hash table, initializes it, and returns a
pointer to it.
When writing the linker routines for a new back end, you will
generally not know exactly which fields will be required until
you have finished. You should simply create a new hash table
which defines no additional fields, and then simply add fields
as they become necessary.
@node Adding Symbols to the Hash Table, Performing the Final Link, Creating a Linker Hash Table, Linker Functions
@subsection Adding symbols to the hash table
@cindex _bfd_link_add_symbols in target vector
@cindex target vector (_bfd_link_add_symbols)
The linker proper will call the @code{_bfd_link_add_symbols}
entry point for each object file or archive which is to be
linked (typically these are the files named on the command
line, but some may also come from the linker script). The
entry point is responsible for examining the file. For an
object file, BFD must add any relevant symbol information to
the hash table. For an archive, BFD must determine which
elements of the archive should be used and adding them to the
link.
The a.out version of this entry point is
@code{NAME(aout,link_add_symbols)}.
@menu
* Differing file formats::
* Adding symbols from an object file::
* Adding symbols from an archive::
@end menu
@node Differing file formats, Adding symbols from an object file, Adding Symbols to the Hash Table, Adding Symbols to the Hash Table
@subsubsection Differing file formats
Normally all the files involved in a link will be of the same
format, but it is also possible to link together different
format object files, and the back end must support that. The
@code{_bfd_link_add_symbols} entry point is called via the target
vector of the file to be added. This has an important
consequence: the function may not assume that the hash table
is the type created by the corresponding
@code{_bfd_link_hash_table_create} vector. All the
@code{_bfd_link_add_symbols} function can assume about the hash
table is that it is derived from @code{struct
bfd_link_hash_table}.
Sometimes the @code{_bfd_link_add_symbols} function must store
some information in the hash table entry to be used by the
@code{_bfd_final_link} function. In such a case the @code{creator}
field of the hash table must be checked to make sure that the
hash table was created by an object file of the same format.
The @code{_bfd_final_link} routine must be prepared to handle a
hash entry without any extra information added by the
@code{_bfd_link_add_symbols} function. A hash entry without
extra information will also occur when the linker script
directs the linker to create a symbol. Note that, regardless
of how a hash table entry is added, all the fields will be
initialized to some sort of null value by the hash table entry
initialization function.
See @code{ecoff_link_add_externals} for an example of how to
check the @code{creator} field before saving information (in this
case, the ECOFF external symbol debugging information) in a
hash table entry.
@node Adding symbols from an object file, Adding symbols from an archive, Differing file formats, Adding Symbols to the Hash Table
@subsubsection Adding symbols from an object file
When the @code{_bfd_link_add_symbols} routine is passed an object
file, it must add all externally visible symbols in that
object file to the hash table. The actual work of adding the
symbol to the hash table is normally handled by the function
@code{_bfd_generic_link_add_one_symbol}. The
@code{_bfd_link_add_symbols} routine is responsible for reading
all the symbols from the object file and passing the correct
information to @code{_bfd_generic_link_add_one_symbol}.
The @code{_bfd_link_add_symbols} routine should not use
@code{bfd_canonicalize_symtab} to read the symbols. The point of
providing this routine is to avoid the overhead of converting
the symbols into generic @code{asymbol} structures.
@findex _bfd_generic_link_add_one_symbol
@code{_bfd_generic_link_add_one_symbol} handles the details of
combining common symbols, warning about multiple definitions,
and so forth. It takes arguments which describe the symbol to
add, notably symbol flags, a section, and an offset. The
symbol flags include such things as @code{BSF_WEAK} or
@code{BSF_INDIRECT}. The section is a section in the object
file, or something like @code{bfd_und_section_ptr} for an undefined
symbol or @code{bfd_com_section_ptr} for a common symbol.
If the @code{_bfd_final_link} routine is also going to need to
read the symbol information, the @code{_bfd_link_add_symbols}
routine should save it somewhere attached to the object file
BFD. However, the information should only be saved if the
@code{keep_memory} field of the @code{info} argument is true, so
that the @code{-no-keep-memory} linker switch is effective.
The a.out function which adds symbols from an object file is
@code{aout_link_add_object_symbols}, and most of the interesting
work is in @code{aout_link_add_symbols}. The latter saves
pointers to the hash tables entries created by
@code{_bfd_generic_link_add_one_symbol} indexed by symbol number,
so that the @code{_bfd_final_link} routine does not have to call
the hash table lookup routine to locate the entry.
@node Adding symbols from an archive, , Adding symbols from an object file, Adding Symbols to the Hash Table
@subsubsection Adding symbols from an archive
When the @code{_bfd_link_add_symbols} routine is passed an
archive, it must look through the symbols defined by the
archive and decide which elements of the archive should be
included in the link. For each such element it must call the
@code{add_archive_element} linker callback, and it must add the
symbols from the object file to the linker hash table.
@findex _bfd_generic_link_add_archive_symbols
In most cases the work of looking through the symbols in the
archive should be done by the
@code{_bfd_generic_link_add_archive_symbols} function. This
function builds a hash table from the archive symbol table and
looks through the list of undefined symbols to see which
elements should be included.
@code{_bfd_generic_link_add_archive_symbols} is passed a function
to call to make the final decision about adding an archive
element to the link and to do the actual work of adding the
symbols to the linker hash table.
The function passed to
@code{_bfd_generic_link_add_archive_symbols} must read the
symbols of the archive element and decide whether the archive
element should be included in the link. If the element is to
be included, the @code{add_archive_element} linker callback
routine must be called with the element as an argument, and
the elements symbols must be added to the linker hash table
just as though the element had itself been passed to the
@code{_bfd_link_add_symbols} function.
When the a.out @code{_bfd_link_add_symbols} function receives an
archive, it calls @code{_bfd_generic_link_add_archive_symbols}
passing @code{aout_link_check_archive_element} as the function
argument. @code{aout_link_check_archive_element} calls
@code{aout_link_check_ar_symbols}. If the latter decides to add
the element (an element is only added if it provides a real,
non-common, definition for a previously undefined or common
symbol) it calls the @code{add_archive_element} callback and then
@code{aout_link_check_archive_element} calls
@code{aout_link_add_symbols} to actually add the symbols to the
linker hash table.
The ECOFF back end is unusual in that it does not normally
call @code{_bfd_generic_link_add_archive_symbols}, because ECOFF
archives already contain a hash table of symbols. The ECOFF
back end searches the archive itself to avoid the overhead of
creating a new hash table.
@node Performing the Final Link, , Adding Symbols to the Hash Table, Linker Functions
@subsection Performing the final link
@cindex _bfd_link_final_link in target vector
@cindex target vector (_bfd_final_link)
When all the input files have been processed, the linker calls
the @code{_bfd_final_link} entry point of the output BFD. This
routine is responsible for producing the final output file,
which has several aspects. It must relocate the contents of
the input sections and copy the data into the output sections.
It must build an output symbol table including any local
symbols from the input files and the global symbols from the
hash table. When producing relocateable output, it must
modify the input relocs and write them into the output file.
There may also be object format dependent work to be done.
The linker will also call the @code{write_object_contents} entry
point when the BFD is closed. The two entry points must work
together in order to produce the correct output file.
The details of how this works are inevitably dependent upon
the specific object file format. The a.out
@code{_bfd_final_link} routine is @code{NAME(aout,final_link)}.
@menu
* Information provided by the linker::
* Relocating the section contents::
* Writing the symbol table::
@end menu
@node Information provided by the linker, Relocating the section contents, Performing the Final Link, Performing the Final Link
@subsubsection Information provided by the linker
Before the linker calls the @code{_bfd_final_link} entry point,
it sets up some data structures for the function to use.
The @code{input_bfds} field of the @code{bfd_link_info} structure
will point to a list of all the input files included in the
link. These files are linked through the @code{link_next} field
of the @code{bfd} structure.
Each section in the output file will have a list of
@code{link_order} structures attached to the @code{link_order_head}
field (the @code{link_order} structure is defined in
@code{bfdlink.h}). These structures describe how to create the
contents of the output section in terms of the contents of
various input sections, fill constants, and, eventually, other
types of information. They also describe relocs that must be
created by the BFD backend, but do not correspond to any input
file; this is used to support -Ur, which builds constructors
while generating a relocateable object file.
@node Relocating the section contents, Writing the symbol table, Information provided by the linker, Performing the Final Link
@subsubsection Relocating the section contents
The @code{_bfd_final_link} function should look through the
@code{link_order} structures attached to each section of the
output file. Each @code{link_order} structure should either be
handled specially, or it should be passed to the function
@code{_bfd_default_link_order} which will do the right thing
(@code{_bfd_default_link_order} is defined in @code{linker.c}).
For efficiency, a @code{link_order} of type
@code{bfd_indirect_link_order} whose associated section belongs
to a BFD of the same format as the output BFD must be handled
specially. This type of @code{link_order} describes part of an
output section in terms of a section belonging to one of the
input files. The @code{_bfd_final_link} function should read the
contents of the section and any associated relocs, apply the
relocs to the section contents, and write out the modified
section contents. If performing a relocateable link, the
relocs themselves must also be modified and written out.
@findex _bfd_relocate_contents
@findex _bfd_final_link_relocate
The functions @code{_bfd_relocate_contents} and
@code{_bfd_final_link_relocate} provide some general support for
performing the actual relocations, notably overflow checking.
Their arguments include information about the symbol the
relocation is against and a @code{reloc_howto_type} argument
which describes the relocation to perform. These functions
are defined in @code{reloc.c}.
The a.out function which handles reading, relocating, and
writing section contents is @code{aout_link_input_section}. The
actual relocation is done in @code{aout_link_input_section_std}
and @code{aout_link_input_section_ext}.
@node Writing the symbol table, , Relocating the section contents, Performing the Final Link
@subsubsection Writing the symbol table
The @code{_bfd_final_link} function must gather all the symbols
in the input files and write them out. It must also write out
all the symbols in the global hash table. This must be
controlled by the @code{strip} and @code{discard} fields of the
@code{bfd_link_info} structure.
The local symbols of the input files will not have been
entered into the linker hash table. The @code{_bfd_final_link}
routine must consider each input file and include the symbols
in the output file. It may be convenient to do this when
looking through the @code{link_order} structures, or it may be
done by stepping through the @code{input_bfds} list.
The @code{_bfd_final_link} routine must also traverse the global
hash table to gather all the externally visible symbols. It
is possible that most of the externally visible symbols may be
written out when considering the symbols of each input file,
but it is still necessary to traverse the hash table since the
linker script may have defined some symbols that are not in
any of the input files.
The @code{strip} field of the @code{bfd_link_info} structure
controls which symbols are written out. The possible values
are listed in @code{bfdlink.h}. If the value is @code{strip_some},
then the @code{keep_hash} field of the @code{bfd_link_info}
structure is a hash table of symbols to keep; each symbol
should be looked up in this hash table, and only symbols which
are present should be included in the output file.
If the @code{strip} field of the @code{bfd_link_info} structure
permits local symbols to be written out, the @code{discard} field
is used to further controls which local symbols are included
in the output file. If the value is @code{discard_l}, then all
local symbols which begin with a certain prefix are discarded;
this is controlled by the @code{bfd_is_local_label_name} entry point.
The a.out backend handles symbols by calling
@code{aout_link_write_symbols} on each input BFD and then
traversing the global hash table with the function
@code{aout_link_write_other_symbol}. It builds a string table
while writing out the symbols, which is written to the output
file at the end of @code{NAME(aout,final_link)}.
@findex bfd_link_split_section
@subsubsection @code{bfd_link_split_section}
@strong{Synopsis}
@example
boolean bfd_link_split_section(bfd *abfd, asection *sec);
@end example
@strong{Description}@*
Return nonzero if @var{sec} should be split during a
reloceatable or final link.
@example
#define bfd_link_split_section(abfd, sec) \
BFD_SEND (abfd, _bfd_link_split_section, (abfd, sec))
@end example

159
bfd/doc/opncls.texi Normal file
View File

@@ -0,0 +1,159 @@
@section Opening and closing BFDs
@findex bfd_openr
@subsubsection @code{bfd_openr}
@strong{Synopsis}
@example
bfd *bfd_openr(CONST char *filename, CONST char *target);
@end example
@strong{Description}@*
Open the file @var{filename} (using @code{fopen}) with the target
@var{target}. Return a pointer to the created BFD.
Calls @code{bfd_find_target}, so @var{target} is interpreted as by
that function.
If @code{NULL} is returned then an error has occured. Possible errors
are @code{bfd_error_no_memory}, @code{bfd_error_invalid_target} or @code{system_call} error.
@findex bfd_fdopenr
@subsubsection @code{bfd_fdopenr}
@strong{Synopsis}
@example
bfd *bfd_fdopenr(CONST char *filename, CONST char *target, int fd);
@end example
@strong{Description}@*
@code{bfd_fdopenr} is to @code{bfd_fopenr} much like @code{fdopen} is to @code{fopen}.
It opens a BFD on a file already described by the @var{fd}
supplied.
When the file is later @code{bfd_close}d, the file descriptor will be closed.
If the caller desires that this file descriptor be cached by BFD
(opened as needed, closed as needed to free descriptors for
other opens), with the supplied @var{fd} used as an initial
file descriptor (but subject to closure at any time), call
bfd_set_cacheable(bfd, 1) on the returned BFD. The default is to
assume no cacheing; the file descriptor will remain open until
@code{bfd_close}, and will not be affected by BFD operations on other
files.
Possible errors are @code{bfd_error_no_memory}, @code{bfd_error_invalid_target} and @code{bfd_error_system_call}.
@findex bfd_openstreamr
@subsubsection @code{bfd_openstreamr}
@strong{Synopsis}
@example
bfd *bfd_openstreamr(const char *, const char *, PTR);
@end example
@strong{Description}@*
Open a BFD for read access on an existing stdio stream. When
the BFD is passed to @code{bfd_close}, the stream will be closed.
@findex bfd_openw
@subsubsection @code{bfd_openw}
@strong{Synopsis}
@example
bfd *bfd_openw(CONST char *filename, CONST char *target);
@end example
@strong{Description}@*
Create a BFD, associated with file @var{filename}, using the
file format @var{target}, and return a pointer to it.
Possible errors are @code{bfd_error_system_call}, @code{bfd_error_no_memory},
@code{bfd_error_invalid_target}.
@findex bfd_close
@subsubsection @code{bfd_close}
@strong{Synopsis}
@example
boolean bfd_close(bfd *abfd);
@end example
@strong{Description}@*
Close a BFD. If the BFD was open for writing,
then pending operations are completed and the file written out
and closed. If the created file is executable, then
@code{chmod} is called to mark it as such.
All memory attached to the BFD is released.
The file descriptor associated with the BFD is closed (even
if it was passed in to BFD by @code{bfd_fdopenr}).
@strong{Returns}@*
@code{true} is returned if all is ok, otherwise @code{false}.
@findex bfd_close_all_done
@subsubsection @code{bfd_close_all_done}
@strong{Synopsis}
@example
boolean bfd_close_all_done(bfd *);
@end example
@strong{Description}@*
Close a BFD. Differs from @code{bfd_close}
since it does not complete any pending operations. This
routine would be used if the application had just used BFD for
swapping and didn't want to use any of the writing code.
If the created file is executable, then @code{chmod} is called
to mark it as such.
All memory attached to the BFD is released.
@strong{Returns}@*
@code{true} is returned if all is ok, otherwise @code{false}.
@findex bfd_create
@subsubsection @code{bfd_create}
@strong{Synopsis}
@example
bfd *bfd_create(CONST char *filename, bfd *templ);
@end example
@strong{Description}@*
Create a new BFD in the manner of
@code{bfd_openw}, but without opening a file. The new BFD
takes the target from the target used by @var{template}. The
format is always set to @code{bfd_object}.
@findex bfd_make_writable
@subsubsection @code{bfd_make_writable}
@strong{Synopsis}
@example
boolean bfd_make_writable(bfd *abfd);
@end example
@strong{Description}@*
Takes a BFD as created by @code{bfd_create} and converts it
into one like as returned by @code{bfd_openw}. It does this
by converting the BFD to BFD_IN_MEMORY. It's assumed that
you will call @code{bfd_make_readable} on this bfd later.
@strong{Returns}@*
@code{true} is returned if all is ok, otherwise @code{false}.
@findex bfd_make_readable
@subsubsection @code{bfd_make_readable}
@strong{Synopsis}
@example
boolean bfd_make_readable(bfd *abfd);
@end example
@strong{Description}@*
Takes a BFD as created by @code{bfd_create} and
@code{bfd_make_writable} and converts it into one like as
returned by @code{bfd_openr}. It does this by writing the
contents out to the memory buffer, then reversing the
direction.
@strong{Returns}@*
@code{true} is returned if all is ok, otherwise @code{false}.
@findex bfd_alloc
@subsubsection @code{bfd_alloc}
@strong{Synopsis}
@example
PTR bfd_alloc (bfd *abfd, size_t wanted);
@end example
@strong{Description}@*
Allocate a block of @var{wanted} bytes of memory attached to
@code{abfd} and return a pointer to it.

1267
bfd/doc/reloc.texi Normal file
View File

File diff suppressed because it is too large Load Diff

707
bfd/doc/section.texi Normal file
View File

@@ -0,0 +1,707 @@
@section Sections
The raw data contained within a BFD is maintained through the
section abstraction. A single BFD may have any number of
sections. It keeps hold of them by pointing to the first;
each one points to the next in the list.
Sections are supported in BFD in @code{section.c}.
@menu
* Section Input::
* Section Output::
* typedef asection::
* section prototypes::
@end menu
@node Section Input, Section Output, Sections, Sections
@subsection Section input
When a BFD is opened for reading, the section structures are
created and attached to the BFD.
Each section has a name which describes the section in the
outside world---for example, @code{a.out} would contain at least
three sections, called @code{.text}, @code{.data} and @code{.bss}.
Names need not be unique; for example a COFF file may have several
sections named @code{.data}.
Sometimes a BFD will contain more than the ``natural'' number of
sections. A back end may attach other sections containing
constructor data, or an application may add a section (using
@code{bfd_make_section}) to the sections attached to an already open
BFD. For example, the linker creates an extra section
@code{COMMON} for each input file's BFD to hold information about
common storage.
The raw data is not necessarily read in when
the section descriptor is created. Some targets may leave the
data in place until a @code{bfd_get_section_contents} call is
made. Other back ends may read in all the data at once. For
example, an S-record file has to be read once to determine the
size of the data. An IEEE-695 file doesn't contain raw data in
sections, but data and relocation expressions intermixed, so
the data area has to be parsed to get out the data and
relocations.
@node Section Output, typedef asection, Section Input, Sections
@subsection Section output
To write a new object style BFD, the various sections to be
written have to be created. They are attached to the BFD in
the same way as input sections; data is written to the
sections using @code{bfd_set_section_contents}.
Any program that creates or combines sections (e.g., the assembler
and linker) must use the @code{asection} fields @code{output_section} and
@code{output_offset} to indicate the file sections to which each
section must be written. (If the section is being created from
scratch, @code{output_section} should probably point to the section
itself and @code{output_offset} should probably be zero.)
The data to be written comes from input sections attached
(via @code{output_section} pointers) to
the output sections. The output section structure can be
considered a filter for the input section: the output section
determines the vma of the output data and the name, but the
input section determines the offset into the output section of
the data to be written.
E.g., to create a section "O", starting at 0x100, 0x123 long,
containing two subsections, "A" at offset 0x0 (i.e., at vma
0x100) and "B" at offset 0x20 (i.e., at vma 0x120) the @code{asection}
structures would look like:
@example
section name "A"
output_offset 0x00
size 0x20
output_section -----------> section name "O"
| vma 0x100
section name "B" | size 0x123
output_offset 0x20 |
size 0x103 |
output_section --------|
@end example
@subsection Link orders
The data within a section is stored in a @dfn{link_order}.
These are much like the fixups in @code{gas}. The link_order
abstraction allows a section to grow and shrink within itself.
A link_order knows how big it is, and which is the next
link_order and where the raw data for it is; it also points to
a list of relocations which apply to it.
The link_order is used by the linker to perform relaxing on
final code. The compiler creates code which is as big as
necessary to make it work without relaxing, and the user can
select whether to relax. Sometimes relaxing takes a lot of
time. The linker runs around the relocations to see if any
are attached to data which can be shrunk, if so it does it on
a link_order by link_order basis.
@node typedef asection, section prototypes, Section Output, Sections
@subsection typedef asection
Here is the section structure:
@example
/* This structure is used for a comdat section, as in PE. A comdat
section is associated with a particular symbol. When the linker
sees a comdat section, it keeps only one of the sections with a
given name and associated with a given symbol. */
struct bfd_comdat_info
@{
/* The name of the symbol associated with a comdat section. */
const char *name;
/* The local symbol table index of the symbol associated with a
comdat section. This is only meaningful to the object file format
specific code; it is not an index into the list returned by
bfd_canonicalize_symtab. */
long symbol;
/* If this section is being discarded, the linker uses this field
to point to the input section which is being kept. */
struct sec *sec;
@};
typedef struct sec
@{
/* The name of the section; the name isn't a copy, the pointer is
the same as that passed to bfd_make_section. */
CONST char *name;
/* Which section is it; 0..nth. */
int index;
/* The next section in the list belonging to the BFD, or NULL. */
struct sec *next;
/* The field flags contains attributes of the section. Some
flags are read in from the object file, and some are
synthesized from other information. */
flagword flags;
#define SEC_NO_FLAGS 0x000
/* Tells the OS to allocate space for this section when loading.
This is clear for a section containing debug information
only. */
#define SEC_ALLOC 0x001
/* Tells the OS to load the section from the file when loading.
This is clear for a .bss section. */
#define SEC_LOAD 0x002
/* The section contains data still to be relocated, so there is
some relocation information too. */
#define SEC_RELOC 0x004
#if 0 /* Obsolete ? */
#define SEC_BALIGN 0x008
#endif
/* A signal to the OS that the section contains read only
data. */
#define SEC_READONLY 0x010
/* The section contains code only. */
#define SEC_CODE 0x020
/* The section contains data only. */
#define SEC_DATA 0x040
/* The section will reside in ROM. */
#define SEC_ROM 0x080
/* The section contains constructor information. This section
type is used by the linker to create lists of constructors and
destructors used by @code{g++}. When a back end sees a symbol
which should be used in a constructor list, it creates a new
section for the type of name (e.g., @code{__CTOR_LIST__}), attaches
the symbol to it, and builds a relocation. To build the lists
of constructors, all the linker has to do is catenate all the
sections called @code{__CTOR_LIST__} and relocate the data
contained within - exactly the operations it would peform on
standard data. */
#define SEC_CONSTRUCTOR 0x100
/* The section is a constructor, and should be placed at the
end of the text, data, or bss section(?). */
#define SEC_CONSTRUCTOR_TEXT 0x1100
#define SEC_CONSTRUCTOR_DATA 0x2100
#define SEC_CONSTRUCTOR_BSS 0x3100
/* The section has contents - a data section could be
@code{SEC_ALLOC} | @code{SEC_HAS_CONTENTS}; a debug section could be
@code{SEC_HAS_CONTENTS} */
#define SEC_HAS_CONTENTS 0x200
/* An instruction to the linker to not output the section
even if it has information which would normally be written. */
#define SEC_NEVER_LOAD 0x400
/* The section is a COFF shared library section. This flag is
only for the linker. If this type of section appears in
the input file, the linker must copy it to the output file
without changing the vma or size. FIXME: Although this
was originally intended to be general, it really is COFF
specific (and the flag was renamed to indicate this). It
might be cleaner to have some more general mechanism to
allow the back end to control what the linker does with
sections. */
#define SEC_COFF_SHARED_LIBRARY 0x800
/* The section contains common symbols (symbols may be defined
multiple times, the value of a symbol is the amount of
space it requires, and the largest symbol value is the one
used). Most targets have exactly one of these (which we
translate to bfd_com_section_ptr), but ECOFF has two. */
#define SEC_IS_COMMON 0x8000
/* The section contains only debugging information. For
example, this is set for ELF .debug and .stab sections.
strip tests this flag to see if a section can be
discarded. */
#define SEC_DEBUGGING 0x10000
/* The contents of this section are held in memory pointed to
by the contents field. This is checked by
bfd_get_section_contents, and the data is retrieved from
memory if appropriate. */
#define SEC_IN_MEMORY 0x20000
/* The contents of this section are to be excluded by the
linker for executable and shared objects unless those
objects are to be further relocated. */
#define SEC_EXCLUDE 0x40000
/* The contents of this section are to be sorted by the
based on the address specified in the associated symbol
table. */
#define SEC_SORT_ENTRIES 0x80000
/* When linking, duplicate sections of the same name should be
discarded, rather than being combined into a single section as
is usually done. This is similar to how common symbols are
handled. See SEC_LINK_DUPLICATES below. */
#define SEC_LINK_ONCE 0x100000
/* If SEC_LINK_ONCE is set, this bitfield describes how the linker
should handle duplicate sections. */
#define SEC_LINK_DUPLICATES 0x600000
/* This value for SEC_LINK_DUPLICATES means that duplicate
sections with the same name should simply be discarded. */
#define SEC_LINK_DUPLICATES_DISCARD 0x0
/* This value for SEC_LINK_DUPLICATES means that the linker
should warn if there are any duplicate sections, although
it should still only link one copy. */
#define SEC_LINK_DUPLICATES_ONE_ONLY 0x200000
/* This value for SEC_LINK_DUPLICATES means that the linker
should warn if any duplicate sections are a different size. */
#define SEC_LINK_DUPLICATES_SAME_SIZE 0x400000
/* This value for SEC_LINK_DUPLICATES means that the linker
should warn if any duplicate sections contain different
contents. */
#define SEC_LINK_DUPLICATES_SAME_CONTENTS 0x600000
/* This section was created by the linker as part of dynamic
relocation or other arcane processing. It is skipped when
going through the first-pass output, trusting that someone
else up the line will take care of it later. */
#define SEC_LINKER_CREATED 0x800000
/* This section should not be subject to garbage collection. */
#define SEC_KEEP 0x1000000
/* This section contains "short" data, and should be placed
"near" the GP. */
#define SEC_SMALL_DATA 0x2000000
/* This section contains data which may be shared with other
executables or shared objects. */
#define SEC_SHARED 0x4000000
/* End of section flags. */
/* Some internal packed boolean fields. */
/* See the vma field. */
unsigned int user_set_vma : 1;
/* Whether relocations have been processed. */
unsigned int reloc_done : 1;
/* A mark flag used by some of the linker backends. */
unsigned int linker_mark : 1;
/* A mark flag used by some linker backends for garbage collection. */
unsigned int gc_mark : 1;
/* End of internal packed boolean fields. */
/* The virtual memory address of the section - where it will be
at run time. The symbols are relocated against this. The
user_set_vma flag is maintained by bfd; if it's not set, the
backend can assign addresses (for example, in @code{a.out}, where
the default address for @code{.data} is dependent on the specific
target and various flags). */
bfd_vma vma;
/* The load address of the section - where it would be in a
rom image; really only used for writing section header
information. */
bfd_vma lma;
/* The size of the section in octets, as it will be output.
Contains a value even if the section has no contents (e.g., the
size of @code{.bss}). This will be filled in after relocation. */
bfd_size_type _cooked_size;
/* The original size on disk of the section, in octets. Normally this
value is the same as the size, but if some relaxing has
been done, then this value will be bigger. */
bfd_size_type _raw_size;
/* If this section is going to be output, then this value is the
offset in *bytes* into the output section of the first byte in the
input section (byte ==> smallest addressable unit on the
target). In most cases, if this was going to start at the
100th octet (8-bit quantity) in the output section, this value
would be 100. However, if the target byte size is 16 bits
(bfd_octets_per_byte is "2"), this value would be 50. */
bfd_vma output_offset;
/* The output section through which to map on output. */
struct sec *output_section;
/* The alignment requirement of the section, as an exponent of 2 -
e.g., 3 aligns to 2^3 (or 8). */
unsigned int alignment_power;
/* If an input section, a pointer to a vector of relocation
records for the data in this section. */
struct reloc_cache_entry *relocation;
/* If an output section, a pointer to a vector of pointers to
relocation records for the data in this section. */
struct reloc_cache_entry **orelocation;
/* The number of relocation records in one of the above */
unsigned reloc_count;
/* Information below is back end specific - and not always used
or updated. */
/* File position of section data */
file_ptr filepos;
/* File position of relocation info */
file_ptr rel_filepos;
/* File position of line data */
file_ptr line_filepos;
/* Pointer to data for applications */
PTR userdata;
/* If the SEC_IN_MEMORY flag is set, this points to the actual
contents. */
unsigned char *contents;
/* Attached line number information */
alent *lineno;
/* Number of line number records */
unsigned int lineno_count;
/* Optional information about a COMDAT entry; NULL if not COMDAT */
struct bfd_comdat_info *comdat;
/* When a section is being output, this value changes as more
linenumbers are written out */
file_ptr moving_line_filepos;
/* What the section number is in the target world */
int target_index;
PTR used_by_bfd;
/* If this is a constructor section then here is a list of the
relocations created to relocate items within it. */
struct relent_chain *constructor_chain;
/* The BFD which owns the section. */
bfd *owner;
/* A symbol which points at this section only */
struct symbol_cache_entry *symbol;
struct symbol_cache_entry **symbol_ptr_ptr;
struct bfd_link_order *link_order_head;
struct bfd_link_order *link_order_tail;
@} asection ;
/* These sections are global, and are managed by BFD. The application
and target back end are not permitted to change the values in
these sections. New code should use the section_ptr macros rather
than referring directly to the const sections. The const sections
may eventually vanish. */
#define BFD_ABS_SECTION_NAME "*ABS*"
#define BFD_UND_SECTION_NAME "*UND*"
#define BFD_COM_SECTION_NAME "*COM*"
#define BFD_IND_SECTION_NAME "*IND*"
/* the absolute section */
extern const asection bfd_abs_section;
#define bfd_abs_section_ptr ((asection *) &bfd_abs_section)
#define bfd_is_abs_section(sec) ((sec) == bfd_abs_section_ptr)
/* Pointer to the undefined section */
extern const asection bfd_und_section;
#define bfd_und_section_ptr ((asection *) &bfd_und_section)
#define bfd_is_und_section(sec) ((sec) == bfd_und_section_ptr)
/* Pointer to the common section */
extern const asection bfd_com_section;
#define bfd_com_section_ptr ((asection *) &bfd_com_section)
/* Pointer to the indirect section */
extern const asection bfd_ind_section;
#define bfd_ind_section_ptr ((asection *) &bfd_ind_section)
#define bfd_is_ind_section(sec) ((sec) == bfd_ind_section_ptr)
extern const struct symbol_cache_entry * const bfd_abs_symbol;
extern const struct symbol_cache_entry * const bfd_com_symbol;
extern const struct symbol_cache_entry * const bfd_und_symbol;
extern const struct symbol_cache_entry * const bfd_ind_symbol;
#define bfd_get_section_size_before_reloc(section) \
((section)->reloc_done ? (abort (), (bfd_size_type) 1) \
: (section)->_raw_size)
#define bfd_get_section_size_after_reloc(section) \
((section)->reloc_done ? (section)->_cooked_size \
: (abort (), (bfd_size_type) 1))
@end example
@node section prototypes, , typedef asection, Sections
@subsection Section prototypes
These are the functions exported by the section handling part of BFD.
@findex bfd_get_section_by_name
@subsubsection @code{bfd_get_section_by_name}
@strong{Synopsis}
@example
asection *bfd_get_section_by_name(bfd *abfd, CONST char *name);
@end example
@strong{Description}@*
Run through @var{abfd} and return the one of the
@code{asection}s whose name matches @var{name}, otherwise @code{NULL}.
@xref{Sections}, for more information.
This should only be used in special cases; the normal way to process
all sections of a given name is to use @code{bfd_map_over_sections} and
@code{strcmp} on the name (or better yet, base it on the section flags
or something else) for each section.
@findex bfd_make_section_old_way
@subsubsection @code{bfd_make_section_old_way}
@strong{Synopsis}
@example
asection *bfd_make_section_old_way(bfd *abfd, CONST char *name);
@end example
@strong{Description}@*
Create a new empty section called @var{name}
and attach it to the end of the chain of sections for the
BFD @var{abfd}. An attempt to create a section with a name which
is already in use returns its pointer without changing the
section chain.
It has the funny name since this is the way it used to be
before it was rewritten....
Possible errors are:
@itemize @bullet
@item
@code{bfd_error_invalid_operation} -
If output has already started for this BFD.
@item
@code{bfd_error_no_memory} -
If memory allocation fails.
@end itemize
@findex bfd_make_section_anyway
@subsubsection @code{bfd_make_section_anyway}
@strong{Synopsis}
@example
asection *bfd_make_section_anyway(bfd *abfd, CONST char *name);
@end example
@strong{Description}@*
Create a new empty section called @var{name} and attach it to the end of
the chain of sections for @var{abfd}. Create a new section even if there
is already a section with that name.
Return @code{NULL} and set @code{bfd_error} on error; possible errors are:
@itemize @bullet
@item
@code{bfd_error_invalid_operation} - If output has already started for @var{abfd}.
@item
@code{bfd_error_no_memory} - If memory allocation fails.
@end itemize
@findex bfd_make_section
@subsubsection @code{bfd_make_section}
@strong{Synopsis}
@example
asection *bfd_make_section(bfd *, CONST char *name);
@end example
@strong{Description}@*
Like @code{bfd_make_section_anyway}, but return @code{NULL} (without calling
bfd_set_error ()) without changing the section chain if there is already a
section named @var{name}. If there is an error, return @code{NULL} and set
@code{bfd_error}.
@findex bfd_set_section_flags
@subsubsection @code{bfd_set_section_flags}
@strong{Synopsis}
@example
boolean bfd_set_section_flags(bfd *abfd, asection *sec, flagword flags);
@end example
@strong{Description}@*
Set the attributes of the section @var{sec} in the BFD
@var{abfd} to the value @var{flags}. Return @code{true} on success,
@code{false} on error. Possible error returns are:
@itemize @bullet
@item
@code{bfd_error_invalid_operation} -
The section cannot have one or more of the attributes
requested. For example, a .bss section in @code{a.out} may not
have the @code{SEC_HAS_CONTENTS} field set.
@end itemize
@findex bfd_map_over_sections
@subsubsection @code{bfd_map_over_sections}
@strong{Synopsis}
@example
void bfd_map_over_sections(bfd *abfd,
void (*func)(bfd *abfd,
asection *sect,
PTR obj),
PTR obj);
@end example
@strong{Description}@*
Call the provided function @var{func} for each section
attached to the BFD @var{abfd}, passing @var{obj} as an
argument. The function will be called as if by
@example
func(abfd, the_section, obj);
@end example
This is the prefered method for iterating over sections; an
alternative would be to use a loop:
@example
section *p;
for (p = abfd->sections; p != NULL; p = p->next)
func(abfd, p, ...)
@end example
@findex bfd_set_section_size
@subsubsection @code{bfd_set_section_size}
@strong{Synopsis}
@example
boolean bfd_set_section_size(bfd *abfd, asection *sec, bfd_size_type val);
@end example
@strong{Description}@*
Set @var{sec} to the size @var{val}. If the operation is
ok, then @code{true} is returned, else @code{false}.
Possible error returns:
@itemize @bullet
@item
@code{bfd_error_invalid_operation} -
Writing has started to the BFD, so setting the size is invalid.
@end itemize
@findex bfd_set_section_contents
@subsubsection @code{bfd_set_section_contents}
@strong{Synopsis}
@example
boolean bfd_set_section_contents
(bfd *abfd,
asection *section,
PTR data,
file_ptr offset,
bfd_size_type count);
@end example
@strong{Description}@*
Sets the contents of the section @var{section} in BFD
@var{abfd} to the data starting in memory at @var{data}. The
data is written to the output section starting at offset
@var{offset} for @var{count} octets.
Normally @code{true} is returned, else @code{false}. Possible error
returns are:
@itemize @bullet
@item
@code{bfd_error_no_contents} -
The output section does not have the @code{SEC_HAS_CONTENTS}
attribute, so nothing can be written to it.
@item
and some more too
@end itemize
This routine is front end to the back end function
@code{_bfd_set_section_contents}.
@findex bfd_get_section_contents
@subsubsection @code{bfd_get_section_contents}
@strong{Synopsis}
@example
boolean bfd_get_section_contents
(bfd *abfd, asection *section, PTR location,
file_ptr offset, bfd_size_type count);
@end example
@strong{Description}@*
Read data from @var{section} in BFD @var{abfd}
into memory starting at @var{location}. The data is read at an
offset of @var{offset} from the start of the input section,
and is read for @var{count} bytes.
If the contents of a constructor with the @code{SEC_CONSTRUCTOR}
flag set are requested or if the section does not have the
@code{SEC_HAS_CONTENTS} flag set, then the @var{location} is filled
with zeroes. If no errors occur, @code{true} is returned, else
@code{false}.
@findex bfd_copy_private_section_data
@subsubsection @code{bfd_copy_private_section_data}
@strong{Synopsis}
@example
boolean bfd_copy_private_section_data(bfd *ibfd, asection *isec, bfd *obfd, asection *osec);
@end example
@strong{Description}@*
Copy private section information from @var{isec} in the BFD
@var{ibfd} to the section @var{osec} in the BFD @var{obfd}.
Return @code{true} on success, @code{false} on error. Possible error
returns are:
@itemize @bullet
@item
@code{bfd_error_no_memory} -
Not enough memory exists to create private data for @var{osec}.
@end itemize
@example
#define bfd_copy_private_section_data(ibfd, isection, obfd, osection) \
BFD_SEND (obfd, _bfd_copy_private_section_data, \
(ibfd, isection, obfd, osection))
@end example
@findex _bfd_strip_section_from_output
@subsubsection @code{_bfd_strip_section_from_output}
@strong{Synopsis}
@example
void _bfd_strip_section_from_output
(struct bfd_link_info *info, asection *section);
@end example
@strong{Description}@*
Remove @var{section} from the output. If the output section
becomes empty, remove it from the output bfd. @var{info} may
be NULL; if it is not, it is used to decide whether the output
section is empty.

424
bfd/doc/syms.texi Normal file
View File

@@ -0,0 +1,424 @@
@section Symbols
BFD tries to maintain as much symbol information as it can when
it moves information from file to file. BFD passes information
to applications though the @code{asymbol} structure. When the
application requests the symbol table, BFD reads the table in
the native form and translates parts of it into the internal
format. To maintain more than the information passed to
applications, some targets keep some information ``behind the
scenes'' in a structure only the particular back end knows
about. For example, the coff back end keeps the original
symbol table structure as well as the canonical structure when
a BFD is read in. On output, the coff back end can reconstruct
the output symbol table so that no information is lost, even
information unique to coff which BFD doesn't know or
understand. If a coff symbol table were read, but were written
through an a.out back end, all the coff specific information
would be lost. The symbol table of a BFD
is not necessarily read in until a canonicalize request is
made. Then the BFD back end fills in a table provided by the
application with pointers to the canonical information. To
output symbols, the application provides BFD with a table of
pointers to pointers to @code{asymbol}s. This allows applications
like the linker to output a symbol as it was read, since the ``behind
the scenes'' information will be still available.
@menu
* Reading Symbols::
* Writing Symbols::
* Mini Symbols::
* typedef asymbol::
* symbol handling functions::
@end menu
@node Reading Symbols, Writing Symbols, Symbols, Symbols
@subsection Reading symbols
There are two stages to reading a symbol table from a BFD:
allocating storage, and the actual reading process. This is an
excerpt from an application which reads the symbol table:
@example
long storage_needed;
asymbol **symbol_table;
long number_of_symbols;
long i;
storage_needed = bfd_get_symtab_upper_bound (abfd);
if (storage_needed < 0)
FAIL
if (storage_needed == 0) @{
return ;
@}
symbol_table = (asymbol **) xmalloc (storage_needed);
...
number_of_symbols =
bfd_canonicalize_symtab (abfd, symbol_table);
if (number_of_symbols < 0)
FAIL
for (i = 0; i < number_of_symbols; i++) @{
process_symbol (symbol_table[i]);
@}
@end example
All storage for the symbols themselves is in an objalloc
connected to the BFD; it is freed when the BFD is closed.
@node Writing Symbols, Mini Symbols, Reading Symbols, Symbols
@subsection Writing symbols
Writing of a symbol table is automatic when a BFD open for
writing is closed. The application attaches a vector of
pointers to pointers to symbols to the BFD being written, and
fills in the symbol count. The close and cleanup code reads
through the table provided and performs all the necessary
operations. The BFD output code must always be provided with an
``owned'' symbol: one which has come from another BFD, or one
which has been created using @code{bfd_make_empty_symbol}. Here is an
example showing the creation of a symbol table with only one element:
@example
#include "bfd.h"
main()
@{
bfd *abfd;
asymbol *ptrs[2];
asymbol *new;
abfd = bfd_openw("foo","a.out-sunos-big");
bfd_set_format(abfd, bfd_object);
new = bfd_make_empty_symbol(abfd);
new->name = "dummy_symbol";
new->section = bfd_make_section_old_way(abfd, ".text");
new->flags = BSF_GLOBAL;
new->value = 0x12345;
ptrs[0] = new;
ptrs[1] = (asymbol *)0;
bfd_set_symtab(abfd, ptrs, 1);
bfd_close(abfd);
@}
./makesym
nm foo
00012345 A dummy_symbol
@end example
Many formats cannot represent arbitary symbol information; for
instance, the @code{a.out} object format does not allow an
arbitary number of sections. A symbol pointing to a section
which is not one of @code{.text}, @code{.data} or @code{.bss} cannot
be described.
@node Mini Symbols, typedef asymbol, Writing Symbols, Symbols
@subsection Mini Symbols
Mini symbols provide read-only access to the symbol table.
They use less memory space, but require more time to access.
They can be useful for tools like nm or objdump, which may
have to handle symbol tables of extremely large executables.
The @code{bfd_read_minisymbols} function will read the symbols
into memory in an internal form. It will return a @code{void *}
pointer to a block of memory, a symbol count, and the size of
each symbol. The pointer is allocated using @code{malloc}, and
should be freed by the caller when it is no longer needed.
The function @code{bfd_minisymbol_to_symbol} will take a pointer
to a minisymbol, and a pointer to a structure returned by
@code{bfd_make_empty_symbol}, and return a @code{asymbol} structure.
The return value may or may not be the same as the value from
@code{bfd_make_empty_symbol} which was passed in.
@node typedef asymbol, symbol handling functions, Mini Symbols, Symbols
@subsection typedef asymbol
An @code{asymbol} has the form:
@example
typedef struct symbol_cache_entry
@{
/* A pointer to the BFD which owns the symbol. This information
is necessary so that a back end can work out what additional
information (invisible to the application writer) is carried
with the symbol.
This field is *almost* redundant, since you can use section->owner
instead, except that some symbols point to the global sections
bfd_@{abs,com,und@}_section. This could be fixed by making
these globals be per-bfd (or per-target-flavor). FIXME. */
struct _bfd *the_bfd; /* Use bfd_asymbol_bfd(sym) to access this field. */
/* The text of the symbol. The name is left alone, and not copied; the
application may not alter it. */
CONST char *name;
/* The value of the symbol. This really should be a union of a
numeric value with a pointer, since some flags indicate that
a pointer to another symbol is stored here. */
symvalue value;
/* Attributes of a symbol: */
#define BSF_NO_FLAGS 0x00
/* The symbol has local scope; @code{static} in @code{C}. The value
is the offset into the section of the data. */
#define BSF_LOCAL 0x01
/* The symbol has global scope; initialized data in @code{C}. The
value is the offset into the section of the data. */
#define BSF_GLOBAL 0x02
/* The symbol has global scope and is exported. The value is
the offset into the section of the data. */
#define BSF_EXPORT BSF_GLOBAL /* no real difference */
/* A normal C symbol would be one of:
@code{BSF_LOCAL}, @code{BSF_FORT_COMM}, @code{BSF_UNDEFINED} or
@code{BSF_GLOBAL} */
/* The symbol is a debugging record. The value has an arbitary
meaning, unless BSF_DEBUGGING_RELOC is also set. */
#define BSF_DEBUGGING 0x08
/* The symbol denotes a function entry point. Used in ELF,
perhaps others someday. */
#define BSF_FUNCTION 0x10
/* Used by the linker. */
#define BSF_KEEP 0x20
#define BSF_KEEP_G 0x40
/* A weak global symbol, overridable without warnings by
a regular global symbol of the same name. */
#define BSF_WEAK 0x80
/* This symbol was created to point to a section, e.g. ELF's
STT_SECTION symbols. */
#define BSF_SECTION_SYM 0x100
/* The symbol used to be a common symbol, but now it is
allocated. */
#define BSF_OLD_COMMON 0x200
/* The default value for common data. */
#define BFD_FORT_COMM_DEFAULT_VALUE 0
/* In some files the type of a symbol sometimes alters its
location in an output file - ie in coff a @code{ISFCN} symbol
which is also @code{C_EXT} symbol appears where it was
declared and not at the end of a section. This bit is set
by the target BFD part to convey this information. */
#define BSF_NOT_AT_END 0x400
/* Signal that the symbol is the label of constructor section. */
#define BSF_CONSTRUCTOR 0x800
/* Signal that the symbol is a warning symbol. The name is a
warning. The name of the next symbol is the one to warn about;
if a reference is made to a symbol with the same name as the next
symbol, a warning is issued by the linker. */
#define BSF_WARNING 0x1000
/* Signal that the symbol is indirect. This symbol is an indirect
pointer to the symbol with the same name as the next symbol. */
#define BSF_INDIRECT 0x2000
/* BSF_FILE marks symbols that contain a file name. This is used
for ELF STT_FILE symbols. */
#define BSF_FILE 0x4000
/* Symbol is from dynamic linking information. */
#define BSF_DYNAMIC 0x8000
/* The symbol denotes a data object. Used in ELF, and perhaps
others someday. */
#define BSF_OBJECT 0x10000
/* This symbol is a debugging symbol. The value is the offset
into the section of the data. BSF_DEBUGGING should be set
as well. */
#define BSF_DEBUGGING_RELOC 0x20000
flagword flags;
/* A pointer to the section to which this symbol is
relative. This will always be non NULL, there are special
sections for undefined and absolute symbols. */
struct sec *section;
/* Back end special data. */
union
@{
PTR p;
bfd_vma i;
@} udata;
@} asymbol;
@end example
@node symbol handling functions, , typedef asymbol, Symbols
@subsection Symbol handling functions
@findex bfd_get_symtab_upper_bound
@subsubsection @code{bfd_get_symtab_upper_bound}
@strong{Description}@*
Return the number of bytes required to store a vector of pointers
to @code{asymbols} for all the symbols in the BFD @var{abfd},
including a terminal NULL pointer. If there are no symbols in
the BFD, then return 0. If an error occurs, return -1.
@example
#define bfd_get_symtab_upper_bound(abfd) \
BFD_SEND (abfd, _bfd_get_symtab_upper_bound, (abfd))
@end example
@findex bfd_is_local_label
@subsubsection @code{bfd_is_local_label}
@strong{Synopsis}
@example
boolean bfd_is_local_label(bfd *abfd, asymbol *sym);
@end example
@strong{Description}@*
Return true if the given symbol @var{sym} in the BFD @var{abfd} is
a compiler generated local label, else return false.
@findex bfd_is_local_label_name
@subsubsection @code{bfd_is_local_label_name}
@strong{Synopsis}
@example
boolean bfd_is_local_label_name(bfd *abfd, const char *name);
@end example
@strong{Description}@*
Return true if a symbol with the name @var{name} in the BFD
@var{abfd} is a compiler generated local label, else return
false. This just checks whether the name has the form of a
local label.
@example
#define bfd_is_local_label_name(abfd, name) \
BFD_SEND (abfd, _bfd_is_local_label_name, (abfd, name))
@end example
@findex bfd_canonicalize_symtab
@subsubsection @code{bfd_canonicalize_symtab}
@strong{Description}@*
Read the symbols from the BFD @var{abfd}, and fills in
the vector @var{location} with pointers to the symbols and
a trailing NULL.
Return the actual number of symbol pointers, not
including the NULL.
@example
#define bfd_canonicalize_symtab(abfd, location) \
BFD_SEND (abfd, _bfd_canonicalize_symtab,\
(abfd, location))
@end example
@findex bfd_set_symtab
@subsubsection @code{bfd_set_symtab}
@strong{Synopsis}
@example
boolean bfd_set_symtab (bfd *abfd, asymbol **location, unsigned int count);
@end example
@strong{Description}@*
Arrange that when the output BFD @var{abfd} is closed,
the table @var{location} of @var{count} pointers to symbols
will be written.
@findex bfd_print_symbol_vandf
@subsubsection @code{bfd_print_symbol_vandf}
@strong{Synopsis}
@example
void bfd_print_symbol_vandf(PTR file, asymbol *symbol);
@end example
@strong{Description}@*
Print the value and flags of the @var{symbol} supplied to the
stream @var{file}.
@findex bfd_make_empty_symbol
@subsubsection @code{bfd_make_empty_symbol}
@strong{Description}@*
Create a new @code{asymbol} structure for the BFD @var{abfd}
and return a pointer to it.
This routine is necessary because each back end has private
information surrounding the @code{asymbol}. Building your own
@code{asymbol} and pointing to it will not create the private
information, and will cause problems later on.
@example
#define bfd_make_empty_symbol(abfd) \
BFD_SEND (abfd, _bfd_make_empty_symbol, (abfd))
@end example
@findex bfd_make_debug_symbol
@subsubsection @code{bfd_make_debug_symbol}
@strong{Description}@*
Create a new @code{asymbol} structure for the BFD @var{abfd},
to be used as a debugging symbol. Further details of its use have
yet to be worked out.
@example
#define bfd_make_debug_symbol(abfd,ptr,size) \
BFD_SEND (abfd, _bfd_make_debug_symbol, (abfd, ptr, size))
@end example
@findex bfd_decode_symclass
@subsubsection @code{bfd_decode_symclass}
@strong{Description}@*
Return a character corresponding to the symbol
class of @var{symbol}, or '?' for an unknown class.
@strong{Synopsis}
@example
int bfd_decode_symclass(asymbol *symbol);
@end example
@findex bfd_is_undefined_symclass
@subsubsection @code{bfd_is_undefined_symclass }
@strong{Description}@*
Returns non-zero if the class symbol returned by
bfd_decode_symclass represents an undefined symbol.
Returns zero otherwise.
@strong{Synopsis}
@example
boolean bfd_is_undefined_symclass (int symclass);
@end example
@findex bfd_symbol_info
@subsubsection @code{bfd_symbol_info}
@strong{Description}@*
Fill in the basic info about symbol that nm needs.
Additional info may be added by the back-ends after
calling this function.
@strong{Synopsis}
@example
void bfd_symbol_info(asymbol *symbol, symbol_info *ret);
@end example
@findex bfd_copy_private_symbol_data
@subsubsection @code{bfd_copy_private_symbol_data}
@strong{Synopsis}
@example
boolean bfd_copy_private_symbol_data(bfd *ibfd, asymbol *isym, bfd *obfd, asymbol *osym);
@end example
@strong{Description}@*
Copy private symbol information from @var{isym} in the BFD
@var{ibfd} to the symbol @var{osym} in the BFD @var{obfd}.
Return @code{true} on success, @code{false} on error. Possible error
returns are:
@itemize @bullet
@item
@code{bfd_error_no_memory} -
Not enough memory exists to create private data for @var{osec}.
@end itemize
@example
#define bfd_copy_private_symbol_data(ibfd, isymbol, obfd, osymbol) \
BFD_SEND (obfd, _bfd_copy_private_symbol_data, \
(ibfd, isymbol, obfd, osymbol))
@end example

508
bfd/doc/targets.texi Normal file
View File

@@ -0,0 +1,508 @@
@section Targets
@strong{Description}@*
Each port of BFD to a different machine requries the creation
of a target back end. All the back end provides to the root
part of BFD is a structure containing pointers to functions
which perform certain low level operations on files. BFD
translates the applications's requests through a pointer into
calls to the back end routines.
When a file is opened with @code{bfd_openr}, its format and
target are unknown. BFD uses various mechanisms to determine
how to interpret the file. The operations performed are:
@itemize @bullet
@item
Create a BFD by calling the internal routine
@code{_bfd_new_bfd}, then call @code{bfd_find_target} with the
target string supplied to @code{bfd_openr} and the new BFD pointer.
@item
If a null target string was provided to @code{bfd_find_target},
look up the environment variable @code{GNUTARGET} and use
that as the target string.
@item
If the target string is still @code{NULL}, or the target string is
@code{default}, then use the first item in the target vector
as the target type, and set @code{target_defaulted} in the BFD to
cause @code{bfd_check_format} to loop through all the targets.
@xref{bfd_target}. @xref{Formats}.
@item
Otherwise, inspect the elements in the target vector
one by one, until a match on target name is found. When found,
use it.
@item
Otherwise return the error @code{bfd_error_invalid_target} to
@code{bfd_openr}.
@item
@code{bfd_openr} attempts to open the file using
@code{bfd_open_file}, and returns the BFD.
@end itemize
Once the BFD has been opened and the target selected, the file
format may be determined. This is done by calling
@code{bfd_check_format} on the BFD with a suggested format.
If @code{target_defaulted} has been set, each possible target
type is tried to see if it recognizes the specified format.
@code{bfd_check_format} returns @code{true} when the caller guesses right.
@menu
* bfd_target::
@end menu
@node bfd_target, , Targets, Targets
@subsection bfd_target
@strong{Description}@*
This structure contains everything that BFD knows about a
target. It includes things like its byte order, name, and which
routines to call to do various operations.
Every BFD points to a target structure with its @code{xvec}
member.
The macros below are used to dispatch to functions through the
@code{bfd_target} vector. They are used in a number of macros further
down in @file{bfd.h}, and are also used when calling various
routines by hand inside the BFD implementation. The @var{arglist}
argument must be parenthesized; it contains all the arguments
to the called function.
They make the documentation (more) unpleasant to read, so if
someone wants to fix this and not break the above, please do.
@example
#define BFD_SEND(bfd, message, arglist) \
((*((bfd)->xvec->message)) arglist)
#ifdef DEBUG_BFD_SEND
#undef BFD_SEND
#define BFD_SEND(bfd, message, arglist) \
(((bfd) && (bfd)->xvec && (bfd)->xvec->message) ? \
((*((bfd)->xvec->message)) arglist) : \
(bfd_assert (__FILE__,__LINE__), NULL))
#endif
@end example
For operations which index on the BFD format:
@example
#define BFD_SEND_FMT(bfd, message, arglist) \
(((bfd)->xvec->message[(int)((bfd)->format)]) arglist)
#ifdef DEBUG_BFD_SEND
#undef BFD_SEND_FMT
#define BFD_SEND_FMT(bfd, message, arglist) \
(((bfd) && (bfd)->xvec && (bfd)->xvec->message) ? \
(((bfd)->xvec->message[(int)((bfd)->format)]) arglist) : \
(bfd_assert (__FILE__,__LINE__), NULL))
#endif
@end example
This is the structure which defines the type of BFD this is. The
@code{xvec} member of the struct @code{bfd} itself points here. Each
module that implements access to a different target under BFD,
defines one of these.
FIXME, these names should be rationalised with the names of
the entry points which call them. Too bad we can't have one
macro to define them both!
@example
enum bfd_flavour @{
bfd_target_unknown_flavour,
bfd_target_aout_flavour,
bfd_target_coff_flavour,
bfd_target_ecoff_flavour,
bfd_target_elf_flavour,
bfd_target_ieee_flavour,
bfd_target_nlm_flavour,
bfd_target_oasys_flavour,
bfd_target_tekhex_flavour,
bfd_target_srec_flavour,
bfd_target_ihex_flavour,
bfd_target_som_flavour,
bfd_target_os9k_flavour,
bfd_target_versados_flavour,
bfd_target_msdos_flavour,
bfd_target_ovax_flavour,
bfd_target_evax_flavour
@};
enum bfd_endian @{ BFD_ENDIAN_BIG, BFD_ENDIAN_LITTLE, BFD_ENDIAN_UNKNOWN @};
/* Forward declaration. */
typedef struct bfd_link_info _bfd_link_info;
typedef struct bfd_target
@{
@end example
Identifies the kind of target, e.g., SunOS4, Ultrix, etc.
@example
char *name;
@end example
The "flavour" of a back end is a general indication about the contents
of a file.
@example
enum bfd_flavour flavour;
@end example
The order of bytes within the data area of a file.
@example
enum bfd_endian byteorder;
@end example
The order of bytes within the header parts of a file.
@example
enum bfd_endian header_byteorder;
@end example
A mask of all the flags which an executable may have set -
from the set @code{BFD_NO_FLAGS}, @code{HAS_RELOC}, ...@code{D_PAGED}.
@example
flagword object_flags;
@end example
A mask of all the flags which a section may have set - from
the set @code{SEC_NO_FLAGS}, @code{SEC_ALLOC}, ...@code{SET_NEVER_LOAD}.
@example
flagword section_flags;
@end example
The character normally found at the front of a symbol
(if any), perhaps `_'.
@example
char symbol_leading_char;
@end example
The pad character for file names within an archive header.
@example
char ar_pad_char;
@end example
The maximum number of characters in an archive header.
@example
unsigned short ar_max_namelen;
@end example
Entries for byte swapping for data. These are different from the other
entry points, since they don't take a BFD asthe first argument.
Certain other handlers could do the same.
@example
bfd_vma (*bfd_getx64) PARAMS ((const bfd_byte *));
bfd_signed_vma (*bfd_getx_signed_64) PARAMS ((const bfd_byte *));
void (*bfd_putx64) PARAMS ((bfd_vma, bfd_byte *));
bfd_vma (*bfd_getx32) PARAMS ((const bfd_byte *));
bfd_signed_vma (*bfd_getx_signed_32) PARAMS ((const bfd_byte *));
void (*bfd_putx32) PARAMS ((bfd_vma, bfd_byte *));
bfd_vma (*bfd_getx16) PARAMS ((const bfd_byte *));
bfd_signed_vma (*bfd_getx_signed_16) PARAMS ((const bfd_byte *));
void (*bfd_putx16) PARAMS ((bfd_vma, bfd_byte *));
@end example
Byte swapping for the headers
@example
bfd_vma (*bfd_h_getx64) PARAMS ((const bfd_byte *));
bfd_signed_vma (*bfd_h_getx_signed_64) PARAMS ((const bfd_byte *));
void (*bfd_h_putx64) PARAMS ((bfd_vma, bfd_byte *));
bfd_vma (*bfd_h_getx32) PARAMS ((const bfd_byte *));
bfd_signed_vma (*bfd_h_getx_signed_32) PARAMS ((const bfd_byte *));
void (*bfd_h_putx32) PARAMS ((bfd_vma, bfd_byte *));
bfd_vma (*bfd_h_getx16) PARAMS ((const bfd_byte *));
bfd_signed_vma (*bfd_h_getx_signed_16) PARAMS ((const bfd_byte *));
void (*bfd_h_putx16) PARAMS ((bfd_vma, bfd_byte *));
@end example
Format dependent routines: these are vectors of entry points
within the target vector structure, one for each format to check.
Check the format of a file being read. Return a @code{bfd_target *} or zero.
@example
const struct bfd_target *(*_bfd_check_format[bfd_type_end]) PARAMS ((bfd *));
@end example
Set the format of a file being written.
@example
boolean (*_bfd_set_format[bfd_type_end]) PARAMS ((bfd *));
@end example
Write cached information into a file being written, at @code{bfd_close}.
@example
boolean (*_bfd_write_contents[bfd_type_end]) PARAMS ((bfd *));
@end example
The general target vector. These vectors are initialized using the
BFD_JUMP_TABLE macros.
@example
/* Generic entry points. */
#define BFD_JUMP_TABLE_GENERIC(NAME)\
CAT(NAME,_close_and_cleanup),\
CAT(NAME,_bfd_free_cached_info),\
CAT(NAME,_new_section_hook),\
CAT(NAME,_get_section_contents),\
CAT(NAME,_get_section_contents_in_window)
/* Called when the BFD is being closed to do any necessary cleanup. */
boolean (*_close_and_cleanup) PARAMS ((bfd *));
/* Ask the BFD to free all cached information. */
boolean (*_bfd_free_cached_info) PARAMS ((bfd *));
/* Called when a new section is created. */
boolean (*_new_section_hook) PARAMS ((bfd *, sec_ptr));
/* Read the contents of a section. */
boolean (*_bfd_get_section_contents) PARAMS ((bfd *, sec_ptr, PTR,
file_ptr, bfd_size_type));
boolean (*_bfd_get_section_contents_in_window)
PARAMS ((bfd *, sec_ptr, bfd_window *,
file_ptr, bfd_size_type));
/* Entry points to copy private data. */
#define BFD_JUMP_TABLE_COPY(NAME)\
CAT(NAME,_bfd_copy_private_bfd_data),\
CAT(NAME,_bfd_merge_private_bfd_data),\
CAT(NAME,_bfd_copy_private_section_data),\
CAT(NAME,_bfd_copy_private_symbol_data),\
CAT(NAME,_bfd_set_private_flags),\
CAT(NAME,_bfd_print_private_bfd_data)\
/* Called to copy BFD general private data from one object file
to another. */
boolean (*_bfd_copy_private_bfd_data) PARAMS ((bfd *, bfd *));
/* Called to merge BFD general private data from one object file
to a common output file when linking. */
boolean (*_bfd_merge_private_bfd_data) PARAMS ((bfd *, bfd *));
/* Called to copy BFD private section data from one object file
to another. */
boolean (*_bfd_copy_private_section_data) PARAMS ((bfd *, sec_ptr,
bfd *, sec_ptr));
/* Called to copy BFD private symbol data from one symbol
to another. */
boolean (*_bfd_copy_private_symbol_data) PARAMS ((bfd *, asymbol *,
bfd *, asymbol *));
/* Called to set private backend flags */
boolean (*_bfd_set_private_flags) PARAMS ((bfd *, flagword));
/* Called to print private BFD data */
boolean (*_bfd_print_private_bfd_data) PARAMS ((bfd *, PTR));
/* Core file entry points. */
#define BFD_JUMP_TABLE_CORE(NAME)\
CAT(NAME,_core_file_failing_command),\
CAT(NAME,_core_file_failing_signal),\
CAT(NAME,_core_file_matches_executable_p)
char * (*_core_file_failing_command) PARAMS ((bfd *));
int (*_core_file_failing_signal) PARAMS ((bfd *));
boolean (*_core_file_matches_executable_p) PARAMS ((bfd *, bfd *));
/* Archive entry points. */
#define BFD_JUMP_TABLE_ARCHIVE(NAME)\
CAT(NAME,_slurp_armap),\
CAT(NAME,_slurp_extended_name_table),\
CAT(NAME,_construct_extended_name_table),\
CAT(NAME,_truncate_arname),\
CAT(NAME,_write_armap),\
CAT(NAME,_read_ar_hdr),\
CAT(NAME,_openr_next_archived_file),\
CAT(NAME,_get_elt_at_index),\
CAT(NAME,_generic_stat_arch_elt),\
CAT(NAME,_update_armap_timestamp)
boolean (*_bfd_slurp_armap) PARAMS ((bfd *));
boolean (*_bfd_slurp_extended_name_table) PARAMS ((bfd *));
boolean (*_bfd_construct_extended_name_table)
PARAMS ((bfd *, char **, bfd_size_type *, const char **));
void (*_bfd_truncate_arname) PARAMS ((bfd *, CONST char *, char *));
boolean (*write_armap) PARAMS ((bfd *arch,
unsigned int elength,
struct orl *map,
unsigned int orl_count,
int stridx));
PTR (*_bfd_read_ar_hdr_fn) PARAMS ((bfd *));
bfd * (*openr_next_archived_file) PARAMS ((bfd *arch, bfd *prev));
#define bfd_get_elt_at_index(b,i) BFD_SEND(b, _bfd_get_elt_at_index, (b,i))
bfd * (*_bfd_get_elt_at_index) PARAMS ((bfd *, symindex));
int (*_bfd_stat_arch_elt) PARAMS ((bfd *, struct stat *));
boolean (*_bfd_update_armap_timestamp) PARAMS ((bfd *));
/* Entry points used for symbols. */
#define BFD_JUMP_TABLE_SYMBOLS(NAME)\
CAT(NAME,_get_symtab_upper_bound),\
CAT(NAME,_get_symtab),\
CAT(NAME,_make_empty_symbol),\
CAT(NAME,_print_symbol),\
CAT(NAME,_get_symbol_info),\
CAT(NAME,_bfd_is_local_label_name),\
CAT(NAME,_get_lineno),\
CAT(NAME,_find_nearest_line),\
CAT(NAME,_bfd_make_debug_symbol),\
CAT(NAME,_read_minisymbols),\
CAT(NAME,_minisymbol_to_symbol)
long (*_bfd_get_symtab_upper_bound) PARAMS ((bfd *));
long (*_bfd_canonicalize_symtab) PARAMS ((bfd *,
struct symbol_cache_entry **));
struct symbol_cache_entry *
(*_bfd_make_empty_symbol) PARAMS ((bfd *));
void (*_bfd_print_symbol) PARAMS ((bfd *, PTR,
struct symbol_cache_entry *,
bfd_print_symbol_type));
#define bfd_print_symbol(b,p,s,e) BFD_SEND(b, _bfd_print_symbol, (b,p,s,e))
void (*_bfd_get_symbol_info) PARAMS ((bfd *,
struct symbol_cache_entry *,
symbol_info *));
#define bfd_get_symbol_info(b,p,e) BFD_SEND(b, _bfd_get_symbol_info, (b,p,e))
boolean (*_bfd_is_local_label_name) PARAMS ((bfd *, const char *));
alent * (*_get_lineno) PARAMS ((bfd *, struct symbol_cache_entry *));
boolean (*_bfd_find_nearest_line) PARAMS ((bfd *abfd,
struct sec *section, struct symbol_cache_entry **symbols,
bfd_vma offset, CONST char **file, CONST char **func,
unsigned int *line));
/* Back-door to allow format-aware applications to create debug symbols
while using BFD for everything else. Currently used by the assembler
when creating COFF files. */
asymbol * (*_bfd_make_debug_symbol) PARAMS ((
bfd *abfd,
void *ptr,
unsigned long size));
#define bfd_read_minisymbols(b, d, m, s) \
BFD_SEND (b, _read_minisymbols, (b, d, m, s))
long (*_read_minisymbols) PARAMS ((bfd *, boolean, PTR *,
unsigned int *));
#define bfd_minisymbol_to_symbol(b, d, m, f) \
BFD_SEND (b, _minisymbol_to_symbol, (b, d, m, f))
asymbol *(*_minisymbol_to_symbol) PARAMS ((bfd *, boolean, const PTR,
asymbol *));
/* Routines for relocs. */
#define BFD_JUMP_TABLE_RELOCS(NAME)\
CAT(NAME,_get_reloc_upper_bound),\
CAT(NAME,_canonicalize_reloc),\
CAT(NAME,_bfd_reloc_type_lookup)
long (*_get_reloc_upper_bound) PARAMS ((bfd *, sec_ptr));
long (*_bfd_canonicalize_reloc) PARAMS ((bfd *, sec_ptr, arelent **,
struct symbol_cache_entry **));
/* See documentation on reloc types. */
reloc_howto_type *
(*reloc_type_lookup) PARAMS ((bfd *abfd,
bfd_reloc_code_real_type code));
/* Routines used when writing an object file. */
#define BFD_JUMP_TABLE_WRITE(NAME)\
CAT(NAME,_set_arch_mach),\
CAT(NAME,_set_section_contents)
boolean (*_bfd_set_arch_mach) PARAMS ((bfd *, enum bfd_architecture,
unsigned long));
boolean (*_bfd_set_section_contents) PARAMS ((bfd *, sec_ptr, PTR,
file_ptr, bfd_size_type));
/* Routines used by the linker. */
#define BFD_JUMP_TABLE_LINK(NAME)\
CAT(NAME,_sizeof_headers),\
CAT(NAME,_bfd_get_relocated_section_contents),\
CAT(NAME,_bfd_relax_section),\
CAT(NAME,_bfd_link_hash_table_create),\
CAT(NAME,_bfd_link_add_symbols),\
CAT(NAME,_bfd_final_link),\
CAT(NAME,_bfd_link_split_section),\
CAT(NAME,_bfd_gc_sections)
int (*_bfd_sizeof_headers) PARAMS ((bfd *, boolean));
bfd_byte * (*_bfd_get_relocated_section_contents) PARAMS ((bfd *,
struct bfd_link_info *, struct bfd_link_order *,
bfd_byte *data, boolean relocateable,
struct symbol_cache_entry **));
boolean (*_bfd_relax_section) PARAMS ((bfd *, struct sec *,
struct bfd_link_info *, boolean *again));
/* Create a hash table for the linker. Different backends store
different information in this table. */
struct bfd_link_hash_table *(*_bfd_link_hash_table_create) PARAMS ((bfd *));
/* Add symbols from this object file into the hash table. */
boolean (*_bfd_link_add_symbols) PARAMS ((bfd *, struct bfd_link_info *));
/* Do a link based on the link_order structures attached to each
section of the BFD. */
boolean (*_bfd_final_link) PARAMS ((bfd *, struct bfd_link_info *));
/* Should this section be split up into smaller pieces during linking. */
boolean (*_bfd_link_split_section) PARAMS ((bfd *, struct sec *));
/* Remove sections that are not referenced from the output. */
boolean (*_bfd_gc_sections) PARAMS ((bfd *, struct bfd_link_info *));
/* Routines to handle dynamic symbols and relocs. */
#define BFD_JUMP_TABLE_DYNAMIC(NAME)\
CAT(NAME,_get_dynamic_symtab_upper_bound),\
CAT(NAME,_canonicalize_dynamic_symtab),\
CAT(NAME,_get_dynamic_reloc_upper_bound),\
CAT(NAME,_canonicalize_dynamic_reloc)
/* Get the amount of memory required to hold the dynamic symbols. */
long (*_bfd_get_dynamic_symtab_upper_bound) PARAMS ((bfd *));
/* Read in the dynamic symbols. */
long (*_bfd_canonicalize_dynamic_symtab)
PARAMS ((bfd *, struct symbol_cache_entry **));
/* Get the amount of memory required to hold the dynamic relocs. */
long (*_bfd_get_dynamic_reloc_upper_bound) PARAMS ((bfd *));
/* Read in the dynamic relocs. */
long (*_bfd_canonicalize_dynamic_reloc)
PARAMS ((bfd *, arelent **, struct symbol_cache_entry **));
@end example
A pointer to an alternative bfd_target in case the current one is not
satisfactory. This can happen when the target cpu supports both big
and little endian code, and target chosen by the linker has the wrong
endianness. The function open_output() in ld/ldlang.c uses this field
to find an alternative output format that is suitable.
@example
/* Opposite endian version of this target. */
const struct bfd_target * alternative_target;
@end example
Data for use by back-end routines, which isn't generic enough to belong
in this structure.
@example
PTR backend_data;
@} bfd_target;
@end example
@findex bfd_set_default_target
@subsubsection @code{bfd_set_default_target}
@strong{Synopsis}
@example
boolean bfd_set_default_target (const char *name);
@end example
@strong{Description}@*
Set the default target vector to use when recognizing a BFD.
This takes the name of the target, which may be a BFD target
name or a configuration triplet.
@findex bfd_find_target
@subsubsection @code{bfd_find_target}
@strong{Synopsis}
@example
const bfd_target *bfd_find_target(CONST char *target_name, bfd *abfd);
@end example
@strong{Description}@*
Return a pointer to the transfer vector for the object target
named @var{target_name}. If @var{target_name} is @code{NULL}, choose the
one in the environment variable @code{GNUTARGET}; if that is null or not
defined, then choose the first entry in the target list.
Passing in the string "default" or setting the environment
variable to "default" will cause the first entry in the target
list to be returned, and "target_defaulted" will be set in the
BFD. This causes @code{bfd_check_format} to loop over all the
targets to find the one that matches the file being read.
@findex bfd_target_list
@subsubsection @code{bfd_target_list}
@strong{Synopsis}
@example
const char **bfd_target_list(void);
@end example
@strong{Description}@*
Return a freshly malloced NULL-terminated
vector of the names of all the valid BFD targets. Do not
modify the names.
@findex bfd_seach_for_target
@subsubsection @code{bfd_seach_for_target}
@strong{Synopsis}
@example
const bfd_target * bfd_search_for_target (int (* search_func)(const bfd_target *, void *), void *);
@end example
@strong{Description}@*
Return a pointer to the first transfer vector in the list of
transfer vectors maintained by BFD that produces a non-zero
result when passed to the function @var{search_func}. The
parameter @var{data} is passed, unexamined, to the search
function.

1835
binutils/arlex.c Normal file
View File

File diff suppressed because it is too large Load Diff

1090
binutils/arparse.c Normal file
View File

File diff suppressed because it is too large Load Diff

26
binutils/arparse.h Normal file
View File

@@ -0,0 +1,26 @@
typedef union {
char *name;
struct list *list ;
} YYSTYPE;
#define NEWLINE 257
#define VERBOSE 258
#define FILENAME 259
#define ADDLIB 260
#define LIST 261
#define ADDMOD 262
#define CLEAR 263
#define CREATE 264
#define DELETE 265
#define DIRECTORY 266
#define END 267
#define EXTRACT 268
#define FULLDIR 269
#define HELP 270
#define QUIT 271
#define REPLACE 272
#define SAVE 273
#define OPEN 274
extern YYSTYPE yylval;

74
binutils/binutils.info Normal file
View File

@@ -0,0 +1,74 @@
This is binutils.info, produced by makeinfo version 4.0 from
binutils.texi.
START-INFO-DIR-ENTRY
* Binutils: (binutils). The GNU binary utilities.
* ar: (binutils)ar. Create, modify, and extract from archives
* nm: (binutils)nm. List symbols from object files
* objcopy: (binutils)objcopy. Copy and translate object files
* objdump: (binutils)objdump. Display information from object files
* ranlib: (binutils)ranlib. Generate index to archive contents
* readelf: (binutils)readelf. Display the contents of ELF format files.
* size: (binutils)size. List section sizes and total size
* strings: (binutils)strings. List printable strings from files
* strip: (binutils)strip. Discard symbols
* c++filt: (binutils)c++filt. Filter to demangle encoded C++ symbols
* cxxfilt: (binutils)c++filt. MS-DOS name for c++filt
* addr2line: (binutils)addr2line. Convert addresses to file and line
* nlmconv: (binutils)nlmconv. Converts object code into an NLM
* windres: (binutils)windres. Manipulate Windows resources
* dlltool: (binutils)dlltool. Create files needed to build and use DLLs
END-INFO-DIR-ENTRY
Copyright (C) 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000 Free
Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.
Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided also
that the entire resulting derived work is distributed under the terms
of a permission notice identical to this one.
Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions.

Indirect:
binutils.info-1: 1845
binutils.info-2: 49760
binutils.info-3: 96951

Tag Table:
(Indirect)
Node: Top1845
Node: ar3094
Node: ar cmdline5268
Node: ar scripts13107
Node: nm18786
Node: objcopy25756
Node: objdump38583
Node: ranlib49011
Node: size49760
Node: strings52491
Node: strip54316
Node: c++filt57281
Ref: c++filt-Footnote-160138
Node: addr2line60244
Node: nlmconv62650
Node: windres65254
Node: dlltool70306
Node: readelf79647
Node: Selecting The Target System82798
Node: Target Selection83815
Node: Architecture Selection86516
Node: Linker Emulation Selection87747
Node: Reporting Bugs88625
Node: Bug Criteria89376
Node: Bug Reporting89922
Node: Index96951

End Tag Table

1277
binutils/binutils.info-1 Normal file
View File

File diff suppressed because it is too large Load Diff

1404
binutils/binutils.info-2 Normal file
View File

File diff suppressed because it is too large Load Diff

182
binutils/binutils.info-3 Normal file
View File

@@ -0,0 +1,182 @@
This is binutils.info, produced by makeinfo version 4.0 from
binutils.texi.
START-INFO-DIR-ENTRY
* Binutils: (binutils). The GNU binary utilities.
* ar: (binutils)ar. Create, modify, and extract from archives
* nm: (binutils)nm. List symbols from object files
* objcopy: (binutils)objcopy. Copy and translate object files
* objdump: (binutils)objdump. Display information from object files
* ranlib: (binutils)ranlib. Generate index to archive contents
* readelf: (binutils)readelf. Display the contents of ELF format files.
* size: (binutils)size. List section sizes and total size
* strings: (binutils)strings. List printable strings from files
* strip: (binutils)strip. Discard symbols
* c++filt: (binutils)c++filt. Filter to demangle encoded C++ symbols
* cxxfilt: (binutils)c++filt. MS-DOS name for c++filt
* addr2line: (binutils)addr2line. Convert addresses to file and line
* nlmconv: (binutils)nlmconv. Converts object code into an NLM
* windres: (binutils)windres. Manipulate Windows resources
* dlltool: (binutils)dlltool. Create files needed to build and use DLLs
END-INFO-DIR-ENTRY
Copyright (C) 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000 Free
Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.
Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided also
that the entire resulting derived work is distributed under the terms
of a permission notice identical to this one.
Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions.

File: binutils.info, Node: Index, Prev: Reporting Bugs, Up: Top
Index
*****
* Menu:
* .stab: objdump.
* addr2line: addr2line.
* address to file name and line number: addr2line.
* all header information, object file: objdump.
* ar: ar.
* ar compatibility: ar.
* architecture: objdump.
* architectures available: objdump.
* archive contents: ranlib.
* archive headers: objdump.
* archives: ar.
* base files: dlltool.
* bug criteria: Bug Criteria.
* bug reports: Bug Reporting.
* bugs: Reporting Bugs.
* bugs, reporting: Bug Reporting.
* c++filt: c++filt.
* changing object addresses: objcopy.
* changing section address: objcopy.
* changing section LMA: objcopy.
* changing section VMA: objcopy.
* changing start address: objcopy.
* collections of files: ar.
* compatibility, ar: ar.
* contents of archive: ar cmdline.
* crash: Bug Criteria.
* creating archives: ar cmdline.
* cxxfilt: c++filt.
* dates in archive: ar cmdline.
* debug symbols: objdump.
* debugging symbols: nm.
* deleting from archive: ar cmdline.
* demangling C++ symbols: c++filt.
* demangling in nm: nm.
* demangling in objdump <1>: addr2line.
* demangling in objdump: objdump.
* disassembling object code: objdump.
* disassembly architecture: objdump.
* disassembly endianness: objdump.
* disassembly, with source: objdump.
* discarding symbols: strip.
* DLL: dlltool.
* dlltool: dlltool.
* dynamic relocation entries, in object file: objdump.
* dynamic symbol table entries, printing: objdump.
* dynamic symbols: nm.
* ELF core notes: readelf.
* ELF dynamic section information: readelf.
* ELF file header information: readelf.
* ELF file information: readelf.
* ELF object file format: objdump.
* ELF program header information: readelf.
* ELF reloc information: readelf.
* ELF section information: readelf.
* ELF segment information: readelf.
* ELF symbol table information: readelf.
* ELF version sections informations: readelf.
* endianness: objdump.
* error on valid input: Bug Criteria.
* external symbols: nm.
* extract from archive: ar cmdline.
* fatal signal: Bug Criteria.
* file name: nm.
* header information, all: objdump.
* input .def file: dlltool.
* input file name: nm.
* libraries: ar.
* listings strings: strings.
* machine instructions: objdump.
* moving in archive: ar cmdline.
* MRI compatibility, ar: ar scripts.
* name duplication in archive: ar cmdline.
* name length: ar.
* nm: nm.
* nm compatibility: nm.
* nm format: nm.
* not writing archive index: ar cmdline.
* objdump: objdump.
* object code format <1>: addr2line.
* object code format <2>: strings.
* object code format <3>: size.
* object code format <4>: objdump.
* object code format: nm.
* object file header: objdump.
* object file information: objdump.
* object file sections: objdump.
* object formats available: objdump.
* operations on archive: ar cmdline.
* printing from archive: ar cmdline.
* printing strings: strings.
* quick append to archive: ar cmdline.
* radix for section sizes: size.
* ranlib: ranlib.
* readelf: readelf.
* relative placement in archive: ar cmdline.
* relocation entries, in object file: objdump.
* removing symbols: strip.
* repeated names in archive: ar cmdline.
* replacement in archive: ar cmdline.
* reporting bugs: Reporting Bugs.
* scripts, ar: ar scripts.
* section addresses in objdump: objdump.
* section headers: objdump.
* section information: objdump.
* section sizes: size.
* sections, full contents: objdump.
* size: size.
* size display format: size.
* size number format: size.
* sorting symbols: nm.
* source code context: objdump.
* source disassembly: objdump.
* source file name: nm.
* source filenames for object files: objdump.
* stab: objdump.
* start-address: objdump.
* stop-address: objdump.
* strings: strings.
* strings, printing: strings.
* strip: strip.
* symbol index <1>: ranlib.
* symbol index: ar.
* symbol index, listing: nm.
* symbol line numbers: nm.
* symbol table entries, printing: objdump.
* symbols: nm.
* symbols, discarding: strip.
* undefined symbols: nm.
* Unix compatibility, ar: ar cmdline.
* updating an archive: ar cmdline.
* version: Top.
* VMA in objdump: objdump.
* wide output, printing: objdump.
* writing archive index: ar cmdline.

1
binutils/config.texi Normal file
View File

@@ -0,0 +1 @@
@set VERSION 2.10

1844
binutils/deflex.c Normal file
View File

File diff suppressed because it is too large Load Diff

1202
binutils/defparse.c Normal file
View File

File diff suppressed because it is too large Load Diff

34
binutils/defparse.h Normal file
View File

@@ -0,0 +1,34 @@
typedef union {
char *id;
int number;
} YYSTYPE;
#define NAME 257
#define LIBRARY 258
#define DESCRIPTION 259
#define STACKSIZE 260
#define HEAPSIZE 261
#define CODE 262
#define DATA 263
#define SECTIONS 264
#define EXPORTS 265
#define IMPORTS 266
#define VERSIONK 267
#define BASE 268
#define CONSTANT 269
#define READ 270
#define WRITE 271
#define EXECUTE 272
#define SHARED 273
#define NONSHARED 274
#define NONAME 275
#define SINGLE 276
#define MULTIPLE 277
#define INITINSTANCE 278
#define INITGLOBAL 279
#define TERMINSTANCE 280
#define TERMGLOBAL 281
#define ID 282
#define NUMBER 283
extern YYSTYPE yylval;

1991
binutils/nlmheader.c Normal file
View File

File diff suppressed because it is too large Load Diff

43
binutils/nlmheader.h Normal file
View File

@@ -0,0 +1,43 @@
typedef union
{
char *string;
struct string_list *list;
} YYSTYPE;
#define CHECK 257
#define CODESTART 258
#define COPYRIGHT 259
#define CUSTOM 260
#define DATE 261
#define DEBUG 262
#define DESCRIPTION 263
#define EXIT 264
#define EXPORT 265
#define FLAG_ON 266
#define FLAG_OFF 267
#define FULLMAP 268
#define HELP 269
#define IMPORT 270
#define INPUT 271
#define MAP 272
#define MESSAGES 273
#define MODULE 274
#define MULTIPLE 275
#define OS_DOMAIN 276
#define OUTPUT 277
#define PSEUDOPREEMPTION 278
#define REENTRANT 279
#define SCREENNAME 280
#define SHARELIB 281
#define STACK 282
#define START 283
#define SYNCHRONIZE 284
#define THREADNAME 285
#define TYPE 286
#define VERBOSE 287
#define VERSIONK 288
#define XDCDATA 289
#define STRING 290
#define QUOTED_STRING 291
extern YYSTYPE yylval;

2589
binutils/rclex.c Normal file
View File

File diff suppressed because it is too large Load Diff

3107
binutils/rcparse.c Normal file
View File

File diff suppressed because it is too large Load Diff

125
binutils/rcparse.h Normal file
View File

@@ -0,0 +1,125 @@
typedef union
{
struct accelerator acc;
struct accelerator *pacc;
struct dialog_control *dialog_control;
struct menuitem *menuitem;
struct
{
struct rcdata_item *first;
struct rcdata_item *last;
} rcdata;
struct rcdata_item *rcdata_item;
struct stringtable_data *stringtable;
struct fixed_versioninfo *fixver;
struct ver_info *verinfo;
struct ver_stringinfo *verstring;
struct ver_varinfo *vervar;
struct res_id id;
struct res_res_info res_info;
struct
{
unsigned short on;
unsigned short off;
} memflags;
struct
{
unsigned long val;
/* Nonzero if this number was explicitly specified as long. */
int dword;
} i;
unsigned long il;
unsigned short is;
const char *s;
struct
{
unsigned long length;
const char *s;
} ss;
} YYSTYPE;
#define BEG 257
#define END 258
#define ACCELERATORS 259
#define VIRTKEY 260
#define ASCII 261
#define NOINVERT 262
#define SHIFT 263
#define CONTROL 264
#define ALT 265
#define BITMAP 266
#define CURSOR 267
#define DIALOG 268
#define DIALOGEX 269
#define EXSTYLE 270
#define CAPTION 271
#define CLASS 272
#define STYLE 273
#define AUTO3STATE 274
#define AUTOCHECKBOX 275
#define AUTORADIOBUTTON 276
#define CHECKBOX 277
#define COMBOBOX 278
#define CTEXT 279
#define DEFPUSHBUTTON 280
#define EDITTEXT 281
#define GROUPBOX 282
#define LISTBOX 283
#define LTEXT 284
#define PUSHBOX 285
#define PUSHBUTTON 286
#define RADIOBUTTON 287
#define RTEXT 288
#define SCROLLBAR 289
#define STATE3 290
#define USERBUTTON 291
#define BEDIT 292
#define HEDIT 293
#define IEDIT 294
#define FONT 295
#define ICON 296
#define LANGUAGE 297
#define CHARACTERISTICS 298
#define VERSIONK 299
#define MENU 300
#define MENUEX 301
#define MENUITEM 302
#define SEPARATOR 303
#define POPUP 304
#define CHECKED 305
#define GRAYED 306
#define HELP 307
#define INACTIVE 308
#define MENUBARBREAK 309
#define MENUBREAK 310
#define MESSAGETABLE 311
#define RCDATA 312
#define STRINGTABLE 313
#define VERSIONINFO 314
#define FILEVERSION 315
#define PRODUCTVERSION 316
#define FILEFLAGSMASK 317
#define FILEFLAGS 318
#define FILEOS 319
#define FILETYPE 320
#define FILESUBTYPE 321
#define BLOCKSTRINGFILEINFO 322
#define BLOCKVARFILEINFO 323
#define VALUE 324
#define BLOCK 325
#define MOVEABLE 326
#define FIXED 327
#define PURE 328
#define IMPURE 329
#define PRELOAD 330
#define LOADONCALL 331
#define DISCARDABLE 332
#define NOT 333
#define QUOTEDSTRING 334
#define STRING 335
#define NUMBER 336
#define SIZEDSTRING 337
#define IGNORED_TOKEN 338
#define NEG 339
extern YYSTYPE yylval;

1309
binutils/sysinfo.c Normal file
View File

File diff suppressed because it is too large Load Diff

13
binutils/sysinfo.h Normal file
View File

@@ -0,0 +1,13 @@
typedef union {
int i;
char *s;
} YYSTYPE;
#define COND 257
#define REPEAT 258
#define TYPE 259
#define NAME 260
#define NUMBER 261
#define UNIT 262
extern YYSTYPE yylval;

1683
binutils/syslex.c Normal file
View File

File diff suppressed because it is too large Load Diff

95
etc/configure.info Normal file
View File

@@ -0,0 +1,95 @@
This is configure.info, produced by makeinfo version 4.0 from
./configure.texi.
INFO-DIR-SECTION GNU admin
START-INFO-DIR-ENTRY
* configure: (configure). The GNU configure and build system
END-INFO-DIR-ENTRY
This file documents the GNU configure and build system.
Copyright (C) 1998 Cygnus Solutions.
Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.
Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.
Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Foundation.

Indirect:
configure.info-1: 971
configure.info-2: 48782
configure.info-3: 98073

Tag Table:
(Indirect)
Node: Top971
Node: Introduction1502
Node: Goals2583
Node: Tools3302
Node: History4291
Node: Building7284
Node: Getting Started10374
Node: Write configure.in10886
Node: Write Makefile.am18132
Node: Write acconfig.h21290
Node: Generate files22827
Node: Getting Started Example24788
Node: Getting Started Example 125538
Node: Getting Started Example 227475
Node: Getting Started Example 330591
Node: Generate Files in Example32961
Node: Files34042
Node: Developer Files34653
Node: Developer Files Picture35028
Node: Written Developer Files36320
Node: Generated Developer Files38863
Node: Build Files41998
Node: Build Files Picture42654
Node: Build Files Description43409
Node: Support Files45406
Node: Configuration Names48283
Node: Configuration Name Definition48782
Node: Using Configuration Names51100
Node: Cross Compilation Tools53067
Node: Cross Compilation Concepts53757
Node: Host and Target54719
Node: Using the Host Type56215
Node: Specifying the Target57559
Node: Using the Target Type58343
Node: Cross Tools in the Cygnus Tree61769
Node: Host and Target Libraries62821
Node: Target Library Configure Scripts66561
Node: Make Targets in Cygnus Tree69644
Node: Target libiberty70983
Node: Canadian Cross72361
Node: Canadian Cross Example73201
Node: Canadian Cross Concepts74315
Node: Build Cross Host Tools75822
Node: Build and Host Options76769
Node: CCross not in Cygnus Tree78550
Node: CCross in Cygnus Tree79523
Node: Standard Cygnus CCross79939
Node: Cross Cygnus CCross81294
Node: Supporting Canadian Cross84085
Node: CCross in Configure84695
Node: CCross in Make87852
Node: Cygnus Configure89446
Node: Cygnus Configure Basics90280
Node: Cygnus Configure in C++ Libraries94954
Node: Multilibs95956
Node: Multilibs in gcc97000
Node: Multilibs in Target Libraries98073
Node: FAQ102257
Node: Index106353

End Tag Table

1313
etc/configure.info-1 Normal file
View File

File diff suppressed because it is too large Load Diff

1137
etc/configure.info-2 Normal file
View File

File diff suppressed because it is too large Load Diff

285
etc/configure.info-3 Normal file
View File

@@ -0,0 +1,285 @@
This is configure.info, produced by makeinfo version 4.0 from
./configure.texi.
INFO-DIR-SECTION GNU admin
START-INFO-DIR-ENTRY
* configure: (configure). The GNU configure and build system
END-INFO-DIR-ENTRY
This file documents the GNU configure and build system.
Copyright (C) 1998 Cygnus Solutions.
Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.
Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.
Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Foundation.

File: configure.info, Node: Multilibs in Target Libraries, Prev: Multilibs in gcc, Up: Multilibs
Multilibs in Target Libraries
=============================
The target libraries in the Cygnus tree are automatically built with
multilibs. That means that each library is built multiple times.
This default is set in the top level `configure.in' file, by adding
`--enable-multilib' to the list of arguments passed to configure when
it is run for the target libraries (*note Host and Target Libraries::).
Each target library uses the shell script `config-ml.in', written by
Doug Evans, to prepare to build target libraries. This shell script is
invoked after the `Makefile' has been created by the `configure'
script. If multilibs are not enabled, it does nothing, otherwise it
modifies the `Makefile' to support multilibs.
The `config-ml.in' script makes one copy of the `Makefile' for each
multilib in the appropriate subdirectory. When configuring in the
source directory (which is not recommended), it will build a symlink
tree of the sources in each subdirectory.
The `config-ml.in' script sets several variables in the various
`Makefile's. The `Makefile.in' must have definitions for these
variables already; `config-ml.in' simply changes the existing values.
The `Makefile' should use default values for these variables which will
do the right thing in the subdirectories.
`MULTISRCTOP'
`config-ml.in' will set this to a sequence of `../' strings, where
the number of strings is the number of multilib levels in the
source tree. The default value should be the empty string.
`MULTIBUILDTOP'
`config-ml.in' will set this to a sequence of `../' strings, where
the number of strings is number of multilib levels in the object
directory. The default value should be the empty string. This
will differ from `MULTISRCTOP' when configuring in the source tree
(which is not recommended).
`MULTIDIRS'
In the top level `Makefile' only, `config-ml.in' will set this to
the list of multilib subdirectories. The default value should be
the empty string.
`MULTISUBDIR'
`config-ml.in' will set this to the installed subdirectory name to
use for this subdirectory, with a leading `/'. The default value
shold be the empty string.
`MULTIDO'
`MULTICLEAN'
In the top level `Makefile' only, `config-ml.in' will set these
variables to commands to use when doing a recursive make. These
variables should both default to the string `true', so that by
default nothing happens.
All references to the parent of the source directory should use the
variable `MULTISRCTOP'. Instead of writing `$(srcdir)/..', you must
write `$(srcdir)/$(MULTISRCTOP)..'.
Similarly, references to the parent of the object directory should
use the variable `MULTIBUILDTOP'.
In the installation target, the libraries should be installed in the
subdirectory `MULTISUBDIR'. Instead of installing
`$(libdir)/libfoo.a', install `$(libdir)$(MULTISUBDIR)/libfoo.a'.
The `config-ml.in' script also modifies the top level `Makefile' to
add `multi-do' and `multi-clean' targets which are used when building
multilibs.
The default target of the `Makefile' should include the following
command:
@$(MULTIDO) $(FLAGS_TO_PASS) DO=all multi-do
This assumes that `$(FLAGS_TO_PASS)' is defined as a set of variables
to pass to a recursive invocation of `make'. This will build all the
multilibs. Note that the default value of `MULTIDO' is `true', so by
default this command will do nothing. It will only do something in the
top level `Makefile' if multilibs were enabled.
The `install' target of the `Makefile' should include the following
command:
@$(MULTIDO) $(FLAGS_TO_PASS) DO=install multi-do
In general, any operation, other than clean, which should be
performed on all the multilibs should use a `$(MULTIDO)' line, setting
the variable `DO' to the target of each recursive call to `make'.
The `clean' targets (`clean', `mostlyclean', etc.) should use
`$(MULTICLEAN)'. For example, the `clean' target should do this:
@$(MULTICLEAN) DO=clean multi-clean

File: configure.info, Node: FAQ, Next: Index, Prev: Multilibs, Up: Top
Frequently Asked Questions
**************************
Which do I run first, `autoconf' or `automake'?
Except when you first add autoconf or automake support to a
package, you shouldn't run either by hand. Instead, configure
with the `--enable-maintainer-mode' option, and let `make' take
care of it.
`autoconf' says something about undefined macros.
This means that you have macros in your `configure.in' which are
not defined by `autoconf'. You may be using an old version of
`autoconf'; try building and installing a newer one. Make sure the
newly installled `autoconf' is first on your `PATH'. Also, see
the next question.
My `configure' script has stuff like `CY_GNU_GETTEXT' in it.
This means that you have macros in your `configure.in' which should
be defined in your `aclocal.m4' file, but aren't. This usually
means that `aclocal' was not able to appropriate definitions of the
macros. Make sure that you have installed all the packages you
need. In particular, make sure that you have installed libtool
(this is where `AM_PROG_LIBTOOL' is defined) and gettext (this is
where `CY_GNU_GETTEXT' is defined, at least in the Cygnus version
of gettext).
My `Makefile' has `@' characters in it.
This may mean that you tried to use an autoconf substitution in
your `Makefile.in' without adding the appropriate `AC_SUBST' call
to your `configure' script. Or it may just mean that you need to
rebuild `Makefile' in your build directory. To rebuild `Makefile'
from `Makefile.in', run the shell script `config.status' with no
arguments. If you need to force `configure' to run again, first
run `config.status --recheck'. These runs are normally done
automatically by `Makefile' targets, but if your `Makefile' has
gotten messed up you'll need to help them along.
Why do I have to run both `config.status --recheck' and `config.status'?
Normally, you don't; they will be run automatically by `Makefile'
targets. If you do need to run them, use `config.status --recheck'
to run the `configure' script again with the same arguments as the
first time you ran it. Use `config.status' (with no arguments) to
regenerate all files (`Makefile', `config.h', etc.) based on the
results of the configure script. The two cases are separate
because it isn't always necessary to regenerate all the files
after running `config.status --recheck'. The `Makefile' targets
generated by automake will use the environment variables
`CONFIG_FILES' and `CONFIG_HEADERS' to only regenerate files as
they are needed.
What is the Cygnus tree?
The Cygnus tree is used for various packages including gdb, the GNU
binutils, and egcs. It is also, of course, used for Cygnus
releases. It is the build system which was developed at Cygnus,
using the Cygnus configure script. It permits building many
different packages with a single configure and make. The
configure scripts in the tree are being converted to autoconf, but
the general build structure remains intact.
Why do I have to keep rebuilding and reinstalling the tools?
I know, it's a pain. Unfortunately, there are bugs in the tools
themselves which need to be fixed, and each time that happens
everybody who uses the tools need to reinstall new versions of
them. I don't know if there is going to be a clever fix until the
tools stabilize.
Why not just have a Cygnus tree `make' target to update the tools?
The tools unfortunately need to be installed before they can be
used. That means that they must be built using an appropriate
prefix, and it seems unwise to assume that every configuration
uses an appropriate prefix. It might be possible to make them
work in place, or it might be possible to install them in some
subdirectory; so far these approaches have not been implemented.

File: configure.info, Node: Index, Prev: FAQ, Up: Top
Index
*****
* Menu:
* --build option: Build and Host Options.
* --host option: Build and Host Options.
* --target option: Specifying the Target.
* _GNU_SOURCE: Write configure.in.
* AC_CANONICAL_HOST: Using the Host Type.
* AC_CANONICAL_SYSTEM: Using the Target Type.
* AC_CONFIG_HEADER: Write configure.in.
* AC_EXEEXT: Write configure.in.
* AC_INIT: Write configure.in.
* AC_OUTPUT: Write configure.in.
* AC_PREREQ: Write configure.in.
* AC_PROG_CC: Write configure.in.
* AC_PROG_CXX: Write configure.in.
* acconfig.h: Written Developer Files.
* acconfig.h, writing: Write acconfig.h.
* acinclude.m4: Written Developer Files.
* aclocal.m4: Generated Developer Files.
* AM_CONFIG_HEADER: Write configure.in.
* AM_DISABLE_SHARED: Write configure.in.
* AM_EXEEXT: Write configure.in.
* AM_INIT_AUTOMAKE: Write configure.in.
* AM_MAINTAINER_MODE: Write configure.in.
* AM_PROG_LIBTOOL: Write configure.in.
* AM_PROG_LIBTOOL in configure: FAQ.
* build option: Build and Host Options.
* building with a cross compiler: Canadian Cross.
* canadian cross: Canadian Cross.
* canadian cross in configure: CCross in Configure.
* canadian cross in cygnus tree: CCross in Cygnus Tree.
* canadian cross in makefile: CCross in Make.
* canadian cross, configuring: Build and Host Options.
* canonical system names: Configuration Names.
* config.cache: Build Files Description.
* config.h: Build Files Description.
* config.h.in: Generated Developer Files.
* config.in: Generated Developer Files.
* config.status: Build Files Description.
* config.status --recheck: FAQ.
* configuration names: Configuration Names.
* configuration triplets: Configuration Names.
* configure: Generated Developer Files.
* configure build system: Build and Host Options.
* configure host: Build and Host Options.
* configure target: Specifying the Target.
* configure.in: Written Developer Files.
* configure.in, writing: Write configure.in.
* configuring a canadian cross: Build and Host Options.
* cross compiler: Cross Compilation Concepts.
* cross compiler, building with: Canadian Cross.
* cross tools: Cross Compilation Tools.
* CY_GNU_GETTEXT in configure: FAQ.
* cygnus configure: Cygnus Configure.
* goals: Goals.
* history: History.
* host names: Configuration Names.
* host option: Build and Host Options.
* host system: Host and Target.
* host triplets: Configuration Names.
* HOST_CC: CCross in Make.
* libg++ configure: Cygnus Configure in C++ Libraries.
* libio configure: Cygnus Configure in C++ Libraries.
* libstdc++ configure: Cygnus Configure in C++ Libraries.
* Makefile: Build Files Description.
* Makefile, garbage characters: FAQ.
* Makefile.am: Written Developer Files.
* Makefile.am, writing: Write Makefile.am.
* Makefile.in: Generated Developer Files.
* multilibs: Multilibs.
* stamp-h: Build Files Description.
* stamp-h.in: Generated Developer Files.
* system names: Configuration Names.
* system types: Configuration Names.
* target option: Specifying the Target.
* target system: Host and Target.
* triplets: Configuration Names.
* undefined macros: FAQ.

3833
etc/standards.info Normal file
View File

File diff suppressed because it is too large Load Diff

343
gas/doc/as.info Normal file
View File

@@ -0,0 +1,343 @@
This is as.info, produced by makeinfo version 4.0 from as.texinfo.
START-INFO-DIR-ENTRY
* As: (as). The GNU assembler.
END-INFO-DIR-ENTRY
This file documents the GNU Assembler "as".
Copyright (C) 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000 Free
Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.
Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.
Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions.

Indirect:
as.info-1: 866
as.info-2: 50563
as.info-3: 100403
as.info-4: 149485
as.info-5: 197985
as.info-6: 244546
as.info-7: 294439
as.info-8: 315111

Tag Table:
(Indirect)
Node: Top866
Node: Overview1538
Node: Manual13605
Node: GNU Assembler14544
Node: Object Formats15710
Node: Command Line16157
Node: Input Files17239
Node: Object19218
Node: Errors20165
Node: Invoking21355
Node: a23201
Node: D24535
Node: f24755
Node: I25258
Node: K25797
Node: L26096
Node: M26947
Node: MD31337
Node: o31756
Node: R32204
Node: statistics33220
Node: traditional-format33620
Node: v34086
Node: W34354
Node: Z35254
Node: Syntax35769
Node: Preprocessing36359
Node: Whitespace37919
Node: Comments38309
Node: Symbol Intro40329
Node: Statements41012
Node: Constants42926
Node: Characters43552
Node: Strings44045
Node: Chars46198
Node: Numbers46939
Node: Integers47470
Node: Bignums48113
Node: Flonums48456
Node: Sections50189
Node: Secs Background50563
Node: Ld Sections55589
Node: As Sections57983
Node: Sub-Sections58888
Node: bss61887
Node: Symbols62832
Node: Labels63479
Node: Setting Symbols64205
Node: Symbol Names64570
Node: Dot67532
Node: Symbol Attributes67974
Node: Symbol Value68706
Node: Symbol Type69742
Node: a.out Symbols70121
Node: Symbol Desc70371
Node: Symbol Other70653
Node: COFF Symbols70809
Node: SOM Symbols71438
Node: Expressions71871
Node: Empty Exprs72619
Node: Integer Exprs72961
Node: Arguments73351
Node: Operators74448
Node: Prefix Ops74774
Node: Infix Ops75093
Node: Pseudo Ops76585
Node: Abort80802
Node: ABORT81203
Node: Align81465
Node: Ascii83627
Node: Asciz83928
Node: Balign84168
Node: Byte86026
Node: Comm86259
Node: Data87618
Node: Def87928
Node: Desc88296
Node: Dim88789
Node: Double89180
Node: Eject89511
Node: Else89679
Node: Elseif89969
Node: End90253
Node: Endef90461
Node: Endfunc90784
Node: Endif90952
Node: Equ91205
Node: Equiv91508
Node: Err91904
Node: Exitm92207
Node: Extern92367
Node: Fail92621
Node: File93059
Node: Fill93668
Node: Float94625
Node: Func94959
Node: Global95539
Node: hword96281
Node: Ident96602
Node: If96902
Node: Include99494
Node: Int100034
Node: Irp100403
Node: Irpc101197
Node: Lcomm102016
Node: Lflags102757
Node: Line102944
Node: Linkonce103967
Node: Ln105187
Node: MRI105335
Node: List105662
Node: Long106265
Node: Macro106435
Node: Nolist108819
Node: Octa109235
Node: Org109561
Node: P2align110836
Node: Print112752
Node: Psize112969
Node: Purgem113642
Node: Quad113849
Node: Rept114290
Node: Sbttl114696
Node: Scl115054
Node: Section115550
Node: Set117951
Node: Short118503
Node: Single118816
Node: Size119153
Node: Sleb128119548
Node: Skip119863
Node: Space120178
Node: Stab121063
Node: String123058
Node: Struct123477
Node: Symver124189
Node: Tag125774
Node: Text126282
Node: Title126594
Node: Type126966
Node: Val127342
Node: Uleb128127703
Node: Visibility128025
Node: Word129068
Node: Deprecated130904
Node: Machine Dependencies131129
Node: ARC-Dependent133007
Node: ARC-Opts133321
Node: ARC-Float134055
Node: ARC-Directives134353
Node: AMD29K-Dependent134746
Node: AMD29K Options135127
Node: AMD29K Syntax135301
Node: AMD29K-Macros135565
Node: AMD29K-Chars135816
Node: AMD29K-Regs136079
Node: AMD29K Floating Point137343
Node: AMD29K Directives137549
Node: AMD29K Opcodes138957
Node: ARM-Dependent139293
Node: ARM Options139667
Node: ARM Syntax142165
Node: ARM-Chars142385
Node: ARM-Regs142937
Node: ARM Floating Point143109
Node: ARM Directives143299
Node: ARM Opcodes144977
Node: D10V-Dependent147030
Node: D10V-Opts147372
Node: D10V-Syntax148005
Node: D10V-Size148525
Node: D10V-Subs149485
Node: D10V-Chars150507
Node: D10V-Regs152093
Node: D10V-Addressing153124
Node: D10V-Word153797
Node: D10V-Float154298
Node: D10V-Opcodes154600
Node: D30V-Dependent154984
Node: D30V-Opts155329
Node: D30V-Syntax155995
Node: D30V-Size156518
Node: D30V-Subs157476
Node: D30V-Chars158498
Node: D30V-Guarded160783
Node: D30V-Regs161451
Node: D30V-Addressing162577
Node: D30V-Float163232
Node: D30V-Opcodes163534
Node: H8/300-Dependent163918
Node: H8/300 Options164322
Node: H8/300 Syntax164503
Node: H8/300-Chars164790
Node: H8/300-Regs165074
Node: H8/300-Addressing165978
Node: H8/300 Floating Point167004
Node: H8/300 Directives167320
Node: H8/300 Opcodes167840
Node: H8/500-Dependent176193
Node: H8/500 Options176597
Node: H8/500 Syntax176778
Node: H8/500-Chars177065
Node: H8/500-Regs177356
Node: H8/500-Addressing178112
Node: H8/500 Floating Point178729
Node: H8/500 Directives179045
Node: H8/500 Opcodes179364
Node: HPPA-Dependent184477
Node: HPPA Notes184902
Node: HPPA Options185649
Node: HPPA Syntax185833
Node: HPPA Floating Point187092
Node: HPPA Directives187287
Node: HPPA Opcodes193878
Node: ESA/390-Dependent194126
Node: ESA/390 Notes194576
Node: ESA/390 Options195356
Node: ESA/390 Syntax195555
Node: ESA/390 Floating Point197716
Node: ESA/390 Directives197985
Node: ESA/390 Opcodes201262
Node: i386-Dependent201513
Node: i386-Options202321
Node: i386-Syntax202465
Node: i386-Mnemonics204578
Node: i386-Regs206720
Node: i386-Prefixes207863
Node: i386-Memory209951
Node: i386-jumps212260
Node: i386-Float213350
Node: i386-SIMD215168
Node: i386-16bit216266
Node: i386-Bugs218229
Node: i386-Notes218969
Node: i960-Dependent219809
Node: Options-i960220201
Node: Floating Point-i960224082
Node: Directives-i960224339
Node: Opcodes for i960226359
Node: callj-i960226965
Node: Compare-and-branch-i960227440
Node: M68K-Dependent229329
Node: M68K-Opts229783
Node: M68K-Syntax234731
Node: M68K-Moto-Syntax236559
Node: M68K-Float239137
Node: M68K-Directives239646
Node: M68K-opcodes240241
Node: M68K-Branch240453
Node: M68K-Chars243268
Node: MIPS-Dependent243666
Node: MIPS Opts244546
Node: MIPS Object248576
Node: MIPS Stabs250131
Node: MIPS ISA250842
Node: MIPS autoextend251950
Node: MIPS insn252661
Node: MIPS option stack253147
Node: PJ-Dependent253860
Node: PJ Options254073
Node: SH-Dependent254340
Node: SH Options254720
Node: SH Syntax254885
Node: SH-Chars255144
Node: SH-Regs255423
Node: SH-Addressing256022
Node: SH Floating Point256916
Node: SH Directives257212
Node: SH Opcodes257568
Node: Sparc-Dependent261815
Node: Sparc-Opts262187
Node: Sparc-Aligned-Data264433
Node: Sparc-Float265277
Node: Sparc-Directives265467
Node: Z8000-Dependent267416
Node: Z8000 Options268375
Node: Z8000 Syntax268550
Node: Z8000-Chars268826
Node: Z8000-Regs269044
Node: Z8000-Addressing269834
Node: Z8000 Directives270777
Node: Z8000 Opcodes272375
Node: Vax-Dependent282311
Node: VAX-Opts282818
Node: VAX-float286542
Node: VAX-directives287163
Node: VAX-opcodes288012
Node: VAX-branch288390
Node: VAX-operands290886
Node: VAX-no291638
Node: V850-Dependent291864
Node: V850 Options292250
Node: V850 Syntax294063
Node: V850-Chars294289
Node: V850-Regs294439
Node: V850 Floating Point295976
Node: V850 Directives296171
Node: V850 Opcodes297071
Node: Reporting Bugs302356
Node: Bug Criteria303079
Node: Bug Reporting303839
Node: Acknowledgements310408
Ref: Acknowledgements-Footnote-1315085
Node: Index315111

End Tag Table

1424
gas/doc/as.info-1 Normal file
View File

File diff suppressed because it is too large Load Diff

1391
gas/doc/as.info-2 Normal file
View File

File diff suppressed because it is too large Load Diff

1482
gas/doc/as.info-3 Normal file
View File

File diff suppressed because it is too large Load Diff

1507
gas/doc/as.info-4 Normal file
View File

File diff suppressed because it is too large Load Diff

1214
gas/doc/as.info-5 Normal file
View File

File diff suppressed because it is too large Load Diff

1384
gas/doc/as.info-6 Normal file
View File

File diff suppressed because it is too large Load Diff

612
gas/doc/as.info-7 Normal file
View File

@@ -0,0 +1,612 @@
This is as.info, produced by makeinfo version 4.0 from as.texinfo.
START-INFO-DIR-ENTRY
* As: (as). The GNU assembler.
END-INFO-DIR-ENTRY
This file documents the GNU Assembler "as".
Copyright (C) 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000 Free
Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.
Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.
Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions.

File: as.info, Node: V850-Regs, Prev: V850-Chars, Up: V850 Syntax
Register Names
..............
`as' supports the following names for registers:
`general register 0'
r0, zero
`general register 1'
r1
`general register 2'
r2, hp
`general register 3'
r3, sp
`general register 4'
r4, gp
`general register 5'
r5, tp
`general register 6'
r6
`general register 7'
r7
`general register 8'
r8
`general register 9'
r9
`general register 10'
r10
`general register 11'
r11
`general register 12'
r12
`general register 13'
r13
`general register 14'
r14
`general register 15'
r15
`general register 16'
r16
`general register 17'
r17
`general register 18'
r18
`general register 19'
r19
`general register 20'
r20
`general register 21'
r21
`general register 22'
r22
`general register 23'
r23
`general register 24'
r24
`general register 25'
r25
`general register 26'
r26
`general register 27'
r27
`general register 28'
r28
`general register 29'
r29
`general register 30'
r30, ep
`general register 31'
r31, lp
`system register 0'
eipc
`system register 1'
eipsw
`system register 2'
fepc
`system register 3'
fepsw
`system register 4'
ecr
`system register 5'
psw
`system register 16'
ctpc
`system register 17'
ctpsw
`system register 18'
dbpc
`system register 19'
dbpsw
`system register 20'
ctbp

File: as.info, Node: V850 Floating Point, Next: V850 Directives, Prev: V850 Syntax, Up: V850-Dependent
Floating Point
--------------
The V850 family uses IEEE floating-point numbers.

File: as.info, Node: V850 Directives, Next: V850 Opcodes, Prev: V850 Floating Point, Up: V850-Dependent
V850 Machine Directives
-----------------------
`.offset <EXPRESSION>'
Moves the offset into the current section to the specified amount.
`.section "name", <type>'
This is an extension to the standard .section directive. It sets
the current section to be <type> and creates an alias for this
section called "name".
`.v850'
Specifies that the assembled code should be marked as being
targeted at the V850 processor. This allows the linker to detect
attempts to link such code with code assembled for other
processors.
`.v850e'
Specifies that the assembled code should be marked as being
targeted at the V850E processor. This allows the linker to detect
attempts to link such code with code assembled for other
processors.

File: as.info, Node: V850 Opcodes, Prev: V850 Directives, Up: V850-Dependent
Opcodes
-------
`as' implements all the standard V850 opcodes.
`as' also implements the following pseudo ops:
`hi0()'
Computes the higher 16 bits of the given expression and stores it
into the immediate operand field of the given instruction. For
example:
`mulhi hi0(here - there), r5, r6'
computes the difference between the address of labels 'here' and
'there', takes the upper 16 bits of this difference, shifts it
down 16 bits and then mutliplies it by the lower 16 bits in
register 5, putting the result into register 6.
`lo()'
Computes the lower 16 bits of the given expression and stores it
into the immediate operand field of the given instruction. For
example:
`addi lo(here - there), r5, r6'
computes the difference between the address of labels 'here' and
'there', takes the lower 16 bits of this difference and adds it to
register 5, putting the result into register 6.
`hi()'
Computes the higher 16 bits of the given expression and then adds
the value of the most significant bit of the lower 16 bits of the
expression and stores the result into the immediate operand field
of the given instruction. For example the following code can be
used to compute the address of the label 'here' and store it into
register 6:
`movhi hi(here), r0, r6' `movea lo(here), r6, r6'
The reason for this special behaviour is that movea performs a sign
extention on its immediate operand. So for example if the address
of 'here' was 0xFFFFFFFF then without the special behaviour of the
hi() pseudo-op the movhi instruction would put 0xFFFF0000 into r6,
then the movea instruction would takes its immediate operand,
0xFFFF, sign extend it to 32 bits, 0xFFFFFFFF, and then add it
into r6 giving 0xFFFEFFFF which is wrong (the fifth nibble is E).
With the hi() pseudo op adding in the top bit of the lo() pseudo
op, the movhi instruction actually stores 0 into r6 (0xFFFF + 1 =
0x0000), so that the movea instruction stores 0xFFFFFFFF into r6 -
the right value.
`hilo()'
Computes the 32 bit value of the given expression and stores it
into the immediate operand field of the given instruction (which
must be a mov instruction). For example:
`mov hilo(here), r6'
computes the absolute address of label 'here' and puts the result
into register 6.
`sdaoff()'
Computes the offset of the named variable from the start of the
Small Data Area (whoes address is held in register 4, the GP
register) and stores the result as a 16 bit signed value in the
immediate operand field of the given instruction. For example:
`ld.w sdaoff(_a_variable)[gp],r6'
loads the contents of the location pointed to by the label
'_a_variable' into register 6, provided that the label is located
somewhere within +/- 32K of the address held in the GP register.
[Note the linker assumes that the GP register contains a fixed
address set to the address of the label called '__gp'. This can
either be set up automatically by the linker, or specifically set
by using the `--defsym __gp=<value>' command line option].
`tdaoff()'
Computes the offset of the named variable from the start of the
Tiny Data Area (whoes address is held in register 30, the EP
register) and stores the result as a 4,5, 7 or 8 bit unsigned
value in the immediate operand field of the given instruction.
For example:
`sld.w tdaoff(_a_variable)[ep],r6'
loads the contents of the location pointed to by the label
'_a_variable' into register 6, provided that the label is located
somewhere within +256 bytes of the address held in the EP
register. [Note the linker assumes that the EP register contains
a fixed address set to the address of the label called '__ep'.
This can either be set up automatically by the linker, or
specifically set by using the `--defsym __ep=<value>' command line
option].
`zdaoff()'
Computes the offset of the named variable from address 0 and
stores the result as a 16 bit signed value in the immediate
operand field of the given instruction. For example:
`movea zdaoff(_a_variable),zero,r6'
puts the address of the label '_a_variable' into register 6,
assuming that the label is somewhere within the first 32K of
memory. (Strictly speaking it also possible to access the last
32K of memory as well, as the offsets are signed).
`ctoff()'
Computes the offset of the named variable from the start of the
Call Table Area (whoes address is helg in system register 20, the
CTBP register) and stores the result a 6 or 16 bit unsigned value
in the immediate field of then given instruction or piece of data.
For example:
`callt ctoff(table_func1)'
will put the call the function whoes address is held in the call
table at the location labeled 'table_func1'.
For information on the V850 instruction set, see `V850 Family
32-/16-Bit single-Chip Microcontroller Architecture Manual' from NEC.
Ltd.

File: as.info, Node: Reporting Bugs, Next: Acknowledgements, Prev: Machine Dependencies, Up: Top
Reporting Bugs
**************
Your bug reports play an essential role in making `as' reliable.
Reporting a bug may help you by bringing a solution to your problem,
or it may not. But in any case the principal function of a bug report
is to help the entire community by making the next version of `as' work
better. Bug reports are your contribution to the maintenance of `as'.
In order for a bug report to serve its purpose, you must include the
information that enables us to fix the bug.
* Menu:
* Bug Criteria:: Have you found a bug?
* Bug Reporting:: How to report bugs

File: as.info, Node: Bug Criteria, Next: Bug Reporting, Up: Reporting Bugs
Have you found a bug?
=====================
If you are not sure whether you have found a bug, here are some
guidelines:
* If the assembler gets a fatal signal, for any input whatever, that
is a `as' bug. Reliable assemblers never crash.
* If `as' produces an error message for valid input, that is a bug.
* If `as' does not produce an error message for invalid input, that
is a bug. However, you should note that your idea of "invalid
input" might be our idea of "an extension" or "support for
traditional practice".
* If you are an experienced user of assemblers, your suggestions for
improvement of `as' are welcome in any case.

File: as.info, Node: Bug Reporting, Prev: Bug Criteria, Up: Reporting Bugs
How to report bugs
==================
A number of companies and individuals offer support for GNU
products. If you obtained `as' from a support organization, we
recommend you contact that organization first.
You can find contact information for many support companies and
individuals in the file `etc/SERVICE' in the GNU Emacs distribution.
In any event, we also recommend that you send bug reports for `as'
to `bug-gnu-utils@gnu.org'.
The fundamental principle of reporting bugs usefully is this:
*report all the facts*. If you are not sure whether to state a fact or
leave it out, state it!
Often people omit facts because they think they know what causes the
problem and assume that some details do not matter. Thus, you might
assume that the name of a symbol you use in an example does not matter.
Well, probably it does not, but one cannot be sure. Perhaps the bug
is a stray memory reference which happens to fetch from the location
where that name is stored in memory; perhaps, if the name were
different, the contents of that location would fool the assembler into
doing the right thing despite the bug. Play it safe and give a
specific, complete example. That is the easiest thing for you to do,
and the most helpful.
Keep in mind that the purpose of a bug report is to enable us to fix
the bug if it is new to us. Therefore, always write your bug reports
on the assumption that the bug has not been reported previously.
Sometimes people give a few sketchy facts and ask, "Does this ring a
bell?" Those bug reports are useless, and we urge everyone to _refuse
to respond to them_ except to chide the sender to report bugs properly.
To enable us to fix the bug, you should include all these things:
* The version of `as'. `as' announces it if you start it with the
`--version' argument.
Without this, we will not know whether there is any point in
looking for the bug in the current version of `as'.
* Any patches you may have applied to the `as' source.
* The type of machine you are using, and the operating system name
and version number.
* What compiler (and its version) was used to compile `as'--e.g.
"`gcc-2.7'".
* The command arguments you gave the assembler to assemble your
example and observe the bug. To guarantee you will not omit
something important, list them all. A copy of the Makefile (or
the output from make) is sufficient.
If we were to try to guess the arguments, we would probably guess
wrong and then we might not encounter the bug.
* A complete input file that will reproduce the bug. If the bug is
observed when the assembler is invoked via a compiler, send the
assembler source, not the high level language source. Most
compilers will produce the assembler source when run with the `-S'
option. If you are using `gcc', use the options `-v
--save-temps'; this will save the assembler source in a file with
an extension of `.s', and also show you exactly how `as' is being
run.
* A description of what behavior you observe that you believe is
incorrect. For example, "It gets a fatal signal."
Of course, if the bug is that `as' gets a fatal signal, then we
will certainly notice it. But if the bug is incorrect output, we
might not notice unless it is glaringly wrong. You might as well
not give us a chance to make a mistake.
Even if the problem you experience is a fatal signal, you should
still say so explicitly. Suppose something strange is going on,
such as, your copy of `as' is out of synch, or you have
encountered a bug in the C library on your system. (This has
happened!) Your copy might crash and ours would not. If you told
us to expect a crash, then when ours fails to crash, we would know
that the bug was not happening for us. If you had not told us to
expect a crash, then we would not be able to draw any conclusion
from our observations.
* If you wish to suggest changes to the `as' source, send us context
diffs, as generated by `diff' with the `-u', `-c', or `-p' option.
Always send diffs from the old file to the new file. If you even
discuss something in the `as' source, refer to it by context, not
by line number.
The line numbers in our development sources will not match those
in your sources. Your line numbers would convey no useful
information to us.
Here are some things that are not necessary:
* A description of the envelope of the bug.
Often people who encounter a bug spend a lot of time investigating
which changes to the input file will make the bug go away and which
changes will not affect it.
This is often time consuming and not very useful, because the way
we will find the bug is by running a single example under the
debugger with breakpoints, not by pure deduction from a series of
examples. We recommend that you save your time for something else.
Of course, if you can find a simpler example to report _instead_
of the original one, that is a convenience for us. Errors in the
output will be easier to spot, running under the debugger will take
less time, and so on.
However, simplification is not vital; if you do not want to do
this, report the bug anyway and send us the entire test case you
used.
* A patch for the bug.
A patch for the bug does help us if it is a good one. But do not
omit the necessary information, such as the test case, on the
assumption that a patch is all we need. We might see problems
with your patch and decide to fix the problem another way, or we
might not understand it at all.
Sometimes with a program as complicated as `as' it is very hard to
construct an example that will make the program follow a certain
path through the code. If you do not send us the example, we will
not be able to construct one, so we will not be able to verify
that the bug is fixed.
And if we cannot understand what bug you are trying to fix, or why
your patch should be an improvement, we will not install it. A
test case will help us to understand.
* A guess about what the bug is or what it depends on.
Such guesses are usually wrong. Even we cannot guess right about
such things without first using the debugger to find the facts.

File: as.info, Node: Acknowledgements, Next: Index, Prev: Reporting Bugs, Up: Top
Acknowledgements
****************
If you have contributed to `as' and your name isn't listed here, it
is not meant as a slight. We just don't know about it. Send mail to
the maintainer, and we'll correct the situation. Currently the
maintainer is Ken Raeburn (email address `raeburn@cygnus.com').
Dean Elsner wrote the original GNU assembler for the VAX.(1)
Jay Fenlason maintained GAS for a while, adding support for
GDB-specific debug information and the 68k series machines, most of the
preprocessing pass, and extensive changes in `messages.c',
`input-file.c', `write.c'.
K. Richard Pixley maintained GAS for a while, adding various
enhancements and many bug fixes, including merging support for several
processors, breaking GAS up to handle multiple object file format back
ends (including heavy rewrite, testing, an integration of the coff and
b.out back ends), adding configuration including heavy testing and
verification of cross assemblers and file splits and renaming,
converted GAS to strictly ANSI C including full prototypes, added
support for m680[34]0 and cpu32, did considerable work on i960
including a COFF port (including considerable amounts of reverse
engineering), a SPARC opcode file rewrite, DECstation, rs6000, and
hp300hpux host ports, updated "know" assertions and made them work,
much other reorganization, cleanup, and lint.
Ken Raeburn wrote the high-level BFD interface code to replace most
of the code in format-specific I/O modules.
The original VMS support was contributed by David L. Kashtan. Eric
Youngdale has done much work with it since.
The Intel 80386 machine description was written by Eliot Dresselhaus.
Minh Tran-Le at IntelliCorp contributed some AIX 386 support.
The Motorola 88k machine description was contributed by Devon Bowen
of Buffalo University and Torbjorn Granlund of the Swedish Institute of
Computer Science.
Keith Knowles at the Open Software Foundation wrote the original
MIPS back end (`tc-mips.c', `tc-mips.h'), and contributed Rose format
support (which hasn't been merged in yet). Ralph Campbell worked with
the MIPS code to support a.out format.
Support for the Zilog Z8k and Hitachi H8/300 and H8/500 processors
(tc-z8k, tc-h8300, tc-h8500), and IEEE 695 object file format
(obj-ieee), was written by Steve Chamberlain of Cygnus Support. Steve
also modified the COFF back end to use BFD for some low-level
operations, for use with the H8/300 and AMD 29k targets.
John Gilmore built the AMD 29000 support, added `.include' support,
and simplified the configuration of which versions accept which
directives. He updated the 68k machine description so that Motorola's
opcodes always produced fixed-size instructions (e.g. `jsr'), while
synthetic instructions remained shrinkable (`jbsr'). John fixed many
bugs, including true tested cross-compilation support, and one bug in
relaxation that took a week and required the proverbial one-bit fix.
Ian Lance Taylor of Cygnus Support merged the Motorola and MIT
syntax for the 68k, completed support for some COFF targets (68k, i386
SVR3, and SCO Unix), added support for MIPS ECOFF and ELF targets,
wrote the initial RS/6000 and PowerPC assembler, and made a few other
minor patches.
Steve Chamberlain made `as' able to generate listings.
Hewlett-Packard contributed support for the HP9000/300.
Jeff Law wrote GAS and BFD support for the native HPPA object format
(SOM) along with a fairly extensive HPPA testsuite (for both SOM and
ELF object formats). This work was supported by both the Center for
Software Science at the University of Utah and Cygnus Support.
Support for ELF format files has been worked on by Mark Eichin of
Cygnus Support (original, incomplete implementation for SPARC), Pete
Hoogenboom and Jeff Law at the University of Utah (HPPA mainly),
Michael Meissner of the Open Software Foundation (i386 mainly), and Ken
Raeburn of Cygnus Support (sparc, and some initial 64-bit support).
Linas Vepstas added GAS support for the ESA/390 "IBM 370"
architecture.
Richard Henderson rewrote the Alpha assembler. Klaus Kaempf wrote
GAS and BFD support for openVMS/Alpha.
Several engineers at Cygnus Support have also provided many small
bug fixes and configuration enhancements.
Many others have contributed large or small bugfixes and
enhancements. If you have contributed significant work and are not
mentioned on this list, and want to be, let us know. Some of the
history has been lost; we are not intentionally leaving anyone out.
---------- Footnotes ----------
(1) Any more details?

1038
gas/doc/as.info-8 Normal file
View File

File diff suppressed because it is too large Load Diff

1085
gas/doc/gasp.info Normal file
View File

File diff suppressed because it is too large Load Diff

1
gas/doc/gasver.texi Normal file
View File

@@ -0,0 +1 @@
@set VERSION 2.10

1346
gas/itbl-parse.c Normal file
View File

File diff suppressed because it is too large Load Diff

20
gas/itbl-parse.h Normal file
View File

@@ -0,0 +1,20 @@
typedef union
{
char *str;
int num;
int processor;
unsigned long val;
} YYSTYPE;
#define DREG 257
#define CREG 258
#define GREG 259
#define IMMED 260
#define ADDR 261
#define INSN 262
#define NUM 263
#define ID 264
#define NL 265
#define PNUM 266
extern YYSTYPE yylval;

2066
gas/m68k-parse.c Normal file
View File

File diff suppressed because it is too large Load Diff

155
gas/make-gas.com Normal file
View File

@@ -0,0 +1,155 @@
$!make-gas.com
$! Set the def dir to proper place for use in batch. Works for interactive to.
$flnm = f$enviroment("PROCEDURE") ! get current procedure name
$set default 'f$parse(flnm,,,"DEVICE")''f$parse(flnm,,,"DIRECTORY")'
$v = 'f$verify(0)'
$!
$! Command file to build a GNU assembler on VMS
$!
$! If you are using a version of GCC that supports global constants
$! you should remove the define="const=" from the gcc lines.
$!
$! Caution: Versions 1.38.1 and earlier had a bug in the handling of
$! some static constants. If you are using such a version of the
$! assembler, and you wish to compile without the "const=" hack,
$! you should first build this version *with* the "const="
$! definition, and then use that assembler to rebuild it without the
$! "const=" definition. Failure to do this will result in an assembler
$! that will mung floating point constants.
$!
$! Note: The version of gas shipped on the GCC VMS tapes has been patched
$! to fix the above mentioned bug.
$!
$ !The gcc-vms driver was modified to use `-1' quite some time ago,
$ !so don't echo this text any more...
$ !write sys$output "If this assembler is going to be used with GCC 1.n, you"
$ !write sys$output "need to modify the driver to supply the -1 switch to gas."
$ !write sys$output "This is required because of a small change in how global"
$ !write sys$output "constant variables are handled. Failure to include this"
$ !write sys$output "will result in linker warning messages about mismatched
$ !write sys$output "psect attributes."
$!
$ gas_host="vms"
$ arch_indx = 1 + ((f$getsyi("CPU").ge.128).and.1) ! vax==1, alpha==2
$ arch = f$element(arch_indx,"|","|VAX|Alpha|")
$ if arch.eqs."VAX"
$ then
$ cpu_type="vax"
$ obj_format="vms"
$ atof="vax"
$ else
$ cpu_type="alpha"
$ obj_format="evax"
$ atof="ieee"
$ endif
$ emulation="generic"
$!
$ COPY = "copy/noLog"
$!
$ C_DEFS :="""VMS"""
$! C_DEFS :="""VMS""","""const="""
$ C_INCLUDES = "/Include=([],[.config],[-.include],[-.include.aout])"
$ C_FLAGS = "/noVerbose/Debug" + c_includes
$!
$!
$ on error then goto bail
$ if f$search("[-.libiberty]liberty.olb").eqs.""
$ then @[-.libiberty]vmsbuild.com
$ write sys$output "Now building gas."
$ endif
$ if "''p1'" .eqs. "LINK" then goto Link
$!
$! This helps gcc 1.nn find the aout/* files.
$!
$ aout_dev = f$parse(flnm,,,"DEVICE")
$ tmp = aout_dev - ":"
$if f$trnlnm(tmp).nes."" then aout_dev = f$trnlnm(tmp)
$ aout_dir = aout_dev+f$parse(flnm,,,"DIRECTORY")' -
- "GAS]" + "INCLUDE.AOUT.]" - "]["
$assign 'aout_dir' aout/tran=conc
$ opcode_dir = aout_dev+f$parse(flnm,,,"DIRECTORY")' -
- "GAS]" + "INCLUDE.OPCODE.]" - "]["
$assign 'opcode_dir' opcode/tran=conc
$!
$ set verify
$!
$ gcc 'c_flags'/Define=('C_DEFS')/Object=[]tc-'cpu_type'.obj [.config]tc-'cpu_type'.c
$ gcc 'c_flags'/Define=('C_DEFS')/Object=[]obj-'obj_format'.obj [.config]obj-'obj_format'.c
$ gcc 'c_flags'/Define=('C_DEFS')/Object=[]atof-'atof'.obj [.config]atof-'atof'.c
$ gcc 'c_flags'/Define=('C_DEFS') app.c
$ gcc 'c_flags'/Define=('C_DEFS') as.c
$ gcc 'c_flags'/Define=('C_DEFS') atof-generic.c
$ gcc 'c_flags'/Define=('C_DEFS') bignum-copy.c
$ gcc 'c_flags'/Define=('C_DEFS') cond.c
$ gcc 'c_flags'/Define=('C_DEFS') depend.c
$ gcc 'c_flags'/Define=('C_DEFS') dwarf2dbg.c
$ gcc 'c_flags'/Define=('C_DEFS') ehopt.c
$ gcc 'c_flags'/Define=('C_DEFS') expr.c
$ gcc 'c_flags'/Define=('C_DEFS') flonum-konst.c
$ gcc 'c_flags'/Define=('C_DEFS') flonum-copy.c
$ gcc 'c_flags'/Define=('C_DEFS') flonum-mult.c
$ gcc 'c_flags'/Define=('C_DEFS') frags.c
$ gcc 'c_flags'/Define=('C_DEFS') hash.c
$ gcc 'c_flags'/Define=('C_DEFS') input-file.c
$ gcc 'c_flags'/Define=('C_DEFS') input-scrub.c
$ gcc 'c_flags'/Define=('C_DEFS') literal.c
$ gcc 'c_flags'/Define=('C_DEFS') messages.c
$ gcc 'c_flags'/Define=('C_DEFS') output-file.c
$ gcc 'c_flags'/Define=('C_DEFS') read.c
$ gcc 'c_flags'/Define=('C_DEFS') subsegs.c
$ gcc 'c_flags'/Define=('C_DEFS') symbols.c
$ gcc 'c_flags'/Define=('C_DEFS') write.c
$ gcc 'c_flags'/Define=('C_DEFS') listing.c
$ gcc 'c_flags'/Define=('C_DEFS') ecoff.c
$ gcc 'c_flags'/Define=('C_DEFS') stabs.c
$ gcc 'c_flags'/Define=('C_DEFS') sb.c
$ gcc 'c_flags'/Define=('C_DEFS') macro.c
$link:
$!'f$verify(0)'
$ if f$trnlnm("IFILE$").nes."" then close/noLog ifile$
$ create gcc-as.opt
!
! Linker options file for GNU assembler
!
$ open/Append ifile$ gcc-as.opt
$ write ifile$ "tc-''cpu_type'.obj"
$ write ifile$ "obj-''obj_format'.obj"
$ write ifile$ "atof-''atof'.obj"
$ COPY sys$input: ifile$:
app.obj,-
as.obj,-
atof-generic.obj,-
bignum-copy.obj,-
cond.obj,-
depend.obj,-
dwarf2dbg.obj,-
ehopt.obj,-
expr.obj,-
flonum-konst.obj,-
flonum-copy.obj,-
flonum-mult.obj,-
frags.obj,-
hash.obj,-
input-file.obj,-
input-scrub.obj,-
literal.obj,-
messages.obj,-
output-file.obj,-
read.obj,-
subsegs.obj,-
symbols.obj,-
write.obj,-
listing.obj,-
ecoff.obj,-
stabs.obj,-
sb.obj,-
macro.obj,-
[-.libiberty]liberty.olb/Lib
gnu_cc:[000000]gcclib.olb/Lib,sys$library:vaxcrtl.olb/Lib
! Tell linker exactly what psect attributes we want -- match VAXCRTL.
psect_attr=ENVIRON,long,pic,ovr,rel,gbl,noshr,noexe,rd,wrt
$ close ifile$
$ set verify=(Proc,noImag)
$ link/noMap/Exec=gcc-as.exe gcc-as.opt/Opt,version.opt/Opt
$!
$bail: exit $status + 0*f$verify(v) !'f$verify(0)'

118
gprof/bsd_callg_bl.c Normal file
View File

@@ -0,0 +1,118 @@
/* ==> Do not modify this file!! It is created automatically
from bsd_callg_bl.m using the gen-c-prog.awk script. <== */
#include <stdio.h>
void
bsd_callg_blurb (file)
FILE *file;
{
fputs ("\n", file);
fputs ("\n", file);
fputs ("\n", file);
fputs ("call graph profile:\n", file);
fputs (" The sum of self and descendents is the major sort\n", file);
fputs (" for this listing.\n", file);
fputs ("\n", file);
fputs (" function entries:\n", file);
fputs ("\n", file);
fputs ("index the index of the function in the call graph\n", file);
fputs (" listing, as an aid to locating it (see below).\n", file);
fputs ("\n", file);
fputs ("%time the percentage of the total time of the program\n", file);
fputs (" accounted for by this function and its\n", file);
fputs (" descendents.\n", file);
fputs ("\n", file);
fputs ("self the number of seconds spent in this function\n", file);
fputs (" itself.\n", file);
fputs ("\n", file);
fputs ("descendents\n", file);
fputs (" the number of seconds spent in the descendents of\n", file);
fputs (" this function on behalf of this function.\n", file);
fputs ("\n", file);
fputs ("called the number of times this function is called (other\n", file);
fputs (" than recursive calls).\n", file);
fputs ("\n", file);
fputs ("self the number of times this function calls itself\n", file);
fputs (" recursively.\n", file);
fputs ("\n", file);
fputs ("name the name of the function, with an indication of\n", file);
fputs (" its membership in a cycle, if any.\n", file);
fputs ("\n", file);
fputs ("index the index of the function in the call graph\n", file);
fputs (" listing, as an aid to locating it.\n", file);
fputs ("\n", file);
fputs ("\n", file);
fputs ("\n", file);
fputs (" parent listings:\n", file);
fputs ("\n", file);
fputs ("self* the number of seconds of this function's self time\n", file);
fputs (" which is due to calls from this parent.\n", file);
fputs ("\n", file);
fputs ("descendents*\n", file);
fputs (" the number of seconds of this function's\n", file);
fputs (" descendent time which is due to calls from this\n", file);
fputs (" parent.\n", file);
fputs ("\n", file);
fputs ("called** the number of times this function is called by\n", file);
fputs (" this parent. This is the numerator of the\n", file);
fputs (" fraction which divides up the function's time to\n", file);
fputs (" its parents.\n", file);
fputs ("\n", file);
fputs ("total* the number of times this function was called by\n", file);
fputs (" all of its parents. This is the denominator of\n", file);
fputs (" the propagation fraction.\n", file);
fputs ("\n", file);
fputs ("parents the name of this parent, with an indication of the\n", file);
fputs (" parent's membership in a cycle, if any.\n", file);
fputs ("\n", file);
fputs ("index the index of this parent in the call graph\n", file);
fputs (" listing, as an aid in locating it.\n", file);
fputs ("\n", file);
fputs ("\n", file);
fputs ("\n", file);
fputs (" children listings:\n", file);
fputs ("\n", file);
fputs ("self* the number of seconds of this child's self time\n", file);
fputs (" which is due to being called by this function.\n", file);
fputs ("\n", file);
fputs ("descendent*\n", file);
fputs (" the number of seconds of this child's descendent's\n", file);
fputs (" time which is due to being called by this\n", file);
fputs (" function.\n", file);
fputs ("\n", file);
fputs ("called** the number of times this child is called by this\n", file);
fputs (" function. This is the numerator of the\n", file);
fputs (" propagation fraction for this child.\n", file);
fputs ("\n", file);
fputs ("total* the number of times this child is called by all\n", file);
fputs (" functions. This is the denominator of the\n", file);
fputs (" propagation fraction.\n", file);
fputs ("\n", file);
fputs ("children the name of this child, and an indication of its\n", file);
fputs (" membership in a cycle, if any.\n", file);
fputs ("\n", file);
fputs ("index the index of this child in the call graph listing,\n", file);
fputs (" as an aid to locating it.\n", file);
fputs ("\n", file);
fputs ("\n", file);
fputs ("\n", file);
fputs (" * these fields are omitted for parents (or\n", file);
fputs (" children) in the same cycle as the function. If\n", file);
fputs (" the function (or child) is a member of a cycle,\n", file);
fputs (" the propagated times and propagation denominator\n", file);
fputs (" represent the self time and descendent time of the\n", file);
fputs (" cycle as a whole.\n", file);
fputs ("\n", file);
fputs (" ** static-only parents and children are indicated\n", file);
fputs (" by a call count of 0.\n", file);
fputs ("\n", file);
fputs ("\n", file);
fputs ("\n", file);
fputs (" cycle listings:\n", file);
fputs (" the cycle as a whole is listed with the same\n", file);
fputs (" fields as a function entry. Below it are listed\n", file);
fputs (" the members of the cycle, and their contributions\n", file);
fputs (" to the time and call counts of the cycle.\n", file);
fputs (" \n", file);
}

37
gprof/flat_bl.c Normal file
View File

@@ -0,0 +1,37 @@
/* ==> Do not modify this file!! It is created automatically
from flat_bl.m using the gen-c-prog.awk script. <== */
#include <stdio.h>
void
flat_blurb (file)
FILE *file;
{
fputs ("\n", file);
fputs (" % the percentage of the total running time of the\n", file);
fputs ("time program used by this function.\n", file);
fputs ("\n", file);
fputs ("cumulative a running sum of the number of seconds accounted\n", file);
fputs (" seconds for by this function and those listed above it.\n", file);
fputs ("\n", file);
fputs (" self the number of seconds accounted for by this\n", file);
fputs ("seconds function alone. This is the major sort for this\n", file);
fputs (" listing.\n", file);
fputs ("\n", file);
fputs ("calls the number of times this function was invoked, if\n", file);
fputs (" this function is profiled, else blank.\n", file);
fputs (" \n", file);
fputs (" self the average number of milliseconds spent in this\n", file);
fputs ("ms/call function per call, if this function is profiled,\n", file);
fputs (" else blank.\n", file);
fputs ("\n", file);
fputs (" total the average number of milliseconds spent in this\n", file);
fputs ("ms/call function and its descendents per call, if this \n", file);
fputs (" function is profiled, else blank.\n", file);
fputs ("\n", file);
fputs ("name the name of the function. This is the minor sort\n", file);
fputs (" for this listing. The index shows the location of\n", file);
fputs (" the function in the gprof listing. If the index is\n", file);
fputs (" in parenthesis it shows where it would appear in\n", file);
fputs (" the gprof listing if it were to be printed.\n", file);
}

93
gprof/fsf_callg_bl.c Normal file
View File

@@ -0,0 +1,93 @@
/* ==> Do not modify this file!! It is created automatically
from fsf_callg_bl.m using the gen-c-prog.awk script. <== */
#include <stdio.h>
void
fsf_callg_blurb (file)
FILE *file;
{
fputs ("\n", file);
fputs (" This table describes the call tree of the program, and was sorted by\n", file);
fputs (" the total amount of time spent in each function and its children.\n", file);
fputs ("\n", file);
fputs (" Each entry in this table consists of several lines. The line with the\n", file);
fputs (" index number at the left hand margin lists the current function.\n", file);
fputs (" The lines above it list the functions that called this function,\n", file);
fputs (" and the lines below it list the functions this one called.\n", file);
fputs (" This line lists:\n", file);
fputs (" index A unique number given to each element of the table.\n", file);
fputs (" Index numbers are sorted numerically.\n", file);
fputs (" The index number is printed next to every function name so\n", file);
fputs (" it is easier to look up where the function in the table.\n", file);
fputs ("\n", file);
fputs (" % time This is the percentage of the `total' time that was spent\n", file);
fputs (" in this function and its children. Note that due to\n", file);
fputs (" different viewpoints, functions excluded by options, etc,\n", file);
fputs (" these numbers will NOT add up to 100%.\n", file);
fputs ("\n", file);
fputs (" self This is the total amount of time spent in this function.\n", file);
fputs ("\n", file);
fputs (" children This is the total amount of time propagated into this\n", file);
fputs (" function by its children.\n", file);
fputs ("\n", file);
fputs (" called This is the number of times the function was called.\n", file);
fputs (" If the function called itself recursively, the number\n", file);
fputs (" only includes non-recursive calls, and is followed by\n", file);
fputs (" a `+' and the number of recursive calls.\n", file);
fputs ("\n", file);
fputs (" name The name of the current function. The index number is\n", file);
fputs (" printed after it. If the function is a member of a\n", file);
fputs (" cycle, the cycle number is printed between the\n", file);
fputs (" function's name and the index number.\n", file);
fputs ("\n", file);
fputs ("\n", file);
fputs (" For the function's parents, the fields have the following meanings:\n", file);
fputs ("\n", file);
fputs (" self This is the amount of time that was propagated directly\n", file);
fputs (" from the function into this parent.\n", file);
fputs ("\n", file);
fputs (" children This is the amount of time that was propagated from\n", file);
fputs (" the function's children into this parent.\n", file);
fputs ("\n", file);
fputs (" called This is the number of times this parent called the\n", file);
fputs (" function `/' the total number of times the function\n", file);
fputs (" was called. Recursive calls to the function are not\n", file);
fputs (" included in the number after the `/'.\n", file);
fputs ("\n", file);
fputs (" name This is the name of the parent. The parent's index\n", file);
fputs (" number is printed after it. If the parent is a\n", file);
fputs (" member of a cycle, the cycle number is printed between\n", file);
fputs (" the name and the index number.\n", file);
fputs ("\n", file);
fputs (" If the parents of the function cannot be determined, the word\n", file);
fputs (" `<spontaneous>' is printed in the `name' field, and all the other\n", file);
fputs (" fields are blank.\n", file);
fputs ("\n", file);
fputs (" For the function's children, the fields have the following meanings:\n", file);
fputs ("\n", file);
fputs (" self This is the amount of time that was propagated directly\n", file);
fputs (" from the child into the function.\n", file);
fputs ("\n", file);
fputs (" children This is the amount of time that was propagated from the\n", file);
fputs (" child's children to the function.\n", file);
fputs ("\n", file);
fputs (" called This is the number of times the function called\n", file);
fputs (" this child `/' the total number of times the child\n", file);
fputs (" was called. Recursive calls by the child are not\n", file);
fputs (" listed in the number after the `/'.\n", file);
fputs ("\n", file);
fputs (" name This is the name of the child. The child's index\n", file);
fputs (" number is printed after it. If the child is a\n", file);
fputs (" member of a cycle, the cycle number is printed\n", file);
fputs (" between the name and the index number.\n", file);
fputs ("\n", file);
fputs (" If there are any cycles (circles) in the call graph, there is an\n", file);
fputs (" entry for the cycle-as-a-whole. This entry shows who called the\n", file);
fputs (" cycle (as parents) and the members of the cycle (as children.)\n", file);
fputs (" The `+' recursive calls entry shows the number of function calls that\n", file);
fputs (" were internal to the cycle, and the calls entry for each member shows,\n", file);
fputs (" for that member, how many times it was called from other members of\n", file);
fputs (" the cycle.\n", file);
fputs ("\n", file);
}

62
gprof/gprof.info Normal file
View File

@@ -0,0 +1,62 @@
This is gprof.info, produced by makeinfo version 4.0 from gprof.texi.
START-INFO-DIR-ENTRY
* gprof: (gprof). Profiling your program's execution
END-INFO-DIR-ENTRY
This file documents the gprof profiler of the GNU system.
Copyright (C) 1988, 92, 97, 98, 99, 2000 Free Software Foundation,
Inc.
Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.
Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.
Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions.

Indirect:
gprof.info-1: 884
gprof.info-2: 47890

Tag Table:
(Indirect)
Node: Top884
Node: Introduction1878
Node: Compiling4207
Node: Executing6868
Node: Invoking9232
Node: Output Options10646
Node: Analysis Options17270
Node: Miscellaneous Options20463
Node: Deprecated Options21624
Node: Symspecs23694
Node: Output25515
Node: Flat Profile26540
Node: Call Graph31470
Node: Primary34685
Node: Callers37217
Node: Subroutines39325
Node: Cycles41125
Node: Line-by-line47890
Node: Annotated Source51689
Node: Inaccuracy54550
Node: Sampling Error54804
Node: Assumptions57369
Node: How do I?58837
Node: Incompatibilities60055
Node: Details61522
Node: Implementation61872
Node: File Format67764
Node: Internals72019
Node: Debugging80389

End Tag Table

1121
gprof/gprof.info-1 Normal file
View File

File diff suppressed because it is too large Load Diff

760
gprof/gprof.info-2 Normal file
View File

@@ -0,0 +1,760 @@
This is gprof.info, produced by makeinfo version 4.0 from gprof.texi.
START-INFO-DIR-ENTRY
* gprof: (gprof). Profiling your program's execution
END-INFO-DIR-ENTRY
This file documents the gprof profiler of the GNU system.
Copyright (C) 1988, 92, 97, 98, 99, 2000 Free Software Foundation,
Inc.
Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.
Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.
Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions.

File: gprof.info, Node: Line-by-line, Next: Annotated Source, Prev: Call Graph, Up: Output
Line-by-line Profiling
======================
`gprof''s `-l' option causes the program to perform "line-by-line"
profiling. In this mode, histogram samples are assigned not to
functions, but to individual lines of source code. The program usually
must be compiled with a `-g' option, in addition to `-pg', in order to
generate debugging symbols for tracking source code lines.
The flat profile is the most useful output table in line-by-line
mode. The call graph isn't as useful as normal, since the current
version of `gprof' does not propagate call graph arcs from source code
lines to the enclosing function. The call graph does, however, show
each line of code that called each function, along with a count.
Here is a section of `gprof''s output, without line-by-line
profiling. Note that `ct_init' accounted for four histogram hits, and
13327 calls to `init_block'.
Flat profile:
Each sample counts as 0.01 seconds.
% cumulative self self total
time seconds seconds calls us/call us/call name
30.77 0.13 0.04 6335 6.31 6.31 ct_init
Call graph (explanation follows)
granularity: each sample hit covers 4 byte(s) for 7.69% of 0.13 seconds
index % time self children called name
0.00 0.00 1/13496 name_too_long
0.00 0.00 40/13496 deflate
0.00 0.00 128/13496 deflate_fast
0.00 0.00 13327/13496 ct_init
[7] 0.0 0.00 0.00 13496 init_block
Now let's look at some of `gprof''s output from the same program run,
this time with line-by-line profiling enabled. Note that `ct_init''s
four histogram hits are broken down into four lines of source code -
one hit occurred on each of lines 349, 351, 382 and 385. In the call
graph, note how `ct_init''s 13327 calls to `init_block' are broken down
into one call from line 396, 3071 calls from line 384, 3730 calls from
line 385, and 6525 calls from 387.
Flat profile:
Each sample counts as 0.01 seconds.
% cumulative self
time seconds seconds calls name
7.69 0.10 0.01 ct_init (trees.c:349)
7.69 0.11 0.01 ct_init (trees.c:351)
7.69 0.12 0.01 ct_init (trees.c:382)
7.69 0.13 0.01 ct_init (trees.c:385)
Call graph (explanation follows)
granularity: each sample hit covers 4 byte(s) for 7.69% of 0.13 seconds
% time self children called name
0.00 0.00 1/13496 name_too_long (gzip.c:1440)
0.00 0.00 1/13496 deflate (deflate.c:763)
0.00 0.00 1/13496 ct_init (trees.c:396)
0.00 0.00 2/13496 deflate (deflate.c:727)
0.00 0.00 4/13496 deflate (deflate.c:686)
0.00 0.00 5/13496 deflate (deflate.c:675)
0.00 0.00 12/13496 deflate (deflate.c:679)
0.00 0.00 16/13496 deflate (deflate.c:730)
0.00 0.00 128/13496 deflate_fast (deflate.c:654)
0.00 0.00 3071/13496 ct_init (trees.c:384)
0.00 0.00 3730/13496 ct_init (trees.c:385)
0.00 0.00 6525/13496 ct_init (trees.c:387)
[6] 0.0 0.00 0.00 13496 init_block (trees.c:408)

File: gprof.info, Node: Annotated Source, Prev: Line-by-line, Up: Output
The Annotated Source Listing
============================
`gprof''s `-A' option triggers an annotated source listing, which
lists the program's source code, each function labeled with the number
of times it was called. You may also need to specify the `-I' option,
if `gprof' can't find the source code files.
Compiling with `gcc ... -g -pg -a' augments your program with
basic-block counting code, in addition to function counting code. This
enables `gprof' to determine how many times each line of code was
executed. For example, consider the following function, taken from
gzip, with line numbers added:
1 ulg updcrc(s, n)
2 uch *s;
3 unsigned n;
4 {
5 register ulg c;
6
7 static ulg crc = (ulg)0xffffffffL;
8
9 if (s == NULL) {
10 c = 0xffffffffL;
11 } else {
12 c = crc;
13 if (n) do {
14 c = crc_32_tab[...];
15 } while (--n);
16 }
17 crc = c;
18 return c ^ 0xffffffffL;
19 }
`updcrc' has at least five basic-blocks. One is the function
itself. The `if' statement on line 9 generates two more basic-blocks,
one for each branch of the `if'. A fourth basic-block results from the
`if' on line 13, and the contents of the `do' loop form the fifth
basic-block. The compiler may also generate additional basic-blocks to
handle various special cases.
A program augmented for basic-block counting can be analyzed with
`gprof -l -A'. I also suggest use of the `-x' option, which ensures
that each line of code is labeled at least once. Here is `updcrc''s
annotated source listing for a sample `gzip' run:
ulg updcrc(s, n)
uch *s;
unsigned n;
2 ->{
register ulg c;
static ulg crc = (ulg)0xffffffffL;
2 -> if (s == NULL) {
1 -> c = 0xffffffffL;
1 -> } else {
1 -> c = crc;
1 -> if (n) do {
26312 -> c = crc_32_tab[...];
26312,1,26311 -> } while (--n);
}
2 -> crc = c;
2 -> return c ^ 0xffffffffL;
2 ->}
In this example, the function was called twice, passing once through
each branch of the `if' statement. The body of the `do' loop was
executed a total of 26312 times. Note how the `while' statement is
annotated. It began execution 26312 times, once for each iteration
through the loop. One of those times (the last time) it exited, while
it branched back to the beginning of the loop 26311 times.

File: gprof.info, Node: Inaccuracy, Next: How do I?, Prev: Output, Up: Top
Inaccuracy of `gprof' Output
****************************
* Menu:
* Sampling Error:: Statistical margins of error
* Assumptions:: Estimating children times

File: gprof.info, Node: Sampling Error, Next: Assumptions, Up: Inaccuracy
Statistical Sampling Error
==========================
The run-time figures that `gprof' gives you are based on a sampling
process, so they are subject to statistical inaccuracy. If a function
runs only a small amount of time, so that on the average the sampling
process ought to catch that function in the act only once, there is a
pretty good chance it will actually find that function zero times, or
twice.
By contrast, the number-of-calls and basic-block figures are derived
by counting, not sampling. They are completely accurate and will not
vary from run to run if your program is deterministic.
The "sampling period" that is printed at the beginning of the flat
profile says how often samples are taken. The rule of thumb is that a
run-time figure is accurate if it is considerably bigger than the
sampling period.
The actual amount of error can be predicted. For N samples, the
_expected_ error is the square-root of N. For example, if the sampling
period is 0.01 seconds and `foo''s run-time is 1 second, N is 100
samples (1 second/0.01 seconds), sqrt(N) is 10 samples, so the expected
error in `foo''s run-time is 0.1 seconds (10*0.01 seconds), or ten
percent of the observed value. Again, if the sampling period is 0.01
seconds and `bar''s run-time is 100 seconds, N is 10000 samples,
sqrt(N) is 100 samples, so the expected error in `bar''s run-time is 1
second, or one percent of the observed value. It is likely to vary
this much _on the average_ from one profiling run to the next.
(_Sometimes_ it will vary more.)
This does not mean that a small run-time figure is devoid of
information. If the program's _total_ run-time is large, a small
run-time for one function does tell you that that function used an
insignificant fraction of the whole program's time. Usually this means
it is not worth optimizing.
One way to get more accuracy is to give your program more (but
similar) input data so it will take longer. Another way is to combine
the data from several runs, using the `-s' option of `gprof'. Here is
how:
1. Run your program once.
2. Issue the command `mv gmon.out gmon.sum'.
3. Run your program again, the same as before.
4. Merge the new data in `gmon.out' into `gmon.sum' with this command:
gprof -s EXECUTABLE-FILE gmon.out gmon.sum
5. Repeat the last two steps as often as you wish.
6. Analyze the cumulative data using this command:
gprof EXECUTABLE-FILE gmon.sum > OUTPUT-FILE

File: gprof.info, Node: Assumptions, Prev: Sampling Error, Up: Inaccuracy
Estimating `children' Times
===========================
Some of the figures in the call graph are estimates--for example, the
`children' time values and all the the time figures in caller and
subroutine lines.
There is no direct information about these measurements in the
profile data itself. Instead, `gprof' estimates them by making an
assumption about your program that might or might not be true.
The assumption made is that the average time spent in each call to
any function `foo' is not correlated with who called `foo'. If `foo'
used 5 seconds in all, and 2/5 of the calls to `foo' came from `a',
then `foo' contributes 2 seconds to `a''s `children' time, by
assumption.
This assumption is usually true enough, but for some programs it is
far from true. Suppose that `foo' returns very quickly when its
argument is zero; suppose that `a' always passes zero as an argument,
while other callers of `foo' pass other arguments. In this program,
all the time spent in `foo' is in the calls from callers other than `a'.
But `gprof' has no way of knowing this; it will blindly and incorrectly
charge 2 seconds of time in `foo' to the children of `a'.
We hope some day to put more complete data into `gmon.out', so that
this assumption is no longer needed, if we can figure out how. For the
nonce, the estimated figures are usually more useful than misleading.

File: gprof.info, Node: How do I?, Next: Incompatibilities, Prev: Inaccuracy, Up: Top
Answers to Common Questions
***************************
How do I find which lines in my program were executed the most times?
Compile your program with basic-block counting enabled, run it,
then use the following pipeline:
gprof -l -C OBJFILE | sort -k 3 -n -r
This listing will show you the lines in your code executed most
often, but not necessarily those that consumed the most time.
How do I find which lines in my program called a particular function?
Use `gprof -l' and lookup the function in the call graph. The
callers will be broken down by function and line number.
How do I analyze a program that runs for less than a second?
Try using a shell script like this one:
for i in `seq 1 100`; do
fastprog
mv gmon.out gmon.out.$i
done
gprof -s fastprog gmon.out.*
gprof fastprog gmon.sum
If your program is completely deterministic, all the call counts
will be simple multiples of 100 (i.e. a function called once in
each run will appear with a call count of 100).

File: gprof.info, Node: Incompatibilities, Next: Details, Prev: How do I?, Up: Top
Incompatibilities with Unix `gprof'
***********************************
GNU `gprof' and Berkeley Unix `gprof' use the same data file
`gmon.out', and provide essentially the same information. But there
are a few differences.
* GNU `gprof' uses a new, generalized file format with support for
basic-block execution counts and non-realtime histograms. A magic
cookie and version number allows `gprof' to easily identify new
style files. Old BSD-style files can still be read. *Note File
Format::.
* For a recursive function, Unix `gprof' lists the function as a
parent and as a child, with a `calls' field that lists the number
of recursive calls. GNU `gprof' omits these lines and puts the
number of recursive calls in the primary line.
* When a function is suppressed from the call graph with `-e', GNU
`gprof' still lists it as a subroutine of functions that call it.
* GNU `gprof' accepts the `-k' with its argument in the form
`from/to', instead of `from to'.
* In the annotated source listing, if there are multiple basic
blocks on the same line, GNU `gprof' prints all of their counts,
separated by commas.
* The blurbs, field widths, and output formats are different. GNU
`gprof' prints blurbs after the tables, so that you can see the
tables without skipping the blurbs.

File: gprof.info, Node: Details, Prev: Incompatibilities, Up: Top
Details of Profiling
********************
* Menu:
* Implementation:: How a program collects profiling information
* File Format:: Format of `gmon.out' files
* Internals:: `gprof''s internal operation
* Debugging:: Using `gprof''s `-d' option

File: gprof.info, Node: Implementation, Next: File Format, Up: Details
Implementation of Profiling
===========================
Profiling works by changing how every function in your program is
compiled so that when it is called, it will stash away some information
about where it was called from. From this, the profiler can figure out
what function called it, and can count how many times it was called.
This change is made by the compiler when your program is compiled with
the `-pg' option, which causes every function to call `mcount' (or
`_mcount', or `__mcount', depending on the OS and compiler) as one of
its first operations.
The `mcount' routine, included in the profiling library, is
responsible for recording in an in-memory call graph table both its
parent routine (the child) and its parent's parent. This is typically
done by examining the stack frame to find both the address of the
child, and the return address in the original parent. Since this is a
very machine-dependent operation, `mcount' itself is typically a short
assembly-language stub routine that extracts the required information,
and then calls `__mcount_internal' (a normal C function) with two
arguments - `frompc' and `selfpc'. `__mcount_internal' is responsible
for maintaining the in-memory call graph, which records `frompc',
`selfpc', and the number of times each of these call arcs was traversed.
GCC Version 2 provides a magical function
(`__builtin_return_address'), which allows a generic `mcount' function
to extract the required information from the stack frame. However, on
some architectures, most notably the SPARC, using this builtin can be
very computationally expensive, and an assembly language version of
`mcount' is used for performance reasons.
Number-of-calls information for library routines is collected by
using a special version of the C library. The programs in it are the
same as in the usual C library, but they were compiled with `-pg'. If
you link your program with `gcc ... -pg', it automatically uses the
profiling version of the library.
Profiling also involves watching your program as it runs, and
keeping a histogram of where the program counter happens to be every
now and then. Typically the program counter is looked at around 100
times per second of run time, but the exact frequency may vary from
system to system.
This is done is one of two ways. Most UNIX-like operating systems
provide a `profil()' system call, which registers a memory array with
the kernel, along with a scale factor that determines how the program's
address space maps into the array. Typical scaling values cause every
2 to 8 bytes of address space to map into a single array slot. On
every tick of the system clock (assuming the profiled program is
running), the value of the program counter is examined and the
corresponding slot in the memory array is incremented. Since this is
done in the kernel, which had to interrupt the process anyway to handle
the clock interrupt, very little additional system overhead is required.
However, some operating systems, most notably Linux 2.0 (and
earlier), do not provide a `profil()' system call. On such a system,
arrangements are made for the kernel to periodically deliver a signal
to the process (typically via `setitimer()'), which then performs the
same operation of examining the program counter and incrementing a slot
in the memory array. Since this method requires a signal to be
delivered to user space every time a sample is taken, it uses
considerably more overhead than kernel-based profiling. Also, due to
the added delay required to deliver the signal, this method is less
accurate as well.
A special startup routine allocates memory for the histogram and
either calls `profil()' or sets up a clock signal handler. This
routine (`monstartup') can be invoked in several ways. On Linux
systems, a special profiling startup file `gcrt0.o', which invokes
`monstartup' before `main', is used instead of the default `crt0.o'.
Use of this special startup file is one of the effects of using `gcc
... -pg' to link. On SPARC systems, no special startup files are used.
Rather, the `mcount' routine, when it is invoked for the first time
(typically when `main' is called), calls `monstartup'.
If the compiler's `-a' option was used, basic-block counting is also
enabled. Each object file is then compiled with a static array of
counts, initially zero. In the executable code, every time a new
basic-block begins (i.e. when an `if' statement appears), an extra
instruction is inserted to increment the corresponding count in the
array. At compile time, a paired array was constructed that recorded
the starting address of each basic-block. Taken together, the two
arrays record the starting address of every basic-block, along with the
number of times it was executed.
The profiling library also includes a function (`mcleanup') which is
typically registered using `atexit()' to be called as the program
exits, and is responsible for writing the file `gmon.out'. Profiling
is turned off, various headers are output, and the histogram is
written, followed by the call-graph arcs and the basic-block counts.
The output from `gprof' gives no indication of parts of your program
that are limited by I/O or swapping bandwidth. This is because samples
of the program counter are taken at fixed intervals of the program's
run time. Therefore, the time measurements in `gprof' output say
nothing about time that your program was not running. For example, a
part of the program that creates so much data that it cannot all fit in
physical memory at once may run very slowly due to thrashing, but
`gprof' will say it uses little time. On the other hand, sampling by
run time has the advantage that the amount of load due to other users
won't directly affect the output you get.

File: gprof.info, Node: File Format, Next: Internals, Prev: Implementation, Up: Details
Profiling Data File Format
==========================
The old BSD-derived file format used for profile data does not
contain a magic cookie that allows to check whether a data file really
is a `gprof' file. Furthermore, it does not provide a version number,
thus rendering changes to the file format almost impossible. GNU
`gprof' uses a new file format that provides these features. For
backward compatibility, GNU `gprof' continues to support the old
BSD-derived format, but not all features are supported with it. For
example, basic-block execution counts cannot be accommodated by the old
file format.
The new file format is defined in header file `gmon_out.h'. It
consists of a header containing the magic cookie and a version number,
as well as some spare bytes available for future extensions. All data
in a profile data file is in the native format of the host on which the
profile was collected. GNU `gprof' adapts automatically to the
byte-order in use.
In the new file format, the header is followed by a sequence of
records. Currently, there are three different record types: histogram
records, call-graph arc records, and basic-block execution count
records. Each file can contain any number of each record type. When
reading a file, GNU `gprof' will ensure records of the same type are
compatible with each other and compute the union of all records. For
example, for basic-block execution counts, the union is simply the sum
of all execution counts for each basic-block.
Histogram Records
-----------------
Histogram records consist of a header that is followed by an array of
bins. The header contains the text-segment range that the histogram
spans, the size of the histogram in bytes (unlike in the old BSD
format, this does not include the size of the header), the rate of the
profiling clock, and the physical dimension that the bin counts
represent after being scaled by the profiling clock rate. The physical
dimension is specified in two parts: a long name of up to 15 characters
and a single character abbreviation. For example, a histogram
representing real-time would specify the long name as "seconds" and the
abbreviation as "s". This feature is useful for architectures that
support performance monitor hardware (which, fortunately, is becoming
increasingly common). For example, under DEC OSF/1, the "uprofile"
command can be used to produce a histogram of, say, instruction cache
misses. In this case, the dimension in the histogram header could be
set to "i-cache misses" and the abbreviation could be set to "1"
(because it is simply a count, not a physical dimension). Also, the
profiling rate would have to be set to 1 in this case.
Histogram bins are 16-bit numbers and each bin represent an equal
amount of text-space. For example, if the text-segment is one thousand
bytes long and if there are ten bins in the histogram, each bin
represents one hundred bytes.
Call-Graph Records
------------------
Call-graph records have a format that is identical to the one used in
the BSD-derived file format. It consists of an arc in the call graph
and a count indicating the number of times the arc was traversed during
program execution. Arcs are specified by a pair of addresses: the
first must be within caller's function and the second must be within
the callee's function. When performing profiling at the function
level, these addresses can point anywhere within the respective
function. However, when profiling at the line-level, it is better if
the addresses are as close to the call-site/entry-point as possible.
This will ensure that the line-level call-graph is able to identify
exactly which line of source code performed calls to a function.
Basic-Block Execution Count Records
-----------------------------------
Basic-block execution count records consist of a header followed by a
sequence of address/count pairs. The header simply specifies the
length of the sequence. In an address/count pair, the address
identifies a basic-block and the count specifies the number of times
that basic-block was executed. Any address within the basic-address can
be used.

File: gprof.info, Node: Internals, Next: Debugging, Prev: File Format, Up: Details
`gprof''s Internal Operation
============================
Like most programs, `gprof' begins by processing its options.
During this stage, it may building its symspec list
(`sym_ids.c:sym_id_add'), if options are specified which use symspecs.
`gprof' maintains a single linked list of symspecs, which will
eventually get turned into 12 symbol tables, organized into six
include/exclude pairs - one pair each for the flat profile
(INCL_FLAT/EXCL_FLAT), the call graph arcs (INCL_ARCS/EXCL_ARCS),
printing in the call graph (INCL_GRAPH/EXCL_GRAPH), timing propagation
in the call graph (INCL_TIME/EXCL_TIME), the annotated source listing
(INCL_ANNO/EXCL_ANNO), and the execution count listing
(INCL_EXEC/EXCL_EXEC).
After option processing, `gprof' finishes building the symspec list
by adding all the symspecs in `default_excluded_list' to the exclude
lists EXCL_TIME and EXCL_GRAPH, and if line-by-line profiling is
specified, EXCL_FLAT as well. These default excludes are not added to
EXCL_ANNO, EXCL_ARCS, and EXCL_EXEC.
Next, the BFD library is called to open the object file, verify that
it is an object file, and read its symbol table (`core.c:core_init'),
using `bfd_canonicalize_symtab' after mallocing an appropriately sized
array of symbols. At this point, function mappings are read (if the
`--file-ordering' option has been specified), and the core text space
is read into memory (if the `-c' option was given).
`gprof''s own symbol table, an array of Sym structures, is now built.
This is done in one of two ways, by one of two routines, depending on
whether line-by-line profiling (`-l' option) has been enabled. For
normal profiling, the BFD canonical symbol table is scanned. For
line-by-line profiling, every text space address is examined, and a new
symbol table entry gets created every time the line number changes. In
either case, two passes are made through the symbol table - one to
count the size of the symbol table required, and the other to actually
read the symbols. In between the two passes, a single array of type
`Sym' is created of the appropriate length. Finally,
`symtab.c:symtab_finalize' is called to sort the symbol table and
remove duplicate entries (entries with the same memory address).
The symbol table must be a contiguous array for two reasons. First,
the `qsort' library function (which sorts an array) will be used to
sort the symbol table. Also, the symbol lookup routine
(`symtab.c:sym_lookup'), which finds symbols based on memory address,
uses a binary search algorithm which requires the symbol table to be a
sorted array. Function symbols are indicated with an `is_func' flag.
Line number symbols have no special flags set. Additionally, a symbol
can have an `is_static' flag to indicate that it is a local symbol.
With the symbol table read, the symspecs can now be translated into
Syms (`sym_ids.c:sym_id_parse'). Remember that a single symspec can
match multiple symbols. An array of symbol tables (`syms') is created,
each entry of which is a symbol table of Syms to be included or
excluded from a particular listing. The master symbol table and the
symspecs are examined by nested loops, and every symbol that matches a
symspec is inserted into the appropriate syms table. This is done
twice, once to count the size of each required symbol table, and again
to build the tables, which have been malloced between passes. From now
on, to determine whether a symbol is on an include or exclude symspec
list, `gprof' simply uses its standard symbol lookup routine on the
appropriate table in the `syms' array.
Now the profile data file(s) themselves are read
(`gmon_io.c:gmon_out_read'), first by checking for a new-style
`gmon.out' header, then assuming this is an old-style BSD `gmon.out' if
the magic number test failed.
New-style histogram records are read by `hist.c:hist_read_rec'. For
the first histogram record, allocate a memory array to hold all the
bins, and read them in. When multiple profile data files (or files
with multiple histogram records) are read, the starting address, ending
address, number of bins and sampling rate must match between the
various histograms, or a fatal error will result. If everything
matches, just sum the additional histograms into the existing in-memory
array.
As each call graph record is read (`call_graph.c:cg_read_rec'), the
parent and child addresses are matched to symbol table entries, and a
call graph arc is created by `cg_arcs.c:arc_add', unless the arc fails
a symspec check against INCL_ARCS/EXCL_ARCS. As each arc is added, a
linked list is maintained of the parent's child arcs, and of the child's
parent arcs. Both the child's call count and the arc's call count are
incremented by the record's call count.
Basic-block records are read (`basic_blocks.c:bb_read_rec'), but
only if line-by-line profiling has been selected. Each basic-block
address is matched to a corresponding line symbol in the symbol table,
and an entry made in the symbol's bb_addr and bb_calls arrays. Again,
if multiple basic-block records are present for the same address, the
call counts are cumulative.
A gmon.sum file is dumped, if requested (`gmon_io.c:gmon_out_write').
If histograms were present in the data files, assign them to symbols
(`hist.c:hist_assign_samples') by iterating over all the sample bins
and assigning them to symbols. Since the symbol table is sorted in
order of ascending memory addresses, we can simple follow along in the
symbol table as we make our pass over the sample bins. This step
includes a symspec check against INCL_FLAT/EXCL_FLAT. Depending on the
histogram scale factor, a sample bin may span multiple symbols, in
which case a fraction of the sample count is allocated to each symbol,
proportional to the degree of overlap. This effect is rare for normal
profiling, but overlaps are more common during line-by-line profiling,
and can cause each of two adjacent lines to be credited with half a
hit, for example.
If call graph data is present, `cg_arcs.c:cg_assemble' is called.
First, if `-c' was specified, a machine-dependent routine (`find_call')
scans through each symbol's machine code, looking for subroutine call
instructions, and adding them to the call graph with a zero call count.
A topological sort is performed by depth-first numbering all the
symbols (`cg_dfn.c:cg_dfn'), so that children are always numbered less
than their parents, then making a array of pointers into the symbol
table and sorting it into numerical order, which is reverse topological
order (children appear before parents). Cycles are also detected at
this point, all members of which are assigned the same topological
number. Two passes are now made through this sorted array of symbol
pointers. The first pass, from end to beginning (parents to children),
computes the fraction of child time to propagate to each parent and a
print flag. The print flag reflects symspec handling of
INCL_GRAPH/EXCL_GRAPH, with a parent's include or exclude (print or no
print) property being propagated to its children, unless they
themselves explicitly appear in INCL_GRAPH or EXCL_GRAPH. A second
pass, from beginning to end (children to parents) actually propagates
the timings along the call graph, subject to a check against
INCL_TIME/EXCL_TIME. With the print flag, fractions, and timings now
stored in the symbol structures, the topological sort array is now
discarded, and a new array of pointers is assembled, this time sorted
by propagated time.
Finally, print the various outputs the user requested, which is now
fairly straightforward. The call graph (`cg_print.c:cg_print') and
flat profile (`hist.c:hist_print') are regurgitations of values already
computed. The annotated source listing
(`basic_blocks.c:print_annotated_source') uses basic-block information,
if present, to label each line of code with call counts, otherwise only
the function call counts are presented.
The function ordering code is marginally well documented in the
source code itself (`cg_print.c'). Basically, the functions with the
most use and the most parents are placed first, followed by other
functions with the most use, followed by lower use functions, followed
by unused functions at the end.

File: gprof.info, Node: Debugging, Prev: Internals, Up: Details
Debugging `gprof'
-----------------
If `gprof' was compiled with debugging enabled, the `-d' option
triggers debugging output (to stdout) which can be helpful in
understanding its operation. The debugging number specified is
interpreted as a sum of the following options:
2 - Topological sort
Monitor depth-first numbering of symbols during call graph analysis
4 - Cycles
Shows symbols as they are identified as cycle heads
16 - Tallying
As the call graph arcs are read, show each arc and how the total
calls to each function are tallied
32 - Call graph arc sorting
Details sorting individual parents/children within each call graph
entry
64 - Reading histogram and call graph records
Shows address ranges of histograms as they are read, and each call
graph arc
128 - Symbol table
Reading, classifying, and sorting the symbol table from the object
file. For line-by-line profiling (`-l' option), also shows line
numbers being assigned to memory addresses.
256 - Static call graph
Trace operation of `-c' option
512 - Symbol table and arc table lookups
Detail operation of lookup routines
1024 - Call graph propagation
Shows how function times are propagated along the call graph
2048 - Basic-blocks
Shows basic-block records as they are read from profile data (only
meaningful with `-l' option)
4096 - Symspecs
Shows symspec-to-symbol pattern matching operation
8192 - Annotate source
Tracks operation of `-A' option

97
ld/ld.info Normal file
View File

@@ -0,0 +1,97 @@
This is ld.info, produced by makeinfo version 4.0 from ./ld.texinfo.
START-INFO-DIR-ENTRY
* Ld: (ld). The GNU linker.
END-INFO-DIR-ENTRY
This file documents the GNU linker LD version 2.10.
Copyright (C) 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000 Free
Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.
Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided also
that the entire resulting derived work is distributed under the terms
of a permission notice identical to this one.
Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions.

Indirect:
ld.info-1: 880
ld.info-2: 50060
ld.info-3: 98401
ld.info-4: 146817

Tag Table:
(Indirect)
Node: Top880
Node: Overview1397
Node: Invocation2510
Node: Options2917
Node: Environment50060
Node: Scripts51815
Node: Basic Script Concepts53548
Node: Script Format56250
Node: Simple Example57108
Node: Simple Commands60198
Node: Entry Point60644
Node: File Commands61394
Node: Format Commands64447
Node: Miscellaneous Commands66403
Node: Assignments68394
Node: Simple Assignments68726
Node: PROVIDE70422
Node: SECTIONS71595
Node: Output Section Description73481
Node: Output Section Name74466
Node: Output Section Address75333
Node: Input Section76967
Node: Input Section Basics77759
Node: Input Section Wildcards80027
Node: Input Section Common82834
Node: Input Section Keep84303
Node: Input Section Example84772
Node: Output Section Data85729
Node: Output Section Keywords88174
Node: Output Section Discarding91606
Node: Output Section Attributes92551
Node: Output Section Type93385
Node: Output Section LMA94526
Node: Output Section Region96630
Node: Output Section Phdr97043
Node: Output Section Fill97694
Node: Overlay Description98401
Node: MEMORY102640
Node: PHDRS106717
Node: VERSION111756
Node: Expressions117834
Node: Constants118668
Node: Symbols119224
Node: Location Counter119956
Node: Operators122261
Node: Evaluation123172
Node: Expression Section124526
Node: Builtin Functions126002
Node: Implicit Linker Scripts131004
Node: Machine Dependent131772
Node: H8/300132226
Node: i960133022
Node: ARM134702
Node: BFD135837
Node: BFD outline137291
Node: BFD information loss138576
Node: Canonical format141084
Node: Reporting Bugs145430
Node: Bug Criteria146123
Node: Bug Reporting146817
Node: MRI153578
Node: Index158177

End Tag Table

1141
ld/ld.info-1 Normal file
View File

File diff suppressed because it is too large Load Diff

1229
ld/ld.info-2 Normal file
View File

File diff suppressed because it is too large Load Diff

1204
ld/ld.info-3 Normal file
View File

File diff suppressed because it is too large Load Diff

759
ld/ld.info-4 Normal file
View File

@@ -0,0 +1,759 @@
This is ld.info, produced by makeinfo version 4.0 from ./ld.texinfo.
START-INFO-DIR-ENTRY
* Ld: (ld). The GNU linker.
END-INFO-DIR-ENTRY
This file documents the GNU linker LD version 2.10.
Copyright (C) 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000 Free
Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.
Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided also
that the entire resulting derived work is distributed under the terms
of a permission notice identical to this one.
Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions.

File: ld.info, Node: Bug Reporting, Prev: Bug Criteria, Up: Reporting Bugs
How to report bugs
==================
A number of companies and individuals offer support for GNU
products. If you obtained `ld' from a support organization, we
recommend you contact that organization first.
You can find contact information for many support companies and
individuals in the file `etc/SERVICE' in the GNU Emacs distribution.
Otherwise, send bug reports for `ld' to `bug-gnu-utils@gnu.org'.
The fundamental principle of reporting bugs usefully is this:
*report all the facts*. If you are not sure whether to state a fact or
leave it out, state it!
Often people omit facts because they think they know what causes the
problem and assume that some details do not matter. Thus, you might
assume that the name of a symbol you use in an example does not matter.
Well, probably it does not, but one cannot be sure. Perhaps the bug is
a stray memory reference which happens to fetch from the location where
that name is stored in memory; perhaps, if the name were different, the
contents of that location would fool the linker into doing the right
thing despite the bug. Play it safe and give a specific, complete
example. That is the easiest thing for you to do, and the most helpful.
Keep in mind that the purpose of a bug report is to enable us to fix
the bug if it is new to us. Therefore, always write your bug reports
on the assumption that the bug has not been reported previously.
Sometimes people give a few sketchy facts and ask, "Does this ring a
bell?" Those bug reports are useless, and we urge everyone to _refuse
to respond to them_ except to chide the sender to report bugs properly.
To enable us to fix the bug, you should include all these things:
* The version of `ld'. `ld' announces it if you start it with the
`--version' argument.
Without this, we will not know whether there is any point in
looking for the bug in the current version of `ld'.
* Any patches you may have applied to the `ld' source, including any
patches made to the `BFD' library.
* The type of machine you are using, and the operating system name
and version number.
* What compiler (and its version) was used to compile `ld'--e.g.
"`gcc-2.7'".
* The command arguments you gave the linker to link your example and
observe the bug. To guarantee you will not omit something
important, list them all. A copy of the Makefile (or the output
from make) is sufficient.
If we were to try to guess the arguments, we would probably guess
wrong and then we might not encounter the bug.
* A complete input file, or set of input files, that will reproduce
the bug. It is generally most helpful to send the actual object
files, uuencoded if necessary to get them through the mail system.
Making them available for anonymous FTP is not as good, but may
be the only reasonable choice for large object files.
If the source files were assembled using `gas' or compiled using
`gcc', then it may be OK to send the source files rather than the
object files. In this case, be sure to say exactly what version of
`gas' or `gcc' was used to produce the object files. Also say how
`gas' or `gcc' were configured.
* A description of what behavior you observe that you believe is
incorrect. For example, "It gets a fatal signal."
Of course, if the bug is that `ld' gets a fatal signal, then we
will certainly notice it. But if the bug is incorrect output, we
might not notice unless it is glaringly wrong. You might as well
not give us a chance to make a mistake.
Even if the problem you experience is a fatal signal, you should
still say so explicitly. Suppose something strange is going on,
such as, your copy of `ld' is out of synch, or you have
encountered a bug in the C library on your system. (This has
happened!) Your copy might crash and ours would not. If you told
us to expect a crash, then when ours fails to crash, we would know
that the bug was not happening for us. If you had not told us to
expect a crash, then we would not be able to draw any conclusion
from our observations.
* If you wish to suggest changes to the `ld' source, send us context
diffs, as generated by `diff' with the `-u', `-c', or `-p' option.
Always send diffs from the old file to the new file. If you even
discuss something in the `ld' source, refer to it by context, not
by line number.
The line numbers in our development sources will not match those
in your sources. Your line numbers would convey no useful
information to us.
Here are some things that are not necessary:
* A description of the envelope of the bug.
Often people who encounter a bug spend a lot of time investigating
which changes to the input file will make the bug go away and which
changes will not affect it.
This is often time consuming and not very useful, because the way
we will find the bug is by running a single example under the
debugger with breakpoints, not by pure deduction from a series of
examples. We recommend that you save your time for something else.
Of course, if you can find a simpler example to report _instead_
of the original one, that is a convenience for us. Errors in the
output will be easier to spot, running under the debugger will take
less time, and so on.
However, simplification is not vital; if you do not want to do
this, report the bug anyway and send us the entire test case you
used.
* A patch for the bug.
A patch for the bug does help us if it is a good one. But do not
omit the necessary information, such as the test case, on the
assumption that a patch is all we need. We might see problems
with your patch and decide to fix the problem another way, or we
might not understand it at all.
Sometimes with a program as complicated as `ld' it is very hard to
construct an example that will make the program follow a certain
path through the code. If you do not send us the example, we will
not be able to construct one, so we will not be able to verify
that the bug is fixed.
And if we cannot understand what bug you are trying to fix, or why
your patch should be an improvement, we will not install it. A
test case will help us to understand.
* A guess about what the bug is or what it depends on.
Such guesses are usually wrong. Even we cannot guess right about
such things without first using the debugger to find the facts.

File: ld.info, Node: MRI, Next: Index, Prev: Reporting Bugs, Up: Top
MRI Compatible Script Files
***************************
To aid users making the transition to GNU `ld' from the MRI linker,
`ld' can use MRI compatible linker scripts as an alternative to the
more general-purpose linker scripting language described in *Note
Scripts::. MRI compatible linker scripts have a much simpler command
set than the scripting language otherwise used with `ld'. GNU `ld'
supports the most commonly used MRI linker commands; these commands are
described here.
In general, MRI scripts aren't of much use with the `a.out' object
file format, since it only has three sections and MRI scripts lack some
features to make use of them.
You can specify a file containing an MRI-compatible script using the
`-c' command-line option.
Each command in an MRI-compatible script occupies its own line; each
command line starts with the keyword that identifies the command (though
blank lines are also allowed for punctuation). If a line of an
MRI-compatible script begins with an unrecognized keyword, `ld' issues
a warning message, but continues processing the script.
Lines beginning with `*' are comments.
You can write these commands using all upper-case letters, or all
lower case; for example, `chip' is the same as `CHIP'. The following
list shows only the upper-case form of each command.
`ABSOLUTE SECNAME'
`ABSOLUTE SECNAME, SECNAME, ... SECNAME'
Normally, `ld' includes in the output file all sections from all
the input files. However, in an MRI-compatible script, you can
use the `ABSOLUTE' command to restrict the sections that will be
present in your output program. If the `ABSOLUTE' command is used
at all in a script, then only the sections named explicitly in
`ABSOLUTE' commands will appear in the linker output. You can
still use other input sections (whatever you select on the command
line, or using `LOAD') to resolve addresses in the output file.
`ALIAS OUT-SECNAME, IN-SECNAME'
Use this command to place the data from input section IN-SECNAME
in a section called OUT-SECNAME in the linker output file.
IN-SECNAME may be an integer.
`ALIGN SECNAME = EXPRESSION'
Align the section called SECNAME to EXPRESSION. The EXPRESSION
should be a power of two.
`BASE EXPRESSION'
Use the value of EXPRESSION as the lowest address (other than
absolute addresses) in the output file.
`CHIP EXPRESSION'
`CHIP EXPRESSION, EXPRESSION'
This command does nothing; it is accepted only for compatibility.
`END'
This command does nothing whatever; it's only accepted for
compatibility.
`FORMAT OUTPUT-FORMAT'
Similar to the `OUTPUT_FORMAT' command in the more general linker
language, but restricted to one of these output formats:
1. S-records, if OUTPUT-FORMAT is `S'
2. IEEE, if OUTPUT-FORMAT is `IEEE'
3. COFF (the `coff-m68k' variant in BFD), if OUTPUT-FORMAT is
`COFF'
`LIST ANYTHING...'
Print (to the standard output file) a link map, as produced by the
`ld' command-line option `-M'.
The keyword `LIST' may be followed by anything on the same line,
with no change in its effect.
`LOAD FILENAME'
`LOAD FILENAME, FILENAME, ... FILENAME'
Include one or more object file FILENAME in the link; this has the
same effect as specifying FILENAME directly on the `ld' command
line.
`NAME OUTPUT-NAME'
OUTPUT-NAME is the name for the program produced by `ld'; the
MRI-compatible command `NAME' is equivalent to the command-line
option `-o' or the general script language command `OUTPUT'.
`ORDER SECNAME, SECNAME, ... SECNAME'
`ORDER SECNAME SECNAME SECNAME'
Normally, `ld' orders the sections in its output file in the order
in which they first appear in the input files. In an
MRI-compatible script, you can override this ordering with the
`ORDER' command. The sections you list with `ORDER' will appear
first in your output file, in the order specified.
`PUBLIC NAME=EXPRESSION'
`PUBLIC NAME,EXPRESSION'
`PUBLIC NAME EXPRESSION'
Supply a value (EXPRESSION) for external symbol NAME used in the
linker input files.
`SECT SECNAME, EXPRESSION'
`SECT SECNAME=EXPRESSION'
`SECT SECNAME EXPRESSION'
You can use any of these three forms of the `SECT' command to
specify the start address (EXPRESSION) for section SECNAME. If
you have more than one `SECT' statement for the same SECNAME, only
the _first_ sets the start address.

File: ld.info, Node: Index, Prev: MRI, Up: Top
Index
*****
* Menu:
* ": Symbols.
* -(: Options.
* --add-stdcall-alias: Options.
* --architecture=ARCH: Options.
* --auxiliary: Options.
* --base-file: Options.
* --check-sections: Options.
* --cref: Options.
* --defsym SYMBOL=EXP: Options.
* --demangle: Options.
* --disable-stdcall-fixup: Options.
* --discard-all: Options.
* --discard-locals: Options.
* --dll: Options.
* --dynamic-linker FILE: Options.
* --embedded-relocs: Options.
* --enable-stdcall-fixup: Options.
* --entry=ENTRY: Options.
* --exclude-symbols: Options.
* --export-all-symbols: Options.
* --export-dynamic: Options.
* --file-alignment: Options.
* --filter: Options.
* --force-exe-suffix: Options.
* --format=FORMAT: Options.
* --gc-sections: Options.
* --gpsize: Options.
* --heap: Options.
* --help: Options.
* --image-base: Options.
* --just-symbols=FILE: Options.
* --kill-at: Options.
* --library-path=DIR: Options.
* --library=ARCHIVE: Options.
* --major-image-version: Options.
* --major-os-version: Options.
* --major-subsystem-version: Options.
* --minor-image-version: Options.
* --minor-os-version: Options.
* --minor-subsystem-version: Options.
* --mri-script=MRI-CMDFILE: Options.
* --nmagic: Options.
* --no-check-sections: Options.
* --no-demangle: Options.
* --no-gc-sections: Options.
* --no-keep-memory: Options.
* --no-undefined: Options.
* --no-warn-mismatch: Options.
* --no-whole-archive: Options.
* --noinhibit-exec: Options.
* --oformat: Options.
* --omagic: Options.
* --output-def: Options.
* --output=OUTPUT: Options.
* --print-map: Options.
* --relax: Options.
* --relax on i960: i960.
* --relocateable: Options.
* --script=SCRIPT: Options.
* --section-alignment: Options.
* --sort-common: Options.
* --split-by-file: Options.
* --split-by-reloc: Options.
* --stack: Options.
* --stats: Options.
* --strip-all: Options.
* --strip-debug: Options.
* --subsystem: Options.
* --support-old-code: ARM.
* --thumb-entry=ENTRY: ARM.
* --trace: Options.
* --trace-symbol=SYMBOL: Options.
* --traditional-format: Options.
* --undefined=SYMBOL: Options.
* --verbose: Options.
* --version: Options.
* --version-script=VERSION-SCRIPTFILE: Options.
* --warn-comon: Options.
* --warn-constructors: Options.
* --warn-multiple-gp: Options.
* --warn-once: Options.
* --warn-section-align: Options.
* --whole-archive: Options.
* --wrap: Options.
* -AARCH: Options.
* -aKEYWORD: Options.
* -assert KEYWORD: Options.
* -b FORMAT: Options.
* -Bdynamic: Options.
* -Bshareable: Options.
* -Bstatic: Options.
* -Bsymbolic: Options.
* -c MRI-CMDFILE: Options.
* -call_shared: Options.
* -d: Options.
* -dc: Options.
* -dn: Options.
* -dp: Options.
* -dy: Options.
* -E: Options.
* -e ENTRY: Options.
* -EB: Options.
* -EL: Options.
* -F: Options.
* -f: Options.
* -fini: Options.
* -G: Options.
* -g: Options.
* -hNAME: Options.
* -i: Options.
* -init: Options.
* -lARCHIVE: Options.
* -LDIR: Options.
* -M: Options.
* -m EMULATION: Options.
* -Map: Options.
* -N: Options.
* -n: Options.
* -non_shared: Options.
* -O LEVEL: Options.
* -o OUTPUT: Options.
* -qmagic: Options.
* -Qy: Options.
* -r: Options.
* -R FILE: Options.
* -rpath: Options.
* -rpath-link: Options.
* -S: Options.
* -s: Options.
* -shared: Options.
* -soname=NAME: Options.
* -static: Options.
* -t: Options.
* -T SCRIPT: Options.
* -Tbss ORG: Options.
* -Tdata ORG: Options.
* -Ttext ORG: Options.
* -u SYMBOL: Options.
* -Ur: Options.
* -V: Options.
* -v: Options.
* -X: Options.
* -x: Options.
* -Y PATH: Options.
* -y SYMBOL: Options.
* -z KEYWORD: Options.
* .: Location Counter.
* /DISCARD/: Output Section Discarding.
* :PHDR: Output Section Phdr.
* =FILLEXP: Output Section Fill.
* >REGION: Output Section Region.
* [COMMON]: Input Section Common.
* ABSOLUTE (MRI): MRI.
* absolute and relocatable symbols: Expression Section.
* absolute expressions: Expression Section.
* ABSOLUTE(EXP): Builtin Functions.
* ADDR(SECTION): Builtin Functions.
* address, section: Output Section Address.
* ALIAS (MRI): MRI.
* ALIGN (MRI): MRI.
* align location counter: Builtin Functions.
* ALIGN(EXP): Builtin Functions.
* allocating memory: MEMORY.
* architecture: Miscellaneous Commands.
* architectures: Options.
* archive files, from cmd line: Options.
* archive search path in linker script: File Commands.
* arithmetic: Expressions.
* arithmetic operators: Operators.
* ARM interworking support: ARM.
* ASSERT: Miscellaneous Commands.
* assertion in linker script: Miscellaneous Commands.
* assignment in scripts: Assignments.
* AT(LMA): Output Section LMA.
* AT>LMA_REGION: Output Section LMA.
* back end: BFD.
* BASE (MRI): MRI.
* BFD canonical format: Canonical format.
* BFD requirements: BFD.
* big-endian objects: Options.
* binary input format: Options.
* BLOCK(EXP): Builtin Functions.
* bug criteria: Bug Criteria.
* bug reports: Bug Reporting.
* bugs in ld: Reporting Bugs.
* BYTE(EXPRESSION): Output Section Data.
* C++ constructors, arranging in link: Output Section Keywords.
* CHIP (MRI): MRI.
* COLLECT_NO_DEMANGLE: Environment.
* combining symbols, warnings on: Options.
* command files: Scripts.
* command line: Options.
* common allocation: Options.
* common allocation in linker script: Miscellaneous Commands.
* common symbol placement: Input Section Common.
* compatibility, MRI: Options.
* constants in linker scripts: Constants.
* CONSTRUCTORS: Output Section Keywords.
* constructors: Options.
* constructors, arranging in link: Output Section Keywords.
* crash of linker: Bug Criteria.
* CREATE_OBJECT_SYMBOLS: Output Section Keywords.
* cross reference table: Options.
* cross references: Miscellaneous Commands.
* current output location: Location Counter.
* data: Output Section Data.
* dbx: Options.
* DEF files, creating: Options.
* default emulation: Environment.
* default input format: Environment.
* DEFINED(SYMBOL): Builtin Functions.
* deleting local symbols: Options.
* demangling, default: Environment.
* demangling, from command line: Options.
* discarding sections: Output Section Discarding.
* discontinuous memory: MEMORY.
* DLLs, creating: Options.
* dot: Location Counter.
* dot inside sections: Location Counter.
* dynamic linker, from command line: Options.
* dynamic symbol table: Options.
* ELF program headers: PHDRS.
* emulation: Options.
* emulation, default: Environment.
* END (MRI): MRI.
* endianness: Options.
* entry point: Entry Point.
* entry point, from command line: Options.
* entry point, thumb: ARM.
* ENTRY(SYMBOL): Entry Point.
* error on valid input: Bug Criteria.
* example of linker script: Simple Example.
* expression evaluation order: Evaluation.
* expression sections: Expression Section.
* expression, absolute: Builtin Functions.
* expressions: Expressions.
* EXTERN: Miscellaneous Commands.
* fatal signal: Bug Criteria.
* file name wildcard patterns: Input Section Wildcards.
* FILEHDR: PHDRS.
* filename symbols: Output Section Keywords.
* fill pattern, entire section: Output Section Fill.
* FILL(EXPRESSION): Output Section Data.
* finalization function: Options.
* first input file: File Commands.
* first instruction: Entry Point.
* FORCE_COMMON_ALLOCATION: Miscellaneous Commands.
* FORMAT (MRI): MRI.
* functions in expressions: Builtin Functions.
* garbage collection <1>: Input Section Keep.
* garbage collection: Options.
* generating optimized output: Options.
* GNU linker: Overview.
* GNUTARGET: Environment.
* GROUP(FILES): File Commands.
* grouping input files: File Commands.
* groups of archives: Options.
* H8/300 support: H8/300.
* header size: Builtin Functions.
* heap size: Options.
* help: Options.
* holes: Location Counter.
* holes, filling: Output Section Data.
* i960 support: i960.
* image base: Options.
* implicit linker scripts: Implicit Linker Scripts.
* INCLUDE FILENAME: File Commands.
* including a linker script: File Commands.
* including an entire archive: Options.
* incremental link: Options.
* initialization function: Options.
* initialized data in ROM: Output Section LMA.
* input file format in linker script: Format Commands.
* input filename symbols: Output Section Keywords.
* input files in linker scripts: File Commands.
* input files, displaying: Options.
* input format: Options.
* input object files in linker scripts: File Commands.
* input section basics: Input Section Basics.
* input section wildcards: Input Section Wildcards.
* input sections: Input Section.
* INPUT(FILES): File Commands.
* integer notation: Constants.
* integer suffixes: Constants.
* internal object-file format: Canonical format.
* invalid input: Bug Criteria.
* K and M integer suffixes: Constants.
* KEEP: Input Section Keep.
* l =: MEMORY.
* L, deleting symbols beginning: Options.
* lazy evaluation: Evaluation.
* ld bugs, reporting: Bug Reporting.
* LDEMULATION: Environment.
* len =: MEMORY.
* LENGTH =: MEMORY.
* library search path in linker script: File Commands.
* link map: Options.
* link-time runtime library search path: Options.
* linker crash: Bug Criteria.
* linker script concepts: Basic Script Concepts.
* linker script example: Simple Example.
* linker script file commands: File Commands.
* linker script format: Script Format.
* linker script input object files: File Commands.
* linker script simple commands: Simple Commands.
* linker scripts: Scripts.
* LIST (MRI): MRI.
* little-endian objects: Options.
* LOAD (MRI): MRI.
* load address: Output Section LMA.
* LOADADDR(SECTION): Builtin Functions.
* loading, preventing: Output Section Type.
* local symbols, deleting: Options.
* location counter: Location Counter.
* LONG(EXPRESSION): Output Section Data.
* M and K integer suffixes: Constants.
* machine architecture: Miscellaneous Commands.
* machine dependencies: Machine Dependent.
* mapping input sections to output sections: Input Section.
* MAX: Builtin Functions.
* MEMORY: MEMORY.
* memory region attributes: MEMORY.
* memory regions: MEMORY.
* memory regions and sections: Output Section Region.
* memory usage: Options.
* MIN: Builtin Functions.
* MIPS embedded PIC code: Options.
* MRI compatibility: MRI.
* NAME (MRI): MRI.
* name, section: Output Section Name.
* names: Symbols.
* naming the output file: Options.
* NEXT(EXP): Builtin Functions.
* NMAGIC: Options.
* NOCROSSREFS(SECTIONS): Miscellaneous Commands.
* NOLOAD: Output Section Type.
* not enough room for program headers: Builtin Functions.
* o =: MEMORY.
* objdump -i: BFD.
* object file management: BFD.
* object files: Options.
* object formats available: BFD.
* object size: Options.
* OMAGIC: Options.
* opening object files: BFD outline.
* operators for arithmetic: Operators.
* options: Options.
* ORDER (MRI): MRI.
* org =: MEMORY.
* ORIGIN =: MEMORY.
* output file after errors: Options.
* output file format in linker script: Format Commands.
* output file name in linker scripot: File Commands.
* output section attributes: Output Section Attributes.
* output section data: Output Section Data.
* OUTPUT(FILENAME): File Commands.
* OUTPUT_ARCH(BFDARCH): Miscellaneous Commands.
* OUTPUT_FORMAT(BFDNAME): Format Commands.
* OVERLAY: Overlay Description.
* overlays: Overlay Description.
* partial link: Options.
* PHDRS: PHDRS.
* precedence in expressions: Operators.
* prevent unnecessary loading: Output Section Type.
* program headers: PHDRS.
* program headers and sections: Output Section Phdr.
* program headers, not enough room: Builtin Functions.
* program segments: PHDRS.
* PROVIDE: PROVIDE.
* PUBLIC (MRI): MRI.
* QUAD(EXPRESSION): Output Section Data.
* quoted symbol names: Symbols.
* read-only text: Options.
* read/write from cmd line: Options.
* regions of memory: MEMORY.
* relative expressions: Expression Section.
* relaxing addressing modes: Options.
* relaxing on H8/300: H8/300.
* relaxing on i960: i960.
* relocatable and absolute symbols: Expression Section.
* relocatable output: Options.
* removing sections: Output Section Discarding.
* reporting bugs in ld: Reporting Bugs.
* requirements for BFD: BFD.
* retaining specified symbols: Options.
* ROM initialized data: Output Section LMA.
* round up location counter: Builtin Functions.
* runtime library name: Options.
* runtime library search path: Options.
* scaled integers: Constants.
* scommon section: Input Section Common.
* script files: Options.
* scripts: Scripts.
* search directory, from cmd line: Options.
* search path in linker script: File Commands.
* SEARCH_DIR(PATH): File Commands.
* SECT (MRI): MRI.
* section address: Output Section Address.
* section address in expression: Builtin Functions.
* section alignment, warnings on: Options.
* section data: Output Section Data.
* section fill pattern: Output Section Fill.
* section load address: Output Section LMA.
* section load address in expression: Builtin Functions.
* section name: Output Section Name.
* section name wildcard patterns: Input Section Wildcards.
* section size: Builtin Functions.
* section, assigning to memory region: Output Section Region.
* section, assigning to program header: Output Section Phdr.
* SECTIONS: SECTIONS.
* sections, discarding: Output Section Discarding.
* segment origins, cmd line: Options.
* segments, ELF: PHDRS.
* shared libraries: Options.
* SHORT(EXPRESSION): Output Section Data.
* SIZEOF(SECTION): Builtin Functions.
* SIZEOF_HEADERS: Builtin Functions.
* small common symbols: Input Section Common.
* SORT: Input Section Wildcards.
* SQUAD(EXPRESSION): Output Section Data.
* stack size: Options.
* standard Unix system: Options.
* start of execution: Entry Point.
* STARTUP(FILENAME): File Commands.
* strip all symbols: Options.
* strip debugger symbols: Options.
* stripping all but some symbols: Options.
* suffixes for integers: Constants.
* symbol defaults: Builtin Functions.
* symbol definition, scripts: Assignments.
* symbol names: Symbols.
* symbol tracing: Options.
* symbol versions: VERSION.
* symbol-only input: Options.
* symbols, from command line: Options.
* symbols, relocatable and absolute: Expression Section.
* symbols, retaining selectively: Options.
* synthesizing linker: Options.
* synthesizing on H8/300: H8/300.
* TARGET(BFDNAME): Format Commands.
* thumb entry point: ARM.
* traditional format: Options.
* unallocated address, next: Builtin Functions.
* undefined symbol: Options.
* undefined symbol in linker script: Miscellaneous Commands.
* undefined symbols, warnings on: Options.
* uninitialized data placement: Input Section Common.
* unspecified memory: Output Section Data.
* usage: Options.
* variables, defining: Assignments.
* verbose: Options.
* version: Options.
* version script: VERSION.
* version script, symbol versions: Options.
* VERSION {script text}: VERSION.
* versions of symbols: VERSION.
* warnings, on combining symbols: Options.
* warnings, on section alignment: Options.
* warnings, on undefined symbols: Options.
* what is this?: Overview.
* wildcard file name patterns: Input Section Wildcards.

2808
ld/ldgram.c Normal file
View File

File diff suppressed because it is too large Load Diff

126
ld/ldgram.h Normal file
View File

@@ -0,0 +1,126 @@
typedef union {
bfd_vma integer;
char *name;
const char *cname;
struct wildcard_spec wildcard;
struct name_list *name_list;
int token;
union etree_union *etree;
struct phdr_info
{
boolean filehdr;
boolean phdrs;
union etree_union *at;
union etree_union *flags;
} phdr;
struct lang_nocrossref *nocrossref;
struct lang_output_section_phdr_list *section_phdr;
struct bfd_elf_version_deps *deflist;
struct bfd_elf_version_expr *versyms;
struct bfd_elf_version_tree *versnode;
} YYSTYPE;
#define INT 257
#define NAME 258
#define LNAME 259
#define PLUSEQ 260
#define MINUSEQ 261
#define MULTEQ 262
#define DIVEQ 263
#define LSHIFTEQ 264
#define RSHIFTEQ 265
#define ANDEQ 266
#define OREQ 267
#define OROR 268
#define ANDAND 269
#define EQ 270
#define NE 271
#define LE 272
#define GE 273
#define LSHIFT 274
#define RSHIFT 275
#define UNARY 276
#define END 277
#define ALIGN_K 278
#define BLOCK 279
#define BIND 280
#define QUAD 281
#define SQUAD 282
#define LONG 283
#define SHORT 284
#define BYTE 285
#define SECTIONS 286
#define PHDRS 287
#define SORT 288
#define SIZEOF_HEADERS 289
#define OUTPUT_FORMAT 290
#define FORCE_COMMON_ALLOCATION 291
#define OUTPUT_ARCH 292
#define INCLUDE 293
#define MEMORY 294
#define DEFSYMEND 295
#define NOLOAD 296
#define DSECT 297
#define COPY 298
#define INFO 299
#define OVERLAY 300
#define DEFINED 301
#define TARGET_K 302
#define SEARCH_DIR 303
#define MAP 304
#define ENTRY 305
#define NEXT 306
#define SIZEOF 307
#define ADDR 308
#define LOADADDR 309
#define MAX_K 310
#define MIN_K 311
#define STARTUP 312
#define HLL 313
#define SYSLIB 314
#define FLOAT 315
#define NOFLOAT 316
#define NOCROSSREFS 317
#define ORIGIN 318
#define FILL 319
#define LENGTH 320
#define CREATE_OBJECT_SYMBOLS 321
#define INPUT 322
#define GROUP 323
#define OUTPUT 324
#define CONSTRUCTORS 325
#define ALIGNMOD 326
#define AT 327
#define PROVIDE 328
#define CHIP 329
#define LIST 330
#define SECT 331
#define ABSOLUTE 332
#define LOAD 333
#define NEWLINE 334
#define ENDWORD 335
#define ORDER 336
#define NAMEWORD 337
#define ASSERT_K 338
#define FORMAT 339
#define PUBLIC 340
#define BASE 341
#define ALIAS 342
#define TRUNCATE 343
#define REL 344
#define INPUT_SCRIPT 345
#define INPUT_MRI_SCRIPT 346
#define INPUT_DEFSYM 347
#define CASE 348
#define EXTERN 349
#define START 350
#define VERS_TAG 351
#define VERS_IDENTIFIER 352
#define GLOBAL 353
#define LOCAL 354
#define VERSIONK 355
#define INPUT_VERSION_SCRIPT 356
#define KEEP 357
#define EXCLUDE_FILE 358
extern YYSTYPE yylval;

3592
ld/ldlex.c Normal file
View File

File diff suppressed because it is too large Load Diff

1
ld/ldver.texi Normal file
View File

@@ -0,0 +1 @@
@set VERSION 2.10