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}
17 This file documents the internals of the BFD library.
19 Copyright 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998,
20 2000, 2001, 2002, 2003, 2004, 2006
21 Free Software Foundation, Inc.
22 Contributed by Cygnus Support.
24 Permission is granted to copy, distribute and/or modify this document
25 under the terms of the GNU Free Documentation License, Version 1.1
26 or any later version published by the Free Software Foundation;
27 with no Invariant Sections, with no Front-Cover Texts, and with no
28 Back-Cover Texts. A copy of the license is included in the
29 section entitled "GNU Free Documentation License".
32 Permission is granted to process this file through Tex and print the
33 results, provided the printed document carries copying permission
34 notice identical to this one except for the removal of this paragraph
35 (this paragraph not being relevant to the printed manual).
45 This document describes some BFD internal information which may be
46 helpful when working on BFD. It is very incomplete.
48 This document is not updated regularly, and may be out of date.
50 The initial version of this document was written by Ian Lance Taylor
51 @email{ian@@cygnus.com}.
54 * BFD overview:: BFD overview
55 * BFD guidelines:: BFD programming guidelines
56 * BFD target vector:: BFD target vector
57 * BFD generated files:: BFD generated files
58 * BFD multiple compilations:: Files compiled multiple times in BFD
59 * BFD relocation handling:: BFD relocation handling
60 * BFD ELF support:: BFD ELF support
61 * BFD glossary:: Glossary
68 BFD is a library which provides a single interface to read and write
69 object files, executables, archive files, and core files in any format.
72 * BFD library interfaces:: BFD library interfaces
73 * BFD library users:: BFD library users
74 * BFD view:: The BFD view of a file
75 * BFD blindness:: BFD loses information
78 @node BFD library interfaces
79 @subsection BFD library interfaces
81 One way to look at the BFD library is to divide it into four parts by
84 The first interface is the set of generic functions which programs using
85 the BFD library will call. These generic function normally translate
86 directly or indirectly into calls to routines which are specific to a
87 particular object file format. Many of these generic functions are
88 actually defined as macros in @file{bfd.h}. These functions comprise
89 the official BFD interface.
91 The second interface is the set of functions which appear in the target
92 vectors. This is the bulk of the code in BFD. A target vector is a set
93 of function pointers specific to a particular object file format. The
94 target vector is used to implement the generic BFD functions. These
95 functions are always called through the target vector, and are never
96 called directly. The target vector is described in detail in @ref{BFD
97 target vector}. The set of functions which appear in a particular
98 target vector is often referred to as a BFD backend.
100 The third interface is a set of oddball functions which are typically
101 specific to a particular object file format, are not generic functions,
102 and are called from outside of the BFD library. These are used as hooks
103 by the linker and the assembler when a particular object file format
104 requires some action which the BFD generic interface does not provide.
105 These functions are typically declared in @file{bfd.h}, but in many
106 cases they are only provided when BFD is configured with support for a
107 particular object file format. These functions live in a grey area, and
108 are not really part of the official BFD interface.
110 The fourth interface is the set of BFD support functions which are
111 called by the other BFD functions. These manage issues like memory
112 allocation, error handling, file access, hash tables, swapping, and the
113 like. These functions are never called from outside of the BFD library.
115 @node BFD library users
116 @subsection BFD library users
118 Another way to look at the BFD library is to divide it into three parts
119 by the manner in which it is used.
121 The first use is to read an object file. The object file readers are
122 programs like @samp{gdb}, @samp{nm}, @samp{objdump}, and @samp{objcopy}.
123 These programs use BFD to view an object file in a generic form. The
124 official BFD interface is normally fully adequate for these programs.
126 The second use is to write an object file. The object file writers are
127 programs like @samp{gas} and @samp{objcopy}. These programs use BFD to
128 create an object file. The official BFD interface is normally adequate
129 for these programs, but for some object file formats the assembler needs
130 some additional hooks in order to set particular flags or other
131 information. The official BFD interface includes functions to copy
132 private information from one object file to another, and these functions
133 are used by @samp{objcopy} to avoid information loss.
135 The third use is to link object files. There is only one object file
136 linker, @samp{ld}. Originally, @samp{ld} was an object file reader and
137 an object file writer, and it did the link operation using the generic
138 BFD structures. However, this turned out to be too slow and too memory
141 The official BFD linker functions were written to permit specific BFD
142 backends to perform the link without translating through the generic
143 structures, in the normal case where all the input files and output file
144 have the same object file format. Not all of the backends currently
145 implement the new interface, and there are default linking functions
146 within BFD which use the generic structures and which work with all
149 For several object file formats the linker needs additional hooks which
150 are not provided by the official BFD interface, particularly for dynamic
151 linking support. These functions are typically called from the linker
155 @subsection The BFD view of a file
157 BFD uses generic structures to manage information. It translates data
158 into the generic form when reading files, and out of the generic form
161 BFD describes a file as a pointer to the @samp{bfd} type. A @samp{bfd}
162 is composed of the following elements. The BFD information can be
163 displayed using the @samp{objdump} program with various options.
166 @item general information
167 The object file format, a few general flags, the start address.
169 The architecture, including both a general processor type (m68k, MIPS
170 etc.) and a specific machine number (m68000, R4000, etc.).
177 BFD represents a section as a pointer to the @samp{asection} type. Each
178 section has a name and a size. Most sections also have an associated
179 block of data, known as the section contents. Sections also have
180 associated flags, a virtual memory address, a load memory address, a
181 required alignment, a list of relocations, and other miscellaneous
184 BFD represents a relocation as a pointer to the @samp{arelent} type. A
185 relocation describes an action which the linker must take to modify the
186 section contents. Relocations have a symbol, an address, an addend, and
187 a pointer to a howto structure which describes how to perform the
188 relocation. For more information, see @ref{BFD relocation handling}.
190 BFD represents a symbol as a pointer to the @samp{asymbol} type. A
191 symbol has a name, a pointer to a section, an offset within that
192 section, and some flags.
194 Archive files do not have any sections or symbols. Instead, BFD
195 represents an archive file as a file which contains a list of
196 @samp{bfd}s. BFD also provides access to the archive symbol map, as a
197 list of symbol names. BFD provides a function to return the @samp{bfd}
198 within the archive which corresponds to a particular entry in the
202 @subsection BFD loses information
204 Most object file formats have information which BFD can not represent in
205 its generic form, at least as currently defined.
207 There is often explicit information which BFD can not represent. For
208 example, the COFF version stamp, or the ELF program segments. BFD
209 provides special hooks to handle this information when copying,
210 printing, or linking an object file. The BFD support for a particular
211 object file format will normally store this information in private data
212 and handle it using the special hooks.
214 In some cases there is also implicit information which BFD can not
215 represent. For example, the MIPS processor distinguishes small and
216 large symbols, and requires that all small symbols be within 32K of the
217 GP register. This means that the MIPS assembler must be able to mark
218 variables as either small or large, and the MIPS linker must know to put
219 small symbols within range of the GP register. Since BFD can not
220 represent this information, this means that the assembler and linker
221 must have information that is specific to a particular object file
222 format which is outside of the BFD library.
224 This loss of information indicates areas where the BFD paradigm breaks
225 down. It is not actually possible to represent the myriad differences
226 among object file formats using a single generic interface, at least not
227 in the manner which BFD does it today.
229 Nevertheless, the BFD library does greatly simplify the task of dealing
230 with object files, and particular problems caused by information loss
231 can normally be solved using some sort of relatively constrained hook
237 @section BFD programming guidelines
238 @cindex bfd programming guidelines
239 @cindex programming guidelines for bfd
240 @cindex guidelines, bfd programming
242 There is a lot of poorly written and confusing code in BFD. New BFD
243 code should be written to a higher standard. Merely because some BFD
244 code is written in a particular manner does not mean that you should
247 Here are some general BFD programming guidelines:
251 Follow the GNU coding standards.
254 Avoid global variables. We ideally want BFD to be fully reentrant, so
255 that it can be used in multiple threads. All uses of global or static
256 variables interfere with that. Initialized constant variables are OK,
257 and they should be explicitly marked with @samp{const}. Instead of global
258 variables, use data attached to a BFD or to a linker hash table.
261 All externally visible functions should have names which start with
262 @samp{bfd_}. All such functions should be declared in some header file,
263 typically @file{bfd.h}. See, for example, the various declarations near
264 the end of @file{bfd-in.h}, which mostly declare functions required by
265 specific linker emulations.
268 All functions which need to be visible from one file to another within
269 BFD, but should not be visible outside of BFD, should start with
270 @samp{_bfd_}. Although external names beginning with @samp{_} are
271 prohibited by the ANSI standard, in practice this usage will always
272 work, and it is required by the GNU coding standards.
275 Always remember that people can compile using @samp{--enable-targets} to
276 build several, or all, targets at once. It must be possible to link
277 together the files for all targets.
280 BFD code should compile with few or no warnings using @samp{gcc -Wall}.
281 Some warnings are OK, like the absence of certain function declarations
282 which may or may not be declared in system header files. Warnings about
283 ambiguous expressions and the like should always be fixed.
286 @node BFD target vector
287 @section BFD target vector
288 @cindex bfd target vector
289 @cindex target vector in bfd
291 BFD supports multiple object file formats by using the @dfn{target
292 vector}. This is simply a set of function pointers which implement
293 behaviour that is specific to a particular object file format.
295 In this section I list all of the entries in the target vector and
296 describe what they do.
299 * BFD target vector miscellaneous:: Miscellaneous constants
300 * BFD target vector swap:: Swapping functions
301 * BFD target vector format:: Format type dependent functions
302 * BFD_JUMP_TABLE macros:: BFD_JUMP_TABLE macros
303 * BFD target vector generic:: Generic functions
304 * BFD target vector copy:: Copy functions
305 * BFD target vector core:: Core file support functions
306 * BFD target vector archive:: Archive functions
307 * BFD target vector symbols:: Symbol table functions
308 * BFD target vector relocs:: Relocation support
309 * BFD target vector write:: Output functions
310 * BFD target vector link:: Linker functions
311 * BFD target vector dynamic:: Dynamic linking information functions
314 @node BFD target vector miscellaneous
315 @subsection Miscellaneous constants
317 The target vector starts with a set of constants.
321 The name of the target vector. This is an arbitrary string. This is
322 how the target vector is named in command line options for tools which
323 use BFD, such as the @samp{--oformat} linker option.
326 A general description of the type of target. The following flavours are
330 @item bfd_target_unknown_flavour
331 Undefined or unknown.
332 @item bfd_target_aout_flavour
334 @item bfd_target_coff_flavour
336 @item bfd_target_ecoff_flavour
338 @item bfd_target_elf_flavour
340 @item bfd_target_ieee_flavour
342 @item bfd_target_nlm_flavour
344 @item bfd_target_oasys_flavour
346 @item bfd_target_tekhex_flavour
347 Tektronix hex format.
348 @item bfd_target_srec_flavour
349 Motorola S-record format.
350 @item bfd_target_ihex_flavour
352 @item bfd_target_som_flavour
354 @item bfd_target_os9k_flavour
356 @item bfd_target_versados_flavour
358 @item bfd_target_msdos_flavour
360 @item bfd_target_evax_flavour
362 @item bfd_target_mmo_flavour
363 Donald Knuth's MMIXware object format.
367 The byte order of data in the object file. One of
368 @samp{BFD_ENDIAN_BIG}, @samp{BFD_ENDIAN_LITTLE}, or
369 @samp{BFD_ENDIAN_UNKNOWN}. The latter would be used for a format such
370 as S-records which do not record the architecture of the data.
372 @item header_byteorder
373 The byte order of header information in the object file. Normally the
374 same as the @samp{byteorder} field, but there are certain cases where it
378 Flags which may appear in the @samp{flags} field of a BFD with this
382 Flags which may appear in the @samp{flags} field of a section within a
383 BFD with this format.
385 @item symbol_leading_char
386 A character which the C compiler normally puts before a symbol. For
387 example, an a.out compiler will typically generate the symbol
388 @samp{_foo} for a function named @samp{foo} in the C source, in which
389 case this field would be @samp{_}. If there is no such character, this
390 field will be @samp{0}.
393 The padding character to use at the end of an archive name. Normally
397 The maximum length of a short name in an archive. Normally @samp{14}.
400 A pointer to constant backend data. This is used by backends to store
401 whatever additional information they need to distinguish similar target
402 vectors which use the same sets of functions.
405 @node BFD target vector swap
406 @subsection Swapping functions
408 Every target vector has function pointers used for swapping information
409 in and out of the target representation. There are two sets of
410 functions: one for data information, and one for header information.
411 Each set has three sizes: 64-bit, 32-bit, and 16-bit. Each size has
412 three actual functions: put, get unsigned, and get signed.
414 These 18 functions are used to convert data between the host and target
417 @node BFD target vector format
418 @subsection Format type dependent functions
420 Every target vector has three arrays of function pointers which are
421 indexed by the BFD format type. The BFD format types are as follows:
425 Unknown format. Not used for anything useful.
434 The three arrays of function pointers are as follows:
437 @item bfd_check_format
438 Check whether the BFD is of a particular format (object file, archive
439 file, or core file) corresponding to this target vector. This is called
440 by the @samp{bfd_check_format} function when examining an existing BFD.
441 If the BFD matches the desired format, this function will initialize any
442 format specific information such as the @samp{tdata} field of the BFD.
443 This function must be called before any other BFD target vector function
444 on a file opened for reading.
447 Set the format of a BFD which was created for output. This is called by
448 the @samp{bfd_set_format} function after creating the BFD with a
449 function such as @samp{bfd_openw}. This function will initialize format
450 specific information required to write out an object file or whatever of
451 the given format. This function must be called before any other BFD
452 target vector function on a file opened for writing.
454 @item bfd_write_contents
455 Write out the contents of the BFD in the given format. This is called
456 by @samp{bfd_close} function for a BFD opened for writing. This really
457 should not be an array selected by format type, as the
458 @samp{bfd_set_format} function provides all the required information.
459 In fact, BFD will fail if a different format is used when calling
460 through the @samp{bfd_set_format} and the @samp{bfd_write_contents}
461 arrays; fortunately, since @samp{bfd_close} gets it right, this is a
462 difficult error to make.
465 @node BFD_JUMP_TABLE macros
466 @subsection @samp{BFD_JUMP_TABLE} macros
467 @cindex @samp{BFD_JUMP_TABLE}
469 Most target vectors are defined using @samp{BFD_JUMP_TABLE} macros.
470 These macros take a single argument, which is a prefix applied to a set
471 of functions. The macros are then used to initialize the fields in the
474 For example, the @samp{BFD_JUMP_TABLE_RELOCS} macro defines three
475 functions: @samp{_get_reloc_upper_bound}, @samp{_canonicalize_reloc},
476 and @samp{_bfd_reloc_type_lookup}. A reference like
477 @samp{BFD_JUMP_TABLE_RELOCS (foo)} will expand into three functions
478 prefixed with @samp{foo}: @samp{foo_get_reloc_upper_bound}, etc. The
479 @samp{BFD_JUMP_TABLE_RELOCS} macro will be placed such that those three
480 functions initialize the appropriate fields in the BFD target vector.
482 This is done because it turns out that many different target vectors can
483 share certain classes of functions. For example, archives are similar
484 on most platforms, so most target vectors can use the same archive
485 functions. Those target vectors all use @samp{BFD_JUMP_TABLE_ARCHIVE}
486 with the same argument, calling a set of functions which is defined in
489 Each of the @samp{BFD_JUMP_TABLE} macros is mentioned below along with
490 the description of the function pointers which it defines. The function
491 pointers will be described using the name without the prefix which the
492 @samp{BFD_JUMP_TABLE} macro defines. This name is normally the same as
493 the name of the field in the target vector structure. Any differences
496 @node BFD target vector generic
497 @subsection Generic functions
498 @cindex @samp{BFD_JUMP_TABLE_GENERIC}
500 The @samp{BFD_JUMP_TABLE_GENERIC} macro is used for some catch all
501 functions which don't easily fit into other categories.
504 @item _close_and_cleanup
505 Free any target specific information associated with the BFD. This is
506 called when any BFD is closed (the @samp{bfd_write_contents} function
507 mentioned earlier is only called for a BFD opened for writing). Most
508 targets use @samp{bfd_alloc} to allocate all target specific
509 information, and therefore don't have to do anything in this function.
510 This function pointer is typically set to
511 @samp{_bfd_generic_close_and_cleanup}, which simply returns true.
513 @item _bfd_free_cached_info
514 Free any cached information associated with the BFD which can be
515 recreated later if necessary. This is used to reduce the memory
516 consumption required by programs using BFD. This is normally called via
517 the @samp{bfd_free_cached_info} macro. It is used by the default
518 archive routines when computing the archive map. Most targets do not
519 do anything special for this entry point, and just set it to
520 @samp{_bfd_generic_free_cached_info}, which simply returns true.
522 @item _new_section_hook
523 This is called from @samp{bfd_make_section_anyway} whenever a new
524 section is created. Most targets use it to initialize section specific
525 information. This function is called whether or not the section
526 corresponds to an actual section in an actual BFD.
528 @item _get_section_contents
529 Get the contents of a section. This is called from
530 @samp{bfd_get_section_contents}. Most targets set this to
531 @samp{_bfd_generic_get_section_contents}, which does a @samp{bfd_seek}
532 based on the section's @samp{filepos} field and a @samp{bfd_bread}. The
533 corresponding field in the target vector is named
534 @samp{_bfd_get_section_contents}.
536 @item _get_section_contents_in_window
537 Set a @samp{bfd_window} to hold the contents of a section. This is
538 called from @samp{bfd_get_section_contents_in_window}. The
539 @samp{bfd_window} idea never really caught on, and I don't think this is
540 ever called. Pretty much all targets implement this as
541 @samp{bfd_generic_get_section_contents_in_window}, which uses
542 @samp{bfd_get_section_contents} to do the right thing. The
543 corresponding field in the target vector is named
544 @samp{_bfd_get_section_contents_in_window}.
547 @node BFD target vector copy
548 @subsection Copy functions
549 @cindex @samp{BFD_JUMP_TABLE_COPY}
551 The @samp{BFD_JUMP_TABLE_COPY} macro is used for functions which are
552 called when copying BFDs, and for a couple of functions which deal with
553 internal BFD information.
556 @item _bfd_copy_private_bfd_data
557 This is called when copying a BFD, via @samp{bfd_copy_private_bfd_data}.
558 If the input and output BFDs have the same format, this will copy any
559 private information over. This is called after all the section contents
560 have been written to the output file. Only a few targets do anything in
563 @item _bfd_merge_private_bfd_data
564 This is called when linking, via @samp{bfd_merge_private_bfd_data}. It
565 gives the backend linker code a chance to set any special flags in the
566 output file based on the contents of the input file. Only a few targets
567 do anything in this function.
569 @item _bfd_copy_private_section_data
570 This is similar to @samp{_bfd_copy_private_bfd_data}, but it is called
571 for each section, via @samp{bfd_copy_private_section_data}. This
572 function is called before any section contents have been written. Only
573 a few targets do anything in this function.
575 @item _bfd_copy_private_symbol_data
576 This is called via @samp{bfd_copy_private_symbol_data}, but I don't
577 think anything actually calls it. If it were defined, it could be used
578 to copy private symbol data from one BFD to another. However, most BFDs
579 store extra symbol information by allocating space which is larger than
580 the @samp{asymbol} structure and storing private information in the
581 extra space. Since @samp{objcopy} and other programs copy symbol
582 information by copying pointers to @samp{asymbol} structures, the
583 private symbol information is automatically copied as well. Most
584 targets do not do anything in this function.
586 @item _bfd_set_private_flags
587 This is called via @samp{bfd_set_private_flags}. It is basically a hook
588 for the assembler to set magic information. For example, the PowerPC
589 ELF assembler uses it to set flags which appear in the e_flags field of
590 the ELF header. Most targets do not do anything in this function.
592 @item _bfd_print_private_bfd_data
593 This is called by @samp{objdump} when the @samp{-p} option is used. It
594 is called via @samp{bfd_print_private_data}. It prints any interesting
595 information about the BFD which can not be otherwise represented by BFD
596 and thus can not be printed by @samp{objdump}. Most targets do not do
597 anything in this function.
600 @node BFD target vector core
601 @subsection Core file support functions
602 @cindex @samp{BFD_JUMP_TABLE_CORE}
604 The @samp{BFD_JUMP_TABLE_CORE} macro is used for functions which deal
605 with core files. Obviously, these functions only do something
606 interesting for targets which have core file support.
609 @item _core_file_failing_command
610 Given a core file, this returns the command which was run to produce the
613 @item _core_file_failing_signal
614 Given a core file, this returns the signal number which produced the
617 @item _core_file_matches_executable_p
618 Given a core file and a BFD for an executable, this returns whether the
619 core file was generated by the executable.
622 @node BFD target vector archive
623 @subsection Archive functions
624 @cindex @samp{BFD_JUMP_TABLE_ARCHIVE}
626 The @samp{BFD_JUMP_TABLE_ARCHIVE} macro is used for functions which deal
627 with archive files. Most targets use COFF style archive files
628 (including ELF targets), and these use @samp{_bfd_archive_coff} as the
629 argument to @samp{BFD_JUMP_TABLE_ARCHIVE}. Some targets use BSD/a.out
630 style archives, and these use @samp{_bfd_archive_bsd}. (The main
631 difference between BSD and COFF archives is the format of the archive
632 symbol table). Targets with no archive support use
633 @samp{_bfd_noarchive}. Finally, a few targets have unusual archive
638 Read in the archive symbol table, storing it in private BFD data. This
639 is normally called from the archive @samp{check_format} routine. The
640 corresponding field in the target vector is named
641 @samp{_bfd_slurp_armap}.
643 @item _slurp_extended_name_table
644 Read in the extended name table from the archive, if there is one,
645 storing it in private BFD data. This is normally called from the
646 archive @samp{check_format} routine. The corresponding field in the
647 target vector is named @samp{_bfd_slurp_extended_name_table}.
649 @item construct_extended_name_table
650 Build and return an extended name table if one is needed to write out
651 the archive. This also adjusts the archive headers to refer to the
652 extended name table appropriately. This is normally called from the
653 archive @samp{write_contents} routine. The corresponding field in the
654 target vector is named @samp{_bfd_construct_extended_name_table}.
656 @item _truncate_arname
657 This copies a file name into an archive header, truncating it as
658 required. It is normally called from the archive @samp{write_contents}
659 routine. This function is more interesting in targets which do not
660 support extended name tables, but I think the GNU @samp{ar} program
661 always uses extended name tables anyhow. The corresponding field in the
662 target vector is named @samp{_bfd_truncate_arname}.
665 Write out the archive symbol table using calls to @samp{bfd_bwrite}.
666 This is normally called from the archive @samp{write_contents} routine.
667 The corresponding field in the target vector is named @samp{write_armap}
668 (no leading underscore).
671 Read and parse an archive header. This handles expanding the archive
672 header name into the real file name using the extended name table. This
673 is called by routines which read the archive symbol table or the archive
674 itself. The corresponding field in the target vector is named
675 @samp{_bfd_read_ar_hdr_fn}.
677 @item _openr_next_archived_file
678 Given an archive and a BFD representing a file stored within the
679 archive, return a BFD for the next file in the archive. This is called
680 via @samp{bfd_openr_next_archived_file}. The corresponding field in the
681 target vector is named @samp{openr_next_archived_file} (no leading
684 @item _get_elt_at_index
685 Given an archive and an index, return a BFD for the file in the archive
686 corresponding to that entry in the archive symbol table. This is called
687 via @samp{bfd_get_elt_at_index}. The corresponding field in the target
688 vector is named @samp{_bfd_get_elt_at_index}.
690 @item _generic_stat_arch_elt
691 Do a stat on an element of an archive, returning information read from
692 the archive header (modification time, uid, gid, file mode, size). This
693 is called via @samp{bfd_stat_arch_elt}. The corresponding field in the
694 target vector is named @samp{_bfd_stat_arch_elt}.
696 @item _update_armap_timestamp
697 After the entire contents of an archive have been written out, update
698 the timestamp of the archive symbol table to be newer than that of the
699 file. This is required for a.out style archives. This is normally
700 called by the archive @samp{write_contents} routine. The corresponding
701 field in the target vector is named @samp{_bfd_update_armap_timestamp}.
704 @node BFD target vector symbols
705 @subsection Symbol table functions
706 @cindex @samp{BFD_JUMP_TABLE_SYMBOLS}
708 The @samp{BFD_JUMP_TABLE_SYMBOLS} macro is used for functions which deal
712 @item _get_symtab_upper_bound
713 Return a sensible upper bound on the amount of memory which will be
714 required to read the symbol table. In practice most targets return the
715 amount of memory required to hold @samp{asymbol} pointers for all the
716 symbols plus a trailing @samp{NULL} entry, and store the actual symbol
717 information in BFD private data. This is called via
718 @samp{bfd_get_symtab_upper_bound}. The corresponding field in the
719 target vector is named @samp{_bfd_get_symtab_upper_bound}.
721 @item _canonicalize_symtab
722 Read in the symbol table. This is called via
723 @samp{bfd_canonicalize_symtab}. The corresponding field in the target
724 vector is named @samp{_bfd_canonicalize_symtab}.
726 @item _make_empty_symbol
727 Create an empty symbol for the BFD. This is needed because most targets
728 store extra information with each symbol by allocating a structure
729 larger than an @samp{asymbol} and storing the extra information at the
730 end. This function will allocate the right amount of memory, and return
731 what looks like a pointer to an empty @samp{asymbol}. This is called
732 via @samp{bfd_make_empty_symbol}. The corresponding field in the target
733 vector is named @samp{_bfd_make_empty_symbol}.
736 Print information about the symbol. This is called via
737 @samp{bfd_print_symbol}. One of the arguments indicates what sort of
738 information should be printed:
741 @item bfd_print_symbol_name
742 Just print the symbol name.
743 @item bfd_print_symbol_more
744 Print the symbol name and some interesting flags. I don't think
745 anything actually uses this.
746 @item bfd_print_symbol_all
747 Print all information about the symbol. This is used by @samp{objdump}
748 when run with the @samp{-t} option.
750 The corresponding field in the target vector is named
751 @samp{_bfd_print_symbol}.
753 @item _get_symbol_info
754 Return a standard set of information about the symbol. This is called
755 via @samp{bfd_symbol_info}. The corresponding field in the target
756 vector is named @samp{_bfd_get_symbol_info}.
758 @item _bfd_is_local_label_name
759 Return whether the given string would normally represent the name of a
760 local label. This is called via @samp{bfd_is_local_label} and
761 @samp{bfd_is_local_label_name}. Local labels are normally discarded by
762 the assembler. In the linker, this defines the difference between the
763 @samp{-x} and @samp{-X} options.
766 Return line number information for a symbol. This is only meaningful
767 for a COFF target. This is called when writing out COFF line numbers.
769 @item _find_nearest_line
770 Given an address within a section, use the debugging information to find
771 the matching file name, function name, and line number, if any. This is
772 called via @samp{bfd_find_nearest_line}. The corresponding field in the
773 target vector is named @samp{_bfd_find_nearest_line}.
775 @item _bfd_make_debug_symbol
776 Make a debugging symbol. This is only meaningful for a COFF target,
777 where it simply returns a symbol which will be placed in the
778 @samp{N_DEBUG} section when it is written out. This is called via
779 @samp{bfd_make_debug_symbol}.
781 @item _read_minisymbols
782 Minisymbols are used to reduce the memory requirements of programs like
783 @samp{nm}. A minisymbol is a cookie pointing to internal symbol
784 information which the caller can use to extract complete symbol
785 information. This permits BFD to not convert all the symbols into
786 generic form, but to instead convert them one at a time. This is called
787 via @samp{bfd_read_minisymbols}. Most targets do not implement this,
788 and just use generic support which is based on using standard
789 @samp{asymbol} structures.
791 @item _minisymbol_to_symbol
792 Convert a minisymbol to a standard @samp{asymbol}. This is called via
793 @samp{bfd_minisymbol_to_symbol}.
796 @node BFD target vector relocs
797 @subsection Relocation support
798 @cindex @samp{BFD_JUMP_TABLE_RELOCS}
800 The @samp{BFD_JUMP_TABLE_RELOCS} macro is used for functions which deal
804 @item _get_reloc_upper_bound
805 Return a sensible upper bound on the amount of memory which will be
806 required to read the relocations for a section. In practice most
807 targets return the amount of memory required to hold @samp{arelent}
808 pointers for all the relocations plus a trailing @samp{NULL} entry, and
809 store the actual relocation information in BFD private data. This is
810 called via @samp{bfd_get_reloc_upper_bound}.
812 @item _canonicalize_reloc
813 Return the relocation information for a section. This is called via
814 @samp{bfd_canonicalize_reloc}. The corresponding field in the target
815 vector is named @samp{_bfd_canonicalize_reloc}.
817 @item _bfd_reloc_type_lookup
818 Given a relocation code, return the corresponding howto structure
819 (@pxref{BFD relocation codes}). This is called via
820 @samp{bfd_reloc_type_lookup}. The corresponding field in the target
821 vector is named @samp{reloc_type_lookup}.
824 @node BFD target vector write
825 @subsection Output functions
826 @cindex @samp{BFD_JUMP_TABLE_WRITE}
828 The @samp{BFD_JUMP_TABLE_WRITE} macro is used for functions which deal
829 with writing out a BFD.
833 Set the architecture and machine number for a BFD. This is called via
834 @samp{bfd_set_arch_mach}. Most targets implement this by calling
835 @samp{bfd_default_set_arch_mach}. The corresponding field in the target
836 vector is named @samp{_bfd_set_arch_mach}.
838 @item _set_section_contents
839 Write out the contents of a section. This is called via
840 @samp{bfd_set_section_contents}. The corresponding field in the target
841 vector is named @samp{_bfd_set_section_contents}.
844 @node BFD target vector link
845 @subsection Linker functions
846 @cindex @samp{BFD_JUMP_TABLE_LINK}
848 The @samp{BFD_JUMP_TABLE_LINK} macro is used for functions called by the
852 @item _sizeof_headers
853 Return the size of the header information required for a BFD. This is
854 used to implement the @samp{SIZEOF_HEADERS} linker script function. It
855 is normally used to align the first section at an efficient position on
856 the page. This is called via @samp{bfd_sizeof_headers}. The
857 corresponding field in the target vector is named
858 @samp{_bfd_sizeof_headers}.
860 @item _bfd_get_relocated_section_contents
861 Read the contents of a section and apply the relocation information.
862 This handles both a final link and a relocatable link; in the latter
863 case, it adjust the relocation information as well. This is called via
864 @samp{bfd_get_relocated_section_contents}. Most targets implement it by
865 calling @samp{bfd_generic_get_relocated_section_contents}.
867 @item _bfd_relax_section
868 Try to use relaxation to shrink the size of a section. This is called
869 by the linker when the @samp{-relax} option is used. This is called via
870 @samp{bfd_relax_section}. Most targets do not support any sort of
873 @item _bfd_link_hash_table_create
874 Create the symbol hash table to use for the linker. This linker hook
875 permits the backend to control the size and information of the elements
876 in the linker symbol hash table. This is called via
877 @samp{bfd_link_hash_table_create}.
879 @item _bfd_link_add_symbols
880 Given an object file or an archive, add all symbols into the linker
881 symbol hash table. Use callbacks to the linker to include archive
882 elements in the link. This is called via @samp{bfd_link_add_symbols}.
884 @item _bfd_final_link
885 Finish the linking process. The linker calls this hook after all of the
886 input files have been read, when it is ready to finish the link and
887 generate the output file. This is called via @samp{bfd_final_link}.
889 @item _bfd_link_split_section
890 I don't know what this is for. Nothing seems to call it. The only
891 non-trivial definition is in @file{som.c}.
894 @node BFD target vector dynamic
895 @subsection Dynamic linking information functions
896 @cindex @samp{BFD_JUMP_TABLE_DYNAMIC}
898 The @samp{BFD_JUMP_TABLE_DYNAMIC} macro is used for functions which read
899 dynamic linking information.
902 @item _get_dynamic_symtab_upper_bound
903 Return a sensible upper bound on the amount of memory which will be
904 required to read the dynamic symbol table. In practice most targets
905 return the amount of memory required to hold @samp{asymbol} pointers for
906 all the symbols plus a trailing @samp{NULL} entry, and store the actual
907 symbol information in BFD private data. This is called via
908 @samp{bfd_get_dynamic_symtab_upper_bound}. The corresponding field in
909 the target vector is named @samp{_bfd_get_dynamic_symtab_upper_bound}.
911 @item _canonicalize_dynamic_symtab
912 Read the dynamic symbol table. This is called via
913 @samp{bfd_canonicalize_dynamic_symtab}. The corresponding field in the
914 target vector is named @samp{_bfd_canonicalize_dynamic_symtab}.
916 @item _get_dynamic_reloc_upper_bound
917 Return a sensible upper bound on the amount of memory which will be
918 required to read the dynamic relocations. In practice most targets
919 return the amount of memory required to hold @samp{arelent} pointers for
920 all the relocations plus a trailing @samp{NULL} entry, and store the
921 actual relocation information in BFD private data. This is called via
922 @samp{bfd_get_dynamic_reloc_upper_bound}. The corresponding field in
923 the target vector is named @samp{_bfd_get_dynamic_reloc_upper_bound}.
925 @item _canonicalize_dynamic_reloc
926 Read the dynamic relocations. This is called via
927 @samp{bfd_canonicalize_dynamic_reloc}. The corresponding field in the
928 target vector is named @samp{_bfd_canonicalize_dynamic_reloc}.
931 @node BFD generated files
932 @section BFD generated files
933 @cindex generated files in bfd
934 @cindex bfd generated files
936 BFD contains several automatically generated files. This section
937 describes them. Some files are created at configure time, when you
938 configure BFD. Some files are created at make time, when you build
939 BFD. Some files are automatically rebuilt at make time, but only if
940 you configure with the @samp{--enable-maintainer-mode} option. Some
941 files live in the object directory---the directory from which you run
942 configure---and some live in the source directory. All files that live
943 in the source directory are checked into the CVS repository.
948 @cindex @file{bfd-in3.h}
949 Lives in the object directory. Created at make time from
950 @file{bfd-in2.h} via @file{bfd-in3.h}. @file{bfd-in3.h} is created at
951 configure time from @file{bfd-in2.h}. There are automatic dependencies
952 to rebuild @file{bfd-in3.h} and hence @file{bfd.h} if @file{bfd-in2.h}
953 changes, so you can normally ignore @file{bfd-in3.h}, and just think
954 about @file{bfd-in2.h} and @file{bfd.h}.
956 @file{bfd.h} is built by replacing a few strings in @file{bfd-in2.h}.
957 To see them, search for @samp{@@} in @file{bfd-in2.h}. They mainly
958 control whether BFD is built for a 32 bit target or a 64 bit target.
961 @cindex @file{bfd-in2.h}
962 Lives in the source directory. Created from @file{bfd-in.h} and several
963 other BFD source files. If you configure with the
964 @samp{--enable-maintainer-mode} option, @file{bfd-in2.h} is rebuilt
965 automatically when a source file changes.
968 @itemx elf64-target.h
969 @cindex @file{elf32-target.h}
970 @cindex @file{elf64-target.h}
971 Live in the object directory. Created from @file{elfxx-target.h}.
972 These files are versions of @file{elfxx-target.h} customized for either
973 a 32 bit ELF target or a 64 bit ELF target.
976 @cindex @file{libbfd.h}
977 Lives in the source directory. Created from @file{libbfd-in.h} and
978 several other BFD source files. If you configure with the
979 @samp{--enable-maintainer-mode} option, @file{libbfd.h} is rebuilt
980 automatically when a source file changes.
983 @cindex @file{libcoff.h}
984 Lives in the source directory. Created from @file{libcoff-in.h} and
985 @file{coffcode.h}. If you configure with the
986 @samp{--enable-maintainer-mode} option, @file{libcoff.h} is rebuilt
987 automatically when a source file changes.
990 @cindex @file{targmatch.h}
991 Lives in the object directory. Created at make time from
992 @file{config.bfd}. This file is used to map configuration triplets into
993 BFD target vector variable names at run time.
996 @node BFD multiple compilations
997 @section Files compiled multiple times in BFD
998 Several files in BFD are compiled multiple times. By this I mean that
999 there are header files which contain function definitions. These header
1000 files are included by other files, and thus the functions are compiled
1001 once per file which includes them.
1003 Preprocessor macros are used to control the compilation, so that each
1004 time the files are compiled the resulting functions are slightly
1005 different. Naturally, if they weren't different, there would be no
1006 reason to compile them multiple times.
1008 This is a not a particularly good programming technique, and future BFD
1009 work should avoid it.
1013 Since this technique is rarely used, even experienced C programmers find
1017 It is difficult to debug programs which use BFD, since there is no way
1018 to describe which version of a particular function you are looking at.
1021 Programs which use BFD wind up incorporating two or more slightly
1022 different versions of the same function, which wastes space in the
1026 This technique is never required nor is it especially efficient. It is
1027 always possible to use statically initialized structures holding
1028 function pointers and magic constants instead.
1031 The following is a list of the files which are compiled multiple times.
1035 @cindex @file{aout-target.h}
1036 Describes a few functions and the target vector for a.out targets. This
1037 is used by individual a.out targets with different definitions of
1038 @samp{N_TXTADDR} and similar a.out macros.
1041 @cindex @file{aoutf1.h}
1042 Implements standard SunOS a.out files. In principle it supports 64 bit
1043 a.out targets based on the preprocessor macro @samp{ARCH_SIZE}, but
1044 since all known a.out targets are 32 bits, this code may or may not
1045 work. This file is only included by a few other files, and it is
1046 difficult to justify its existence.
1049 @cindex @file{aoutx.h}
1050 Implements basic a.out support routines. This file can be compiled for
1051 either 32 or 64 bit support. Since all known a.out targets are 32 bits,
1052 the 64 bit support may or may not work. I believe the original
1053 intention was that this file would only be included by @samp{aout32.c}
1054 and @samp{aout64.c}, and that other a.out targets would simply refer to
1055 the functions it defined. Unfortunately, some other a.out targets
1056 started including it directly, leading to a somewhat confused state of
1060 @cindex @file{coffcode.h}
1061 Implements basic COFF support routines. This file is included by every
1062 COFF target. It implements code which handles COFF magic numbers as
1063 well as various hook functions called by the generic COFF functions in
1064 @file{coffgen.c}. This file is controlled by a number of different
1065 macros, and more are added regularly.
1068 @cindex @file{coffswap.h}
1069 Implements COFF swapping routines. This file is included by
1070 @file{coffcode.h}, and thus by every COFF target. It implements the
1071 routines which swap COFF structures between internal and external
1072 format. The main control for this file is the external structure
1073 definitions in the files in the @file{include/coff} directory. A COFF
1074 target file will include one of those files before including
1075 @file{coffcode.h} and thus @file{coffswap.h}. There are a few other
1076 macros which affect @file{coffswap.h} as well, mostly describing whether
1077 certain fields are present in the external structures.
1080 @cindex @file{ecoffswap.h}
1081 Implements ECOFF swapping routines. This is like @file{coffswap.h}, but
1082 for ECOFF. It is included by the ECOFF target files (of which there are
1083 only two). The control is the preprocessor macro @samp{ECOFF_32} or
1087 @cindex @file{elfcode.h}
1088 Implements ELF functions that use external structure definitions. This
1089 file is included by two other files: @file{elf32.c} and @file{elf64.c}.
1090 It is controlled by the @samp{ARCH_SIZE} macro which is defined to be
1091 @samp{32} or @samp{64} before including it. The @samp{NAME} macro is
1092 used internally to give the functions different names for the two target
1096 @cindex @file{elfcore.h}
1097 Like @file{elfcode.h}, but for functions that are specific to ELF core
1098 files. This is included only by @file{elfcode.h}.
1100 @item elfxx-target.h
1101 @cindex @file{elfxx-target.h}
1102 This file is the source for the generated files @file{elf32-target.h}
1103 and @file{elf64-target.h}, one of which is included by every ELF target.
1104 It defines the ELF target vector.
1107 @cindex @file{freebsd.h}
1108 Presumably intended to be included by all FreeBSD targets, but in fact
1109 there is only one such target, @samp{i386-freebsd}. This defines a
1110 function used to set the right magic number for FreeBSD, as well as
1111 various macros, and includes @file{aout-target.h}.
1114 @cindex @file{netbsd.h}
1115 Like @file{freebsd.h}, except that there are several files which include
1119 @cindex @file{nlm-target.h}
1120 Defines the target vector for a standard NLM target.
1123 @cindex @file{nlmcode.h}
1124 Like @file{elfcode.h}, but for NLM targets. This is only included by
1125 @file{nlm32.c} and @file{nlm64.c}, both of which define the macro
1126 @samp{ARCH_SIZE} to an appropriate value. There are no 64 bit NLM
1127 targets anyhow, so this is sort of useless.
1130 @cindex @file{nlmswap.h}
1131 Like @file{coffswap.h}, but for NLM targets. This is included by each
1132 NLM target, but I think it winds up compiling to the exact same code for
1133 every target, and as such is fairly useless.
1136 @cindex @file{peicode.h}
1137 Provides swapping routines and other hooks for PE targets.
1138 @file{coffcode.h} will include this rather than @file{coffswap.h} for a
1139 PE target. This defines PE specific versions of the COFF swapping
1140 routines, and also defines some macros which control @file{coffcode.h}
1144 @node BFD relocation handling
1145 @section BFD relocation handling
1146 @cindex bfd relocation handling
1147 @cindex relocations in bfd
1149 The handling of relocations is one of the more confusing aspects of BFD.
1150 Relocation handling has been implemented in various different ways, all
1151 somewhat incompatible, none perfect.
1154 * BFD relocation concepts:: BFD relocation concepts
1155 * BFD relocation functions:: BFD relocation functions
1156 * BFD relocation codes:: BFD relocation codes
1157 * BFD relocation future:: BFD relocation future
1160 @node BFD relocation concepts
1161 @subsection BFD relocation concepts
1163 A relocation is an action which the linker must take when linking. It
1164 describes a change to the contents of a section. The change is normally
1165 based on the final value of one or more symbols. Relocations are
1166 created by the assembler when it creates an object file.
1168 Most relocations are simple. A typical simple relocation is to set 32
1169 bits at a given offset in a section to the value of a symbol. This type
1170 of relocation would be generated for code like @code{int *p = &i;} where
1171 @samp{p} and @samp{i} are global variables. A relocation for the symbol
1172 @samp{i} would be generated such that the linker would initialize the
1173 area of memory which holds the value of @samp{p} to the value of the
1176 Slightly more complex relocations may include an addend, which is a
1177 constant to add to the symbol value before using it. In some cases a
1178 relocation will require adding the symbol value to the existing contents
1179 of the section in the object file. In others the relocation will simply
1180 replace the contents of the section with the symbol value. Some
1181 relocations are PC relative, so that the value to be stored in the
1182 section is the difference between the value of a symbol and the final
1183 address of the section contents.
1185 In general, relocations can be arbitrarily complex. For example,
1186 relocations used in dynamic linking systems often require the linker to
1187 allocate space in a different section and use the offset within that
1188 section as the value to store. In the IEEE object file format,
1189 relocations may involve arbitrary expressions.
1191 When doing a relocatable link, the linker may or may not have to do
1192 anything with a relocation, depending upon the definition of the
1193 relocation. Simple relocations generally do not require any special
1196 @node BFD relocation functions
1197 @subsection BFD relocation functions
1199 In BFD, each section has an array of @samp{arelent} structures. Each
1200 structure has a pointer to a symbol, an address within the section, an
1201 addend, and a pointer to a @samp{reloc_howto_struct} structure. The
1202 howto structure has a bunch of fields describing the reloc, including a
1203 type field. The type field is specific to the object file format
1204 backend; none of the generic code in BFD examines it.
1206 Originally, the function @samp{bfd_perform_relocation} was supposed to
1207 handle all relocations. In theory, many relocations would be simple
1208 enough to be described by the fields in the howto structure. For those
1209 that weren't, the howto structure included a @samp{special_function}
1210 field to use as an escape.
1212 While this seems plausible, a look at @samp{bfd_perform_relocation}
1213 shows that it failed. The function has odd special cases. Some of the
1214 fields in the howto structure, such as @samp{pcrel_offset}, were not
1215 adequately documented.
1217 The linker uses @samp{bfd_perform_relocation} to do all relocations when
1218 the input and output file have different formats (e.g., when generating
1219 S-records). The generic linker code, which is used by all targets which
1220 do not define their own special purpose linker, uses
1221 @samp{bfd_get_relocated_section_contents}, which for most targets turns
1222 into a call to @samp{bfd_generic_get_relocated_section_contents}, which
1223 calls @samp{bfd_perform_relocation}. So @samp{bfd_perform_relocation}
1224 is still widely used, which makes it difficult to change, since it is
1225 difficult to test all possible cases.
1227 The assembler used @samp{bfd_perform_relocation} for a while. This
1228 turned out to be the wrong thing to do, since
1229 @samp{bfd_perform_relocation} was written to handle relocations on an
1230 existing object file, while the assembler needed to create relocations
1231 in a new object file. The assembler was changed to use the new function
1232 @samp{bfd_install_relocation} instead, and @samp{bfd_install_relocation}
1233 was created as a copy of @samp{bfd_perform_relocation}.
1235 Unfortunately, the work did not progress any farther, so
1236 @samp{bfd_install_relocation} remains a simple copy of
1237 @samp{bfd_perform_relocation}, with all the odd special cases and
1238 confusing code. This again is difficult to change, because again any
1239 change can affect any assembler target, and so is difficult to test.
1241 The new linker, when using the same object file format for all input
1242 files and the output file, does not convert relocations into
1243 @samp{arelent} structures, so it can not use
1244 @samp{bfd_perform_relocation} at all. Instead, users of the new linker
1245 are expected to write a @samp{relocate_section} function which will
1246 handle relocations in a target specific fashion.
1248 There are two helper functions for target specific relocation:
1249 @samp{_bfd_final_link_relocate} and @samp{_bfd_relocate_contents}.
1250 These functions use a howto structure, but they @emph{do not} use the
1251 @samp{special_function} field. Since the functions are normally called
1252 from target specific code, the @samp{special_function} field adds
1253 little; any relocations which require special handling can be handled
1254 without calling those functions.
1256 So, if you want to add a new target, or add a new relocation to an
1257 existing target, you need to do the following:
1261 Make sure you clearly understand what the contents of the section should
1262 look like after assembly, after a relocatable link, and after a final
1263 link. Make sure you clearly understand the operations the linker must
1264 perform during a relocatable link and during a final link.
1267 Write a howto structure for the relocation. The howto structure is
1268 flexible enough to represent any relocation which should be handled by
1269 setting a contiguous bitfield in the destination to the value of a
1270 symbol, possibly with an addend, possibly adding the symbol value to the
1271 value already present in the destination.
1274 Change the assembler to generate your relocation. The assembler will
1275 call @samp{bfd_install_relocation}, so your howto structure has to be
1276 able to handle that. You may need to set the @samp{special_function}
1277 field to handle assembly correctly. Be careful to ensure that any code
1278 you write to handle the assembler will also work correctly when doing a
1279 relocatable link. For example, see @samp{bfd_elf_generic_reloc}.
1282 Test the assembler. Consider the cases of relocation against an
1283 undefined symbol, a common symbol, a symbol defined in the object file
1284 in the same section, and a symbol defined in the object file in a
1285 different section. These cases may not all be applicable for your
1289 If your target uses the new linker, which is recommended, add any
1290 required handling to the target specific relocation function. In simple
1291 cases this will just involve a call to @samp{_bfd_final_link_relocate}
1292 or @samp{_bfd_relocate_contents}, depending upon the definition of the
1293 relocation and whether the link is relocatable or not.
1296 Test the linker. Test the case of a final link. If the relocation can
1297 overflow, use a linker script to force an overflow and make sure the
1298 error is reported correctly. Test a relocatable link, whether the
1299 symbol is defined or undefined in the relocatable output. For both the
1300 final and relocatable link, test the case when the symbol is a common
1301 symbol, when the symbol looked like a common symbol but became a defined
1302 symbol, when the symbol is defined in a different object file, and when
1303 the symbol is defined in the same object file.
1306 In order for linking to another object file format, such as S-records,
1307 to work correctly, @samp{bfd_perform_relocation} has to do the right
1308 thing for the relocation. You may need to set the
1309 @samp{special_function} field to handle this correctly. Test this by
1310 doing a link in which the output object file format is S-records.
1313 Using the linker to generate relocatable output in a different object
1314 file format is impossible in the general case, so you generally don't
1315 have to worry about that. The GNU linker makes sure to stop that from
1316 happening when an input file in a different format has relocations.
1318 Linking input files of different object file formats together is quite
1319 unusual, but if you're really dedicated you may want to consider testing
1320 this case, both when the output object file format is the same as your
1321 format, and when it is different.
1324 @node BFD relocation codes
1325 @subsection BFD relocation codes
1327 BFD has another way of describing relocations besides the howto
1328 structures described above: the enum @samp{bfd_reloc_code_real_type}.
1330 Every known relocation type can be described as a value in this
1331 enumeration. The enumeration contains many target specific relocations,
1332 but where two or more targets have the same relocation, a single code is
1333 used. For example, the single value @samp{BFD_RELOC_32} is used for all
1334 simple 32 bit relocation types.
1336 The main purpose of this relocation code is to give the assembler some
1337 mechanism to create @samp{arelent} structures. In order for the
1338 assembler to create an @samp{arelent} structure, it has to be able to
1339 obtain a howto structure. The function @samp{bfd_reloc_type_lookup},
1340 which simply calls the target vector entry point
1341 @samp{reloc_type_lookup}, takes a relocation code and returns a howto
1344 The function @samp{bfd_get_reloc_code_name} returns the name of a
1345 relocation code. This is mainly used in error messages.
1347 Using both howto structures and relocation codes can be somewhat
1348 confusing. There are many processor specific relocation codes.
1349 However, the relocation is only fully defined by the howto structure.
1350 The same relocation code will map to different howto structures in
1351 different object file formats. For example, the addend handling may be
1354 Most of the relocation codes are not really general. The assembler can
1355 not use them without already understanding what sorts of relocations can
1356 be used for a particular target. It might be possible to replace the
1357 relocation codes with something simpler.
1359 @node BFD relocation future
1360 @subsection BFD relocation future
1362 Clearly the current BFD relocation support is in bad shape. A
1363 wholescale rewrite would be very difficult, because it would require
1364 thorough testing of every BFD target. So some sort of incremental
1367 My vague thoughts on this would involve defining a new, clearly defined,
1368 howto structure. Some mechanism would be used to determine which type
1369 of howto structure was being used by a particular format.
1371 The new howto structure would clearly define the relocation behaviour in
1372 the case of an assembly, a relocatable link, and a final link. At
1373 least one special function would be defined as an escape, and it might
1374 make sense to define more.
1376 One or more generic functions similar to @samp{bfd_perform_relocation}
1377 would be written to handle the new howto structure.
1379 This should make it possible to write a generic version of the relocate
1380 section functions used by the new linker. The target specific code
1381 would provide some mechanism (a function pointer or an initial
1382 conversion) to convert target specific relocations into howto
1385 Ideally it would be possible to use this generic relocate section
1386 function for the generic linker as well. That is, it would replace the
1387 @samp{bfd_generic_get_relocated_section_contents} function which is
1388 currently normally used.
1390 For the special case of ELF dynamic linking, more consideration needs to
1391 be given to writing ELF specific but ELF target generic code to handle
1392 special relocation types such as GOT and PLT.
1394 @node BFD ELF support
1395 @section BFD ELF support
1396 @cindex elf support in bfd
1397 @cindex bfd elf support
1399 The ELF object file format is defined in two parts: a generic ABI and a
1400 processor specific supplement. The ELF support in BFD is split in a
1401 similar fashion. The processor specific support is largely kept within
1402 a single file. The generic support is provided by several other files.
1403 The processor specific support provides a set of function pointers and
1404 constants used by the generic support.
1407 * BFD ELF sections and segments:: ELF sections and segments
1408 * BFD ELF generic support:: BFD ELF generic support
1409 * BFD ELF processor specific support:: BFD ELF processor specific support
1410 * BFD ELF core files:: BFD ELF core files
1411 * BFD ELF future:: BFD ELF future
1414 @node BFD ELF sections and segments
1415 @subsection ELF sections and segments
1417 The ELF ABI permits a file to have either sections or segments or both.
1418 Relocatable object files conventionally have only sections.
1419 Executables conventionally have both. Core files conventionally have
1420 only program segments.
1422 ELF sections are similar to sections in other object file formats: they
1423 have a name, a VMA, file contents, flags, and other miscellaneous
1424 information. ELF relocations are stored in sections of a particular
1425 type; BFD automatically converts these sections into internal relocation
1428 ELF program segments are intended for fast interpretation by a system
1429 loader. They have a type, a VMA, an LMA, file contents, and a couple of
1430 other fields. When an ELF executable is run on a Unix system, the
1431 system loader will examine the program segments to decide how to load
1432 it. The loader will ignore the section information. Loadable program
1433 segments (type @samp{PT_LOAD}) are directly loaded into memory. Other
1434 program segments are interpreted by the loader, and generally provide
1435 dynamic linking information.
1437 When an ELF file has both program segments and sections, an ELF program
1438 segment may encompass one or more ELF sections, in the sense that the
1439 portion of the file which corresponds to the program segment may include
1440 the portions of the file corresponding to one or more sections. When
1441 there is more than one section in a loadable program segment, the
1442 relative positions of the section contents in the file must correspond
1443 to the relative positions they should hold when the program segment is
1444 loaded. This requirement should be obvious if you consider that the
1445 system loader will load an entire program segment at a time.
1447 On a system which supports dynamic paging, such as any native Unix
1448 system, the contents of a loadable program segment must be at the same
1449 offset in the file as in memory, modulo the memory page size used on the
1450 system. This is because the system loader will map the file into memory
1451 starting at the start of a page. The system loader can easily remap
1452 entire pages to the correct load address. However, if the contents of
1453 the file were not correctly aligned within the page, the system loader
1454 would have to shift the contents around within the page, which is too
1455 expensive. For example, if the LMA of a loadable program segment is
1456 @samp{0x40080} and the page size is @samp{0x1000}, then the position of
1457 the segment contents within the file must equal @samp{0x80} modulo
1460 BFD has only a single set of sections. It does not provide any generic
1461 way to examine both sections and segments. When BFD is used to open an
1462 object file or executable, the BFD sections will represent ELF sections.
1463 When BFD is used to open a core file, the BFD sections will represent
1464 ELF program segments.
1466 When BFD is used to examine an object file or executable, any program
1467 segments will be read to set the LMA of the sections. This is because
1468 ELF sections only have a VMA, while ELF program segments have both a VMA
1469 and an LMA. Any program segments will be copied by the
1470 @samp{copy_private} entry points. They will be printed by the
1471 @samp{print_private} entry point. Otherwise, the program segments are
1472 ignored. In particular, programs which use BFD currently have no direct
1473 access to the program segments.
1475 When BFD is used to create an executable, the program segments will be
1476 created automatically based on the section information. This is done in
1477 the function @samp{assign_file_positions_for_segments} in @file{elf.c}.
1478 This function has been tweaked many times, and probably still has
1479 problems that arise in particular cases.
1481 There is a hook which may be used to explicitly define the program
1482 segments when creating an executable: the @samp{bfd_record_phdr}
1483 function in @file{bfd.c}. If this function is called, BFD will not
1484 create program segments itself, but will only create the program
1485 segments specified by the caller. The linker uses this function to
1486 implement the @samp{PHDRS} linker script command.
1488 @node BFD ELF generic support
1489 @subsection BFD ELF generic support
1491 In general, functions which do not read external data from the ELF file
1492 are found in @file{elf.c}. They operate on the internal forms of the
1493 ELF structures, which are defined in @file{include/elf/internal.h}. The
1494 internal structures are defined in terms of @samp{bfd_vma}, and so may
1495 be used for both 32 bit and 64 bit ELF targets.
1497 The file @file{elfcode.h} contains functions which operate on the
1498 external data. @file{elfcode.h} is compiled twice, once via
1499 @file{elf32.c} with @samp{ARCH_SIZE} defined as @samp{32}, and once via
1500 @file{elf64.c} with @samp{ARCH_SIZE} defined as @samp{64}.
1501 @file{elfcode.h} includes functions to swap the ELF structures in and
1502 out of external form, as well as a few more complex functions.
1504 Linker support is found in @file{elflink.c}. The
1505 linker support is only used if the processor specific file defines
1506 @samp{elf_backend_relocate_section}, which is required to relocate the
1507 section contents. If that macro is not defined, the generic linker code
1508 is used, and relocations are handled via @samp{bfd_perform_relocation}.
1510 The core file support is in @file{elfcore.h}, which is compiled twice,
1511 for both 32 and 64 bit support. The more interesting cases of core file
1512 support only work on a native system which has the @file{sys/procfs.h}
1513 header file. Without that file, the core file support does little more
1514 than read the ELF program segments as BFD sections.
1516 The BFD internal header file @file{elf-bfd.h} is used for communication
1517 among these files and the processor specific files.
1519 The default entries for the BFD ELF target vector are found mainly in
1520 @file{elf.c}. Some functions are found in @file{elfcode.h}.
1522 The processor specific files may override particular entries in the
1523 target vector, but most do not, with one exception: the
1524 @samp{bfd_reloc_type_lookup} entry point is always processor specific.
1526 @node BFD ELF processor specific support
1527 @subsection BFD ELF processor specific support
1529 By convention, the processor specific support for a particular processor
1530 will be found in @file{elf@var{nn}-@var{cpu}.c}, where @var{nn} is
1531 either 32 or 64, and @var{cpu} is the name of the processor.
1534 * BFD ELF processor required:: Required processor specific support
1535 * BFD ELF processor linker:: Processor specific linker support
1536 * BFD ELF processor other:: Other processor specific support options
1539 @node BFD ELF processor required
1540 @subsubsection Required processor specific support
1542 When writing a @file{elf@var{nn}-@var{cpu}.c} file, you must do the
1547 Define either @samp{TARGET_BIG_SYM} or @samp{TARGET_LITTLE_SYM}, or
1548 both, to a unique C name to use for the target vector. This name should
1549 appear in the list of target vectors in @file{targets.c}, and will also
1550 have to appear in @file{config.bfd} and @file{configure.in}. Define
1551 @samp{TARGET_BIG_SYM} for a big-endian processor,
1552 @samp{TARGET_LITTLE_SYM} for a little-endian processor, and define both
1553 for a bi-endian processor.
1555 Define either @samp{TARGET_BIG_NAME} or @samp{TARGET_LITTLE_NAME}, or
1556 both, to a string used as the name of the target vector. This is the
1557 name which a user of the BFD tool would use to specify the object file
1558 format. It would normally appear in a linker emulation parameters
1561 Define @samp{ELF_ARCH} to the BFD architecture (an element of the
1562 @samp{bfd_architecture} enum, typically @samp{bfd_arch_@var{cpu}}).
1564 Define @samp{ELF_MACHINE_CODE} to the magic number which should appear
1565 in the @samp{e_machine} field of the ELF header. As of this writing,
1566 these magic numbers are assigned by Caldera; if you want to get a magic
1567 number for a particular processor, try sending a note to
1568 @email{registry@@caldera.com}. In the BFD sources, the magic numbers are
1569 found in @file{include/elf/common.h}; they have names beginning with
1572 Define @samp{ELF_MAXPAGESIZE} to the maximum size of a virtual page in
1573 memory. This can normally be found at the start of chapter 5 in the
1574 processor specific supplement. For a processor which will only be used
1575 in an embedded system, or which has no memory management hardware, this
1576 can simply be @samp{1}.
1578 If the format should use @samp{Rel} rather than @samp{Rela} relocations,
1579 define @samp{USE_REL}. This is normally defined in chapter 4 of the
1580 processor specific supplement.
1582 In the absence of a supplement, it's easier to work with @samp{Rela}
1583 relocations. @samp{Rela} relocations will require more space in object
1584 files (but not in executables, except when using dynamic linking).
1585 However, this is outweighed by the simplicity of addend handling when
1586 using @samp{Rela} relocations. With @samp{Rel} relocations, the addend
1587 must be stored in the section contents, which makes relocatable links
1590 For example, consider C code like @code{i = a[1000];} where @samp{a} is
1591 a global array. The instructions which load the value of @samp{a[1000]}
1592 will most likely use a relocation which refers to the symbol
1593 representing @samp{a}, with an addend that gives the offset from the
1594 start of @samp{a} to element @samp{1000}. When using @samp{Rel}
1595 relocations, that addend must be stored in the instructions themselves.
1596 If you are adding support for a RISC chip which uses two or more
1597 instructions to load an address, then the addend may not fit in a single
1598 instruction, and will have to be somehow split among the instructions.
1599 This makes linking awkward, particularly when doing a relocatable link
1600 in which the addend may have to be updated. It can be done---the MIPS
1601 ELF support does it---but it should be avoided when possible.
1603 It is possible, though somewhat awkward, to support both @samp{Rel} and
1604 @samp{Rela} relocations for a single target; @file{elf64-mips.c} does it
1605 by overriding the relocation reading and writing routines.
1607 Define howto structures for all the relocation types.
1609 Define a @samp{bfd_reloc_type_lookup} routine. This must be named
1610 @samp{bfd_elf@var{nn}_bfd_reloc_type_lookup}, and may be either a
1611 function or a macro. It must translate a BFD relocation code into a
1612 howto structure. This is normally a table lookup or a simple switch.
1614 If using @samp{Rel} relocations, define @samp{elf_info_to_howto_rel}.
1615 If using @samp{Rela} relocations, define @samp{elf_info_to_howto}.
1616 Either way, this is a macro defined as the name of a function which
1617 takes an @samp{arelent} and a @samp{Rel} or @samp{Rela} structure, and
1618 sets the @samp{howto} field of the @samp{arelent} based on the
1619 @samp{Rel} or @samp{Rela} structure. This is normally uses
1620 @samp{ELF@var{nn}_R_TYPE} to get the ELF relocation type and uses it as
1621 an index into a table of howto structures.
1624 You must also add the magic number for this processor to the
1625 @samp{prep_headers} function in @file{elf.c}.
1627 You must also create a header file in the @file{include/elf} directory
1628 called @file{@var{cpu}.h}. This file should define any target specific
1629 information which may be needed outside of the BFD code. In particular
1630 it should use the @samp{START_RELOC_NUMBERS}, @samp{RELOC_NUMBER},
1631 @samp{FAKE_RELOC}, @samp{EMPTY_RELOC} and @samp{END_RELOC_NUMBERS}
1632 macros to create a table mapping the number used to identify a
1633 relocation to a name describing that relocation.
1635 While not a BFD component, you probably also want to make the binutils
1636 program @samp{readelf} parse your ELF objects. For this, you need to add
1637 code for @code{EM_@var{cpu}} as appropriate in @file{binutils/readelf.c}.
1639 @node BFD ELF processor linker
1640 @subsubsection Processor specific linker support
1642 The linker will be much more efficient if you define a relocate section
1643 function. This will permit BFD to use the ELF specific linker support.
1645 If you do not define a relocate section function, BFD must use the
1646 generic linker support, which requires converting all symbols and
1647 relocations into BFD @samp{asymbol} and @samp{arelent} structures. In
1648 this case, relocations will be handled by calling
1649 @samp{bfd_perform_relocation}, which will use the howto structures you
1650 have defined. @xref{BFD relocation handling}.
1652 In order to support linking into a different object file format, such as
1653 S-records, @samp{bfd_perform_relocation} must work correctly with your
1654 howto structures, so you can't skip that step. However, if you define
1655 the relocate section function, then in the normal case of linking into
1656 an ELF file the linker will not need to convert symbols and relocations,
1657 and will be much more efficient.
1659 To use a relocation section function, define the macro
1660 @samp{elf_backend_relocate_section} as the name of a function which will
1661 take the contents of a section, as well as relocation, symbol, and other
1662 information, and modify the section contents according to the relocation
1663 information. In simple cases, this is little more than a loop over the
1664 relocations which computes the value of each relocation and calls
1665 @samp{_bfd_final_link_relocate}. The function must check for a
1666 relocatable link, and in that case normally needs to do nothing other
1667 than adjust the addend for relocations against a section symbol.
1669 The complex cases generally have to do with dynamic linker support. GOT
1670 and PLT relocations must be handled specially, and the linker normally
1671 arranges to set up the GOT and PLT sections while handling relocations.
1672 When generating a shared library, random relocations must normally be
1673 copied into the shared library, or converted to RELATIVE relocations
1676 @node BFD ELF processor other
1677 @subsubsection Other processor specific support options
1679 There are many other macros which may be defined in
1680 @file{elf@var{nn}-@var{cpu}.c}. These macros may be found in
1681 @file{elfxx-target.h}.
1683 Macros may be used to override some of the generic ELF target vector
1686 Several processor specific hook functions which may be defined as
1687 macros. These functions are found as function pointers in the
1688 @samp{elf_backend_data} structure defined in @file{elf-bfd.h}. In
1689 general, a hook function is set by defining a macro
1690 @samp{elf_backend_@var{name}}.
1692 There are a few processor specific constants which may also be defined.
1693 These are again found in the @samp{elf_backend_data} structure.
1695 I will not define the various functions and constants here; see the
1696 comments in @file{elf-bfd.h}.
1698 Normally any odd characteristic of a particular ELF processor is handled
1699 via a hook function. For example, the special @samp{SHN_MIPS_SCOMMON}
1700 section number found in MIPS ELF is handled via the hooks
1701 @samp{section_from_bfd_section}, @samp{symbol_processing},
1702 @samp{add_symbol_hook}, and @samp{output_symbol_hook}.
1704 Dynamic linking support, which involves processor specific relocations
1705 requiring special handling, is also implemented via hook functions.
1707 @node BFD ELF core files
1708 @subsection BFD ELF core files
1709 @cindex elf core files
1711 On native ELF Unix systems, core files are generated without any
1712 sections. Instead, they only have program segments.
1714 When BFD is used to read an ELF core file, the BFD sections will
1715 actually represent program segments. Since ELF program segments do not
1716 have names, BFD will invent names like @samp{segment@var{n}} where
1717 @var{n} is a number.
1719 A single ELF program segment may include both an initialized part and an
1720 uninitialized part. The size of the initialized part is given by the
1721 @samp{p_filesz} field. The total size of the segment is given by the
1722 @samp{p_memsz} field. If @samp{p_memsz} is larger than @samp{p_filesz},
1723 then the extra space is uninitialized, or, more precisely, initialized
1726 BFD will represent such a program segment as two different sections.
1727 The first, named @samp{segment@var{n}a}, will represent the initialized
1728 part of the program segment. The second, named @samp{segment@var{n}b},
1729 will represent the uninitialized part.
1731 ELF core files store special information such as register values in
1732 program segments with the type @samp{PT_NOTE}. BFD will attempt to
1733 interpret the information in these segments, and will create additional
1734 sections holding the information. Some of this interpretation requires
1735 information found in the host header file @file{sys/procfs.h}, and so
1736 will only work when BFD is built on a native system.
1738 BFD does not currently provide any way to create an ELF core file. In
1739 general, BFD does not provide a way to create core files. The way to
1740 implement this would be to write @samp{bfd_set_format} and
1741 @samp{bfd_write_contents} routines for the @samp{bfd_core} type; see
1742 @ref{BFD target vector format}.
1744 @node BFD ELF future
1745 @subsection BFD ELF future
1747 The current dynamic linking support has too much code duplication.
1748 While each processor has particular differences, much of the dynamic
1749 linking support is quite similar for each processor. The GOT and PLT
1750 are handled in fairly similar ways, the details of -Bsymbolic linking
1751 are generally similar, etc. This code should be reworked to use more
1752 generic functions, eliminating the duplication.
1754 Similarly, the relocation handling has too much duplication. Many of
1755 the @samp{reloc_type_lookup} and @samp{info_to_howto} functions are
1756 quite similar. The relocate section functions are also often quite
1757 similar, both in the standard linker handling and the dynamic linker
1758 handling. Many of the COFF processor specific backends share a single
1759 relocate section function (@samp{_bfd_coff_generic_relocate_section}),
1760 and it should be possible to do something like this for the ELF targets
1763 The appearance of the processor specific magic number in
1764 @samp{prep_headers} in @file{elf.c} is somewhat bogus. It should be
1765 possible to add support for a new processor without changing the generic
1768 The processor function hooks and constants are ad hoc and need better
1772 @section BFD glossary
1773 @cindex glossary for bfd
1774 @cindex bfd glossary
1776 This is a short glossary of some BFD terms.
1780 The a.out object file format. The original Unix object file format.
1781 Still used on SunOS, though not Solaris. Supports only three sections.
1784 A collection of object files produced and manipulated by the @samp{ar}
1788 The implementation within BFD of a particular object file format. The
1789 set of functions which appear in a particular target vector.
1792 The BFD library itself. Also, each object file, archive, or executable
1793 opened by the BFD library has the type @samp{bfd *}, and is sometimes
1794 referred to as a bfd.
1797 The Common Object File Format. Used on Unix SVR3. Used by some
1798 embedded targets, although ELF is normally better.
1801 A shared library on Windows.
1803 @item dynamic linker
1804 When a program linked against a shared library is run, the dynamic
1805 linker will locate the appropriate shared library and arrange to somehow
1806 include it in the running image.
1808 @item dynamic object
1809 Another name for an ELF shared library.
1812 The Extended Common Object File Format. Used on Alpha Digital Unix
1813 (formerly OSF/1), as well as Ultrix and Irix 4. A variant of COFF.
1816 The Executable and Linking Format. The object file format used on most
1817 modern Unix systems, including GNU/Linux, Solaris, Irix, and SVR4. Also
1818 used on many embedded systems.
1821 A program, with instructions and symbols, and perhaps dynamic linking
1822 information. Normally produced by a linker.
1825 Load Memory Address. This is the address at which a section will be
1826 loaded. Compare with VMA, below.
1829 NetWare Loadable Module. Used to describe the format of an object which
1830 be loaded into NetWare, which is some kind of PC based network server
1834 A binary file including machine instructions, symbols, and relocation
1835 information. Normally produced by an assembler.
1837 @item object file format
1838 The format of an object file. Typically object files and executables
1839 for a particular system are in the same format, although executables
1840 will not contain any relocation information.
1843 The Portable Executable format. This is the object file format used for
1844 Windows (specifically, Win32) object files. It is based closely on
1845 COFF, but has a few significant differences.
1848 The Portable Executable Image format. This is the object file format
1849 used for Windows (specifically, Win32) executables. It is very similar
1850 to PE, but includes some additional header information.
1853 Information used by the linker to adjust section contents. Also called
1857 Object files and executable are composed of sections. Sections have
1858 optional data and optional relocation information.
1860 @item shared library
1861 A library of functions which may be used by many executables without
1862 actually being linked into each executable. There are several different
1863 implementations of shared libraries, each having slightly different
1867 Each object file and executable may have a list of symbols, often
1868 referred to as the symbol table. A symbol is basically a name and an
1869 address. There may also be some additional information like the type of
1870 symbol, although the type of a symbol is normally something simple like
1871 function or object, and should be confused with the more complex C
1872 notion of type. Typically every global function and variable in a C
1873 program will have an associated symbol.
1876 A set of functions which implement support for a particular object file
1877 format. The @samp{bfd_target} structure.
1880 The current Windows API, implemented by Windows 95 and later and Windows
1881 NT 3.51 and later, but not by Windows 3.1.
1884 The eXtended Common Object File Format. Used on AIX. A variant of
1885 COFF, with a completely different symbol table implementation.
1888 Virtual Memory Address. This is the address a section will have when
1889 an executable is run. Compare with LMA, above.
1893 @unnumberedsec Index