2 @c Copyright (C) 1988-2023 Free Software Foundation, Inc.
3 @setfilename bfdint.info
5 @settitle BFD Internals
9 @author{Ian Lance Taylor}
10 @author{Cygnus Solutions}
15 This file documents the internals of the BFD library.
17 Copyright @copyright{} 1988-2023 Free Software Foundation, Inc.
18 Contributed by Cygnus Support.
20 Permission is granted to copy, distribute and/or modify this document
21 under the terms of the GNU Free Documentation License, Version 1.1 or
22 any later version published by the Free Software Foundation; with the
23 Invariant Sections being ``GNU General Public License'' and ``Funding
24 Free Software'', the Front-Cover texts being (a) (see below), and with
25 the Back-Cover Texts being (b) (see below). A copy of the license is
26 included in the section entitled ``GNU Free Documentation License''.
28 (a) The FSF's Front-Cover Text is:
32 (b) The FSF's Back-Cover Text is:
34 You have freedom to copy and modify this GNU Manual, like GNU
35 software. Copies published by the Free Software Foundation raise
36 funds for GNU development.
44 This document describes some BFD internal information which may be
45 helpful when working on BFD. It is very incomplete.
47 This document is not updated regularly, and may be out of date.
49 The initial version of this document was written by Ian Lance Taylor
50 @email{ian@@cygnus.com}.
53 * BFD overview:: BFD overview
54 * BFD guidelines:: BFD programming guidelines
55 * BFD target vector:: BFD target vector
56 * BFD generated files:: BFD generated files
57 * BFD multiple compilations:: Files compiled multiple times in BFD
58 * BFD relocation handling:: BFD relocation handling
59 * BFD ELF support:: BFD ELF support
60 * BFD glossary:: Glossary
67 BFD is a library which provides a single interface to read and write
68 object files, executables, archive files, and core files in any format.
71 * BFD library interfaces:: BFD library interfaces
72 * BFD library users:: BFD library users
73 * BFD view:: The BFD view of a file
74 * BFD blindness:: BFD loses information
77 @node BFD library interfaces
78 @subsection BFD library interfaces
80 One way to look at the BFD library is to divide it into four parts by
83 The first interface is the set of generic functions which programs using
84 the BFD library will call. These generic function normally translate
85 directly or indirectly into calls to routines which are specific to a
86 particular object file format. Many of these generic functions are
87 actually defined as macros in @file{bfd.h}. These functions comprise
88 the official BFD interface.
90 The second interface is the set of functions which appear in the target
91 vectors. This is the bulk of the code in BFD. A target vector is a set
92 of function pointers specific to a particular object file format. The
93 target vector is used to implement the generic BFD functions. These
94 functions are always called through the target vector, and are never
95 called directly. The target vector is described in detail in @ref{BFD
96 target vector}. The set of functions which appear in a particular
97 target vector is often referred to as a BFD backend.
99 The third interface is a set of oddball functions which are typically
100 specific to a particular object file format, are not generic functions,
101 and are called from outside of the BFD library. These are used as hooks
102 by the linker and the assembler when a particular object file format
103 requires some action which the BFD generic interface does not provide.
104 These functions are typically declared in @file{bfd.h}, but in many
105 cases they are only provided when BFD is configured with support for a
106 particular object file format. These functions live in a grey area, and
107 are not really part of the official BFD interface.
109 The fourth interface is the set of BFD support functions which are
110 called by the other BFD functions. These manage issues like memory
111 allocation, error handling, file access, hash tables, swapping, and the
112 like. These functions are never called from outside of the BFD library.
114 @node BFD library users
115 @subsection BFD library users
117 Another way to look at the BFD library is to divide it into three parts
118 by the manner in which it is used.
120 The first use is to read an object file. The object file readers are
121 programs like @samp{gdb}, @samp{nm}, @samp{objdump}, and @samp{objcopy}.
122 These programs use BFD to view an object file in a generic form. The
123 official BFD interface is normally fully adequate for these programs.
125 The second use is to write an object file. The object file writers are
126 programs like @samp{gas} and @samp{objcopy}. These programs use BFD to
127 create an object file. The official BFD interface is normally adequate
128 for these programs, but for some object file formats the assembler needs
129 some additional hooks in order to set particular flags or other
130 information. The official BFD interface includes functions to copy
131 private information from one object file to another, and these functions
132 are used by @samp{objcopy} to avoid information loss.
134 The third use is to link object files. There is only one object file
135 linker, @samp{ld}. Originally, @samp{ld} was an object file reader and
136 an object file writer, and it did the link operation using the generic
137 BFD structures. However, this turned out to be too slow and too memory
140 The official BFD linker functions were written to permit specific BFD
141 backends to perform the link without translating through the generic
142 structures, in the normal case where all the input files and output file
143 have the same object file format. Not all of the backends currently
144 implement the new interface, and there are default linking functions
145 within BFD which use the generic structures and which work with all
148 For several object file formats the linker needs additional hooks which
149 are not provided by the official BFD interface, particularly for dynamic
150 linking support. These functions are typically called from the linker
154 @subsection The BFD view of a file
156 BFD uses generic structures to manage information. It translates data
157 into the generic form when reading files, and out of the generic form
160 BFD describes a file as a pointer to the @samp{bfd} type. A @samp{bfd}
161 is composed of the following elements. The BFD information can be
162 displayed using the @samp{objdump} program with various options.
165 @item general information
166 The object file format, a few general flags, the start address.
168 The architecture, including both a general processor type (m68k, MIPS
169 etc.) and a specific machine number (m68000, R4000, etc.).
176 BFD represents a section as a pointer to the @samp{asection} type. Each
177 section has a name and a size. Most sections also have an associated
178 block of data, known as the section contents. Sections also have
179 associated flags, a virtual memory address, a load memory address, a
180 required alignment, a list of relocations, and other miscellaneous
183 BFD represents a relocation as a pointer to the @samp{arelent} type. A
184 relocation describes an action which the linker must take to modify the
185 section contents. Relocations have a symbol, an address, an addend, and
186 a pointer to a howto structure which describes how to perform the
187 relocation. For more information, see @ref{BFD relocation handling}.
189 BFD represents a symbol as a pointer to the @samp{asymbol} type. A
190 symbol has a name, a pointer to a section, an offset within that
191 section, and some flags.
193 Archive files do not have any sections or symbols. Instead, BFD
194 represents an archive file as a file which contains a list of
195 @samp{bfd}s. BFD also provides access to the archive symbol map, as a
196 list of symbol names. BFD provides a function to return the @samp{bfd}
197 within the archive which corresponds to a particular entry in the
201 @subsection BFD loses information
203 Most object file formats have information which BFD can not represent in
204 its generic form, at least as currently defined.
206 There is often explicit information which BFD can not represent. For
207 example, the COFF version stamp, or the ELF program segments. BFD
208 provides special hooks to handle this information when copying,
209 printing, or linking an object file. The BFD support for a particular
210 object file format will normally store this information in private data
211 and handle it using the special hooks.
213 In some cases there is also implicit information which BFD can not
214 represent. For example, the MIPS processor distinguishes small and
215 large symbols, and requires that all small symbols be within 32K of the
216 GP register. This means that the MIPS assembler must be able to mark
217 variables as either small or large, and the MIPS linker must know to put
218 small symbols within range of the GP register. Since BFD can not
219 represent this information, this means that the assembler and linker
220 must have information that is specific to a particular object file
221 format which is outside of the BFD library.
223 This loss of information indicates areas where the BFD paradigm breaks
224 down. It is not actually possible to represent the myriad differences
225 among object file formats using a single generic interface, at least not
226 in the manner which BFD does it today.
228 Nevertheless, the BFD library does greatly simplify the task of dealing
229 with object files, and particular problems caused by information loss
230 can normally be solved using some sort of relatively constrained hook
236 @section BFD programming guidelines
237 @cindex bfd programming guidelines
238 @cindex programming guidelines for bfd
239 @cindex guidelines, bfd programming
241 There is a lot of poorly written and confusing code in BFD. New BFD
242 code should be written to a higher standard. Merely because some BFD
243 code is written in a particular manner does not mean that you should
246 Here are some general BFD programming guidelines:
250 Follow the GNU coding standards.
253 Avoid global variables. We ideally want BFD to be fully reentrant, so
254 that it can be used in multiple threads. All uses of global or static
255 variables interfere with that. Initialized constant variables are OK,
256 and they should be explicitly marked with @samp{const}. Instead of global
257 variables, use data attached to a BFD or to a linker hash table.
260 All externally visible functions should have names which start with
261 @samp{bfd_}. All such functions should be declared in some header file,
262 typically @file{bfd.h}. See, for example, the various declarations near
263 the end of @file{bfd-in.h}, which mostly declare functions required by
264 specific linker emulations.
267 All functions which need to be visible from one file to another within
268 BFD, but should not be visible outside of BFD, should start with
269 @samp{_bfd_}. Although external names beginning with @samp{_} are
270 prohibited by the ANSI standard, in practice this usage will always
271 work, and it is required by the GNU coding standards.
274 Always remember that people can compile using @samp{--enable-targets} to
275 build several, or all, targets at once. It must be possible to link
276 together the files for all targets.
279 BFD code should compile with few or no warnings using @samp{gcc -Wall}.
280 Some warnings are OK, like the absence of certain function declarations
281 which may or may not be declared in system header files. Warnings about
282 ambiguous expressions and the like should always be fixed.
285 @node BFD target vector
286 @section BFD target vector
287 @cindex bfd target vector
288 @cindex target vector in bfd
290 BFD supports multiple object file formats by using the @dfn{target
291 vector}. This is simply a set of function pointers which implement
292 behaviour that is specific to a particular object file format.
294 In this section I list all of the entries in the target vector and
295 describe what they do.
298 * BFD target vector miscellaneous:: Miscellaneous constants
299 * BFD target vector swap:: Swapping functions
300 * BFD target vector format:: Format type dependent functions
301 * BFD_JUMP_TABLE macros:: BFD_JUMP_TABLE macros
302 * BFD target vector generic:: Generic functions
303 * BFD target vector copy:: Copy functions
304 * BFD target vector core:: Core file support functions
305 * BFD target vector archive:: Archive functions
306 * BFD target vector symbols:: Symbol table functions
307 * BFD target vector relocs:: Relocation support
308 * BFD target vector write:: Output functions
309 * BFD target vector link:: Linker functions
310 * BFD target vector dynamic:: Dynamic linking information functions
313 @node BFD target vector miscellaneous
314 @subsection Miscellaneous constants
316 The target vector starts with a set of constants.
320 The name of the target vector. This is an arbitrary string. This is
321 how the target vector is named in command-line options for tools which
322 use BFD, such as the @samp{--oformat} linker option.
325 A general description of the type of target. The following flavours are
329 @item bfd_target_unknown_flavour
330 Undefined or unknown.
331 @item bfd_target_aout_flavour
333 @item bfd_target_coff_flavour
335 @item bfd_target_ecoff_flavour
337 @item bfd_target_elf_flavour
339 @item bfd_target_tekhex_flavour
340 Tektronix hex format.
341 @item bfd_target_srec_flavour
342 Motorola S-record format.
343 @item bfd_target_ihex_flavour
345 @item bfd_target_som_flavour
347 @item bfd_target_verilog_flavour
348 Verilog memory hex dump format.
349 @item bfd_target_msdos_flavour
351 @item bfd_target_evax_flavour
353 @item bfd_target_mmo_flavour
354 Donald Knuth's MMIXware object format.
358 The byte order of data in the object file. One of
359 @samp{BFD_ENDIAN_BIG}, @samp{BFD_ENDIAN_LITTLE}, or
360 @samp{BFD_ENDIAN_UNKNOWN}. The latter would be used for a format such
361 as S-records which do not record the architecture of the data.
363 @item header_byteorder
364 The byte order of header information in the object file. Normally the
365 same as the @samp{byteorder} field, but there are certain cases where it
369 Flags which may appear in the @samp{flags} field of a BFD with this
373 Flags which may appear in the @samp{flags} field of a section within a
374 BFD with this format.
376 @item symbol_leading_char
377 A character which the C compiler normally puts before a symbol. For
378 example, an a.out compiler will typically generate the symbol
379 @samp{_foo} for a function named @samp{foo} in the C source, in which
380 case this field would be @samp{_}. If there is no such character, this
381 field will be @samp{0}.
384 The padding character to use at the end of an archive name. Normally
388 The maximum length of a short name in an archive. Normally @samp{14}.
391 A pointer to constant backend data. This is used by backends to store
392 whatever additional information they need to distinguish similar target
393 vectors which use the same sets of functions.
396 @node BFD target vector swap
397 @subsection Swapping functions
399 Every target vector has function pointers used for swapping information
400 in and out of the target representation. There are two sets of
401 functions: one for data information, and one for header information.
402 Each set has three sizes: 64-bit, 32-bit, and 16-bit. Each size has
403 three actual functions: put, get unsigned, and get signed.
405 These 18 functions are used to convert data between the host and target
408 @node BFD target vector format
409 @subsection Format type dependent functions
411 Every target vector has three arrays of function pointers which are
412 indexed by the BFD format type. The BFD format types are as follows:
416 Unknown format. Not used for anything useful.
425 The three arrays of function pointers are as follows:
428 @item bfd_check_format
429 Check whether the BFD is of a particular format (object file, archive
430 file, or core file) corresponding to this target vector. This is called
431 by the @samp{bfd_check_format} function when examining an existing BFD.
432 If the BFD matches the desired format, this function will initialize any
433 format specific information such as the @samp{tdata} field of the BFD.
434 This function must be called before any other BFD target vector function
435 on a file opened for reading.
438 Set the format of a BFD which was created for output. This is called by
439 the @samp{bfd_set_format} function after creating the BFD with a
440 function such as @samp{bfd_openw}. This function will initialize format
441 specific information required to write out an object file or whatever of
442 the given format. This function must be called before any other BFD
443 target vector function on a file opened for writing.
445 @item bfd_write_contents
446 Write out the contents of the BFD in the given format. This is called
447 by @samp{bfd_close} function for a BFD opened for writing. This really
448 should not be an array selected by format type, as the
449 @samp{bfd_set_format} function provides all the required information.
450 In fact, BFD will fail if a different format is used when calling
451 through the @samp{bfd_set_format} and the @samp{bfd_write_contents}
452 arrays; fortunately, since @samp{bfd_close} gets it right, this is a
453 difficult error to make.
456 @node BFD_JUMP_TABLE macros
457 @subsection @samp{BFD_JUMP_TABLE} macros
458 @cindex @samp{BFD_JUMP_TABLE}
460 Most target vectors are defined using @samp{BFD_JUMP_TABLE} macros.
461 These macros take a single argument, which is a prefix applied to a set
462 of functions. The macros are then used to initialize the fields in the
465 For example, the @samp{BFD_JUMP_TABLE_RELOCS} macro defines three
466 functions: @samp{_get_reloc_upper_bound}, @samp{_canonicalize_reloc},
467 and @samp{_bfd_reloc_type_lookup}. A reference like
468 @samp{BFD_JUMP_TABLE_RELOCS (foo)} will expand into three functions
469 prefixed with @samp{foo}: @samp{foo_get_reloc_upper_bound}, etc. The
470 @samp{BFD_JUMP_TABLE_RELOCS} macro will be placed such that those three
471 functions initialize the appropriate fields in the BFD target vector.
473 This is done because it turns out that many different target vectors can
474 share certain classes of functions. For example, archives are similar
475 on most platforms, so most target vectors can use the same archive
476 functions. Those target vectors all use @samp{BFD_JUMP_TABLE_ARCHIVE}
477 with the same argument, calling a set of functions which is defined in
480 Each of the @samp{BFD_JUMP_TABLE} macros is mentioned below along with
481 the description of the function pointers which it defines. The function
482 pointers will be described using the name without the prefix which the
483 @samp{BFD_JUMP_TABLE} macro defines. This name is normally the same as
484 the name of the field in the target vector structure. Any differences
487 @node BFD target vector generic
488 @subsection Generic functions
489 @cindex @samp{BFD_JUMP_TABLE_GENERIC}
491 The @samp{BFD_JUMP_TABLE_GENERIC} macro is used for some catch all
492 functions which don't easily fit into other categories.
495 @item _close_and_cleanup
496 Free any target specific information associated with the BFD. This is
497 called when any BFD is closed (the @samp{bfd_write_contents} function
498 mentioned earlier is only called for a BFD opened for writing). Most
499 targets use @samp{bfd_alloc} to allocate all target specific
500 information, and therefore don't have to do anything in this function.
501 This function pointer is typically set to
502 @samp{_bfd_generic_close_and_cleanup}, which simply returns true.
504 @item _bfd_free_cached_info
505 Free any cached information associated with the BFD which can be
506 recreated later if necessary. This is used to reduce the memory
507 consumption required by programs using BFD. This is normally called via
508 the @samp{bfd_free_cached_info} macro. It is used by the default
509 archive routines when computing the archive map. Most targets do not
510 do anything special for this entry point, and just set it to
511 @samp{_bfd_generic_free_cached_info}, which simply returns true.
513 @item _new_section_hook
514 This is called from @samp{bfd_make_section_anyway} whenever a new
515 section is created. Most targets use it to initialize section specific
516 information. This function is called whether or not the section
517 corresponds to an actual section in an actual BFD.
519 @item _get_section_contents
520 Get the contents of a section. This is called from
521 @samp{bfd_get_section_contents}. Most targets set this to
522 @samp{_bfd_generic_get_section_contents}, which does a @samp{bfd_seek}
523 based on the section's @samp{filepos} field and a @samp{bfd_bread}. The
524 corresponding field in the target vector is named
525 @samp{_bfd_get_section_contents}.
527 @item _get_section_contents_in_window
528 Set a @samp{bfd_window} to hold the contents of a section. This is
529 called from @samp{bfd_get_section_contents_in_window}. The
530 @samp{bfd_window} idea never really caught on, and I don't think this is
531 ever called. Pretty much all targets implement this as
532 @samp{bfd_generic_get_section_contents_in_window}, which uses
533 @samp{bfd_get_section_contents} to do the right thing. The
534 corresponding field in the target vector is named
535 @samp{_bfd_get_section_contents_in_window}.
538 @node BFD target vector copy
539 @subsection Copy functions
540 @cindex @samp{BFD_JUMP_TABLE_COPY}
542 The @samp{BFD_JUMP_TABLE_COPY} macro is used for functions which are
543 called when copying BFDs, and for a couple of functions which deal with
544 internal BFD information.
547 @item _bfd_copy_private_bfd_data
548 This is called when copying a BFD, via @samp{bfd_copy_private_bfd_data}.
549 If the input and output BFDs have the same format, this will copy any
550 private information over. This is called after all the section contents
551 have been written to the output file. Only a few targets do anything in
554 @item _bfd_merge_private_bfd_data
555 This is called when linking, via @samp{bfd_merge_private_bfd_data}. It
556 gives the backend linker code a chance to set any special flags in the
557 output file based on the contents of the input file. Only a few targets
558 do anything in this function.
560 @item _bfd_copy_private_section_data
561 This is similar to @samp{_bfd_copy_private_bfd_data}, but it is called
562 for each section, via @samp{bfd_copy_private_section_data}. This
563 function is called before any section contents have been written. Only
564 a few targets do anything in this function.
566 @item _bfd_copy_private_symbol_data
567 This is called via @samp{bfd_copy_private_symbol_data}, but I don't
568 think anything actually calls it. If it were defined, it could be used
569 to copy private symbol data from one BFD to another. However, most BFDs
570 store extra symbol information by allocating space which is larger than
571 the @samp{asymbol} structure and storing private information in the
572 extra space. Since @samp{objcopy} and other programs copy symbol
573 information by copying pointers to @samp{asymbol} structures, the
574 private symbol information is automatically copied as well. Most
575 targets do not do anything in this function.
577 @item _bfd_set_private_flags
578 This is called via @samp{bfd_set_private_flags}. It is basically a hook
579 for the assembler to set magic information. For example, the PowerPC
580 ELF assembler uses it to set flags which appear in the e_flags field of
581 the ELF header. Most targets do not do anything in this function.
583 @item _bfd_print_private_bfd_data
584 This is called by @samp{objdump} when the @samp{-p} option is used. It
585 is called via @samp{bfd_print_private_data}. It prints any interesting
586 information about the BFD which can not be otherwise represented by BFD
587 and thus can not be printed by @samp{objdump}. Most targets do not do
588 anything in this function.
591 @node BFD target vector core
592 @subsection Core file support functions
593 @cindex @samp{BFD_JUMP_TABLE_CORE}
595 The @samp{BFD_JUMP_TABLE_CORE} macro is used for functions which deal
596 with core files. Obviously, these functions only do something
597 interesting for targets which have core file support.
600 @item _core_file_failing_command
601 Given a core file, this returns the command which was run to produce the
604 @item _core_file_failing_signal
605 Given a core file, this returns the signal number which produced the
608 @item _core_file_matches_executable_p
609 Given a core file and a BFD for an executable, this returns whether the
610 core file was generated by the executable.
613 @node BFD target vector archive
614 @subsection Archive functions
615 @cindex @samp{BFD_JUMP_TABLE_ARCHIVE}
617 The @samp{BFD_JUMP_TABLE_ARCHIVE} macro is used for functions which deal
618 with archive files. Most targets use COFF style archive files
619 (including ELF targets), and these use @samp{_bfd_archive_coff} as the
620 argument to @samp{BFD_JUMP_TABLE_ARCHIVE}. Some targets use BSD/a.out
621 style archives, and these use @samp{_bfd_archive_bsd}. (The main
622 difference between BSD and COFF archives is the format of the archive
623 symbol table). Targets with no archive support use
624 @samp{_bfd_noarchive}. Finally, a few targets have unusual archive
629 Read in the archive symbol table, storing it in private BFD data. This
630 is normally called from the archive @samp{check_format} routine. The
631 corresponding field in the target vector is named
632 @samp{_bfd_slurp_armap}.
634 @item _slurp_extended_name_table
635 Read in the extended name table from the archive, if there is one,
636 storing it in private BFD data. This is normally called from the
637 archive @samp{check_format} routine. The corresponding field in the
638 target vector is named @samp{_bfd_slurp_extended_name_table}.
640 @item construct_extended_name_table
641 Build and return an extended name table if one is needed to write out
642 the archive. This also adjusts the archive headers to refer to the
643 extended name table appropriately. This is normally called from the
644 archive @samp{write_contents} routine. The corresponding field in the
645 target vector is named @samp{_bfd_construct_extended_name_table}.
647 @item _truncate_arname
648 This copies a file name into an archive header, truncating it as
649 required. It is normally called from the archive @samp{write_contents}
650 routine. This function is more interesting in targets which do not
651 support extended name tables, but I think the GNU @samp{ar} program
652 always uses extended name tables anyhow. The corresponding field in the
653 target vector is named @samp{_bfd_truncate_arname}.
656 Write out the archive symbol table using calls to @samp{bfd_bwrite}.
657 This is normally called from the archive @samp{write_contents} routine.
658 The corresponding field in the target vector is named @samp{write_armap}
659 (no leading underscore).
662 Read and parse an archive header. This handles expanding the archive
663 header name into the real file name using the extended name table. This
664 is called by routines which read the archive symbol table or the archive
665 itself. The corresponding field in the target vector is named
666 @samp{_bfd_read_ar_hdr_fn}.
668 @item _openr_next_archived_file
669 Given an archive and a BFD representing a file stored within the
670 archive, return a BFD for the next file in the archive. This is called
671 via @samp{bfd_openr_next_archived_file}. The corresponding field in the
672 target vector is named @samp{openr_next_archived_file} (no leading
675 @item _get_elt_at_index
676 Given an archive and an index, return a BFD for the file in the archive
677 corresponding to that entry in the archive symbol table. This is called
678 via @samp{bfd_get_elt_at_index}. The corresponding field in the target
679 vector is named @samp{_bfd_get_elt_at_index}.
681 @item _generic_stat_arch_elt
682 Do a stat on an element of an archive, returning information read from
683 the archive header (modification time, uid, gid, file mode, size). This
684 is called via @samp{bfd_stat_arch_elt}. The corresponding field in the
685 target vector is named @samp{_bfd_stat_arch_elt}.
687 @item _update_armap_timestamp
688 After the entire contents of an archive have been written out, update
689 the timestamp of the archive symbol table to be newer than that of the
690 file. This is required for a.out style archives. This is normally
691 called by the archive @samp{write_contents} routine. The corresponding
692 field in the target vector is named @samp{_bfd_update_armap_timestamp}.
695 @node BFD target vector symbols
696 @subsection Symbol table functions
697 @cindex @samp{BFD_JUMP_TABLE_SYMBOLS}
699 The @samp{BFD_JUMP_TABLE_SYMBOLS} macro is used for functions which deal
703 @item _get_symtab_upper_bound
704 Return a sensible upper bound on the amount of memory which will be
705 required to read the symbol table. In practice most targets return the
706 amount of memory required to hold @samp{asymbol} pointers for all the
707 symbols plus a trailing @samp{NULL} entry, and store the actual symbol
708 information in BFD private data. This is called via
709 @samp{bfd_get_symtab_upper_bound}. The corresponding field in the
710 target vector is named @samp{_bfd_get_symtab_upper_bound}.
712 @item _canonicalize_symtab
713 Read in the symbol table. This is called via
714 @samp{bfd_canonicalize_symtab}. The corresponding field in the target
715 vector is named @samp{_bfd_canonicalize_symtab}.
717 @item _make_empty_symbol
718 Create an empty symbol for the BFD. This is needed because most targets
719 store extra information with each symbol by allocating a structure
720 larger than an @samp{asymbol} and storing the extra information at the
721 end. This function will allocate the right amount of memory, and return
722 what looks like a pointer to an empty @samp{asymbol}. This is called
723 via @samp{bfd_make_empty_symbol}. The corresponding field in the target
724 vector is named @samp{_bfd_make_empty_symbol}.
727 Print information about the symbol. This is called via
728 @samp{bfd_print_symbol}. One of the arguments indicates what sort of
729 information should be printed:
732 @item bfd_print_symbol_name
733 Just print the symbol name.
734 @item bfd_print_symbol_more
735 Print the symbol name and some interesting flags. I don't think
736 anything actually uses this.
737 @item bfd_print_symbol_all
738 Print all information about the symbol. This is used by @samp{objdump}
739 when run with the @samp{-t} option.
741 The corresponding field in the target vector is named
742 @samp{_bfd_print_symbol}.
744 @item _get_symbol_info
745 Return a standard set of information about the symbol. This is called
746 via @samp{bfd_symbol_info}. The corresponding field in the target
747 vector is named @samp{_bfd_get_symbol_info}.
749 @item _bfd_is_local_label_name
750 Return whether the given string would normally represent the name of a
751 local label. This is called via @samp{bfd_is_local_label} and
752 @samp{bfd_is_local_label_name}. Local labels are normally discarded by
753 the assembler. In the linker, this defines the difference between the
754 @samp{-x} and @samp{-X} options.
757 Return line number information for a symbol. This is only meaningful
758 for a COFF target. This is called when writing out COFF line numbers.
760 @item _find_nearest_line
761 Given an address within a section, use the debugging information to find
762 the matching file name, function name, and line number, if any. This is
763 called via @samp{bfd_find_nearest_line}. The corresponding field in the
764 target vector is named @samp{_bfd_find_nearest_line}.
766 @item _bfd_make_debug_symbol
767 Make a debugging symbol. This is only meaningful for a COFF target,
768 where it simply returns a symbol which will be placed in the
769 @samp{N_DEBUG} section when it is written out. This is called via
770 @samp{bfd_make_debug_symbol}.
772 @item _read_minisymbols
773 Minisymbols are used to reduce the memory requirements of programs like
774 @samp{nm}. A minisymbol is a cookie pointing to internal symbol
775 information which the caller can use to extract complete symbol
776 information. This permits BFD to not convert all the symbols into
777 generic form, but to instead convert them one at a time. This is called
778 via @samp{bfd_read_minisymbols}. Most targets do not implement this,
779 and just use generic support which is based on using standard
780 @samp{asymbol} structures.
782 @item _minisymbol_to_symbol
783 Convert a minisymbol to a standard @samp{asymbol}. This is called via
784 @samp{bfd_minisymbol_to_symbol}.
787 @node BFD target vector relocs
788 @subsection Relocation support
789 @cindex @samp{BFD_JUMP_TABLE_RELOCS}
791 The @samp{BFD_JUMP_TABLE_RELOCS} macro is used for functions which deal
795 @item _get_reloc_upper_bound
796 Return a sensible upper bound on the amount of memory which will be
797 required to read the relocations for a section. In practice most
798 targets return the amount of memory required to hold @samp{arelent}
799 pointers for all the relocations plus a trailing @samp{NULL} entry, and
800 store the actual relocation information in BFD private data. This is
801 called via @samp{bfd_get_reloc_upper_bound}.
803 @item _canonicalize_reloc
804 Return the relocation information for a section. This is called via
805 @samp{bfd_canonicalize_reloc}. The corresponding field in the target
806 vector is named @samp{_bfd_canonicalize_reloc}.
808 @item _bfd_reloc_type_lookup
809 Given a relocation code, return the corresponding howto structure
810 (@pxref{BFD relocation codes}). This is called via
811 @samp{bfd_reloc_type_lookup}. The corresponding field in the target
812 vector is named @samp{reloc_type_lookup}.
815 @node BFD target vector write
816 @subsection Output functions
817 @cindex @samp{BFD_JUMP_TABLE_WRITE}
819 The @samp{BFD_JUMP_TABLE_WRITE} macro is used for functions which deal
820 with writing out a BFD.
824 Set the architecture and machine number for a BFD. This is called via
825 @samp{bfd_set_arch_mach}. Most targets implement this by calling
826 @samp{bfd_default_set_arch_mach}. The corresponding field in the target
827 vector is named @samp{_bfd_set_arch_mach}.
829 @item _set_section_contents
830 Write out the contents of a section. This is called via
831 @samp{bfd_set_section_contents}. The corresponding field in the target
832 vector is named @samp{_bfd_set_section_contents}.
835 @node BFD target vector link
836 @subsection Linker functions
837 @cindex @samp{BFD_JUMP_TABLE_LINK}
839 The @samp{BFD_JUMP_TABLE_LINK} macro is used for functions called by the
843 @item _sizeof_headers
844 Return the size of the header information required for a BFD. This is
845 used to implement the @samp{SIZEOF_HEADERS} linker script function. It
846 is normally used to align the first section at an efficient position on
847 the page. This is called via @samp{bfd_sizeof_headers}. The
848 corresponding field in the target vector is named
849 @samp{_bfd_sizeof_headers}.
851 @item _bfd_get_relocated_section_contents
852 Read the contents of a section and apply the relocation information.
853 This handles both a final link and a relocatable link; in the latter
854 case, it adjust the relocation information as well. This is called via
855 @samp{bfd_get_relocated_section_contents}. Most targets implement it by
856 calling @samp{bfd_generic_get_relocated_section_contents}.
858 @item _bfd_relax_section
859 Try to use relaxation to shrink the size of a section. This is called
860 by the linker when the @samp{-relax} option is used. This is called via
861 @samp{bfd_relax_section}. Most targets do not support any sort of
864 @item _bfd_link_hash_table_create
865 Create the symbol hash table to use for the linker. This linker hook
866 permits the backend to control the size and information of the elements
867 in the linker symbol hash table. This is called via
868 @samp{bfd_link_hash_table_create}.
870 @item _bfd_link_add_symbols
871 Given an object file or an archive, add all symbols into the linker
872 symbol hash table. Use callbacks to the linker to include archive
873 elements in the link. This is called via @samp{bfd_link_add_symbols}.
875 @item _bfd_final_link
876 Finish the linking process. The linker calls this hook after all of the
877 input files have been read, when it is ready to finish the link and
878 generate the output file. This is called via @samp{bfd_final_link}.
880 @item _bfd_link_split_section
881 I don't know what this is for. Nothing seems to call it. The only
882 non-trivial definition is in @file{som.c}.
885 @node BFD target vector dynamic
886 @subsection Dynamic linking information functions
887 @cindex @samp{BFD_JUMP_TABLE_DYNAMIC}
889 The @samp{BFD_JUMP_TABLE_DYNAMIC} macro is used for functions which read
890 dynamic linking information.
893 @item _get_dynamic_symtab_upper_bound
894 Return a sensible upper bound on the amount of memory which will be
895 required to read the dynamic symbol table. In practice most targets
896 return the amount of memory required to hold @samp{asymbol} pointers for
897 all the symbols plus a trailing @samp{NULL} entry, and store the actual
898 symbol information in BFD private data. This is called via
899 @samp{bfd_get_dynamic_symtab_upper_bound}. The corresponding field in
900 the target vector is named @samp{_bfd_get_dynamic_symtab_upper_bound}.
902 @item _canonicalize_dynamic_symtab
903 Read the dynamic symbol table. This is called via
904 @samp{bfd_canonicalize_dynamic_symtab}. The corresponding field in the
905 target vector is named @samp{_bfd_canonicalize_dynamic_symtab}.
907 @item _get_dynamic_reloc_upper_bound
908 Return a sensible upper bound on the amount of memory which will be
909 required to read the dynamic relocations. In practice most targets
910 return the amount of memory required to hold @samp{arelent} pointers for
911 all the relocations plus a trailing @samp{NULL} entry, and store the
912 actual relocation information in BFD private data. This is called via
913 @samp{bfd_get_dynamic_reloc_upper_bound}. The corresponding field in
914 the target vector is named @samp{_bfd_get_dynamic_reloc_upper_bound}.
916 @item _canonicalize_dynamic_reloc
917 Read the dynamic relocations. This is called via
918 @samp{bfd_canonicalize_dynamic_reloc}. The corresponding field in the
919 target vector is named @samp{_bfd_canonicalize_dynamic_reloc}.
922 @node BFD generated files
923 @section BFD generated files
924 @cindex generated files in bfd
925 @cindex bfd generated files
927 BFD contains several automatically generated files. This section
928 describes them. Some files are created at configure time, when you
929 configure BFD. Some files are created at make time, when you build
930 BFD. Some files are automatically rebuilt at make time, but only if
931 you configure with the @samp{--enable-maintainer-mode} option. Some
932 files live in the object directory---the directory from which you run
933 configure---and some live in the source directory. All files that live
934 in the source directory are checked into the git repository.
939 @cindex @file{bfd-in3.h}
940 Lives in the object directory. Created at make time from
941 @file{bfd-in2.h} via @file{bfd-in3.h}. @file{bfd-in3.h} is created at
942 configure time from @file{bfd-in2.h}. There are automatic dependencies
943 to rebuild @file{bfd-in3.h} and hence @file{bfd.h} if @file{bfd-in2.h}
944 changes, so you can normally ignore @file{bfd-in3.h}, and just think
945 about @file{bfd-in2.h} and @file{bfd.h}.
947 @file{bfd.h} is built by replacing a few strings in @file{bfd-in2.h}.
948 To see them, search for @samp{@@} in @file{bfd-in2.h}. They mainly
949 control whether BFD is built for a 32 bit target or a 64 bit target.
952 @cindex @file{bfd-in2.h}
953 Lives in the source directory. Created from @file{bfd-in.h} and several
954 other BFD source files. If you configure with the
955 @samp{--enable-maintainer-mode} option, @file{bfd-in2.h} is rebuilt
956 automatically when a source file changes.
959 @itemx elf64-target.h
960 @cindex @file{elf32-target.h}
961 @cindex @file{elf64-target.h}
962 Live in the object directory. Created from @file{elfxx-target.h}.
963 These files are versions of @file{elfxx-target.h} customized for either
964 a 32 bit ELF target or a 64 bit ELF target.
967 @cindex @file{libbfd.h}
968 Lives in the source directory. Created from @file{libbfd-in.h} and
969 several other BFD source files. If you configure with the
970 @samp{--enable-maintainer-mode} option, @file{libbfd.h} is rebuilt
971 automatically when a source file changes.
974 @cindex @file{libcoff.h}
975 Lives in the source directory. Created from @file{libcoff-in.h} and
976 @file{coffcode.h}. If you configure with the
977 @samp{--enable-maintainer-mode} option, @file{libcoff.h} is rebuilt
978 automatically when a source file changes.
981 @cindex @file{targmatch.h}
982 Lives in the object directory. Created at make time from
983 @file{config.bfd}. This file is used to map configuration triplets into
984 BFD target vector variable names at run time.
987 @node BFD multiple compilations
988 @section Files compiled multiple times in BFD
989 Several files in BFD are compiled multiple times. By this I mean that
990 there are header files which contain function definitions. These header
991 files are included by other files, and thus the functions are compiled
992 once per file which includes them.
994 Preprocessor macros are used to control the compilation, so that each
995 time the files are compiled the resulting functions are slightly
996 different. Naturally, if they weren't different, there would be no
997 reason to compile them multiple times.
999 This is a not a particularly good programming technique, and future BFD
1000 work should avoid it.
1004 Since this technique is rarely used, even experienced C programmers find
1008 It is difficult to debug programs which use BFD, since there is no way
1009 to describe which version of a particular function you are looking at.
1012 Programs which use BFD wind up incorporating two or more slightly
1013 different versions of the same function, which wastes space in the
1017 This technique is never required nor is it especially efficient. It is
1018 always possible to use statically initialized structures holding
1019 function pointers and magic constants instead.
1022 The following is a list of the files which are compiled multiple times.
1026 @cindex @file{aout-target.h}
1027 Describes a few functions and the target vector for a.out targets. This
1028 is used by individual a.out targets with different definitions of
1029 @samp{N_TXTADDR} and similar a.out macros.
1032 @cindex @file{aoutf1.h}
1033 Implements standard SunOS a.out files. In principle it supports 64 bit
1034 a.out targets based on the preprocessor macro @samp{ARCH_SIZE}, but
1035 since all known a.out targets are 32 bits, this code may or may not
1036 work. This file is only included by a few other files, and it is
1037 difficult to justify its existence.
1040 @cindex @file{aoutx.h}
1041 Implements basic a.out support routines. This file can be compiled for
1042 either 32 or 64 bit support. Since all known a.out targets are 32 bits,
1043 the 64 bit support may or may not work. I believe the original
1044 intention was that this file would only be included by @samp{aout32.c}
1045 and @samp{aout64.c}, and that other a.out targets would simply refer to
1046 the functions it defined. Unfortunately, some other a.out targets
1047 started including it directly, leading to a somewhat confused state of
1051 @cindex @file{coffcode.h}
1052 Implements basic COFF support routines. This file is included by every
1053 COFF target. It implements code which handles COFF magic numbers as
1054 well as various hook functions called by the generic COFF functions in
1055 @file{coffgen.c}. This file is controlled by a number of different
1056 macros, and more are added regularly.
1059 @cindex @file{coffswap.h}
1060 Implements COFF swapping routines. This file is included by
1061 @file{coffcode.h}, and thus by every COFF target. It implements the
1062 routines which swap COFF structures between internal and external
1063 format. The main control for this file is the external structure
1064 definitions in the files in the @file{include/coff} directory. A COFF
1065 target file will include one of those files before including
1066 @file{coffcode.h} and thus @file{coffswap.h}. There are a few other
1067 macros which affect @file{coffswap.h} as well, mostly describing whether
1068 certain fields are present in the external structures.
1071 @cindex @file{ecoffswap.h}
1072 Implements ECOFF swapping routines. This is like @file{coffswap.h}, but
1073 for ECOFF. It is included by the ECOFF target files (of which there are
1074 only two). The control is the preprocessor macro @samp{ECOFF_32} or
1078 @cindex @file{elfcode.h}
1079 Implements ELF functions that use external structure definitions. This
1080 file is included by two other files: @file{elf32.c} and @file{elf64.c}.
1081 It is controlled by the @samp{ARCH_SIZE} macro which is defined to be
1082 @samp{32} or @samp{64} before including it. The @samp{NAME} macro is
1083 used internally to give the functions different names for the two target
1087 @cindex @file{elfcore.h}
1088 Like @file{elfcode.h}, but for functions that are specific to ELF core
1089 files. This is included only by @file{elfcode.h}.
1091 @item elfxx-target.h
1092 @cindex @file{elfxx-target.h}
1093 This file is the source for the generated files @file{elf32-target.h}
1094 and @file{elf64-target.h}, one of which is included by every ELF target.
1095 It defines the ELF target vector.
1098 @cindex @file{netbsd.h}
1099 Used by all netbsd aout targets. Several other files include it.
1102 @cindex @file{peicode.h}
1103 Provides swapping routines and other hooks for PE targets.
1104 @file{coffcode.h} will include this rather than @file{coffswap.h} for a
1105 PE target. This defines PE specific versions of the COFF swapping
1106 routines, and also defines some macros which control @file{coffcode.h}
1110 @node BFD relocation handling
1111 @section BFD relocation handling
1112 @cindex bfd relocation handling
1113 @cindex relocations in bfd
1115 The handling of relocations is one of the more confusing aspects of BFD.
1116 Relocation handling has been implemented in various different ways, all
1117 somewhat incompatible, none perfect.
1120 * BFD relocation concepts:: BFD relocation concepts
1121 * BFD relocation functions:: BFD relocation functions
1122 * BFD relocation codes:: BFD relocation codes
1123 * BFD relocation future:: BFD relocation future
1126 @node BFD relocation concepts
1127 @subsection BFD relocation concepts
1129 A relocation is an action which the linker must take when linking. It
1130 describes a change to the contents of a section. The change is normally
1131 based on the final value of one or more symbols. Relocations are
1132 created by the assembler when it creates an object file.
1134 Most relocations are simple. A typical simple relocation is to set 32
1135 bits at a given offset in a section to the value of a symbol. This type
1136 of relocation would be generated for code like @code{int *p = &i;} where
1137 @samp{p} and @samp{i} are global variables. A relocation for the symbol
1138 @samp{i} would be generated such that the linker would initialize the
1139 area of memory which holds the value of @samp{p} to the value of the
1142 Slightly more complex relocations may include an addend, which is a
1143 constant to add to the symbol value before using it. In some cases a
1144 relocation will require adding the symbol value to the existing contents
1145 of the section in the object file. In others the relocation will simply
1146 replace the contents of the section with the symbol value. Some
1147 relocations are PC relative, so that the value to be stored in the
1148 section is the difference between the value of a symbol and the final
1149 address of the section contents.
1151 In general, relocations can be arbitrarily complex. For example,
1152 relocations used in dynamic linking systems often require the linker to
1153 allocate space in a different section and use the offset within that
1154 section as the value to store.
1156 When doing a relocatable link, the linker may or may not have to do
1157 anything with a relocation, depending upon the definition of the
1158 relocation. Simple relocations generally do not require any special
1161 @node BFD relocation functions
1162 @subsection BFD relocation functions
1164 In BFD, each section has an array of @samp{arelent} structures. Each
1165 structure has a pointer to a symbol, an address within the section, an
1166 addend, and a pointer to a @samp{reloc_howto_struct} structure. The
1167 howto structure has a bunch of fields describing the reloc, including a
1168 type field. The type field is specific to the object file format
1169 backend; none of the generic code in BFD examines it.
1171 Originally, the function @samp{bfd_perform_relocation} was supposed to
1172 handle all relocations. In theory, many relocations would be simple
1173 enough to be described by the fields in the howto structure. For those
1174 that weren't, the howto structure included a @samp{special_function}
1175 field to use as an escape.
1177 While this seems plausible, a look at @samp{bfd_perform_relocation}
1178 shows that it failed. The function has odd special cases. Some of the
1179 fields in the howto structure, such as @samp{pcrel_offset}, were not
1180 adequately documented.
1182 The linker uses @samp{bfd_perform_relocation} to do all relocations when
1183 the input and output file have different formats (e.g., when generating
1184 S-records). The generic linker code, which is used by all targets which
1185 do not define their own special purpose linker, uses
1186 @samp{bfd_get_relocated_section_contents}, which for most targets turns
1187 into a call to @samp{bfd_generic_get_relocated_section_contents}, which
1188 calls @samp{bfd_perform_relocation}. So @samp{bfd_perform_relocation}
1189 is still widely used, which makes it difficult to change, since it is
1190 difficult to test all possible cases.
1192 The assembler used @samp{bfd_perform_relocation} for a while. This
1193 turned out to be the wrong thing to do, since
1194 @samp{bfd_perform_relocation} was written to handle relocations on an
1195 existing object file, while the assembler needed to create relocations
1196 in a new object file. The assembler was changed to use the new function
1197 @samp{bfd_install_relocation} instead, and @samp{bfd_install_relocation}
1198 was created as a copy of @samp{bfd_perform_relocation}.
1200 Unfortunately, the work did not progress any farther, so
1201 @samp{bfd_install_relocation} remains a simple copy of
1202 @samp{bfd_perform_relocation}, with all the odd special cases and
1203 confusing code. This again is difficult to change, because again any
1204 change can affect any assembler target, and so is difficult to test.
1206 The new linker, when using the same object file format for all input
1207 files and the output file, does not convert relocations into
1208 @samp{arelent} structures, so it can not use
1209 @samp{bfd_perform_relocation} at all. Instead, users of the new linker
1210 are expected to write a @samp{relocate_section} function which will
1211 handle relocations in a target specific fashion.
1213 There are two helper functions for target specific relocation:
1214 @samp{_bfd_final_link_relocate} and @samp{_bfd_relocate_contents}.
1215 These functions use a howto structure, but they @emph{do not} use the
1216 @samp{special_function} field. Since the functions are normally called
1217 from target specific code, the @samp{special_function} field adds
1218 little; any relocations which require special handling can be handled
1219 without calling those functions.
1221 So, if you want to add a new target, or add a new relocation to an
1222 existing target, you need to do the following:
1226 Make sure you clearly understand what the contents of the section should
1227 look like after assembly, after a relocatable link, and after a final
1228 link. Make sure you clearly understand the operations the linker must
1229 perform during a relocatable link and during a final link.
1232 Write a howto structure for the relocation. The howto structure is
1233 flexible enough to represent any relocation which should be handled by
1234 setting a contiguous bitfield in the destination to the value of a
1235 symbol, possibly with an addend, possibly adding the symbol value to the
1236 value already present in the destination.
1239 Change the assembler to generate your relocation. The assembler will
1240 call @samp{bfd_install_relocation}, so your howto structure has to be
1241 able to handle that. You may need to set the @samp{special_function}
1242 field to handle assembly correctly. Be careful to ensure that any code
1243 you write to handle the assembler will also work correctly when doing a
1244 relocatable link. For example, see @samp{bfd_elf_generic_reloc}.
1247 Test the assembler. Consider the cases of relocation against an
1248 undefined symbol, a common symbol, a symbol defined in the object file
1249 in the same section, and a symbol defined in the object file in a
1250 different section. These cases may not all be applicable for your
1254 If your target uses the new linker, which is recommended, add any
1255 required handling to the target specific relocation function. In simple
1256 cases this will just involve a call to @samp{_bfd_final_link_relocate}
1257 or @samp{_bfd_relocate_contents}, depending upon the definition of the
1258 relocation and whether the link is relocatable or not.
1261 Test the linker. Test the case of a final link. If the relocation can
1262 overflow, use a linker script to force an overflow and make sure the
1263 error is reported correctly. Test a relocatable link, whether the
1264 symbol is defined or undefined in the relocatable output. For both the
1265 final and relocatable link, test the case when the symbol is a common
1266 symbol, when the symbol looked like a common symbol but became a defined
1267 symbol, when the symbol is defined in a different object file, and when
1268 the symbol is defined in the same object file.
1271 In order for linking to another object file format, such as S-records,
1272 to work correctly, @samp{bfd_perform_relocation} has to do the right
1273 thing for the relocation. You may need to set the
1274 @samp{special_function} field to handle this correctly. Test this by
1275 doing a link in which the output object file format is S-records.
1278 Using the linker to generate relocatable output in a different object
1279 file format is impossible in the general case, so you generally don't
1280 have to worry about that. The GNU linker makes sure to stop that from
1281 happening when an input file in a different format has relocations.
1283 Linking input files of different object file formats together is quite
1284 unusual, but if you're really dedicated you may want to consider testing
1285 this case, both when the output object file format is the same as your
1286 format, and when it is different.
1289 @node BFD relocation codes
1290 @subsection BFD relocation codes
1292 BFD has another way of describing relocations besides the howto
1293 structures described above: the enum @samp{bfd_reloc_code_real_type}.
1295 Every known relocation type can be described as a value in this
1296 enumeration. The enumeration contains many target specific relocations,
1297 but where two or more targets have the same relocation, a single code is
1298 used. For example, the single value @samp{BFD_RELOC_32} is used for all
1299 simple 32 bit relocation types.
1301 The main purpose of this relocation code is to give the assembler some
1302 mechanism to create @samp{arelent} structures. In order for the
1303 assembler to create an @samp{arelent} structure, it has to be able to
1304 obtain a howto structure. The function @samp{bfd_reloc_type_lookup},
1305 which simply calls the target vector entry point
1306 @samp{reloc_type_lookup}, takes a relocation code and returns a howto
1309 The function @samp{bfd_get_reloc_code_name} returns the name of a
1310 relocation code. This is mainly used in error messages.
1312 Using both howto structures and relocation codes can be somewhat
1313 confusing. There are many processor specific relocation codes.
1314 However, the relocation is only fully defined by the howto structure.
1315 The same relocation code will map to different howto structures in
1316 different object file formats. For example, the addend handling may be
1319 Most of the relocation codes are not really general. The assembler can
1320 not use them without already understanding what sorts of relocations can
1321 be used for a particular target. It might be possible to replace the
1322 relocation codes with something simpler.
1324 @node BFD relocation future
1325 @subsection BFD relocation future
1327 Clearly the current BFD relocation support is in bad shape. A
1328 wholescale rewrite would be very difficult, because it would require
1329 thorough testing of every BFD target. So some sort of incremental
1332 My vague thoughts on this would involve defining a new, clearly defined,
1333 howto structure. Some mechanism would be used to determine which type
1334 of howto structure was being used by a particular format.
1336 The new howto structure would clearly define the relocation behaviour in
1337 the case of an assembly, a relocatable link, and a final link. At
1338 least one special function would be defined as an escape, and it might
1339 make sense to define more.
1341 One or more generic functions similar to @samp{bfd_perform_relocation}
1342 would be written to handle the new howto structure.
1344 This should make it possible to write a generic version of the relocate
1345 section functions used by the new linker. The target specific code
1346 would provide some mechanism (a function pointer or an initial
1347 conversion) to convert target specific relocations into howto
1350 Ideally it would be possible to use this generic relocate section
1351 function for the generic linker as well. That is, it would replace the
1352 @samp{bfd_generic_get_relocated_section_contents} function which is
1353 currently normally used.
1355 For the special case of ELF dynamic linking, more consideration needs to
1356 be given to writing ELF specific but ELF target generic code to handle
1357 special relocation types such as GOT and PLT.
1359 @node BFD ELF support
1360 @section BFD ELF support
1361 @cindex elf support in bfd
1362 @cindex bfd elf support
1364 The ELF object file format is defined in two parts: a generic ABI and a
1365 processor specific supplement. The ELF support in BFD is split in a
1366 similar fashion. The processor specific support is largely kept within
1367 a single file. The generic support is provided by several other files.
1368 The processor specific support provides a set of function pointers and
1369 constants used by the generic support.
1372 * BFD ELF sections and segments:: ELF sections and segments
1373 * BFD ELF generic support:: BFD ELF generic support
1374 * BFD ELF processor specific support:: BFD ELF processor specific support
1375 * BFD ELF core files:: BFD ELF core files
1376 * BFD ELF future:: BFD ELF future
1379 @node BFD ELF sections and segments
1380 @subsection ELF sections and segments
1382 The ELF ABI permits a file to have either sections or segments or both.
1383 Relocatable object files conventionally have only sections.
1384 Executables conventionally have both. Core files conventionally have
1385 only program segments.
1387 ELF sections are similar to sections in other object file formats: they
1388 have a name, a VMA, file contents, flags, and other miscellaneous
1389 information. ELF relocations are stored in sections of a particular
1390 type; BFD automatically converts these sections into internal relocation
1393 ELF program segments are intended for fast interpretation by a system
1394 loader. They have a type, a VMA, an LMA, file contents, and a couple of
1395 other fields. When an ELF executable is run on a Unix system, the
1396 system loader will examine the program segments to decide how to load
1397 it. The loader will ignore the section information. Loadable program
1398 segments (type @samp{PT_LOAD}) are directly loaded into memory. Other
1399 program segments are interpreted by the loader, and generally provide
1400 dynamic linking information.
1402 When an ELF file has both program segments and sections, an ELF program
1403 segment may encompass one or more ELF sections, in the sense that the
1404 portion of the file which corresponds to the program segment may include
1405 the portions of the file corresponding to one or more sections. When
1406 there is more than one section in a loadable program segment, the
1407 relative positions of the section contents in the file must correspond
1408 to the relative positions they should hold when the program segment is
1409 loaded. This requirement should be obvious if you consider that the
1410 system loader will load an entire program segment at a time.
1412 On a system which supports dynamic paging, such as any native Unix
1413 system, the contents of a loadable program segment must be at the same
1414 offset in the file as in memory, modulo the memory page size used on the
1415 system. This is because the system loader will map the file into memory
1416 starting at the start of a page. The system loader can easily remap
1417 entire pages to the correct load address. However, if the contents of
1418 the file were not correctly aligned within the page, the system loader
1419 would have to shift the contents around within the page, which is too
1420 expensive. For example, if the LMA of a loadable program segment is
1421 @samp{0x40080} and the page size is @samp{0x1000}, then the position of
1422 the segment contents within the file must equal @samp{0x80} modulo
1425 BFD has only a single set of sections. It does not provide any generic
1426 way to examine both sections and segments. When BFD is used to open an
1427 object file or executable, the BFD sections will represent ELF sections.
1428 When BFD is used to open a core file, the BFD sections will represent
1429 ELF program segments.
1431 When BFD is used to examine an object file or executable, any program
1432 segments will be read to set the LMA of the sections. This is because
1433 ELF sections only have a VMA, while ELF program segments have both a VMA
1434 and an LMA. Any program segments will be copied by the
1435 @samp{copy_private} entry points. They will be printed by the
1436 @samp{print_private} entry point. Otherwise, the program segments are
1437 ignored. In particular, programs which use BFD currently have no direct
1438 access to the program segments.
1440 When BFD is used to create an executable, the program segments will be
1441 created automatically based on the section information. This is done in
1442 the function @samp{assign_file_positions_for_segments} in @file{elf.c}.
1443 This function has been tweaked many times, and probably still has
1444 problems that arise in particular cases.
1446 There is a hook which may be used to explicitly define the program
1447 segments when creating an executable: the @samp{bfd_record_phdr}
1448 function in @file{bfd.c}. If this function is called, BFD will not
1449 create program segments itself, but will only create the program
1450 segments specified by the caller. The linker uses this function to
1451 implement the @samp{PHDRS} linker script command.
1453 @node BFD ELF generic support
1454 @subsection BFD ELF generic support
1456 In general, functions which do not read external data from the ELF file
1457 are found in @file{elf.c}. They operate on the internal forms of the
1458 ELF structures, which are defined in @file{include/elf/internal.h}. The
1459 internal structures are defined in terms of @samp{bfd_vma}, and so may
1460 be used for both 32 bit and 64 bit ELF targets.
1462 The file @file{elfcode.h} contains functions which operate on the
1463 external data. @file{elfcode.h} is compiled twice, once via
1464 @file{elf32.c} with @samp{ARCH_SIZE} defined as @samp{32}, and once via
1465 @file{elf64.c} with @samp{ARCH_SIZE} defined as @samp{64}.
1466 @file{elfcode.h} includes functions to swap the ELF structures in and
1467 out of external form, as well as a few more complex functions.
1469 Linker support is found in @file{elflink.c}. The
1470 linker support is only used if the processor specific file defines
1471 @samp{elf_backend_relocate_section}, which is required to relocate the
1472 section contents. If that macro is not defined, the generic linker code
1473 is used, and relocations are handled via @samp{bfd_perform_relocation}.
1475 The core file support is in @file{elfcore.h}, which is compiled twice,
1476 for both 32 and 64 bit support. The more interesting cases of core file
1477 support only work on a native system which has the @file{sys/procfs.h}
1478 header file. Without that file, the core file support does little more
1479 than read the ELF program segments as BFD sections.
1481 The BFD internal header file @file{elf-bfd.h} is used for communication
1482 among these files and the processor specific files.
1484 The default entries for the BFD ELF target vector are found mainly in
1485 @file{elf.c}. Some functions are found in @file{elfcode.h}.
1487 The processor specific files may override particular entries in the
1488 target vector, but most do not, with one exception: the
1489 @samp{bfd_reloc_type_lookup} entry point is always processor specific.
1491 @node BFD ELF processor specific support
1492 @subsection BFD ELF processor specific support
1494 By convention, the processor specific support for a particular processor
1495 will be found in @file{elf@var{nn}-@var{cpu}.c}, where @var{nn} is
1496 either 32 or 64, and @var{cpu} is the name of the processor.
1499 * BFD ELF processor required:: Required processor specific support
1500 * BFD ELF processor linker:: Processor specific linker support
1501 * BFD ELF processor other:: Other processor specific support options
1504 @node BFD ELF processor required
1505 @subsubsection Required processor specific support
1507 When writing a @file{elf@var{nn}-@var{cpu}.c} file, you must do the
1512 Define either @samp{TARGET_BIG_SYM} or @samp{TARGET_LITTLE_SYM}, or
1513 both, to a unique C name to use for the target vector. This name should
1514 appear in the list of target vectors in @file{targets.c}, and will also
1515 have to appear in @file{config.bfd} and @file{configure.ac}. Define
1516 @samp{TARGET_BIG_SYM} for a big-endian processor,
1517 @samp{TARGET_LITTLE_SYM} for a little-endian processor, and define both
1518 for a bi-endian processor.
1520 Define either @samp{TARGET_BIG_NAME} or @samp{TARGET_LITTLE_NAME}, or
1521 both, to a string used as the name of the target vector. This is the
1522 name which a user of the BFD tool would use to specify the object file
1523 format. It would normally appear in a linker emulation parameters
1526 Define @samp{ELF_ARCH} to the BFD architecture (an element of the
1527 @samp{bfd_architecture} enum, typically @samp{bfd_arch_@var{cpu}}).
1529 Define @samp{ELF_MACHINE_CODE} to the magic number which should appear
1530 in the @samp{e_machine} field of the ELF header. As of this writing,
1531 these magic numbers are assigned by Caldera; if you want to get a magic
1532 number for a particular processor, try sending a note to
1533 @email{registry@@caldera.com}. In the BFD sources, the magic numbers are
1534 found in @file{include/elf/common.h}; they have names beginning with
1537 Define @samp{ELF_MAXPAGESIZE} to the maximum size of a virtual page in
1538 memory. This can normally be found at the start of chapter 5 in the
1539 processor specific supplement. For a processor which will only be used
1540 in an embedded system, or which has no memory management hardware, this
1541 can simply be @samp{1}.
1543 If the format should use @samp{Rel} rather than @samp{Rela} relocations,
1544 define @samp{USE_REL}. This is normally defined in chapter 4 of the
1545 processor specific supplement.
1547 In the absence of a supplement, it's easier to work with @samp{Rela}
1548 relocations. @samp{Rela} relocations will require more space in object
1549 files (but not in executables, except when using dynamic linking).
1550 However, this is outweighed by the simplicity of addend handling when
1551 using @samp{Rela} relocations. With @samp{Rel} relocations, the addend
1552 must be stored in the section contents, which makes relocatable links
1555 For example, consider C code like @code{i = a[1000];} where @samp{a} is
1556 a global array. The instructions which load the value of @samp{a[1000]}
1557 will most likely use a relocation which refers to the symbol
1558 representing @samp{a}, with an addend that gives the offset from the
1559 start of @samp{a} to element @samp{1000}. When using @samp{Rel}
1560 relocations, that addend must be stored in the instructions themselves.
1561 If you are adding support for a RISC chip which uses two or more
1562 instructions to load an address, then the addend may not fit in a single
1563 instruction, and will have to be somehow split among the instructions.
1564 This makes linking awkward, particularly when doing a relocatable link
1565 in which the addend may have to be updated. It can be done---the MIPS
1566 ELF support does it---but it should be avoided when possible.
1568 It is possible, though somewhat awkward, to support both @samp{Rel} and
1569 @samp{Rela} relocations for a single target; @file{elf64-mips.c} does it
1570 by overriding the relocation reading and writing routines.
1572 Define howto structures for all the relocation types.
1574 Define a @samp{bfd_reloc_type_lookup} routine. This must be named
1575 @samp{bfd_elf@var{nn}_bfd_reloc_type_lookup}, and may be either a
1576 function or a macro. It must translate a BFD relocation code into a
1577 howto structure. This is normally a table lookup or a simple switch.
1579 If using @samp{Rel} relocations, define @samp{elf_info_to_howto_rel}.
1580 If using @samp{Rela} relocations, define @samp{elf_info_to_howto}.
1581 Either way, this is a macro defined as the name of a function which
1582 takes an @samp{arelent} and a @samp{Rel} or @samp{Rela} structure, and
1583 sets the @samp{howto} field of the @samp{arelent} based on the
1584 @samp{Rel} or @samp{Rela} structure. This is normally uses
1585 @samp{ELF@var{nn}_R_TYPE} to get the ELF relocation type and uses it as
1586 an index into a table of howto structures.
1589 You must also add the magic number for this processor to the
1590 @samp{prep_headers} function in @file{elf.c}.
1592 You must also create a header file in the @file{include/elf} directory
1593 called @file{@var{cpu}.h}. This file should define any target specific
1594 information which may be needed outside of the BFD code. In particular
1595 it should use the @samp{START_RELOC_NUMBERS}, @samp{RELOC_NUMBER},
1596 @samp{FAKE_RELOC}, @samp{EMPTY_RELOC} and @samp{END_RELOC_NUMBERS}
1597 macros to create a table mapping the number used to identify a
1598 relocation to a name describing that relocation.
1600 While not a BFD component, you probably also want to make the binutils
1601 program @samp{readelf} parse your ELF objects. For this, you need to add
1602 code for @code{EM_@var{cpu}} as appropriate in @file{binutils/readelf.c}.
1604 @node BFD ELF processor linker
1605 @subsubsection Processor specific linker support
1607 The linker will be much more efficient if you define a relocate section
1608 function. This will permit BFD to use the ELF specific linker support.
1610 If you do not define a relocate section function, BFD must use the
1611 generic linker support, which requires converting all symbols and
1612 relocations into BFD @samp{asymbol} and @samp{arelent} structures. In
1613 this case, relocations will be handled by calling
1614 @samp{bfd_perform_relocation}, which will use the howto structures you
1615 have defined. @xref{BFD relocation handling}.
1617 In order to support linking into a different object file format, such as
1618 S-records, @samp{bfd_perform_relocation} must work correctly with your
1619 howto structures, so you can't skip that step. However, if you define
1620 the relocate section function, then in the normal case of linking into
1621 an ELF file the linker will not need to convert symbols and relocations,
1622 and will be much more efficient.
1624 To use a relocation section function, define the macro
1625 @samp{elf_backend_relocate_section} as the name of a function which will
1626 take the contents of a section, as well as relocation, symbol, and other
1627 information, and modify the section contents according to the relocation
1628 information. In simple cases, this is little more than a loop over the
1629 relocations which computes the value of each relocation and calls
1630 @samp{_bfd_final_link_relocate}. The function must check for a
1631 relocatable link, and in that case normally needs to do nothing other
1632 than adjust the addend for relocations against a section symbol.
1634 The complex cases generally have to do with dynamic linker support. GOT
1635 and PLT relocations must be handled specially, and the linker normally
1636 arranges to set up the GOT and PLT sections while handling relocations.
1637 When generating a shared library, random relocations must normally be
1638 copied into the shared library, or converted to RELATIVE relocations
1641 @node BFD ELF processor other
1642 @subsubsection Other processor specific support options
1644 There are many other macros which may be defined in
1645 @file{elf@var{nn}-@var{cpu}.c}. These macros may be found in
1646 @file{elfxx-target.h}.
1648 Macros may be used to override some of the generic ELF target vector
1651 Several processor specific hook functions which may be defined as
1652 macros. These functions are found as function pointers in the
1653 @samp{elf_backend_data} structure defined in @file{elf-bfd.h}. In
1654 general, a hook function is set by defining a macro
1655 @samp{elf_backend_@var{name}}.
1657 There are a few processor specific constants which may also be defined.
1658 These are again found in the @samp{elf_backend_data} structure.
1660 I will not define the various functions and constants here; see the
1661 comments in @file{elf-bfd.h}.
1663 Normally any odd characteristic of a particular ELF processor is handled
1664 via a hook function. For example, the special @samp{SHN_MIPS_SCOMMON}
1665 section number found in MIPS ELF is handled via the hooks
1666 @samp{section_from_bfd_section}, @samp{symbol_processing},
1667 @samp{add_symbol_hook}, and @samp{output_symbol_hook}.
1669 Dynamic linking support, which involves processor specific relocations
1670 requiring special handling, is also implemented via hook functions.
1672 @node BFD ELF core files
1673 @subsection BFD ELF core files
1674 @cindex elf core files
1676 On native ELF Unix systems, core files are generated without any
1677 sections. Instead, they only have program segments.
1679 When BFD is used to read an ELF core file, the BFD sections will
1680 actually represent program segments. Since ELF program segments do not
1681 have names, BFD will invent names like @samp{segment@var{n}} where
1682 @var{n} is a number.
1684 A single ELF program segment may include both an initialized part and an
1685 uninitialized part. The size of the initialized part is given by the
1686 @samp{p_filesz} field. The total size of the segment is given by the
1687 @samp{p_memsz} field. If @samp{p_memsz} is larger than @samp{p_filesz},
1688 then the extra space is uninitialized, or, more precisely, initialized
1691 BFD will represent such a program segment as two different sections.
1692 The first, named @samp{segment@var{n}a}, will represent the initialized
1693 part of the program segment. The second, named @samp{segment@var{n}b},
1694 will represent the uninitialized part.
1696 ELF core files store special information such as register values in
1697 program segments with the type @samp{PT_NOTE}. BFD will attempt to
1698 interpret the information in these segments, and will create additional
1699 sections holding the information. Some of this interpretation requires
1700 information found in the host header file @file{sys/procfs.h}, and so
1701 will only work when BFD is built on a native system.
1703 BFD does not currently provide any way to create an ELF core file. In
1704 general, BFD does not provide a way to create core files. The way to
1705 implement this would be to write @samp{bfd_set_format} and
1706 @samp{bfd_write_contents} routines for the @samp{bfd_core} type; see
1707 @ref{BFD target vector format}.
1709 @node BFD ELF future
1710 @subsection BFD ELF future
1712 The current dynamic linking support has too much code duplication.
1713 While each processor has particular differences, much of the dynamic
1714 linking support is quite similar for each processor. The GOT and PLT
1715 are handled in fairly similar ways, the details of -Bsymbolic linking
1716 are generally similar, etc. This code should be reworked to use more
1717 generic functions, eliminating the duplication.
1719 Similarly, the relocation handling has too much duplication. Many of
1720 the @samp{reloc_type_lookup} and @samp{info_to_howto} functions are
1721 quite similar. The relocate section functions are also often quite
1722 similar, both in the standard linker handling and the dynamic linker
1723 handling. Many of the COFF processor specific backends share a single
1724 relocate section function (@samp{_bfd_coff_generic_relocate_section}),
1725 and it should be possible to do something like this for the ELF targets
1728 The appearance of the processor specific magic number in
1729 @samp{prep_headers} in @file{elf.c} is somewhat bogus. It should be
1730 possible to add support for a new processor without changing the generic
1733 The processor function hooks and constants are ad hoc and need better
1737 @section BFD glossary
1738 @cindex glossary for bfd
1739 @cindex bfd glossary
1741 This is a short glossary of some BFD terms.
1745 The a.out object file format. The original Unix object file format.
1746 Still used on SunOS, though not Solaris. Supports only three sections.
1749 A collection of object files produced and manipulated by the @samp{ar}
1753 The implementation within BFD of a particular object file format. The
1754 set of functions which appear in a particular target vector.
1757 The BFD library itself. Also, each object file, archive, or executable
1758 opened by the BFD library has the type @samp{bfd *}, and is sometimes
1759 referred to as a bfd.
1762 The Common Object File Format. Used on Unix SVR3. Used by some
1763 embedded targets, although ELF is normally better.
1766 A shared library on Windows.
1768 @item dynamic linker
1769 When a program linked against a shared library is run, the dynamic
1770 linker will locate the appropriate shared library and arrange to somehow
1771 include it in the running image.
1773 @item dynamic object
1774 Another name for an ELF shared library.
1777 The Extended Common Object File Format. Used on Alpha Digital Unix
1778 (formerly OSF/1), as well as Ultrix and Irix 4. A variant of COFF.
1781 The Executable and Linking Format. The object file format used on most
1782 modern Unix systems, including GNU/Linux, Solaris, Irix, and SVR4. Also
1783 used on many embedded systems.
1786 A program, with instructions and symbols, and perhaps dynamic linking
1787 information. Normally produced by a linker.
1790 Load Memory Address. This is the address at which a section will be
1791 loaded. Compare with VMA, below.
1794 A binary file including machine instructions, symbols, and relocation
1795 information. Normally produced by an assembler.
1797 @item object file format
1798 The format of an object file. Typically object files and executables
1799 for a particular system are in the same format, although executables
1800 will not contain any relocation information.
1803 The Portable Executable format. This is the object file format used for
1804 Windows (specifically, Win32) object files. It is based closely on
1805 COFF, but has a few significant differences.
1808 The Portable Executable Image format. This is the object file format
1809 used for Windows (specifically, Win32) executables. It is very similar
1810 to PE, but includes some additional header information.
1813 Information used by the linker to adjust section contents. Also called
1817 Object files and executable are composed of sections. Sections have
1818 optional data and optional relocation information.
1820 @item shared library
1821 A library of functions which may be used by many executables without
1822 actually being linked into each executable. There are several different
1823 implementations of shared libraries, each having slightly different
1827 Each object file and executable may have a list of symbols, often
1828 referred to as the symbol table. A symbol is basically a name and an
1829 address. There may also be some additional information like the type of
1830 symbol, although the type of a symbol is normally something simple like
1831 function or object, and should be confused with the more complex C
1832 notion of type. Typically every global function and variable in a C
1833 program will have an associated symbol.
1836 A set of functions which implement support for a particular object file
1837 format. The @samp{bfd_target} structure.
1840 The current Windows API, implemented by Windows 95 and later and Windows
1841 NT 3.51 and later, but not by Windows 3.1.
1844 The eXtended Common Object File Format. Used on AIX. A variant of
1845 COFF, with a completely different symbol table implementation.
1848 Virtual Memory Address. This is the address a section will have when
1849 an executable is run. Compare with LMA, above.
1853 @unnumberedsec Index