Lines Matching refs:BFD
7 @settitle BFD Internals
10 @title{BFD Internals}
17 @top BFD Internals
21 This document describes some BFD internal information which may be
22 helpful when working on BFD. It is very incomplete.
30 * BFD overview:: BFD overview
31 * BFD guidelines:: BFD programming guidelines
32 * BFD target vector:: BFD target vector
33 * BFD generated files:: BFD generated files
34 * BFD multiple compilations:: Files compiled multiple times in BFD
35 * BFD relocation handling:: BFD relocation handling
36 * BFD ELF support:: BFD ELF support
37 * BFD glossary:: Glossary
41 @node BFD overview
42 @section BFD overview
44 BFD is a library which provides a single interface to read and write
48 * BFD library interfaces:: BFD library interfaces
49 * BFD library users:: BFD library users
50 * BFD view:: The BFD view of a file
51 * BFD blindness:: BFD loses information
54 @node BFD library interfaces
55 @subsection BFD library interfaces
57 One way to look at the BFD library is to divide it into four parts by
61 the BFD library will call. These generic function normally translate
65 the official BFD interface.
68 vectors. This is the bulk of the code in BFD. A target vector is a set
70 target vector is used to implement the generic BFD functions. These
72 called directly. The target vector is described in detail in @ref{BFD
74 target vector is often referred to as a BFD backend.
78 and are called from outside of the BFD library. These are used as hooks
80 requires some action which the BFD generic interface does not provide.
82 cases they are only provided when BFD is configured with support for a
84 are not really part of the official BFD interface.
86 The fourth interface is the set of BFD support functions which are
87 called by the other BFD functions. These manage issues like memory
89 like. These functions are never called from outside of the BFD library.
91 @node BFD library users
92 @subsection BFD library users
94 Another way to look at the BFD library is to divide it into three parts
99 These programs use BFD to view an object file in a generic form. The
100 official BFD interface is normally fully adequate for these programs.
103 programs like @samp{gas} and @samp{objcopy}. These programs use BFD to
104 create an object file. The official BFD interface is normally adequate
107 information. The official BFD interface includes functions to copy
114 BFD structures. However, this turned out to be too slow and too memory
117 The official BFD linker functions were written to permit specific BFD
122 within BFD which use the generic structures and which work with all
126 are not provided by the official BFD interface, particularly for dynamic
130 @node BFD view
131 @subsection The BFD view of a file
133 BFD uses generic structures to manage information. It translates data
137 BFD describes a file as a pointer to the @samp{bfd} type. A @samp{bfd}
138 is composed of the following elements. The BFD information can be
153 BFD represents a section as a pointer to the @samp{asection} type. Each
160 BFD represents a relocation as a pointer to the @samp{arelent} type. A
164 relocation. For more information, see @ref{BFD relocation handling}.
166 BFD represents a symbol as a pointer to the @samp{asymbol} type. A
170 Archive files do not have any sections or symbols. Instead, BFD
172 @samp{bfd}s. BFD also provides access to the archive symbol map, as a
173 list of symbol names. BFD provides a function to return the @samp{bfd}
177 @node BFD blindness
178 @subsection BFD loses information
180 Most object file formats have information which BFD can not represent in
183 There is often explicit information which BFD can not represent. For
184 example, the COFF version stamp, or the ELF program segments. BFD
186 printing, or linking an object file. The BFD support for a particular
190 In some cases there is also implicit information which BFD can not
195 small symbols within range of the GP register. Since BFD can not
198 format which is outside of the BFD library.
200 This loss of information indicates areas where the BFD paradigm breaks
203 in the manner which BFD does it today.
205 Nevertheless, the BFD library does greatly simplify the task of dealing
212 @node BFD guidelines
213 @section BFD programming guidelines
218 There is a lot of poorly written and confusing code in BFD. New BFD
219 code should be written to a higher standard. Merely because some BFD
223 Here are some general BFD programming guidelines:
230 Avoid global variables. We ideally want BFD to be fully reentrant, so
234 variables, use data attached to a BFD or to a linker hash table.
245 BFD, but should not be visible outside of BFD, should start with
256 BFD code should compile with few or no warnings using @samp{gcc -Wall}.
262 @node BFD target vector
263 @section BFD target vector
267 BFD supports multiple object file formats by using the @dfn{target
275 * BFD target vector miscellaneous:: Miscellaneous constants
276 * BFD target vector swap:: Swapping functions
277 * BFD target vector format:: Format type dependent functions
279 * BFD target vector generic:: Generic functions
280 * BFD target vector copy:: Copy functions
281 * BFD target vector core:: Core file support functions
282 * BFD target vector archive:: Archive functions
283 * BFD target vector symbols:: Symbol table functions
284 * BFD target vector relocs:: Relocation support
285 * BFD target vector write:: Output functions
286 * BFD target vector link:: Linker functions
287 * BFD target vector dynamic:: Dynamic linking information functions
290 @node BFD target vector miscellaneous
299 use BFD, such as the @samp{--oformat} linker option.
354 Flags which may appear in the @samp{flags} field of a BFD with this
359 BFD with this format.
381 @node BFD target vector swap
393 @node BFD target vector format
397 indexed by the BFD format type. The BFD format types are as follows:
414 Check whether the BFD is of a particular format (object file, archive
416 by the @samp{bfd_check_format} function when examining an existing BFD.
417 If the BFD matches the desired format, this function will initialize any
418 format specific information such as the @samp{tdata} field of the BFD.
419 This function must be called before any other BFD target vector function
423 Set the format of a BFD which was created for output. This is called by
424 the @samp{bfd_set_format} function after creating the BFD with a
427 the given format. This function must be called before any other BFD
431 Write out the contents of the BFD in the given format. This is called
432 by @samp{bfd_close} function for a BFD opened for writing. This really
435 In fact, BFD will fail if a different format is used when calling
456 functions initialize the appropriate fields in the BFD target vector.
472 @node BFD target vector generic
481 Free any target specific information associated with the BFD. This is
482 called when any BFD is closed (the @samp{bfd_write_contents} function
483 mentioned earlier is only called for a BFD opened for writing). Most
490 Free any cached information associated with the BFD which can be
492 consumption required by programs using BFD. This is normally called via
502 corresponds to an actual section in an actual BFD.
523 @node BFD target vector copy
529 internal BFD information.
533 This is called when copying a BFD, via @samp{bfd_copy_private_bfd_data}.
554 to copy private symbol data from one BFD to another. However, most BFDs
571 information about the BFD which can not be otherwise represented by BFD
576 @node BFD target vector core
594 Given a core file and a BFD for an executable, this returns whether the
598 @node BFD target vector archive
614 Read in the archive symbol table, storing it in private BFD data. This
621 storing it in private BFD data. This is normally called from the
654 Given an archive and a BFD representing a file stored within the
655 archive, return a BFD for the next file in the archive. This is called
661 Given an archive and an index, return a BFD for the file in the archive
680 @node BFD target vector symbols
693 information in BFD private data. This is called via
703 Create an empty symbol for the BFD. This is needed because most targets
761 information. This permits BFD to not convert all the symbols into
772 @node BFD target vector relocs
785 store the actual relocation information in BFD private data. This is
795 (@pxref{BFD relocation codes}). This is called via
800 @node BFD target vector write
805 with writing out a BFD.
809 Set the architecture and machine number for a BFD. This is called via
820 @node BFD target vector link
829 Return the size of the header information required for a BFD. This is
870 @node BFD target vector dynamic
883 symbol information in BFD private data. This is called via
897 actual relocation information in BFD private data. This is called via
907 @node BFD generated files
908 @section BFD generated files
912 BFD contains several automatically generated files. This section
914 configure BFD. Some files are created at make time, when you build
915 BFD. Some files are automatically rebuilt at make time, but only if
934 control whether BFD is built for a 32 bit target or a 64 bit target.
939 other BFD source files. If you configure with the
954 several other BFD source files. If you configure with the
969 BFD target vector variable names at run time.
972 @node BFD multiple compilations
973 @section Files compiled multiple times in BFD
974 Several files in BFD are compiled multiple times. By this I mean that
984 This is a not a particularly good programming technique, and future BFD
993 It is difficult to debug programs which use BFD, since there is no way
997 Programs which use BFD wind up incorporating two or more slightly
1120 @node BFD relocation handling
1121 @section BFD relocation handling
1125 The handling of relocations is one of the more confusing aspects of BFD.
1130 * BFD relocation concepts:: BFD relocation concepts
1131 * BFD relocation functions:: BFD relocation functions
1132 * BFD relocation codes:: BFD relocation codes
1133 * BFD relocation future:: BFD relocation future
1136 @node BFD relocation concepts
1137 @subsection BFD relocation concepts
1172 @node BFD relocation functions
1173 @subsection BFD relocation functions
1175 In BFD, each section has an array of @samp{arelent} structures. Each
1180 backend; none of the generic code in BFD examines it.
1300 @node BFD relocation codes
1301 @subsection BFD relocation codes
1303 BFD has another way of describing relocations besides the howto
1335 @node BFD relocation future
1336 @subsection BFD relocation future
1338 Clearly the current BFD relocation support is in bad shape. A
1340 thorough testing of every BFD target. So some sort of incremental
1370 @node BFD ELF support
1371 @section BFD ELF support
1376 processor specific supplement. The ELF support in BFD is split in a
1383 * BFD ELF sections and segments:: ELF sections and segments
1384 * BFD ELF generic support:: BFD ELF generic support
1385 * BFD ELF processor specific support:: BFD ELF processor specific support
1386 * BFD ELF core files:: BFD ELF core files
1387 * BFD ELF future:: BFD ELF future
1390 @node BFD ELF sections and segments
1401 type; BFD automatically converts these sections into internal relocation
1436 BFD has only a single set of sections. It does not provide any generic
1437 way to examine both sections and segments. When BFD is used to open an
1438 object file or executable, the BFD sections will represent ELF sections.
1439 When BFD is used to open a core file, the BFD sections will represent
1442 When BFD is used to examine an object file or executable, any program
1448 ignored. In particular, programs which use BFD currently have no direct
1451 When BFD is used to create an executable, the program segments will be
1459 function in @file{bfd.c}. If this function is called, BFD will not
1464 @node BFD ELF generic support
1465 @subsection BFD ELF generic support
1490 than read the ELF program segments as BFD sections.
1492 The BFD internal header file @file{elf-bfd.h} is used for communication
1495 The default entries for the BFD ELF target vector are found mainly in
1502 @node BFD ELF processor specific support
1503 @subsection BFD ELF processor specific support
1510 * BFD ELF processor required:: Required processor specific support
1511 * BFD ELF processor linker:: Processor specific linker support
1512 * BFD ELF processor other:: Other processor specific support options
1515 @node BFD ELF processor required
1533 name which a user of the BFD tool would use to specify the object file
1537 Define @samp{ELF_ARCH} to the BFD architecture (an element of the
1544 @email{registry@@caldera.com}. In the BFD sources, the magic numbers are
1587 function or a macro. It must translate a BFD relocation code into a
1605 information which may be needed outside of the BFD code. In particular
1611 While not a BFD component, you probably also want to make the binutils
1615 @node BFD ELF processor linker
1619 function. This will permit BFD to use the ELF specific linker support.
1621 If you do not define a relocate section function, BFD must use the
1623 relocations into BFD @samp{asymbol} and @samp{arelent} structures. In
1626 have defined. @xref{BFD relocation handling}.
1652 @node BFD ELF processor other
1683 @node BFD ELF core files
1684 @subsection BFD ELF core files
1690 When BFD is used to read an ELF core file, the BFD sections will
1692 have names, BFD will invent names like @samp{segment@var{n}} where
1702 BFD will represent such a program segment as two different sections.
1708 program segments with the type @samp{PT_NOTE}. BFD will attempt to
1712 will only work when BFD is built on a native system.
1714 BFD does not currently provide any way to create an ELF core file. In
1715 general, BFD does not provide a way to create core files. The way to
1718 @ref{BFD target vector format}.
1720 @node BFD ELF future
1721 @subsection BFD ELF future
1764 @node BFD glossary
1765 @section BFD glossary
1769 This is a short glossary of some BFD terms.
1781 The implementation within BFD of a particular object file format. The
1784 @item BFD
1785 The BFD library itself. Also, each object file, archive, or executable
1786 opened by the BFD library has the type @samp{bfd *}, and is sometimes