\input texinfo
-@c Copyright 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998,
-@c 2000, 2001, 2002, 2003
-@c Free Software Foundation, Inc.
+@c Copyright (C) 1988-2021 Free Software Foundation, Inc.
@setfilename bfdint.info
@settitle BFD Internals
@page
@end iftex
+@copying
+This file documents the internals of the BFD library.
+
+Copyright @copyright{} 1988-2021 Free Software Foundation, Inc.
+Contributed by Cygnus Support.
+
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.1 or
+any later version published by the Free Software Foundation; with the
+Invariant Sections being ``GNU General Public License'' and ``Funding
+Free Software'', the Front-Cover texts being (a) (see below), and with
+the Back-Cover Texts being (b) (see below). A copy of the license is
+included in the section entitled ``GNU Free Documentation License''.
+
+(a) The FSF's Front-Cover Text is:
+
+ A GNU Manual
+
+(b) The FSF's Back-Cover Text is:
+
+ You have freedom to copy and modify this GNU Manual, like GNU
+ software. Copies published by the Free Software Foundation raise
+ funds for GNU development.
+@end copying
+
@node Top
@top BFD Internals
@raisesections
In some cases there is also implicit information which BFD can not
represent. For example, the MIPS processor distinguishes small and
-large symbols, and requires that all small symbls be within 32K of the
+large symbols, and requires that all small symbols be within 32K of the
GP register. This means that the MIPS assembler must be able to mark
variables as either small or large, and the MIPS linker must know to put
small symbols within range of the GP register. Since BFD can not
Avoid global variables. We ideally want BFD to be fully reentrant, so
that it can be used in multiple threads. All uses of global or static
variables interfere with that. Initialized constant variables are OK,
-and they should be explicitly marked with const. Instead of global
+and they should be explicitly marked with @samp{const}. Instead of global
variables, use data attached to a BFD or to a linker hash table.
@item
@table @samp
@item name
The name of the target vector. This is an arbitrary string. This is
-how the target vector is named in command line options for tools which
+how the target vector is named in command-line options for tools which
use BFD, such as the @samp{--oformat} linker option.
@item flavour
ECOFF.
@item bfd_target_elf_flavour
ELF.
-@item bfd_target_ieee_flavour
-IEEE-695.
-@item bfd_target_nlm_flavour
-NLM.
-@item bfd_target_oasys_flavour
-OASYS.
@item bfd_target_tekhex_flavour
Tektronix hex format.
@item bfd_target_srec_flavour
Intel hex format.
@item bfd_target_som_flavour
SOM (used on HP/UX).
+@item bfd_target_verilog_flavour
+Verilog memory hex dump format.
@item bfd_target_os9k_flavour
os9000.
@item bfd_target_versados_flavour
you configure with the @samp{--enable-maintainer-mode} option. Some
files live in the object directory---the directory from which you run
configure---and some live in the source directory. All files that live
-in the source directory are checked into the CVS repository.
+in the source directory are checked into the git repository.
@table @file
@item bfd.h
Like @file{elfcode.h}, but for functions that are specific to ELF core
files. This is included only by @file{elfcode.h}.
-@item elflink.h
-@cindex @file{elflink.h}
-Like @file{elfcode.h}, but for functions used by the ELF linker. This
-is included only by @file{elfcode.h}.
-
@item elfxx-target.h
@cindex @file{elfxx-target.h}
This file is the source for the generated files @file{elf32-target.h}
and @file{elf64-target.h}, one of which is included by every ELF target.
It defines the ELF target vector.
-@item freebsd.h
-@cindex @file{freebsd.h}
-Presumably intended to be included by all FreeBSD targets, but in fact
-there is only one such target, @samp{i386-freebsd}. This defines a
-function used to set the right magic number for FreeBSD, as well as
-various macros, and includes @file{aout-target.h}.
-
@item netbsd.h
@cindex @file{netbsd.h}
-Like @file{freebsd.h}, except that there are several files which include
-it.
-
-@item nlm-target.h
-@cindex @file{nlm-target.h}
-Defines the target vector for a standard NLM target.
-
-@item nlmcode.h
-@cindex @file{nlmcode.h}
-Like @file{elfcode.h}, but for NLM targets. This is only included by
-@file{nlm32.c} and @file{nlm64.c}, both of which define the macro
-@samp{ARCH_SIZE} to an appropriate value. There are no 64 bit NLM
-targets anyhow, so this is sort of useless.
-
-@item nlmswap.h
-@cindex @file{nlmswap.h}
-Like @file{coffswap.h}, but for NLM targets. This is included by each
-NLM target, but I think it winds up compiling to the exact same code for
-every target, and as such is fairly useless.
+Used by all netbsd aout targets. Several other files include it.
@item peicode.h
@cindex @file{peicode.h}
In general, relocations can be arbitrarily complex. For example,
relocations used in dynamic linking systems often require the linker to
allocate space in a different section and use the offset within that
-section as the value to store. In the IEEE object file format,
-relocations may involve arbitrary expressions.
+section as the value to store.
When doing a relocatable link, the linker may or may not have to do
anything with a relocation, depending upon the definition of the
@subsection ELF sections and segments
The ELF ABI permits a file to have either sections or segments or both.
-Relocateable object files conventionally have only sections.
+Relocatable object files conventionally have only sections.
Executables conventionally have both. Core files conventionally have
only program segments.
@file{elfcode.h} includes functions to swap the ELF structures in and
out of external form, as well as a few more complex functions.
-Linker support is found in @file{elflink.c} and @file{elflink.h}. The
-latter file is compiled twice, for both 32 and 64 bit support. The
+Linker support is found in @file{elflink.c}. The
linker support is only used if the processor specific file defines
@samp{elf_backend_relocate_section}, which is required to relocate the
section contents. If that macro is not defined, the generic linker code
Define either @samp{TARGET_BIG_SYM} or @samp{TARGET_LITTLE_SYM}, or
both, to a unique C name to use for the target vector. This name should
appear in the list of target vectors in @file{targets.c}, and will also
-have to appear in @file{config.bfd} and @file{configure.in}. Define
+have to appear in @file{config.bfd} and @file{configure.ac}. Define
@samp{TARGET_BIG_SYM} for a big-endian processor,
@samp{TARGET_LITTLE_SYM} for a little-endian processor, and define both
for a bi-endian processor.
The processor function hooks and constants are ad hoc and need better
documentation.
-When a linker script uses @samp{SIZEOF_HEADERS}, the ELF backend must
-guess at the number of program segments which will be required, in
-@samp{get_program_header_size}. This is because the linker calls
-@samp{bfd_sizeof_headers} before it knows all the section addresses and
-sizes. The ELF backend may later discover, when creating program
-segments, that more program segments are required. This is currently
-reported as an error in @samp{assign_file_positions_for_segments}.
-
-In practice this makes it difficult to use @samp{SIZEOF_HEADERS} except
-with a carefully defined linker script. Unfortunately,
-@samp{SIZEOF_HEADERS} is required for fast program loading on a native
-system, since it permits the initial code section to appear on the same
-page as the program segments, saving a page read when the program starts
-running. Fortunately, native systems permit careful definition of the
-linker script. Still, ideally it would be possible to use relaxation to
-compute the number of program segments.
-
@node BFD glossary
@section BFD glossary
@cindex glossary for bfd
Load Memory Address. This is the address at which a section will be
loaded. Compare with VMA, below.
-@item NLM
-NetWare Loadable Module. Used to describe the format of an object which
-be loaded into NetWare, which is some kind of PC based network server
-program.
-
@item object file
A binary file including machine instructions, symbols, and relocation
information. Normally produced by an assembler.
projects / thirdparty / binutils-gdb.git / blobdiff