2
@c Copyright 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998,
3
@c 2000, 2001, 2002, 2003, 2004, 2006
4
@c Free Software Foundation, Inc.
5
@setfilename bfdint.info
7
@settitle BFD Internals
11
@author{Ian Lance Taylor}
12
@author{Cygnus Solutions}
21
This document describes some BFD internal information which may be
22
helpful when working on BFD. It is very incomplete.
24
This document is not updated regularly, and may be out of date.
26
The initial version of this document was written by Ian Lance Taylor
27
@email{ian@@cygnus.com}.
30
* BFD overview:: BFD overview
31
* BFD guidelines:: BFD programming guidelines
32
* BFD target vector:: BFD target vector
33
* BFD generated files:: BFD generated files
34
* BFD multiple compilations:: Files compiled multiple times in BFD
35
* BFD relocation handling:: BFD relocation handling
36
* BFD ELF support:: BFD ELF support
37
* BFD glossary:: Glossary
44
BFD is a library which provides a single interface to read and write
45
object files, executables, archive files, and core files in any format.
48
* BFD library interfaces:: BFD library interfaces
49
* BFD library users:: BFD library users
50
* BFD view:: The BFD view of a file
51
* BFD blindness:: BFD loses information
54
@node BFD library interfaces
55
@subsection BFD library interfaces
57
One way to look at the BFD library is to divide it into four parts by
60
The first interface is the set of generic functions which programs using
61
the BFD library will call. These generic function normally translate
62
directly or indirectly into calls to routines which are specific to a
63
particular object file format. Many of these generic functions are
64
actually defined as macros in @file{bfd.h}. These functions comprise
65
the official BFD interface.
67
The second interface is the set of functions which appear in the target
68
vectors. This is the bulk of the code in BFD. A target vector is a set
69
of function pointers specific to a particular object file format. The
70
target vector is used to implement the generic BFD functions. These
71
functions are always called through the target vector, and are never
72
called directly. The target vector is described in detail in @ref{BFD
73
target vector}. The set of functions which appear in a particular
74
target vector is often referred to as a BFD backend.
76
The third interface is a set of oddball functions which are typically
77
specific to a particular object file format, are not generic functions,
78
and are called from outside of the BFD library. These are used as hooks
79
by the linker and the assembler when a particular object file format
80
requires some action which the BFD generic interface does not provide.
81
These functions are typically declared in @file{bfd.h}, but in many
82
cases they are only provided when BFD is configured with support for a
83
particular object file format. These functions live in a grey area, and
84
are not really part of the official BFD interface.
86
The fourth interface is the set of BFD support functions which are
87
called by the other BFD functions. These manage issues like memory
88
allocation, error handling, file access, hash tables, swapping, and the
89
like. These functions are never called from outside of the BFD library.
91
@node BFD library users
92
@subsection BFD library users
94
Another way to look at the BFD library is to divide it into three parts
95
by the manner in which it is used.
97
The first use is to read an object file. The object file readers are
98
programs like @samp{gdb}, @samp{nm}, @samp{objdump}, and @samp{objcopy}.
99
These programs use BFD to view an object file in a generic form. The
100
official BFD interface is normally fully adequate for these programs.
102
The second use is to write an object file. The object file writers are
103
programs like @samp{gas} and @samp{objcopy}. These programs use BFD to
104
create an object file. The official BFD interface is normally adequate
105
for these programs, but for some object file formats the assembler needs
106
some additional hooks in order to set particular flags or other
107
information. The official BFD interface includes functions to copy
108
private information from one object file to another, and these functions
109
are used by @samp{objcopy} to avoid information loss.
111
The third use is to link object files. There is only one object file
112
linker, @samp{ld}. Originally, @samp{ld} was an object file reader and
113
an object file writer, and it did the link operation using the generic
114
BFD structures. However, this turned out to be too slow and too memory
117
The official BFD linker functions were written to permit specific BFD
118
backends to perform the link without translating through the generic
119
structures, in the normal case where all the input files and output file
120
have the same object file format. Not all of the backends currently
121
implement the new interface, and there are default linking functions
122
within BFD which use the generic structures and which work with all
125
For several object file formats the linker needs additional hooks which
126
are not provided by the official BFD interface, particularly for dynamic
127
linking support. These functions are typically called from the linker
131
@subsection The BFD view of a file
133
BFD uses generic structures to manage information. It translates data
134
into the generic form when reading files, and out of the generic form
137
BFD describes a file as a pointer to the @samp{bfd} type. A @samp{bfd}
138
is composed of the following elements. The BFD information can be
139
displayed using the @samp{objdump} program with various options.
142
@item general information
143
The object file format, a few general flags, the start address.
145
The architecture, including both a general processor type (m68k, MIPS
146
etc.) and a specific machine number (m68000, R4000, etc.).
153
BFD represents a section as a pointer to the @samp{asection} type. Each
154
section has a name and a size. Most sections also have an associated
155
block of data, known as the section contents. Sections also have
156
associated flags, a virtual memory address, a load memory address, a
157
required alignment, a list of relocations, and other miscellaneous
160
BFD represents a relocation as a pointer to the @samp{arelent} type. A
161
relocation describes an action which the linker must take to modify the
162
section contents. Relocations have a symbol, an address, an addend, and
163
a pointer to a howto structure which describes how to perform the
164
relocation. For more information, see @ref{BFD relocation handling}.
166
BFD represents a symbol as a pointer to the @samp{asymbol} type. A
167
symbol has a name, a pointer to a section, an offset within that
168
section, and some flags.
170
Archive files do not have any sections or symbols. Instead, BFD
171
represents an archive file as a file which contains a list of
172
@samp{bfd}s. BFD also provides access to the archive symbol map, as a
173
list of symbol names. BFD provides a function to return the @samp{bfd}
174
within the archive which corresponds to a particular entry in the
178
@subsection BFD loses information
180
Most object file formats have information which BFD can not represent in
181
its generic form, at least as currently defined.
183
There is often explicit information which BFD can not represent. For
184
example, the COFF version stamp, or the ELF program segments. BFD
185
provides special hooks to handle this information when copying,
186
printing, or linking an object file. The BFD support for a particular
187
object file format will normally store this information in private data
188
and handle it using the special hooks.
190
In some cases there is also implicit information which BFD can not
191
represent. For example, the MIPS processor distinguishes small and
192
large symbols, and requires that all small symbols be within 32K of the
193
GP register. This means that the MIPS assembler must be able to mark
194
variables as either small or large, and the MIPS linker must know to put
195
small symbols within range of the GP register. Since BFD can not
196
represent this information, this means that the assembler and linker
197
must have information that is specific to a particular object file
198
format which is outside of the BFD library.
200
This loss of information indicates areas where the BFD paradigm breaks
201
down. It is not actually possible to represent the myriad differences
202
among object file formats using a single generic interface, at least not
203
in the manner which BFD does it today.
205
Nevertheless, the BFD library does greatly simplify the task of dealing
206
with object files, and particular problems caused by information loss
207
can normally be solved using some sort of relatively constrained hook
213
@section BFD programming guidelines
214
@cindex bfd programming guidelines
215
@cindex programming guidelines for bfd
216
@cindex guidelines, bfd programming
218
There is a lot of poorly written and confusing code in BFD. New BFD
219
code should be written to a higher standard. Merely because some BFD
220
code is written in a particular manner does not mean that you should
223
Here are some general BFD programming guidelines:
227
Follow the GNU coding standards.
230
Avoid global variables. We ideally want BFD to be fully reentrant, so
231
that it can be used in multiple threads. All uses of global or static
232
variables interfere with that. Initialized constant variables are OK,
233
and they should be explicitly marked with @samp{const}. Instead of global
234
variables, use data attached to a BFD or to a linker hash table.
237
All externally visible functions should have names which start with
238
@samp{bfd_}. All such functions should be declared in some header file,
239
typically @file{bfd.h}. See, for example, the various declarations near
240
the end of @file{bfd-in.h}, which mostly declare functions required by
241
specific linker emulations.
244
All functions which need to be visible from one file to another within
245
BFD, but should not be visible outside of BFD, should start with
246
@samp{_bfd_}. Although external names beginning with @samp{_} are
247
prohibited by the ANSI standard, in practice this usage will always
248
work, and it is required by the GNU coding standards.
251
Always remember that people can compile using @samp{--enable-targets} to
252
build several, or all, targets at once. It must be possible to link
253
together the files for all targets.
256
BFD code should compile with few or no warnings using @samp{gcc -Wall}.
257
Some warnings are OK, like the absence of certain function declarations
258
which may or may not be declared in system header files. Warnings about
259
ambiguous expressions and the like should always be fixed.
262
@node BFD target vector
263
@section BFD target vector
264
@cindex bfd target vector
265
@cindex target vector in bfd
267
BFD supports multiple object file formats by using the @dfn{target
268
vector}. This is simply a set of function pointers which implement
269
behaviour that is specific to a particular object file format.
271
In this section I list all of the entries in the target vector and
272
describe what they do.
275
* BFD target vector miscellaneous:: Miscellaneous constants
276
* BFD target vector swap:: Swapping functions
277
* BFD target vector format:: Format type dependent functions
278
* BFD_JUMP_TABLE macros:: BFD_JUMP_TABLE macros
279
* BFD target vector generic:: Generic functions
280
* BFD target vector copy:: Copy functions
281
* BFD target vector core:: Core file support functions
282
* BFD target vector archive:: Archive functions
283
* BFD target vector symbols:: Symbol table functions
284
* BFD target vector relocs:: Relocation support
285
* BFD target vector write:: Output functions
286
* BFD target vector link:: Linker functions
287
* BFD target vector dynamic:: Dynamic linking information functions
290
@node BFD target vector miscellaneous
291
@subsection Miscellaneous constants
293
The target vector starts with a set of constants.
297
The name of the target vector. This is an arbitrary string. This is
298
how the target vector is named in command line options for tools which
299
use BFD, such as the @samp{--oformat} linker option.
302
A general description of the type of target. The following flavours are
306
@item bfd_target_unknown_flavour
307
Undefined or unknown.
308
@item bfd_target_aout_flavour
310
@item bfd_target_coff_flavour
312
@item bfd_target_ecoff_flavour
314
@item bfd_target_elf_flavour
316
@item bfd_target_ieee_flavour
318
@item bfd_target_nlm_flavour
320
@item bfd_target_oasys_flavour
322
@item bfd_target_tekhex_flavour
323
Tektronix hex format.
324
@item bfd_target_srec_flavour
325
Motorola S-record format.
326
@item bfd_target_ihex_flavour
328
@item bfd_target_som_flavour
330
@item bfd_target_os9k_flavour
332
@item bfd_target_versados_flavour
334
@item bfd_target_msdos_flavour
336
@item bfd_target_evax_flavour
338
@item bfd_target_mmo_flavour
339
Donald Knuth's MMIXware object format.
343
The byte order of data in the object file. One of
344
@samp{BFD_ENDIAN_BIG}, @samp{BFD_ENDIAN_LITTLE}, or
345
@samp{BFD_ENDIAN_UNKNOWN}. The latter would be used for a format such
346
as S-records which do not record the architecture of the data.
348
@item header_byteorder
349
The byte order of header information in the object file. Normally the
350
same as the @samp{byteorder} field, but there are certain cases where it
354
Flags which may appear in the @samp{flags} field of a BFD with this
358
Flags which may appear in the @samp{flags} field of a section within a
359
BFD with this format.
361
@item symbol_leading_char
362
A character which the C compiler normally puts before a symbol. For
363
example, an a.out compiler will typically generate the symbol
364
@samp{_foo} for a function named @samp{foo} in the C source, in which
365
case this field would be @samp{_}. If there is no such character, this
366
field will be @samp{0}.
369
The padding character to use at the end of an archive name. Normally
373
The maximum length of a short name in an archive. Normally @samp{14}.
376
A pointer to constant backend data. This is used by backends to store
377
whatever additional information they need to distinguish similar target
378
vectors which use the same sets of functions.
381
@node BFD target vector swap
382
@subsection Swapping functions
384
Every target vector has function pointers used for swapping information
385
in and out of the target representation. There are two sets of
386
functions: one for data information, and one for header information.
387
Each set has three sizes: 64-bit, 32-bit, and 16-bit. Each size has
388
three actual functions: put, get unsigned, and get signed.
390
These 18 functions are used to convert data between the host and target
393
@node BFD target vector format
394
@subsection Format type dependent functions
396
Every target vector has three arrays of function pointers which are
397
indexed by the BFD format type. The BFD format types are as follows:
401
Unknown format. Not used for anything useful.
410
The three arrays of function pointers are as follows:
413
@item bfd_check_format
414
Check whether the BFD is of a particular format (object file, archive
415
file, or core file) corresponding to this target vector. This is called
416
by the @samp{bfd_check_format} function when examining an existing BFD.
417
If the BFD matches the desired format, this function will initialize any
418
format specific information such as the @samp{tdata} field of the BFD.
419
This function must be called before any other BFD target vector function
420
on a file opened for reading.
423
Set the format of a BFD which was created for output. This is called by
424
the @samp{bfd_set_format} function after creating the BFD with a
425
function such as @samp{bfd_openw}. This function will initialize format
426
specific information required to write out an object file or whatever of
427
the given format. This function must be called before any other BFD
428
target vector function on a file opened for writing.
430
@item bfd_write_contents
431
Write out the contents of the BFD in the given format. This is called
432
by @samp{bfd_close} function for a BFD opened for writing. This really
433
should not be an array selected by format type, as the
434
@samp{bfd_set_format} function provides all the required information.
435
In fact, BFD will fail if a different format is used when calling
436
through the @samp{bfd_set_format} and the @samp{bfd_write_contents}
437
arrays; fortunately, since @samp{bfd_close} gets it right, this is a
438
difficult error to make.
441
@node BFD_JUMP_TABLE macros
442
@subsection @samp{BFD_JUMP_TABLE} macros
443
@cindex @samp{BFD_JUMP_TABLE}
445
Most target vectors are defined using @samp{BFD_JUMP_TABLE} macros.
446
These macros take a single argument, which is a prefix applied to a set
447
of functions. The macros are then used to initialize the fields in the
450
For example, the @samp{BFD_JUMP_TABLE_RELOCS} macro defines three
451
functions: @samp{_get_reloc_upper_bound}, @samp{_canonicalize_reloc},
452
and @samp{_bfd_reloc_type_lookup}. A reference like
453
@samp{BFD_JUMP_TABLE_RELOCS (foo)} will expand into three functions
454
prefixed with @samp{foo}: @samp{foo_get_reloc_upper_bound}, etc. The
455
@samp{BFD_JUMP_TABLE_RELOCS} macro will be placed such that those three
456
functions initialize the appropriate fields in the BFD target vector.
458
This is done because it turns out that many different target vectors can
459
share certain classes of functions. For example, archives are similar
460
on most platforms, so most target vectors can use the same archive
461
functions. Those target vectors all use @samp{BFD_JUMP_TABLE_ARCHIVE}
462
with the same argument, calling a set of functions which is defined in
465
Each of the @samp{BFD_JUMP_TABLE} macros is mentioned below along with
466
the description of the function pointers which it defines. The function
467
pointers will be described using the name without the prefix which the
468
@samp{BFD_JUMP_TABLE} macro defines. This name is normally the same as
469
the name of the field in the target vector structure. Any differences
472
@node BFD target vector generic
473
@subsection Generic functions
474
@cindex @samp{BFD_JUMP_TABLE_GENERIC}
476
The @samp{BFD_JUMP_TABLE_GENERIC} macro is used for some catch all
477
functions which don't easily fit into other categories.
480
@item _close_and_cleanup
481
Free any target specific information associated with the BFD. This is
482
called when any BFD is closed (the @samp{bfd_write_contents} function
483
mentioned earlier is only called for a BFD opened for writing). Most
484
targets use @samp{bfd_alloc} to allocate all target specific
485
information, and therefore don't have to do anything in this function.
486
This function pointer is typically set to
487
@samp{_bfd_generic_close_and_cleanup}, which simply returns true.
489
@item _bfd_free_cached_info
490
Free any cached information associated with the BFD which can be
491
recreated later if necessary. This is used to reduce the memory
492
consumption required by programs using BFD. This is normally called via
493
the @samp{bfd_free_cached_info} macro. It is used by the default
494
archive routines when computing the archive map. Most targets do not
495
do anything special for this entry point, and just set it to
496
@samp{_bfd_generic_free_cached_info}, which simply returns true.
498
@item _new_section_hook
499
This is called from @samp{bfd_make_section_anyway} whenever a new
500
section is created. Most targets use it to initialize section specific
501
information. This function is called whether or not the section
502
corresponds to an actual section in an actual BFD.
504
@item _get_section_contents
505
Get the contents of a section. This is called from
506
@samp{bfd_get_section_contents}. Most targets set this to
507
@samp{_bfd_generic_get_section_contents}, which does a @samp{bfd_seek}
508
based on the section's @samp{filepos} field and a @samp{bfd_bread}. The
509
corresponding field in the target vector is named
510
@samp{_bfd_get_section_contents}.
512
@item _get_section_contents_in_window
513
Set a @samp{bfd_window} to hold the contents of a section. This is
514
called from @samp{bfd_get_section_contents_in_window}. The
515
@samp{bfd_window} idea never really caught on, and I don't think this is
516
ever called. Pretty much all targets implement this as
517
@samp{bfd_generic_get_section_contents_in_window}, which uses
518
@samp{bfd_get_section_contents} to do the right thing. The
519
corresponding field in the target vector is named
520
@samp{_bfd_get_section_contents_in_window}.
523
@node BFD target vector copy
524
@subsection Copy functions
525
@cindex @samp{BFD_JUMP_TABLE_COPY}
527
The @samp{BFD_JUMP_TABLE_COPY} macro is used for functions which are
528
called when copying BFDs, and for a couple of functions which deal with
529
internal BFD information.
532
@item _bfd_copy_private_bfd_data
533
This is called when copying a BFD, via @samp{bfd_copy_private_bfd_data}.
534
If the input and output BFDs have the same format, this will copy any
535
private information over. This is called after all the section contents
536
have been written to the output file. Only a few targets do anything in
539
@item _bfd_merge_private_bfd_data
540
This is called when linking, via @samp{bfd_merge_private_bfd_data}. It
541
gives the backend linker code a chance to set any special flags in the
542
output file based on the contents of the input file. Only a few targets
543
do anything in this function.
545
@item _bfd_copy_private_section_data
546
This is similar to @samp{_bfd_copy_private_bfd_data}, but it is called
547
for each section, via @samp{bfd_copy_private_section_data}. This
548
function is called before any section contents have been written. Only
549
a few targets do anything in this function.
551
@item _bfd_copy_private_symbol_data
552
This is called via @samp{bfd_copy_private_symbol_data}, but I don't
553
think anything actually calls it. If it were defined, it could be used
554
to copy private symbol data from one BFD to another. However, most BFDs
555
store extra symbol information by allocating space which is larger than
556
the @samp{asymbol} structure and storing private information in the
557
extra space. Since @samp{objcopy} and other programs copy symbol
558
information by copying pointers to @samp{asymbol} structures, the
559
private symbol information is automatically copied as well. Most
560
targets do not do anything in this function.
562
@item _bfd_set_private_flags
563
This is called via @samp{bfd_set_private_flags}. It is basically a hook
564
for the assembler to set magic information. For example, the PowerPC
565
ELF assembler uses it to set flags which appear in the e_flags field of
566
the ELF header. Most targets do not do anything in this function.
568
@item _bfd_print_private_bfd_data
569
This is called by @samp{objdump} when the @samp{-p} option is used. It
570
is called via @samp{bfd_print_private_data}. It prints any interesting
571
information about the BFD which can not be otherwise represented by BFD
572
and thus can not be printed by @samp{objdump}. Most targets do not do
573
anything in this function.
576
@node BFD target vector core
577
@subsection Core file support functions
578
@cindex @samp{BFD_JUMP_TABLE_CORE}
580
The @samp{BFD_JUMP_TABLE_CORE} macro is used for functions which deal
581
with core files. Obviously, these functions only do something
582
interesting for targets which have core file support.
585
@item _core_file_failing_command
586
Given a core file, this returns the command which was run to produce the
589
@item _core_file_failing_signal
590
Given a core file, this returns the signal number which produced the
593
@item _core_file_matches_executable_p
594
Given a core file and a BFD for an executable, this returns whether the
595
core file was generated by the executable.
598
@node BFD target vector archive
599
@subsection Archive functions
600
@cindex @samp{BFD_JUMP_TABLE_ARCHIVE}
602
The @samp{BFD_JUMP_TABLE_ARCHIVE} macro is used for functions which deal
603
with archive files. Most targets use COFF style archive files
604
(including ELF targets), and these use @samp{_bfd_archive_coff} as the
605
argument to @samp{BFD_JUMP_TABLE_ARCHIVE}. Some targets use BSD/a.out
606
style archives, and these use @samp{_bfd_archive_bsd}. (The main
607
difference between BSD and COFF archives is the format of the archive
608
symbol table). Targets with no archive support use
609
@samp{_bfd_noarchive}. Finally, a few targets have unusual archive
614
Read in the archive symbol table, storing it in private BFD data. This
615
is normally called from the archive @samp{check_format} routine. The
616
corresponding field in the target vector is named
617
@samp{_bfd_slurp_armap}.
619
@item _slurp_extended_name_table
620
Read in the extended name table from the archive, if there is one,
621
storing it in private BFD data. This is normally called from the
622
archive @samp{check_format} routine. The corresponding field in the
623
target vector is named @samp{_bfd_slurp_extended_name_table}.
625
@item construct_extended_name_table
626
Build and return an extended name table if one is needed to write out
627
the archive. This also adjusts the archive headers to refer to the
628
extended name table appropriately. This is normally called from the
629
archive @samp{write_contents} routine. The corresponding field in the
630
target vector is named @samp{_bfd_construct_extended_name_table}.
632
@item _truncate_arname
633
This copies a file name into an archive header, truncating it as
634
required. It is normally called from the archive @samp{write_contents}
635
routine. This function is more interesting in targets which do not
636
support extended name tables, but I think the GNU @samp{ar} program
637
always uses extended name tables anyhow. The corresponding field in the
638
target vector is named @samp{_bfd_truncate_arname}.
641
Write out the archive symbol table using calls to @samp{bfd_bwrite}.
642
This is normally called from the archive @samp{write_contents} routine.
643
The corresponding field in the target vector is named @samp{write_armap}
644
(no leading underscore).
647
Read and parse an archive header. This handles expanding the archive
648
header name into the real file name using the extended name table. This
649
is called by routines which read the archive symbol table or the archive
650
itself. The corresponding field in the target vector is named
651
@samp{_bfd_read_ar_hdr_fn}.
653
@item _openr_next_archived_file
654
Given an archive and a BFD representing a file stored within the
655
archive, return a BFD for the next file in the archive. This is called
656
via @samp{bfd_openr_next_archived_file}. The corresponding field in the
657
target vector is named @samp{openr_next_archived_file} (no leading
660
@item _get_elt_at_index
661
Given an archive and an index, return a BFD for the file in the archive
662
corresponding to that entry in the archive symbol table. This is called
663
via @samp{bfd_get_elt_at_index}. The corresponding field in the target
664
vector is named @samp{_bfd_get_elt_at_index}.
666
@item _generic_stat_arch_elt
667
Do a stat on an element of an archive, returning information read from
668
the archive header (modification time, uid, gid, file mode, size). This
669
is called via @samp{bfd_stat_arch_elt}. The corresponding field in the
670
target vector is named @samp{_bfd_stat_arch_elt}.
672
@item _update_armap_timestamp
673
After the entire contents of an archive have been written out, update
674
the timestamp of the archive symbol table to be newer than that of the
675
file. This is required for a.out style archives. This is normally
676
called by the archive @samp{write_contents} routine. The corresponding
677
field in the target vector is named @samp{_bfd_update_armap_timestamp}.
680
@node BFD target vector symbols
681
@subsection Symbol table functions
682
@cindex @samp{BFD_JUMP_TABLE_SYMBOLS}
684
The @samp{BFD_JUMP_TABLE_SYMBOLS} macro is used for functions which deal
688
@item _get_symtab_upper_bound
689
Return a sensible upper bound on the amount of memory which will be
690
required to read the symbol table. In practice most targets return the
691
amount of memory required to hold @samp{asymbol} pointers for all the
692
symbols plus a trailing @samp{NULL} entry, and store the actual symbol
693
information in BFD private data. This is called via
694
@samp{bfd_get_symtab_upper_bound}. The corresponding field in the
695
target vector is named @samp{_bfd_get_symtab_upper_bound}.
697
@item _canonicalize_symtab
698
Read in the symbol table. This is called via
699
@samp{bfd_canonicalize_symtab}. The corresponding field in the target
700
vector is named @samp{_bfd_canonicalize_symtab}.
702
@item _make_empty_symbol
703
Create an empty symbol for the BFD. This is needed because most targets
704
store extra information with each symbol by allocating a structure
705
larger than an @samp{asymbol} and storing the extra information at the
706
end. This function will allocate the right amount of memory, and return
707
what looks like a pointer to an empty @samp{asymbol}. This is called
708
via @samp{bfd_make_empty_symbol}. The corresponding field in the target
709
vector is named @samp{_bfd_make_empty_symbol}.
712
Print information about the symbol. This is called via
713
@samp{bfd_print_symbol}. One of the arguments indicates what sort of
714
information should be printed:
717
@item bfd_print_symbol_name
718
Just print the symbol name.
719
@item bfd_print_symbol_more
720
Print the symbol name and some interesting flags. I don't think
721
anything actually uses this.
722
@item bfd_print_symbol_all
723
Print all information about the symbol. This is used by @samp{objdump}
724
when run with the @samp{-t} option.
726
The corresponding field in the target vector is named
727
@samp{_bfd_print_symbol}.
729
@item _get_symbol_info
730
Return a standard set of information about the symbol. This is called
731
via @samp{bfd_symbol_info}. The corresponding field in the target
732
vector is named @samp{_bfd_get_symbol_info}.
734
@item _bfd_is_local_label_name
735
Return whether the given string would normally represent the name of a
736
local label. This is called via @samp{bfd_is_local_label} and
737
@samp{bfd_is_local_label_name}. Local labels are normally discarded by
738
the assembler. In the linker, this defines the difference between the
739
@samp{-x} and @samp{-X} options.
742
Return line number information for a symbol. This is only meaningful
743
for a COFF target. This is called when writing out COFF line numbers.
745
@item _find_nearest_line
746
Given an address within a section, use the debugging information to find
747
the matching file name, function name, and line number, if any. This is
748
called via @samp{bfd_find_nearest_line}. The corresponding field in the
749
target vector is named @samp{_bfd_find_nearest_line}.
751
@item _bfd_make_debug_symbol
752
Make a debugging symbol. This is only meaningful for a COFF target,
753
where it simply returns a symbol which will be placed in the
754
@samp{N_DEBUG} section when it is written out. This is called via
755
@samp{bfd_make_debug_symbol}.
757
@item _read_minisymbols
758
Minisymbols are used to reduce the memory requirements of programs like
759
@samp{nm}. A minisymbol is a cookie pointing to internal symbol
760
information which the caller can use to extract complete symbol
761
information. This permits BFD to not convert all the symbols into
762
generic form, but to instead convert them one at a time. This is called
763
via @samp{bfd_read_minisymbols}. Most targets do not implement this,
764
and just use generic support which is based on using standard
765
@samp{asymbol} structures.
767
@item _minisymbol_to_symbol
768
Convert a minisymbol to a standard @samp{asymbol}. This is called via
769
@samp{bfd_minisymbol_to_symbol}.
772
@node BFD target vector relocs
773
@subsection Relocation support
774
@cindex @samp{BFD_JUMP_TABLE_RELOCS}
776
The @samp{BFD_JUMP_TABLE_RELOCS} macro is used for functions which deal
780
@item _get_reloc_upper_bound
781
Return a sensible upper bound on the amount of memory which will be
782
required to read the relocations for a section. In practice most
783
targets return the amount of memory required to hold @samp{arelent}
784
pointers for all the relocations plus a trailing @samp{NULL} entry, and
785
store the actual relocation information in BFD private data. This is
786
called via @samp{bfd_get_reloc_upper_bound}.
788
@item _canonicalize_reloc
789
Return the relocation information for a section. This is called via
790
@samp{bfd_canonicalize_reloc}. The corresponding field in the target
791
vector is named @samp{_bfd_canonicalize_reloc}.
793
@item _bfd_reloc_type_lookup
794
Given a relocation code, return the corresponding howto structure
795
(@pxref{BFD relocation codes}). This is called via
796
@samp{bfd_reloc_type_lookup}. The corresponding field in the target
797
vector is named @samp{reloc_type_lookup}.
800
@node BFD target vector write
801
@subsection Output functions
802
@cindex @samp{BFD_JUMP_TABLE_WRITE}
804
The @samp{BFD_JUMP_TABLE_WRITE} macro is used for functions which deal
805
with writing out a BFD.
809
Set the architecture and machine number for a BFD. This is called via
810
@samp{bfd_set_arch_mach}. Most targets implement this by calling
811
@samp{bfd_default_set_arch_mach}. The corresponding field in the target
812
vector is named @samp{_bfd_set_arch_mach}.
814
@item _set_section_contents
815
Write out the contents of a section. This is called via
816
@samp{bfd_set_section_contents}. The corresponding field in the target
817
vector is named @samp{_bfd_set_section_contents}.
820
@node BFD target vector link
821
@subsection Linker functions
822
@cindex @samp{BFD_JUMP_TABLE_LINK}
824
The @samp{BFD_JUMP_TABLE_LINK} macro is used for functions called by the
828
@item _sizeof_headers
829
Return the size of the header information required for a BFD. This is
830
used to implement the @samp{SIZEOF_HEADERS} linker script function. It
831
is normally used to align the first section at an efficient position on
832
the page. This is called via @samp{bfd_sizeof_headers}. The
833
corresponding field in the target vector is named
834
@samp{_bfd_sizeof_headers}.
836
@item _bfd_get_relocated_section_contents
837
Read the contents of a section and apply the relocation information.
838
This handles both a final link and a relocatable link; in the latter
839
case, it adjust the relocation information as well. This is called via
840
@samp{bfd_get_relocated_section_contents}. Most targets implement it by
841
calling @samp{bfd_generic_get_relocated_section_contents}.
843
@item _bfd_relax_section
844
Try to use relaxation to shrink the size of a section. This is called
845
by the linker when the @samp{-relax} option is used. This is called via
846
@samp{bfd_relax_section}. Most targets do not support any sort of
849
@item _bfd_link_hash_table_create
850
Create the symbol hash table to use for the linker. This linker hook
851
permits the backend to control the size and information of the elements
852
in the linker symbol hash table. This is called via
853
@samp{bfd_link_hash_table_create}.
855
@item _bfd_link_add_symbols
856
Given an object file or an archive, add all symbols into the linker
857
symbol hash table. Use callbacks to the linker to include archive
858
elements in the link. This is called via @samp{bfd_link_add_symbols}.
860
@item _bfd_final_link
861
Finish the linking process. The linker calls this hook after all of the
862
input files have been read, when it is ready to finish the link and
863
generate the output file. This is called via @samp{bfd_final_link}.
865
@item _bfd_link_split_section
866
I don't know what this is for. Nothing seems to call it. The only
867
non-trivial definition is in @file{som.c}.
870
@node BFD target vector dynamic
871
@subsection Dynamic linking information functions
872
@cindex @samp{BFD_JUMP_TABLE_DYNAMIC}
874
The @samp{BFD_JUMP_TABLE_DYNAMIC} macro is used for functions which read
875
dynamic linking information.
878
@item _get_dynamic_symtab_upper_bound
879
Return a sensible upper bound on the amount of memory which will be
880
required to read the dynamic symbol table. In practice most targets
881
return the amount of memory required to hold @samp{asymbol} pointers for
882
all the symbols plus a trailing @samp{NULL} entry, and store the actual
883
symbol information in BFD private data. This is called via
884
@samp{bfd_get_dynamic_symtab_upper_bound}. The corresponding field in
885
the target vector is named @samp{_bfd_get_dynamic_symtab_upper_bound}.
887
@item _canonicalize_dynamic_symtab
888
Read the dynamic symbol table. This is called via
889
@samp{bfd_canonicalize_dynamic_symtab}. The corresponding field in the
890
target vector is named @samp{_bfd_canonicalize_dynamic_symtab}.
892
@item _get_dynamic_reloc_upper_bound
893
Return a sensible upper bound on the amount of memory which will be
894
required to read the dynamic relocations. In practice most targets
895
return the amount of memory required to hold @samp{arelent} pointers for
896
all the relocations plus a trailing @samp{NULL} entry, and store the
897
actual relocation information in BFD private data. This is called via
898
@samp{bfd_get_dynamic_reloc_upper_bound}. The corresponding field in
899
the target vector is named @samp{_bfd_get_dynamic_reloc_upper_bound}.
901
@item _canonicalize_dynamic_reloc
902
Read the dynamic relocations. This is called via
903
@samp{bfd_canonicalize_dynamic_reloc}. The corresponding field in the
904
target vector is named @samp{_bfd_canonicalize_dynamic_reloc}.
907
@node BFD generated files
908
@section BFD generated files
909
@cindex generated files in bfd
910
@cindex bfd generated files
912
BFD contains several automatically generated files. This section
913
describes them. Some files are created at configure time, when you
914
configure BFD. Some files are created at make time, when you build
915
BFD. Some files are automatically rebuilt at make time, but only if
916
you configure with the @samp{--enable-maintainer-mode} option. Some
917
files live in the object directory---the directory from which you run
918
configure---and some live in the source directory. All files that live
919
in the source directory are checked into the CVS repository.
924
@cindex @file{bfd-in3.h}
925
Lives in the object directory. Created at make time from
926
@file{bfd-in2.h} via @file{bfd-in3.h}. @file{bfd-in3.h} is created at
927
configure time from @file{bfd-in2.h}. There are automatic dependencies
928
to rebuild @file{bfd-in3.h} and hence @file{bfd.h} if @file{bfd-in2.h}
929
changes, so you can normally ignore @file{bfd-in3.h}, and just think
930
about @file{bfd-in2.h} and @file{bfd.h}.
932
@file{bfd.h} is built by replacing a few strings in @file{bfd-in2.h}.
933
To see them, search for @samp{@@} in @file{bfd-in2.h}. They mainly
934
control whether BFD is built for a 32 bit target or a 64 bit target.
937
@cindex @file{bfd-in2.h}
938
Lives in the source directory. Created from @file{bfd-in.h} and several
939
other BFD source files. If you configure with the
940
@samp{--enable-maintainer-mode} option, @file{bfd-in2.h} is rebuilt
941
automatically when a source file changes.
944
@itemx elf64-target.h
945
@cindex @file{elf32-target.h}
946
@cindex @file{elf64-target.h}
947
Live in the object directory. Created from @file{elfxx-target.h}.
948
These files are versions of @file{elfxx-target.h} customized for either
949
a 32 bit ELF target or a 64 bit ELF target.
952
@cindex @file{libbfd.h}
953
Lives in the source directory. Created from @file{libbfd-in.h} and
954
several other BFD source files. If you configure with the
955
@samp{--enable-maintainer-mode} option, @file{libbfd.h} is rebuilt
956
automatically when a source file changes.
959
@cindex @file{libcoff.h}
960
Lives in the source directory. Created from @file{libcoff-in.h} and
961
@file{coffcode.h}. If you configure with the
962
@samp{--enable-maintainer-mode} option, @file{libcoff.h} is rebuilt
963
automatically when a source file changes.
966
@cindex @file{targmatch.h}
967
Lives in the object directory. Created at make time from
968
@file{config.bfd}. This file is used to map configuration triplets into
969
BFD target vector variable names at run time.
972
@node BFD multiple compilations
973
@section Files compiled multiple times in BFD
974
Several files in BFD are compiled multiple times. By this I mean that
975
there are header files which contain function definitions. These header
976
files are included by other files, and thus the functions are compiled
977
once per file which includes them.
979
Preprocessor macros are used to control the compilation, so that each
980
time the files are compiled the resulting functions are slightly
981
different. Naturally, if they weren't different, there would be no
982
reason to compile them multiple times.
984
This is a not a particularly good programming technique, and future BFD
985
work should avoid it.
989
Since this technique is rarely used, even experienced C programmers find
993
It is difficult to debug programs which use BFD, since there is no way
994
to describe which version of a particular function you are looking at.
997
Programs which use BFD wind up incorporating two or more slightly
998
different versions of the same function, which wastes space in the
1002
This technique is never required nor is it especially efficient. It is
1003
always possible to use statically initialized structures holding
1004
function pointers and magic constants instead.
1007
The following is a list of the files which are compiled multiple times.
1011
@cindex @file{aout-target.h}
1012
Describes a few functions and the target vector for a.out targets. This
1013
is used by individual a.out targets with different definitions of
1014
@samp{N_TXTADDR} and similar a.out macros.
1017
@cindex @file{aoutf1.h}
1018
Implements standard SunOS a.out files. In principle it supports 64 bit
1019
a.out targets based on the preprocessor macro @samp{ARCH_SIZE}, but
1020
since all known a.out targets are 32 bits, this code may or may not
1021
work. This file is only included by a few other files, and it is
1022
difficult to justify its existence.
1025
@cindex @file{aoutx.h}
1026
Implements basic a.out support routines. This file can be compiled for
1027
either 32 or 64 bit support. Since all known a.out targets are 32 bits,
1028
the 64 bit support may or may not work. I believe the original
1029
intention was that this file would only be included by @samp{aout32.c}
1030
and @samp{aout64.c}, and that other a.out targets would simply refer to
1031
the functions it defined. Unfortunately, some other a.out targets
1032
started including it directly, leading to a somewhat confused state of
1036
@cindex @file{coffcode.h}
1037
Implements basic COFF support routines. This file is included by every
1038
COFF target. It implements code which handles COFF magic numbers as
1039
well as various hook functions called by the generic COFF functions in
1040
@file{coffgen.c}. This file is controlled by a number of different
1041
macros, and more are added regularly.
1044
@cindex @file{coffswap.h}
1045
Implements COFF swapping routines. This file is included by
1046
@file{coffcode.h}, and thus by every COFF target. It implements the
1047
routines which swap COFF structures between internal and external
1048
format. The main control for this file is the external structure
1049
definitions in the files in the @file{include/coff} directory. A COFF
1050
target file will include one of those files before including
1051
@file{coffcode.h} and thus @file{coffswap.h}. There are a few other
1052
macros which affect @file{coffswap.h} as well, mostly describing whether
1053
certain fields are present in the external structures.
1056
@cindex @file{ecoffswap.h}
1057
Implements ECOFF swapping routines. This is like @file{coffswap.h}, but
1058
for ECOFF. It is included by the ECOFF target files (of which there are
1059
only two). The control is the preprocessor macro @samp{ECOFF_32} or
1063
@cindex @file{elfcode.h}
1064
Implements ELF functions that use external structure definitions. This
1065
file is included by two other files: @file{elf32.c} and @file{elf64.c}.
1066
It is controlled by the @samp{ARCH_SIZE} macro which is defined to be
1067
@samp{32} or @samp{64} before including it. The @samp{NAME} macro is
1068
used internally to give the functions different names for the two target
1072
@cindex @file{elfcore.h}
1073
Like @file{elfcode.h}, but for functions that are specific to ELF core
1074
files. This is included only by @file{elfcode.h}.
1076
@item elfxx-target.h
1077
@cindex @file{elfxx-target.h}
1078
This file is the source for the generated files @file{elf32-target.h}
1079
and @file{elf64-target.h}, one of which is included by every ELF target.
1080
It defines the ELF target vector.
1083
@cindex @file{freebsd.h}
1084
Presumably intended to be included by all FreeBSD targets, but in fact
1085
there is only one such target, @samp{i386-freebsd}. This defines a
1086
function used to set the right magic number for FreeBSD, as well as
1087
various macros, and includes @file{aout-target.h}.
1090
@cindex @file{netbsd.h}
1091
Like @file{freebsd.h}, except that there are several files which include
1095
@cindex @file{nlm-target.h}
1096
Defines the target vector for a standard NLM target.
1099
@cindex @file{nlmcode.h}
1100
Like @file{elfcode.h}, but for NLM targets. This is only included by
1101
@file{nlm32.c} and @file{nlm64.c}, both of which define the macro
1102
@samp{ARCH_SIZE} to an appropriate value. There are no 64 bit NLM
1103
targets anyhow, so this is sort of useless.
1106
@cindex @file{nlmswap.h}
1107
Like @file{coffswap.h}, but for NLM targets. This is included by each
1108
NLM target, but I think it winds up compiling to the exact same code for
1109
every target, and as such is fairly useless.
1112
@cindex @file{peicode.h}
1113
Provides swapping routines and other hooks for PE targets.
1114
@file{coffcode.h} will include this rather than @file{coffswap.h} for a
1115
PE target. This defines PE specific versions of the COFF swapping
1116
routines, and also defines some macros which control @file{coffcode.h}
1120
@node BFD relocation handling
1121
@section BFD relocation handling
1122
@cindex bfd relocation handling
1123
@cindex relocations in bfd
1125
The handling of relocations is one of the more confusing aspects of BFD.
1126
Relocation handling has been implemented in various different ways, all
1127
somewhat incompatible, none perfect.
1130
* BFD relocation concepts:: BFD relocation concepts
1131
* BFD relocation functions:: BFD relocation functions
1132
* BFD relocation codes:: BFD relocation codes
1133
* BFD relocation future:: BFD relocation future
1136
@node BFD relocation concepts
1137
@subsection BFD relocation concepts
1139
A relocation is an action which the linker must take when linking. It
1140
describes a change to the contents of a section. The change is normally
1141
based on the final value of one or more symbols. Relocations are
1142
created by the assembler when it creates an object file.
1144
Most relocations are simple. A typical simple relocation is to set 32
1145
bits at a given offset in a section to the value of a symbol. This type
1146
of relocation would be generated for code like @code{int *p = &i;} where
1147
@samp{p} and @samp{i} are global variables. A relocation for the symbol
1148
@samp{i} would be generated such that the linker would initialize the
1149
area of memory which holds the value of @samp{p} to the value of the
1152
Slightly more complex relocations may include an addend, which is a
1153
constant to add to the symbol value before using it. In some cases a
1154
relocation will require adding the symbol value to the existing contents
1155
of the section in the object file. In others the relocation will simply
1156
replace the contents of the section with the symbol value. Some
1157
relocations are PC relative, so that the value to be stored in the
1158
section is the difference between the value of a symbol and the final
1159
address of the section contents.
1161
In general, relocations can be arbitrarily complex. For example,
1162
relocations used in dynamic linking systems often require the linker to
1163
allocate space in a different section and use the offset within that
1164
section as the value to store. In the IEEE object file format,
1165
relocations may involve arbitrary expressions.
1167
When doing a relocatable link, the linker may or may not have to do
1168
anything with a relocation, depending upon the definition of the
1169
relocation. Simple relocations generally do not require any special
1172
@node BFD relocation functions
1173
@subsection BFD relocation functions
1175
In BFD, each section has an array of @samp{arelent} structures. Each
1176
structure has a pointer to a symbol, an address within the section, an
1177
addend, and a pointer to a @samp{reloc_howto_struct} structure. The
1178
howto structure has a bunch of fields describing the reloc, including a
1179
type field. The type field is specific to the object file format
1180
backend; none of the generic code in BFD examines it.
1182
Originally, the function @samp{bfd_perform_relocation} was supposed to
1183
handle all relocations. In theory, many relocations would be simple
1184
enough to be described by the fields in the howto structure. For those
1185
that weren't, the howto structure included a @samp{special_function}
1186
field to use as an escape.
1188
While this seems plausible, a look at @samp{bfd_perform_relocation}
1189
shows that it failed. The function has odd special cases. Some of the
1190
fields in the howto structure, such as @samp{pcrel_offset}, were not
1191
adequately documented.
1193
The linker uses @samp{bfd_perform_relocation} to do all relocations when
1194
the input and output file have different formats (e.g., when generating
1195
S-records). The generic linker code, which is used by all targets which
1196
do not define their own special purpose linker, uses
1197
@samp{bfd_get_relocated_section_contents}, which for most targets turns
1198
into a call to @samp{bfd_generic_get_relocated_section_contents}, which
1199
calls @samp{bfd_perform_relocation}. So @samp{bfd_perform_relocation}
1200
is still widely used, which makes it difficult to change, since it is
1201
difficult to test all possible cases.
1203
The assembler used @samp{bfd_perform_relocation} for a while. This
1204
turned out to be the wrong thing to do, since
1205
@samp{bfd_perform_relocation} was written to handle relocations on an
1206
existing object file, while the assembler needed to create relocations
1207
in a new object file. The assembler was changed to use the new function
1208
@samp{bfd_install_relocation} instead, and @samp{bfd_install_relocation}
1209
was created as a copy of @samp{bfd_perform_relocation}.
1211
Unfortunately, the work did not progress any farther, so
1212
@samp{bfd_install_relocation} remains a simple copy of
1213
@samp{bfd_perform_relocation}, with all the odd special cases and
1214
confusing code. This again is difficult to change, because again any
1215
change can affect any assembler target, and so is difficult to test.
1217
The new linker, when using the same object file format for all input
1218
files and the output file, does not convert relocations into
1219
@samp{arelent} structures, so it can not use
1220
@samp{bfd_perform_relocation} at all. Instead, users of the new linker
1221
are expected to write a @samp{relocate_section} function which will
1222
handle relocations in a target specific fashion.
1224
There are two helper functions for target specific relocation:
1225
@samp{_bfd_final_link_relocate} and @samp{_bfd_relocate_contents}.
1226
These functions use a howto structure, but they @emph{do not} use the
1227
@samp{special_function} field. Since the functions are normally called
1228
from target specific code, the @samp{special_function} field adds
1229
little; any relocations which require special handling can be handled
1230
without calling those functions.
1232
So, if you want to add a new target, or add a new relocation to an
1233
existing target, you need to do the following:
1237
Make sure you clearly understand what the contents of the section should
1238
look like after assembly, after a relocatable link, and after a final
1239
link. Make sure you clearly understand the operations the linker must
1240
perform during a relocatable link and during a final link.
1243
Write a howto structure for the relocation. The howto structure is
1244
flexible enough to represent any relocation which should be handled by
1245
setting a contiguous bitfield in the destination to the value of a
1246
symbol, possibly with an addend, possibly adding the symbol value to the
1247
value already present in the destination.
1250
Change the assembler to generate your relocation. The assembler will
1251
call @samp{bfd_install_relocation}, so your howto structure has to be
1252
able to handle that. You may need to set the @samp{special_function}
1253
field to handle assembly correctly. Be careful to ensure that any code
1254
you write to handle the assembler will also work correctly when doing a
1255
relocatable link. For example, see @samp{bfd_elf_generic_reloc}.
1258
Test the assembler. Consider the cases of relocation against an
1259
undefined symbol, a common symbol, a symbol defined in the object file
1260
in the same section, and a symbol defined in the object file in a
1261
different section. These cases may not all be applicable for your
1265
If your target uses the new linker, which is recommended, add any
1266
required handling to the target specific relocation function. In simple
1267
cases this will just involve a call to @samp{_bfd_final_link_relocate}
1268
or @samp{_bfd_relocate_contents}, depending upon the definition of the
1269
relocation and whether the link is relocatable or not.
1272
Test the linker. Test the case of a final link. If the relocation can
1273
overflow, use a linker script to force an overflow and make sure the
1274
error is reported correctly. Test a relocatable link, whether the
1275
symbol is defined or undefined in the relocatable output. For both the
1276
final and relocatable link, test the case when the symbol is a common
1277
symbol, when the symbol looked like a common symbol but became a defined
1278
symbol, when the symbol is defined in a different object file, and when
1279
the symbol is defined in the same object file.
1282
In order for linking to another object file format, such as S-records,
1283
to work correctly, @samp{bfd_perform_relocation} has to do the right
1284
thing for the relocation. You may need to set the
1285
@samp{special_function} field to handle this correctly. Test this by
1286
doing a link in which the output object file format is S-records.
1289
Using the linker to generate relocatable output in a different object
1290
file format is impossible in the general case, so you generally don't
1291
have to worry about that. The GNU linker makes sure to stop that from
1292
happening when an input file in a different format has relocations.
1294
Linking input files of different object file formats together is quite
1295
unusual, but if you're really dedicated you may want to consider testing
1296
this case, both when the output object file format is the same as your
1297
format, and when it is different.
1300
@node BFD relocation codes
1301
@subsection BFD relocation codes
1303
BFD has another way of describing relocations besides the howto
1304
structures described above: the enum @samp{bfd_reloc_code_real_type}.
1306
Every known relocation type can be described as a value in this
1307
enumeration. The enumeration contains many target specific relocations,
1308
but where two or more targets have the same relocation, a single code is
1309
used. For example, the single value @samp{BFD_RELOC_32} is used for all
1310
simple 32 bit relocation types.
1312
The main purpose of this relocation code is to give the assembler some
1313
mechanism to create @samp{arelent} structures. In order for the
1314
assembler to create an @samp{arelent} structure, it has to be able to
1315
obtain a howto structure. The function @samp{bfd_reloc_type_lookup},
1316
which simply calls the target vector entry point
1317
@samp{reloc_type_lookup}, takes a relocation code and returns a howto
1320
The function @samp{bfd_get_reloc_code_name} returns the name of a
1321
relocation code. This is mainly used in error messages.
1323
Using both howto structures and relocation codes can be somewhat
1324
confusing. There are many processor specific relocation codes.
1325
However, the relocation is only fully defined by the howto structure.
1326
The same relocation code will map to different howto structures in
1327
different object file formats. For example, the addend handling may be
1330
Most of the relocation codes are not really general. The assembler can
1331
not use them without already understanding what sorts of relocations can
1332
be used for a particular target. It might be possible to replace the
1333
relocation codes with something simpler.
1335
@node BFD relocation future
1336
@subsection BFD relocation future
1338
Clearly the current BFD relocation support is in bad shape. A
1339
wholescale rewrite would be very difficult, because it would require
1340
thorough testing of every BFD target. So some sort of incremental
1343
My vague thoughts on this would involve defining a new, clearly defined,
1344
howto structure. Some mechanism would be used to determine which type
1345
of howto structure was being used by a particular format.
1347
The new howto structure would clearly define the relocation behaviour in
1348
the case of an assembly, a relocatable link, and a final link. At
1349
least one special function would be defined as an escape, and it might
1350
make sense to define more.
1352
One or more generic functions similar to @samp{bfd_perform_relocation}
1353
would be written to handle the new howto structure.
1355
This should make it possible to write a generic version of the relocate
1356
section functions used by the new linker. The target specific code
1357
would provide some mechanism (a function pointer or an initial
1358
conversion) to convert target specific relocations into howto
1361
Ideally it would be possible to use this generic relocate section
1362
function for the generic linker as well. That is, it would replace the
1363
@samp{bfd_generic_get_relocated_section_contents} function which is
1364
currently normally used.
1366
For the special case of ELF dynamic linking, more consideration needs to
1367
be given to writing ELF specific but ELF target generic code to handle
1368
special relocation types such as GOT and PLT.
1370
@node BFD ELF support
1371
@section BFD ELF support
1372
@cindex elf support in bfd
1373
@cindex bfd elf support
1375
The ELF object file format is defined in two parts: a generic ABI and a
1376
processor specific supplement. The ELF support in BFD is split in a
1377
similar fashion. The processor specific support is largely kept within
1378
a single file. The generic support is provided by several other files.
1379
The processor specific support provides a set of function pointers and
1380
constants used by the generic support.
1383
* BFD ELF sections and segments:: ELF sections and segments
1384
* BFD ELF generic support:: BFD ELF generic support
1385
* BFD ELF processor specific support:: BFD ELF processor specific support
1386
* BFD ELF core files:: BFD ELF core files
1387
* BFD ELF future:: BFD ELF future
1390
@node BFD ELF sections and segments
1391
@subsection ELF sections and segments
1393
The ELF ABI permits a file to have either sections or segments or both.
1394
Relocatable object files conventionally have only sections.
1395
Executables conventionally have both. Core files conventionally have
1396
only program segments.
1398
ELF sections are similar to sections in other object file formats: they
1399
have a name, a VMA, file contents, flags, and other miscellaneous
1400
information. ELF relocations are stored in sections of a particular
1401
type; BFD automatically converts these sections into internal relocation
1404
ELF program segments are intended for fast interpretation by a system
1405
loader. They have a type, a VMA, an LMA, file contents, and a couple of
1406
other fields. When an ELF executable is run on a Unix system, the
1407
system loader will examine the program segments to decide how to load
1408
it. The loader will ignore the section information. Loadable program
1409
segments (type @samp{PT_LOAD}) are directly loaded into memory. Other
1410
program segments are interpreted by the loader, and generally provide
1411
dynamic linking information.
1413
When an ELF file has both program segments and sections, an ELF program
1414
segment may encompass one or more ELF sections, in the sense that the
1415
portion of the file which corresponds to the program segment may include
1416
the portions of the file corresponding to one or more sections. When
1417
there is more than one section in a loadable program segment, the
1418
relative positions of the section contents in the file must correspond
1419
to the relative positions they should hold when the program segment is
1420
loaded. This requirement should be obvious if you consider that the
1421
system loader will load an entire program segment at a time.
1423
On a system which supports dynamic paging, such as any native Unix
1424
system, the contents of a loadable program segment must be at the same
1425
offset in the file as in memory, modulo the memory page size used on the
1426
system. This is because the system loader will map the file into memory
1427
starting at the start of a page. The system loader can easily remap
1428
entire pages to the correct load address. However, if the contents of
1429
the file were not correctly aligned within the page, the system loader
1430
would have to shift the contents around within the page, which is too
1431
expensive. For example, if the LMA of a loadable program segment is
1432
@samp{0x40080} and the page size is @samp{0x1000}, then the position of
1433
the segment contents within the file must equal @samp{0x80} modulo
1436
BFD has only a single set of sections. It does not provide any generic
1437
way to examine both sections and segments. When BFD is used to open an
1438
object file or executable, the BFD sections will represent ELF sections.
1439
When BFD is used to open a core file, the BFD sections will represent
1440
ELF program segments.
1442
When BFD is used to examine an object file or executable, any program
1443
segments will be read to set the LMA of the sections. This is because
1444
ELF sections only have a VMA, while ELF program segments have both a VMA
1445
and an LMA. Any program segments will be copied by the
1446
@samp{copy_private} entry points. They will be printed by the
1447
@samp{print_private} entry point. Otherwise, the program segments are
1448
ignored. In particular, programs which use BFD currently have no direct
1449
access to the program segments.
1451
When BFD is used to create an executable, the program segments will be
1452
created automatically based on the section information. This is done in
1453
the function @samp{assign_file_positions_for_segments} in @file{elf.c}.
1454
This function has been tweaked many times, and probably still has
1455
problems that arise in particular cases.
1457
There is a hook which may be used to explicitly define the program
1458
segments when creating an executable: the @samp{bfd_record_phdr}
1459
function in @file{bfd.c}. If this function is called, BFD will not
1460
create program segments itself, but will only create the program
1461
segments specified by the caller. The linker uses this function to
1462
implement the @samp{PHDRS} linker script command.
1464
@node BFD ELF generic support
1465
@subsection BFD ELF generic support
1467
In general, functions which do not read external data from the ELF file
1468
are found in @file{elf.c}. They operate on the internal forms of the
1469
ELF structures, which are defined in @file{include/elf/internal.h}. The
1470
internal structures are defined in terms of @samp{bfd_vma}, and so may
1471
be used for both 32 bit and 64 bit ELF targets.
1473
The file @file{elfcode.h} contains functions which operate on the
1474
external data. @file{elfcode.h} is compiled twice, once via
1475
@file{elf32.c} with @samp{ARCH_SIZE} defined as @samp{32}, and once via
1476
@file{elf64.c} with @samp{ARCH_SIZE} defined as @samp{64}.
1477
@file{elfcode.h} includes functions to swap the ELF structures in and
1478
out of external form, as well as a few more complex functions.
1480
Linker support is found in @file{elflink.c}. The
1481
linker support is only used if the processor specific file defines
1482
@samp{elf_backend_relocate_section}, which is required to relocate the
1483
section contents. If that macro is not defined, the generic linker code
1484
is used, and relocations are handled via @samp{bfd_perform_relocation}.
1486
The core file support is in @file{elfcore.h}, which is compiled twice,
1487
for both 32 and 64 bit support. The more interesting cases of core file
1488
support only work on a native system which has the @file{sys/procfs.h}
1489
header file. Without that file, the core file support does little more
1490
than read the ELF program segments as BFD sections.
1492
The BFD internal header file @file{elf-bfd.h} is used for communication
1493
among these files and the processor specific files.
1495
The default entries for the BFD ELF target vector are found mainly in
1496
@file{elf.c}. Some functions are found in @file{elfcode.h}.
1498
The processor specific files may override particular entries in the
1499
target vector, but most do not, with one exception: the
1500
@samp{bfd_reloc_type_lookup} entry point is always processor specific.
1502
@node BFD ELF processor specific support
1503
@subsection BFD ELF processor specific support
1505
By convention, the processor specific support for a particular processor
1506
will be found in @file{elf@var{nn}-@var{cpu}.c}, where @var{nn} is
1507
either 32 or 64, and @var{cpu} is the name of the processor.
1510
* BFD ELF processor required:: Required processor specific support
1511
* BFD ELF processor linker:: Processor specific linker support
1512
* BFD ELF processor other:: Other processor specific support options
1515
@node BFD ELF processor required
1516
@subsubsection Required processor specific support
1518
When writing a @file{elf@var{nn}-@var{cpu}.c} file, you must do the
1523
Define either @samp{TARGET_BIG_SYM} or @samp{TARGET_LITTLE_SYM}, or
1524
both, to a unique C name to use for the target vector. This name should
1525
appear in the list of target vectors in @file{targets.c}, and will also
1526
have to appear in @file{config.bfd} and @file{configure.in}. Define
1527
@samp{TARGET_BIG_SYM} for a big-endian processor,
1528
@samp{TARGET_LITTLE_SYM} for a little-endian processor, and define both
1529
for a bi-endian processor.
1531
Define either @samp{TARGET_BIG_NAME} or @samp{TARGET_LITTLE_NAME}, or
1532
both, to a string used as the name of the target vector. This is the
1533
name which a user of the BFD tool would use to specify the object file
1534
format. It would normally appear in a linker emulation parameters
1537
Define @samp{ELF_ARCH} to the BFD architecture (an element of the
1538
@samp{bfd_architecture} enum, typically @samp{bfd_arch_@var{cpu}}).
1540
Define @samp{ELF_MACHINE_CODE} to the magic number which should appear
1541
in the @samp{e_machine} field of the ELF header. As of this writing,
1542
these magic numbers are assigned by Caldera; if you want to get a magic
1543
number for a particular processor, try sending a note to
1544
@email{registry@@caldera.com}. In the BFD sources, the magic numbers are
1545
found in @file{include/elf/common.h}; they have names beginning with
1548
Define @samp{ELF_MAXPAGESIZE} to the maximum size of a virtual page in
1549
memory. This can normally be found at the start of chapter 5 in the
1550
processor specific supplement. For a processor which will only be used
1551
in an embedded system, or which has no memory management hardware, this
1552
can simply be @samp{1}.
1554
If the format should use @samp{Rel} rather than @samp{Rela} relocations,
1555
define @samp{USE_REL}. This is normally defined in chapter 4 of the
1556
processor specific supplement.
1558
In the absence of a supplement, it's easier to work with @samp{Rela}
1559
relocations. @samp{Rela} relocations will require more space in object
1560
files (but not in executables, except when using dynamic linking).
1561
However, this is outweighed by the simplicity of addend handling when
1562
using @samp{Rela} relocations. With @samp{Rel} relocations, the addend
1563
must be stored in the section contents, which makes relocatable links
1566
For example, consider C code like @code{i = a[1000];} where @samp{a} is
1567
a global array. The instructions which load the value of @samp{a[1000]}
1568
will most likely use a relocation which refers to the symbol
1569
representing @samp{a}, with an addend that gives the offset from the
1570
start of @samp{a} to element @samp{1000}. When using @samp{Rel}
1571
relocations, that addend must be stored in the instructions themselves.
1572
If you are adding support for a RISC chip which uses two or more
1573
instructions to load an address, then the addend may not fit in a single
1574
instruction, and will have to be somehow split among the instructions.
1575
This makes linking awkward, particularly when doing a relocatable link
1576
in which the addend may have to be updated. It can be done---the MIPS
1577
ELF support does it---but it should be avoided when possible.
1579
It is possible, though somewhat awkward, to support both @samp{Rel} and
1580
@samp{Rela} relocations for a single target; @file{elf64-mips.c} does it
1581
by overriding the relocation reading and writing routines.
1583
Define howto structures for all the relocation types.
1585
Define a @samp{bfd_reloc_type_lookup} routine. This must be named
1586
@samp{bfd_elf@var{nn}_bfd_reloc_type_lookup}, and may be either a
1587
function or a macro. It must translate a BFD relocation code into a
1588
howto structure. This is normally a table lookup or a simple switch.
1590
If using @samp{Rel} relocations, define @samp{elf_info_to_howto_rel}.
1591
If using @samp{Rela} relocations, define @samp{elf_info_to_howto}.
1592
Either way, this is a macro defined as the name of a function which
1593
takes an @samp{arelent} and a @samp{Rel} or @samp{Rela} structure, and
1594
sets the @samp{howto} field of the @samp{arelent} based on the
1595
@samp{Rel} or @samp{Rela} structure. This is normally uses
1596
@samp{ELF@var{nn}_R_TYPE} to get the ELF relocation type and uses it as
1597
an index into a table of howto structures.
1600
You must also add the magic number for this processor to the
1601
@samp{prep_headers} function in @file{elf.c}.
1603
You must also create a header file in the @file{include/elf} directory
1604
called @file{@var{cpu}.h}. This file should define any target specific
1605
information which may be needed outside of the BFD code. In particular
1606
it should use the @samp{START_RELOC_NUMBERS}, @samp{RELOC_NUMBER},
1607
@samp{FAKE_RELOC}, @samp{EMPTY_RELOC} and @samp{END_RELOC_NUMBERS}
1608
macros to create a table mapping the number used to identify a
1609
relocation to a name describing that relocation.
1611
While not a BFD component, you probably also want to make the binutils
1612
program @samp{readelf} parse your ELF objects. For this, you need to add
1613
code for @code{EM_@var{cpu}} as appropriate in @file{binutils/readelf.c}.
1615
@node BFD ELF processor linker
1616
@subsubsection Processor specific linker support
1618
The linker will be much more efficient if you define a relocate section
1619
function. This will permit BFD to use the ELF specific linker support.
1621
If you do not define a relocate section function, BFD must use the
1622
generic linker support, which requires converting all symbols and
1623
relocations into BFD @samp{asymbol} and @samp{arelent} structures. In
1624
this case, relocations will be handled by calling
1625
@samp{bfd_perform_relocation}, which will use the howto structures you
1626
have defined. @xref{BFD relocation handling}.
1628
In order to support linking into a different object file format, such as
1629
S-records, @samp{bfd_perform_relocation} must work correctly with your
1630
howto structures, so you can't skip that step. However, if you define
1631
the relocate section function, then in the normal case of linking into
1632
an ELF file the linker will not need to convert symbols and relocations,
1633
and will be much more efficient.
1635
To use a relocation section function, define the macro
1636
@samp{elf_backend_relocate_section} as the name of a function which will
1637
take the contents of a section, as well as relocation, symbol, and other
1638
information, and modify the section contents according to the relocation
1639
information. In simple cases, this is little more than a loop over the
1640
relocations which computes the value of each relocation and calls
1641
@samp{_bfd_final_link_relocate}. The function must check for a
1642
relocatable link, and in that case normally needs to do nothing other
1643
than adjust the addend for relocations against a section symbol.
1645
The complex cases generally have to do with dynamic linker support. GOT
1646
and PLT relocations must be handled specially, and the linker normally
1647
arranges to set up the GOT and PLT sections while handling relocations.
1648
When generating a shared library, random relocations must normally be
1649
copied into the shared library, or converted to RELATIVE relocations
1652
@node BFD ELF processor other
1653
@subsubsection Other processor specific support options
1655
There are many other macros which may be defined in
1656
@file{elf@var{nn}-@var{cpu}.c}. These macros may be found in
1657
@file{elfxx-target.h}.
1659
Macros may be used to override some of the generic ELF target vector
1662
Several processor specific hook functions which may be defined as
1663
macros. These functions are found as function pointers in the
1664
@samp{elf_backend_data} structure defined in @file{elf-bfd.h}. In
1665
general, a hook function is set by defining a macro
1666
@samp{elf_backend_@var{name}}.
1668
There are a few processor specific constants which may also be defined.
1669
These are again found in the @samp{elf_backend_data} structure.
1671
I will not define the various functions and constants here; see the
1672
comments in @file{elf-bfd.h}.
1674
Normally any odd characteristic of a particular ELF processor is handled
1675
via a hook function. For example, the special @samp{SHN_MIPS_SCOMMON}
1676
section number found in MIPS ELF is handled via the hooks
1677
@samp{section_from_bfd_section}, @samp{symbol_processing},
1678
@samp{add_symbol_hook}, and @samp{output_symbol_hook}.
1680
Dynamic linking support, which involves processor specific relocations
1681
requiring special handling, is also implemented via hook functions.
1683
@node BFD ELF core files
1684
@subsection BFD ELF core files
1685
@cindex elf core files
1687
On native ELF Unix systems, core files are generated without any
1688
sections. Instead, they only have program segments.
1690
When BFD is used to read an ELF core file, the BFD sections will
1691
actually represent program segments. Since ELF program segments do not
1692
have names, BFD will invent names like @samp{segment@var{n}} where
1693
@var{n} is a number.
1695
A single ELF program segment may include both an initialized part and an
1696
uninitialized part. The size of the initialized part is given by the
1697
@samp{p_filesz} field. The total size of the segment is given by the
1698
@samp{p_memsz} field. If @samp{p_memsz} is larger than @samp{p_filesz},
1699
then the extra space is uninitialized, or, more precisely, initialized
1702
BFD will represent such a program segment as two different sections.
1703
The first, named @samp{segment@var{n}a}, will represent the initialized
1704
part of the program segment. The second, named @samp{segment@var{n}b},
1705
will represent the uninitialized part.
1707
ELF core files store special information such as register values in
1708
program segments with the type @samp{PT_NOTE}. BFD will attempt to
1709
interpret the information in these segments, and will create additional
1710
sections holding the information. Some of this interpretation requires
1711
information found in the host header file @file{sys/procfs.h}, and so
1712
will only work when BFD is built on a native system.
1714
BFD does not currently provide any way to create an ELF core file. In
1715
general, BFD does not provide a way to create core files. The way to
1716
implement this would be to write @samp{bfd_set_format} and
1717
@samp{bfd_write_contents} routines for the @samp{bfd_core} type; see
1718
@ref{BFD target vector format}.
1720
@node BFD ELF future
1721
@subsection BFD ELF future
1723
The current dynamic linking support has too much code duplication.
1724
While each processor has particular differences, much of the dynamic
1725
linking support is quite similar for each processor. The GOT and PLT
1726
are handled in fairly similar ways, the details of -Bsymbolic linking
1727
are generally similar, etc. This code should be reworked to use more
1728
generic functions, eliminating the duplication.
1730
Similarly, the relocation handling has too much duplication. Many of
1731
the @samp{reloc_type_lookup} and @samp{info_to_howto} functions are
1732
quite similar. The relocate section functions are also often quite
1733
similar, both in the standard linker handling and the dynamic linker
1734
handling. Many of the COFF processor specific backends share a single
1735
relocate section function (@samp{_bfd_coff_generic_relocate_section}),
1736
and it should be possible to do something like this for the ELF targets
1739
The appearance of the processor specific magic number in
1740
@samp{prep_headers} in @file{elf.c} is somewhat bogus. It should be
1741
possible to add support for a new processor without changing the generic
1744
The processor function hooks and constants are ad hoc and need better
1748
@section BFD glossary
1749
@cindex glossary for bfd
1750
@cindex bfd glossary
1752
This is a short glossary of some BFD terms.
1756
The a.out object file format. The original Unix object file format.
1757
Still used on SunOS, though not Solaris. Supports only three sections.
1760
A collection of object files produced and manipulated by the @samp{ar}
1764
The implementation within BFD of a particular object file format. The
1765
set of functions which appear in a particular target vector.
1768
The BFD library itself. Also, each object file, archive, or executable
1769
opened by the BFD library has the type @samp{bfd *}, and is sometimes
1770
referred to as a bfd.
1773
The Common Object File Format. Used on Unix SVR3. Used by some
1774
embedded targets, although ELF is normally better.
1777
A shared library on Windows.
1779
@item dynamic linker
1780
When a program linked against a shared library is run, the dynamic
1781
linker will locate the appropriate shared library and arrange to somehow
1782
include it in the running image.
1784
@item dynamic object
1785
Another name for an ELF shared library.
1788
The Extended Common Object File Format. Used on Alpha Digital Unix
1789
(formerly OSF/1), as well as Ultrix and Irix 4. A variant of COFF.
1792
The Executable and Linking Format. The object file format used on most
1793
modern Unix systems, including GNU/Linux, Solaris, Irix, and SVR4. Also
1794
used on many embedded systems.
1797
A program, with instructions and symbols, and perhaps dynamic linking
1798
information. Normally produced by a linker.
1801
Load Memory Address. This is the address at which a section will be
1802
loaded. Compare with VMA, below.
1805
NetWare Loadable Module. Used to describe the format of an object which
1806
be loaded into NetWare, which is some kind of PC based network server
1810
A binary file including machine instructions, symbols, and relocation
1811
information. Normally produced by an assembler.
1813
@item object file format
1814
The format of an object file. Typically object files and executables
1815
for a particular system are in the same format, although executables
1816
will not contain any relocation information.
1819
The Portable Executable format. This is the object file format used for
1820
Windows (specifically, Win32) object files. It is based closely on
1821
COFF, but has a few significant differences.
1824
The Portable Executable Image format. This is the object file format
1825
used for Windows (specifically, Win32) executables. It is very similar
1826
to PE, but includes some additional header information.
1829
Information used by the linker to adjust section contents. Also called
1833
Object files and executable are composed of sections. Sections have
1834
optional data and optional relocation information.
1836
@item shared library
1837
A library of functions which may be used by many executables without
1838
actually being linked into each executable. There are several different
1839
implementations of shared libraries, each having slightly different
1843
Each object file and executable may have a list of symbols, often
1844
referred to as the symbol table. A symbol is basically a name and an
1845
address. There may also be some additional information like the type of
1846
symbol, although the type of a symbol is normally something simple like
1847
function or object, and should be confused with the more complex C
1848
notion of type. Typically every global function and variable in a C
1849
program will have an associated symbol.
1852
A set of functions which implement support for a particular object file
1853
format. The @samp{bfd_target} structure.
1856
The current Windows API, implemented by Windows 95 and later and Windows
1857
NT 3.51 and later, but not by Windows 3.1.
1860
The eXtended Common Object File Format. Used on AIX. A variant of
1861
COFF, with a completely different symbol table implementation.
1864
Virtual Memory Address. This is the address a section will have when
1865
an executable is run. Compare with LMA, above.
1869
@unnumberedsec Index
added
removed
bfd/doc/bfdint.texi
