160484Sobrien\input texinfo 278828Sobrien@c Copyright 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998, 3218822Sdim@c 2000, 2001, 2002, 2003, 2004, 2006, 2007 478828Sobrien@c Free Software Foundation, Inc. 560484Sobrien@setfilename bfdint.info 660484Sobrien 760484Sobrien@settitle BFD Internals 860484Sobrien@iftex 960484Sobrien@titlepage 1060484Sobrien@title{BFD Internals} 1160484Sobrien@author{Ian Lance Taylor} 1260484Sobrien@author{Cygnus Solutions} 1360484Sobrien@page 1460484Sobrien@end iftex 1560484Sobrien 16218822Sdim@copying 17218822SdimThis file documents the internals of the BFD library. 18218822Sdim 19218822SdimCopyright @copyright{} 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 20218822Sdim1996, 1998, 2000, 2001, 2002, 2003, 2004, 2006, 2007 21218822SdimFree Software Foundation, Inc. 22218822SdimContributed by Cygnus Support. 23218822Sdim 24218822SdimPermission is granted to copy, distribute and/or modify this document 25218822Sdimunder the terms of the GNU Free Documentation License, Version 1.1 or 26218822Sdimany later version published by the Free Software Foundation; with the 27218822SdimInvariant Sections being ``GNU General Public License'' and ``Funding 28218822SdimFree Software'', the Front-Cover texts being (a) (see below), and with 29218822Sdimthe Back-Cover Texts being (b) (see below). A copy of the license is 30218822Sdimincluded in the section entitled ``GNU Free Documentation License''. 31218822Sdim 32218822Sdim(a) The FSF's Front-Cover Text is: 33218822Sdim 34218822Sdim A GNU Manual 35218822Sdim 36218822Sdim(b) The FSF's Back-Cover Text is: 37218822Sdim 38218822Sdim You have freedom to copy and modify this GNU Manual, like GNU 39218822Sdim software. Copies published by the Free Software Foundation raise 40218822Sdim funds for GNU development. 41218822Sdim@end copying 42218822Sdim 4360484Sobrien@node Top 4460484Sobrien@top BFD Internals 4560484Sobrien@raisesections 4660484Sobrien@cindex bfd internals 4760484Sobrien 4860484SobrienThis document describes some BFD internal information which may be 4960484Sobrienhelpful when working on BFD. It is very incomplete. 5060484Sobrien 5177298SobrienThis document is not updated regularly, and may be out of date. 5260484Sobrien 5360484SobrienThe initial version of this document was written by Ian Lance Taylor 5460484Sobrien@email{ian@@cygnus.com}. 5560484Sobrien 5660484Sobrien@menu 5760484Sobrien* BFD overview:: BFD overview 5860484Sobrien* BFD guidelines:: BFD programming guidelines 5960484Sobrien* BFD target vector:: BFD target vector 6060484Sobrien* BFD generated files:: BFD generated files 6160484Sobrien* BFD multiple compilations:: Files compiled multiple times in BFD 6260484Sobrien* BFD relocation handling:: BFD relocation handling 6360484Sobrien* BFD ELF support:: BFD ELF support 6460484Sobrien* BFD glossary:: Glossary 6560484Sobrien* Index:: Index 6660484Sobrien@end menu 6760484Sobrien 6860484Sobrien@node BFD overview 6960484Sobrien@section BFD overview 7060484Sobrien 7160484SobrienBFD is a library which provides a single interface to read and write 7260484Sobrienobject files, executables, archive files, and core files in any format. 7360484Sobrien 7460484Sobrien@menu 7560484Sobrien* BFD library interfaces:: BFD library interfaces 7660484Sobrien* BFD library users:: BFD library users 7760484Sobrien* BFD view:: The BFD view of a file 7860484Sobrien* BFD blindness:: BFD loses information 7960484Sobrien@end menu 8060484Sobrien 8160484Sobrien@node BFD library interfaces 8260484Sobrien@subsection BFD library interfaces 8360484Sobrien 8460484SobrienOne way to look at the BFD library is to divide it into four parts by 8560484Sobrientype of interface. 8660484Sobrien 8760484SobrienThe first interface is the set of generic functions which programs using 8860484Sobrienthe BFD library will call. These generic function normally translate 8960484Sobriendirectly or indirectly into calls to routines which are specific to a 9060484Sobrienparticular object file format. Many of these generic functions are 9160484Sobrienactually defined as macros in @file{bfd.h}. These functions comprise 9260484Sobrienthe official BFD interface. 9360484Sobrien 9460484SobrienThe second interface is the set of functions which appear in the target 9560484Sobrienvectors. This is the bulk of the code in BFD. A target vector is a set 9660484Sobrienof function pointers specific to a particular object file format. The 9760484Sobrientarget vector is used to implement the generic BFD functions. These 9860484Sobrienfunctions are always called through the target vector, and are never 9960484Sobriencalled directly. The target vector is described in detail in @ref{BFD 10060484Sobrientarget vector}. The set of functions which appear in a particular 10160484Sobrientarget vector is often referred to as a BFD backend. 10260484Sobrien 10360484SobrienThe third interface is a set of oddball functions which are typically 10460484Sobrienspecific to a particular object file format, are not generic functions, 10560484Sobrienand are called from outside of the BFD library. These are used as hooks 10660484Sobrienby the linker and the assembler when a particular object file format 10760484Sobrienrequires some action which the BFD generic interface does not provide. 10860484SobrienThese functions are typically declared in @file{bfd.h}, but in many 10960484Sobriencases they are only provided when BFD is configured with support for a 11060484Sobrienparticular object file format. These functions live in a grey area, and 11160484Sobrienare not really part of the official BFD interface. 11260484Sobrien 11360484SobrienThe fourth interface is the set of BFD support functions which are 11460484Sobriencalled by the other BFD functions. These manage issues like memory 11560484Sobrienallocation, error handling, file access, hash tables, swapping, and the 11660484Sobrienlike. These functions are never called from outside of the BFD library. 11760484Sobrien 11860484Sobrien@node BFD library users 11960484Sobrien@subsection BFD library users 12060484Sobrien 12160484SobrienAnother way to look at the BFD library is to divide it into three parts 12260484Sobrienby the manner in which it is used. 12360484Sobrien 12460484SobrienThe first use is to read an object file. The object file readers are 12560484Sobrienprograms like @samp{gdb}, @samp{nm}, @samp{objdump}, and @samp{objcopy}. 12660484SobrienThese programs use BFD to view an object file in a generic form. The 12760484Sobrienofficial BFD interface is normally fully adequate for these programs. 12860484Sobrien 12960484SobrienThe second use is to write an object file. The object file writers are 13060484Sobrienprograms like @samp{gas} and @samp{objcopy}. These programs use BFD to 13160484Sobriencreate an object file. The official BFD interface is normally adequate 13260484Sobrienfor these programs, but for some object file formats the assembler needs 13360484Sobriensome additional hooks in order to set particular flags or other 13460484Sobrieninformation. The official BFD interface includes functions to copy 13560484Sobrienprivate information from one object file to another, and these functions 13660484Sobrienare used by @samp{objcopy} to avoid information loss. 13760484Sobrien 13860484SobrienThe third use is to link object files. There is only one object file 13960484Sobrienlinker, @samp{ld}. Originally, @samp{ld} was an object file reader and 14060484Sobrienan object file writer, and it did the link operation using the generic 14160484SobrienBFD structures. However, this turned out to be too slow and too memory 14260484Sobrienintensive. 14360484Sobrien 14460484SobrienThe official BFD linker functions were written to permit specific BFD 14560484Sobrienbackends to perform the link without translating through the generic 14660484Sobrienstructures, in the normal case where all the input files and output file 14760484Sobrienhave the same object file format. Not all of the backends currently 14860484Sobrienimplement the new interface, and there are default linking functions 14960484Sobrienwithin BFD which use the generic structures and which work with all 15060484Sobrienbackends. 15160484Sobrien 15260484SobrienFor several object file formats the linker needs additional hooks which 15360484Sobrienare not provided by the official BFD interface, particularly for dynamic 15460484Sobrienlinking support. These functions are typically called from the linker 15560484Sobrienemulation template. 15660484Sobrien 15760484Sobrien@node BFD view 15860484Sobrien@subsection The BFD view of a file 15960484Sobrien 16060484SobrienBFD uses generic structures to manage information. It translates data 16160484Sobrieninto the generic form when reading files, and out of the generic form 16260484Sobrienwhen writing files. 16360484Sobrien 16460484SobrienBFD describes a file as a pointer to the @samp{bfd} type. A @samp{bfd} 16560484Sobrienis composed of the following elements. The BFD information can be 16660484Sobriendisplayed using the @samp{objdump} program with various options. 16760484Sobrien 16860484Sobrien@table @asis 16960484Sobrien@item general information 17060484SobrienThe object file format, a few general flags, the start address. 17160484Sobrien@item architecture 17260484SobrienThe architecture, including both a general processor type (m68k, MIPS 17360484Sobrienetc.) and a specific machine number (m68000, R4000, etc.). 17460484Sobrien@item sections 17560484SobrienA list of sections. 17660484Sobrien@item symbols 17760484SobrienA symbol table. 17860484Sobrien@end table 17960484Sobrien 18060484SobrienBFD represents a section as a pointer to the @samp{asection} type. Each 18160484Sobriensection has a name and a size. Most sections also have an associated 18260484Sobrienblock of data, known as the section contents. Sections also have 18360484Sobrienassociated flags, a virtual memory address, a load memory address, a 18460484Sobrienrequired alignment, a list of relocations, and other miscellaneous 18560484Sobrieninformation. 18660484Sobrien 18760484SobrienBFD represents a relocation as a pointer to the @samp{arelent} type. A 18860484Sobrienrelocation describes an action which the linker must take to modify the 18960484Sobriensection contents. Relocations have a symbol, an address, an addend, and 19060484Sobriena pointer to a howto structure which describes how to perform the 19160484Sobrienrelocation. For more information, see @ref{BFD relocation handling}. 19260484Sobrien 19360484SobrienBFD represents a symbol as a pointer to the @samp{asymbol} type. A 19460484Sobriensymbol has a name, a pointer to a section, an offset within that 19560484Sobriensection, and some flags. 19660484Sobrien 19760484SobrienArchive files do not have any sections or symbols. Instead, BFD 19860484Sobrienrepresents an archive file as a file which contains a list of 19960484Sobrien@samp{bfd}s. BFD also provides access to the archive symbol map, as a 20060484Sobrienlist of symbol names. BFD provides a function to return the @samp{bfd} 20160484Sobrienwithin the archive which corresponds to a particular entry in the 20260484Sobrienarchive symbol map. 20360484Sobrien 20460484Sobrien@node BFD blindness 20560484Sobrien@subsection BFD loses information 20660484Sobrien 20760484SobrienMost object file formats have information which BFD can not represent in 20860484Sobrienits generic form, at least as currently defined. 20960484Sobrien 21060484SobrienThere is often explicit information which BFD can not represent. For 21160484Sobrienexample, the COFF version stamp, or the ELF program segments. BFD 21260484Sobrienprovides special hooks to handle this information when copying, 21360484Sobrienprinting, or linking an object file. The BFD support for a particular 21460484Sobrienobject file format will normally store this information in private data 21560484Sobrienand handle it using the special hooks. 21660484Sobrien 21760484SobrienIn some cases there is also implicit information which BFD can not 21860484Sobrienrepresent. For example, the MIPS processor distinguishes small and 219218822Sdimlarge symbols, and requires that all small symbols be within 32K of the 22060484SobrienGP register. This means that the MIPS assembler must be able to mark 22160484Sobrienvariables as either small or large, and the MIPS linker must know to put 22260484Sobriensmall symbols within range of the GP register. Since BFD can not 22360484Sobrienrepresent this information, this means that the assembler and linker 22460484Sobrienmust have information that is specific to a particular object file 22560484Sobrienformat which is outside of the BFD library. 22660484Sobrien 22760484SobrienThis loss of information indicates areas where the BFD paradigm breaks 22860484Sobriendown. It is not actually possible to represent the myriad differences 22960484Sobrienamong object file formats using a single generic interface, at least not 23060484Sobrienin the manner which BFD does it today. 23160484Sobrien 23260484SobrienNevertheless, the BFD library does greatly simplify the task of dealing 23360484Sobrienwith object files, and particular problems caused by information loss 23460484Sobriencan normally be solved using some sort of relatively constrained hook 23560484Sobrieninto the library. 23660484Sobrien 23760484Sobrien 23860484Sobrien 23960484Sobrien@node BFD guidelines 24060484Sobrien@section BFD programming guidelines 24160484Sobrien@cindex bfd programming guidelines 24260484Sobrien@cindex programming guidelines for bfd 24360484Sobrien@cindex guidelines, bfd programming 24460484Sobrien 24560484SobrienThere is a lot of poorly written and confusing code in BFD. New BFD 24660484Sobriencode should be written to a higher standard. Merely because some BFD 24760484Sobriencode is written in a particular manner does not mean that you should 24860484Sobrienemulate it. 24960484Sobrien 25060484SobrienHere are some general BFD programming guidelines: 25160484Sobrien 25260484Sobrien@itemize @bullet 25360484Sobrien@item 25460484SobrienFollow the GNU coding standards. 25560484Sobrien 25660484Sobrien@item 25760484SobrienAvoid global variables. We ideally want BFD to be fully reentrant, so 25860484Sobrienthat it can be used in multiple threads. All uses of global or static 25960484Sobrienvariables interfere with that. Initialized constant variables are OK, 260218822Sdimand they should be explicitly marked with @samp{const}. Instead of global 26160484Sobrienvariables, use data attached to a BFD or to a linker hash table. 26260484Sobrien 26360484Sobrien@item 26460484SobrienAll externally visible functions should have names which start with 26560484Sobrien@samp{bfd_}. All such functions should be declared in some header file, 26660484Sobrientypically @file{bfd.h}. See, for example, the various declarations near 26760484Sobrienthe end of @file{bfd-in.h}, which mostly declare functions required by 26860484Sobrienspecific linker emulations. 26960484Sobrien 27060484Sobrien@item 27160484SobrienAll functions which need to be visible from one file to another within 27260484SobrienBFD, but should not be visible outside of BFD, should start with 27360484Sobrien@samp{_bfd_}. Although external names beginning with @samp{_} are 27460484Sobrienprohibited by the ANSI standard, in practice this usage will always 27560484Sobrienwork, and it is required by the GNU coding standards. 27660484Sobrien 27760484Sobrien@item 27860484SobrienAlways remember that people can compile using @samp{--enable-targets} to 27960484Sobrienbuild several, or all, targets at once. It must be possible to link 28060484Sobrientogether the files for all targets. 28160484Sobrien 28260484Sobrien@item 28360484SobrienBFD code should compile with few or no warnings using @samp{gcc -Wall}. 28460484SobrienSome warnings are OK, like the absence of certain function declarations 28560484Sobrienwhich may or may not be declared in system header files. Warnings about 28660484Sobrienambiguous expressions and the like should always be fixed. 28760484Sobrien@end itemize 28860484Sobrien 28960484Sobrien@node BFD target vector 29060484Sobrien@section BFD target vector 29160484Sobrien@cindex bfd target vector 29260484Sobrien@cindex target vector in bfd 29360484Sobrien 29460484SobrienBFD supports multiple object file formats by using the @dfn{target 29560484Sobrienvector}. This is simply a set of function pointers which implement 29660484Sobrienbehaviour that is specific to a particular object file format. 29760484Sobrien 29860484SobrienIn this section I list all of the entries in the target vector and 29960484Sobriendescribe what they do. 30060484Sobrien 30160484Sobrien@menu 30260484Sobrien* BFD target vector miscellaneous:: Miscellaneous constants 30360484Sobrien* BFD target vector swap:: Swapping functions 30460484Sobrien* BFD target vector format:: Format type dependent functions 30560484Sobrien* BFD_JUMP_TABLE macros:: BFD_JUMP_TABLE macros 30660484Sobrien* BFD target vector generic:: Generic functions 30760484Sobrien* BFD target vector copy:: Copy functions 30860484Sobrien* BFD target vector core:: Core file support functions 30960484Sobrien* BFD target vector archive:: Archive functions 31060484Sobrien* BFD target vector symbols:: Symbol table functions 31160484Sobrien* BFD target vector relocs:: Relocation support 31260484Sobrien* BFD target vector write:: Output functions 31360484Sobrien* BFD target vector link:: Linker functions 31460484Sobrien* BFD target vector dynamic:: Dynamic linking information functions 31560484Sobrien@end menu 31660484Sobrien 31760484Sobrien@node BFD target vector miscellaneous 31860484Sobrien@subsection Miscellaneous constants 31960484Sobrien 32060484SobrienThe target vector starts with a set of constants. 32160484Sobrien 32260484Sobrien@table @samp 32360484Sobrien@item name 32460484SobrienThe name of the target vector. This is an arbitrary string. This is 32560484Sobrienhow the target vector is named in command line options for tools which 32678828Sobrienuse BFD, such as the @samp{--oformat} linker option. 32760484Sobrien 32860484Sobrien@item flavour 32960484SobrienA general description of the type of target. The following flavours are 33060484Sobriencurrently defined: 33160484Sobrien 33260484Sobrien@table @samp 33360484Sobrien@item bfd_target_unknown_flavour 33460484SobrienUndefined or unknown. 33560484Sobrien@item bfd_target_aout_flavour 33660484Sobriena.out. 33760484Sobrien@item bfd_target_coff_flavour 33860484SobrienCOFF. 33960484Sobrien@item bfd_target_ecoff_flavour 34060484SobrienECOFF. 34160484Sobrien@item bfd_target_elf_flavour 34260484SobrienELF. 34360484Sobrien@item bfd_target_ieee_flavour 34460484SobrienIEEE-695. 34560484Sobrien@item bfd_target_nlm_flavour 34660484SobrienNLM. 34760484Sobrien@item bfd_target_oasys_flavour 34860484SobrienOASYS. 34960484Sobrien@item bfd_target_tekhex_flavour 35060484SobrienTektronix hex format. 35160484Sobrien@item bfd_target_srec_flavour 35260484SobrienMotorola S-record format. 35360484Sobrien@item bfd_target_ihex_flavour 35460484SobrienIntel hex format. 35560484Sobrien@item bfd_target_som_flavour 35660484SobrienSOM (used on HP/UX). 35760484Sobrien@item bfd_target_os9k_flavour 35860484Sobrienos9000. 35960484Sobrien@item bfd_target_versados_flavour 36060484SobrienVERSAdos. 36160484Sobrien@item bfd_target_msdos_flavour 36260484SobrienMS-DOS. 36360484Sobrien@item bfd_target_evax_flavour 36460484SobrienopenVMS. 36589857Sobrien@item bfd_target_mmo_flavour 36689857SobrienDonald Knuth's MMIXware object format. 36760484Sobrien@end table 36860484Sobrien 36960484Sobrien@item byteorder 37060484SobrienThe byte order of data in the object file. One of 37160484Sobrien@samp{BFD_ENDIAN_BIG}, @samp{BFD_ENDIAN_LITTLE}, or 37260484Sobrien@samp{BFD_ENDIAN_UNKNOWN}. The latter would be used for a format such 37360484Sobrienas S-records which do not record the architecture of the data. 37460484Sobrien 37560484Sobrien@item header_byteorder 37660484SobrienThe byte order of header information in the object file. Normally the 37760484Sobriensame as the @samp{byteorder} field, but there are certain cases where it 37860484Sobrienmay be different. 37960484Sobrien 38060484Sobrien@item object_flags 38160484SobrienFlags which may appear in the @samp{flags} field of a BFD with this 38260484Sobrienformat. 38360484Sobrien 38460484Sobrien@item section_flags 38560484SobrienFlags which may appear in the @samp{flags} field of a section within a 38660484SobrienBFD with this format. 38760484Sobrien 38860484Sobrien@item symbol_leading_char 38960484SobrienA character which the C compiler normally puts before a symbol. For 39060484Sobrienexample, an a.out compiler will typically generate the symbol 39160484Sobrien@samp{_foo} for a function named @samp{foo} in the C source, in which 39260484Sobriencase this field would be @samp{_}. If there is no such character, this 39360484Sobrienfield will be @samp{0}. 39460484Sobrien 39560484Sobrien@item ar_pad_char 39660484SobrienThe padding character to use at the end of an archive name. Normally 39760484Sobrien@samp{/}. 39860484Sobrien 39960484Sobrien@item ar_max_namelen 40060484SobrienThe maximum length of a short name in an archive. Normally @samp{14}. 40160484Sobrien 40260484Sobrien@item backend_data 40360484SobrienA pointer to constant backend data. This is used by backends to store 40460484Sobrienwhatever additional information they need to distinguish similar target 40560484Sobrienvectors which use the same sets of functions. 40660484Sobrien@end table 40760484Sobrien 40860484Sobrien@node BFD target vector swap 40960484Sobrien@subsection Swapping functions 41060484Sobrien 41189857SobrienEvery target vector has function pointers used for swapping information 41260484Sobrienin and out of the target representation. There are two sets of 41360484Sobrienfunctions: one for data information, and one for header information. 41460484SobrienEach set has three sizes: 64-bit, 32-bit, and 16-bit. Each size has 41560484Sobrienthree actual functions: put, get unsigned, and get signed. 41660484Sobrien 41760484SobrienThese 18 functions are used to convert data between the host and target 41860484Sobrienrepresentations. 41960484Sobrien 42060484Sobrien@node BFD target vector format 42160484Sobrien@subsection Format type dependent functions 42260484Sobrien 42360484SobrienEvery target vector has three arrays of function pointers which are 42460484Sobrienindexed by the BFD format type. The BFD format types are as follows: 42560484Sobrien 42660484Sobrien@table @samp 42760484Sobrien@item bfd_unknown 42860484SobrienUnknown format. Not used for anything useful. 42960484Sobrien@item bfd_object 43060484SobrienObject file. 43160484Sobrien@item bfd_archive 43260484SobrienArchive file. 43360484Sobrien@item bfd_core 43460484SobrienCore file. 43560484Sobrien@end table 43660484Sobrien 43760484SobrienThe three arrays of function pointers are as follows: 43860484Sobrien 43960484Sobrien@table @samp 44060484Sobrien@item bfd_check_format 44160484SobrienCheck whether the BFD is of a particular format (object file, archive 44260484Sobrienfile, or core file) corresponding to this target vector. This is called 44360484Sobrienby the @samp{bfd_check_format} function when examining an existing BFD. 44460484SobrienIf the BFD matches the desired format, this function will initialize any 44560484Sobrienformat specific information such as the @samp{tdata} field of the BFD. 44660484SobrienThis function must be called before any other BFD target vector function 44760484Sobrienon a file opened for reading. 44860484Sobrien 44960484Sobrien@item bfd_set_format 45060484SobrienSet the format of a BFD which was created for output. This is called by 45160484Sobrienthe @samp{bfd_set_format} function after creating the BFD with a 45260484Sobrienfunction such as @samp{bfd_openw}. This function will initialize format 45360484Sobrienspecific information required to write out an object file or whatever of 45460484Sobrienthe given format. This function must be called before any other BFD 45560484Sobrientarget vector function on a file opened for writing. 45660484Sobrien 45760484Sobrien@item bfd_write_contents 45860484SobrienWrite out the contents of the BFD in the given format. This is called 45960484Sobrienby @samp{bfd_close} function for a BFD opened for writing. This really 46060484Sobrienshould not be an array selected by format type, as the 46160484Sobrien@samp{bfd_set_format} function provides all the required information. 46260484SobrienIn fact, BFD will fail if a different format is used when calling 46360484Sobrienthrough the @samp{bfd_set_format} and the @samp{bfd_write_contents} 46460484Sobrienarrays; fortunately, since @samp{bfd_close} gets it right, this is a 46560484Sobriendifficult error to make. 46660484Sobrien@end table 46760484Sobrien 46860484Sobrien@node BFD_JUMP_TABLE macros 46960484Sobrien@subsection @samp{BFD_JUMP_TABLE} macros 47060484Sobrien@cindex @samp{BFD_JUMP_TABLE} 47160484Sobrien 47260484SobrienMost target vectors are defined using @samp{BFD_JUMP_TABLE} macros. 47360484SobrienThese macros take a single argument, which is a prefix applied to a set 47460484Sobrienof functions. The macros are then used to initialize the fields in the 47560484Sobrientarget vector. 47660484Sobrien 47760484SobrienFor example, the @samp{BFD_JUMP_TABLE_RELOCS} macro defines three 47860484Sobrienfunctions: @samp{_get_reloc_upper_bound}, @samp{_canonicalize_reloc}, 47960484Sobrienand @samp{_bfd_reloc_type_lookup}. A reference like 48060484Sobrien@samp{BFD_JUMP_TABLE_RELOCS (foo)} will expand into three functions 48160484Sobrienprefixed with @samp{foo}: @samp{foo_get_reloc_upper_bound}, etc. The 48260484Sobrien@samp{BFD_JUMP_TABLE_RELOCS} macro will be placed such that those three 48360484Sobrienfunctions initialize the appropriate fields in the BFD target vector. 48460484Sobrien 48560484SobrienThis is done because it turns out that many different target vectors can 48660484Sobrienshare certain classes of functions. For example, archives are similar 48760484Sobrienon most platforms, so most target vectors can use the same archive 48860484Sobrienfunctions. Those target vectors all use @samp{BFD_JUMP_TABLE_ARCHIVE} 48960484Sobrienwith the same argument, calling a set of functions which is defined in 49060484Sobrien@file{archive.c}. 49160484Sobrien 49260484SobrienEach of the @samp{BFD_JUMP_TABLE} macros is mentioned below along with 49360484Sobrienthe description of the function pointers which it defines. The function 49460484Sobrienpointers will be described using the name without the prefix which the 49560484Sobrien@samp{BFD_JUMP_TABLE} macro defines. This name is normally the same as 49660484Sobrienthe name of the field in the target vector structure. Any differences 49760484Sobrienwill be noted. 49860484Sobrien 49960484Sobrien@node BFD target vector generic 50060484Sobrien@subsection Generic functions 50160484Sobrien@cindex @samp{BFD_JUMP_TABLE_GENERIC} 50260484Sobrien 50360484SobrienThe @samp{BFD_JUMP_TABLE_GENERIC} macro is used for some catch all 50460484Sobrienfunctions which don't easily fit into other categories. 50560484Sobrien 50660484Sobrien@table @samp 50760484Sobrien@item _close_and_cleanup 50860484SobrienFree any target specific information associated with the BFD. This is 50960484Sobriencalled when any BFD is closed (the @samp{bfd_write_contents} function 51060484Sobrienmentioned earlier is only called for a BFD opened for writing). Most 51160484Sobrientargets use @samp{bfd_alloc} to allocate all target specific 51260484Sobrieninformation, and therefore don't have to do anything in this function. 51360484SobrienThis function pointer is typically set to 51460484Sobrien@samp{_bfd_generic_close_and_cleanup}, which simply returns true. 51560484Sobrien 51660484Sobrien@item _bfd_free_cached_info 51760484SobrienFree any cached information associated with the BFD which can be 51860484Sobrienrecreated later if necessary. This is used to reduce the memory 51960484Sobrienconsumption required by programs using BFD. This is normally called via 52060484Sobrienthe @samp{bfd_free_cached_info} macro. It is used by the default 52160484Sobrienarchive routines when computing the archive map. Most targets do not 52260484Sobriendo anything special for this entry point, and just set it to 52360484Sobrien@samp{_bfd_generic_free_cached_info}, which simply returns true. 52460484Sobrien 52560484Sobrien@item _new_section_hook 52660484SobrienThis is called from @samp{bfd_make_section_anyway} whenever a new 52760484Sobriensection is created. Most targets use it to initialize section specific 52860484Sobrieninformation. This function is called whether or not the section 52960484Sobriencorresponds to an actual section in an actual BFD. 53060484Sobrien 53160484Sobrien@item _get_section_contents 53260484SobrienGet the contents of a section. This is called from 53360484Sobrien@samp{bfd_get_section_contents}. Most targets set this to 53460484Sobrien@samp{_bfd_generic_get_section_contents}, which does a @samp{bfd_seek} 53589857Sobrienbased on the section's @samp{filepos} field and a @samp{bfd_bread}. The 53660484Sobriencorresponding field in the target vector is named 53760484Sobrien@samp{_bfd_get_section_contents}. 53860484Sobrien 53960484Sobrien@item _get_section_contents_in_window 54060484SobrienSet a @samp{bfd_window} to hold the contents of a section. This is 54160484Sobriencalled from @samp{bfd_get_section_contents_in_window}. The 54260484Sobrien@samp{bfd_window} idea never really caught on, and I don't think this is 54360484Sobrienever called. Pretty much all targets implement this as 54460484Sobrien@samp{bfd_generic_get_section_contents_in_window}, which uses 54560484Sobrien@samp{bfd_get_section_contents} to do the right thing. The 54660484Sobriencorresponding field in the target vector is named 54760484Sobrien@samp{_bfd_get_section_contents_in_window}. 54860484Sobrien@end table 54960484Sobrien 55060484Sobrien@node BFD target vector copy 55160484Sobrien@subsection Copy functions 55260484Sobrien@cindex @samp{BFD_JUMP_TABLE_COPY} 55360484Sobrien 55460484SobrienThe @samp{BFD_JUMP_TABLE_COPY} macro is used for functions which are 55560484Sobriencalled when copying BFDs, and for a couple of functions which deal with 55660484Sobrieninternal BFD information. 55760484Sobrien 55860484Sobrien@table @samp 55960484Sobrien@item _bfd_copy_private_bfd_data 56060484SobrienThis is called when copying a BFD, via @samp{bfd_copy_private_bfd_data}. 56160484SobrienIf the input and output BFDs have the same format, this will copy any 56260484Sobrienprivate information over. This is called after all the section contents 56360484Sobrienhave been written to the output file. Only a few targets do anything in 56460484Sobrienthis function. 56560484Sobrien 56660484Sobrien@item _bfd_merge_private_bfd_data 56760484SobrienThis is called when linking, via @samp{bfd_merge_private_bfd_data}. It 56860484Sobriengives the backend linker code a chance to set any special flags in the 56960484Sobrienoutput file based on the contents of the input file. Only a few targets 57060484Sobriendo anything in this function. 57160484Sobrien 57260484Sobrien@item _bfd_copy_private_section_data 57360484SobrienThis is similar to @samp{_bfd_copy_private_bfd_data}, but it is called 57460484Sobrienfor each section, via @samp{bfd_copy_private_section_data}. This 57560484Sobrienfunction is called before any section contents have been written. Only 57660484Sobriena few targets do anything in this function. 57760484Sobrien 57860484Sobrien@item _bfd_copy_private_symbol_data 57960484SobrienThis is called via @samp{bfd_copy_private_symbol_data}, but I don't 58060484Sobrienthink anything actually calls it. If it were defined, it could be used 58160484Sobriento copy private symbol data from one BFD to another. However, most BFDs 58260484Sobrienstore extra symbol information by allocating space which is larger than 58360484Sobrienthe @samp{asymbol} structure and storing private information in the 58460484Sobrienextra space. Since @samp{objcopy} and other programs copy symbol 58560484Sobrieninformation by copying pointers to @samp{asymbol} structures, the 58660484Sobrienprivate symbol information is automatically copied as well. Most 58760484Sobrientargets do not do anything in this function. 58860484Sobrien 58960484Sobrien@item _bfd_set_private_flags 59060484SobrienThis is called via @samp{bfd_set_private_flags}. It is basically a hook 59160484Sobrienfor the assembler to set magic information. For example, the PowerPC 59260484SobrienELF assembler uses it to set flags which appear in the e_flags field of 59360484Sobrienthe ELF header. Most targets do not do anything in this function. 59460484Sobrien 59560484Sobrien@item _bfd_print_private_bfd_data 59660484SobrienThis is called by @samp{objdump} when the @samp{-p} option is used. It 59760484Sobrienis called via @samp{bfd_print_private_data}. It prints any interesting 59860484Sobrieninformation about the BFD which can not be otherwise represented by BFD 59960484Sobrienand thus can not be printed by @samp{objdump}. Most targets do not do 60060484Sobrienanything in this function. 60160484Sobrien@end table 60260484Sobrien 60360484Sobrien@node BFD target vector core 60460484Sobrien@subsection Core file support functions 60560484Sobrien@cindex @samp{BFD_JUMP_TABLE_CORE} 60660484Sobrien 60760484SobrienThe @samp{BFD_JUMP_TABLE_CORE} macro is used for functions which deal 60860484Sobrienwith core files. Obviously, these functions only do something 60960484Sobrieninteresting for targets which have core file support. 61060484Sobrien 61160484Sobrien@table @samp 61260484Sobrien@item _core_file_failing_command 61360484SobrienGiven a core file, this returns the command which was run to produce the 61460484Sobriencore file. 61560484Sobrien 61660484Sobrien@item _core_file_failing_signal 61760484SobrienGiven a core file, this returns the signal number which produced the 61860484Sobriencore file. 61960484Sobrien 62060484Sobrien@item _core_file_matches_executable_p 62160484SobrienGiven a core file and a BFD for an executable, this returns whether the 62260484Sobriencore file was generated by the executable. 62360484Sobrien@end table 62460484Sobrien 62560484Sobrien@node BFD target vector archive 62660484Sobrien@subsection Archive functions 62760484Sobrien@cindex @samp{BFD_JUMP_TABLE_ARCHIVE} 62860484Sobrien 62960484SobrienThe @samp{BFD_JUMP_TABLE_ARCHIVE} macro is used for functions which deal 63060484Sobrienwith archive files. Most targets use COFF style archive files 63160484Sobrien(including ELF targets), and these use @samp{_bfd_archive_coff} as the 63260484Sobrienargument to @samp{BFD_JUMP_TABLE_ARCHIVE}. Some targets use BSD/a.out 63360484Sobrienstyle archives, and these use @samp{_bfd_archive_bsd}. (The main 63460484Sobriendifference between BSD and COFF archives is the format of the archive 63560484Sobriensymbol table). Targets with no archive support use 63660484Sobrien@samp{_bfd_noarchive}. Finally, a few targets have unusual archive 63760484Sobrienhandling. 63860484Sobrien 63960484Sobrien@table @samp 64060484Sobrien@item _slurp_armap 64160484SobrienRead in the archive symbol table, storing it in private BFD data. This 64260484Sobrienis normally called from the archive @samp{check_format} routine. The 64360484Sobriencorresponding field in the target vector is named 64460484Sobrien@samp{_bfd_slurp_armap}. 64560484Sobrien 64660484Sobrien@item _slurp_extended_name_table 64760484SobrienRead in the extended name table from the archive, if there is one, 64860484Sobrienstoring it in private BFD data. This is normally called from the 64960484Sobrienarchive @samp{check_format} routine. The corresponding field in the 65060484Sobrientarget vector is named @samp{_bfd_slurp_extended_name_table}. 65160484Sobrien 65260484Sobrien@item construct_extended_name_table 65360484SobrienBuild and return an extended name table if one is needed to write out 65460484Sobrienthe archive. This also adjusts the archive headers to refer to the 65560484Sobrienextended name table appropriately. This is normally called from the 65660484Sobrienarchive @samp{write_contents} routine. The corresponding field in the 65760484Sobrientarget vector is named @samp{_bfd_construct_extended_name_table}. 65860484Sobrien 65960484Sobrien@item _truncate_arname 66060484SobrienThis copies a file name into an archive header, truncating it as 66160484Sobrienrequired. It is normally called from the archive @samp{write_contents} 66260484Sobrienroutine. This function is more interesting in targets which do not 66360484Sobriensupport extended name tables, but I think the GNU @samp{ar} program 66460484Sobrienalways uses extended name tables anyhow. The corresponding field in the 66560484Sobrientarget vector is named @samp{_bfd_truncate_arname}. 66660484Sobrien 66760484Sobrien@item _write_armap 66889857SobrienWrite out the archive symbol table using calls to @samp{bfd_bwrite}. 66960484SobrienThis is normally called from the archive @samp{write_contents} routine. 67060484SobrienThe corresponding field in the target vector is named @samp{write_armap} 67160484Sobrien(no leading underscore). 67260484Sobrien 67360484Sobrien@item _read_ar_hdr 67460484SobrienRead and parse an archive header. This handles expanding the archive 67560484Sobrienheader name into the real file name using the extended name table. This 67660484Sobrienis called by routines which read the archive symbol table or the archive 67760484Sobrienitself. The corresponding field in the target vector is named 67860484Sobrien@samp{_bfd_read_ar_hdr_fn}. 67960484Sobrien 68060484Sobrien@item _openr_next_archived_file 68160484SobrienGiven an archive and a BFD representing a file stored within the 68260484Sobrienarchive, return a BFD for the next file in the archive. This is called 68360484Sobrienvia @samp{bfd_openr_next_archived_file}. The corresponding field in the 68460484Sobrientarget vector is named @samp{openr_next_archived_file} (no leading 68560484Sobrienunderscore). 68660484Sobrien 68760484Sobrien@item _get_elt_at_index 68860484SobrienGiven an archive and an index, return a BFD for the file in the archive 68960484Sobriencorresponding to that entry in the archive symbol table. This is called 69060484Sobrienvia @samp{bfd_get_elt_at_index}. The corresponding field in the target 69160484Sobrienvector is named @samp{_bfd_get_elt_at_index}. 69260484Sobrien 69360484Sobrien@item _generic_stat_arch_elt 69460484SobrienDo a stat on an element of an archive, returning information read from 69560484Sobrienthe archive header (modification time, uid, gid, file mode, size). This 69660484Sobrienis called via @samp{bfd_stat_arch_elt}. The corresponding field in the 69760484Sobrientarget vector is named @samp{_bfd_stat_arch_elt}. 69860484Sobrien 69960484Sobrien@item _update_armap_timestamp 70060484SobrienAfter the entire contents of an archive have been written out, update 70160484Sobrienthe timestamp of the archive symbol table to be newer than that of the 70260484Sobrienfile. This is required for a.out style archives. This is normally 70360484Sobriencalled by the archive @samp{write_contents} routine. The corresponding 70460484Sobrienfield in the target vector is named @samp{_bfd_update_armap_timestamp}. 70560484Sobrien@end table 70660484Sobrien 70760484Sobrien@node BFD target vector symbols 70860484Sobrien@subsection Symbol table functions 70960484Sobrien@cindex @samp{BFD_JUMP_TABLE_SYMBOLS} 71060484Sobrien 71160484SobrienThe @samp{BFD_JUMP_TABLE_SYMBOLS} macro is used for functions which deal 71260484Sobrienwith symbols. 71360484Sobrien 71460484Sobrien@table @samp 71560484Sobrien@item _get_symtab_upper_bound 71660484SobrienReturn a sensible upper bound on the amount of memory which will be 71760484Sobrienrequired to read the symbol table. In practice most targets return the 71860484Sobrienamount of memory required to hold @samp{asymbol} pointers for all the 71960484Sobriensymbols plus a trailing @samp{NULL} entry, and store the actual symbol 72060484Sobrieninformation in BFD private data. This is called via 72160484Sobrien@samp{bfd_get_symtab_upper_bound}. The corresponding field in the 72260484Sobrientarget vector is named @samp{_bfd_get_symtab_upper_bound}. 72360484Sobrien 724130561Sobrien@item _canonicalize_symtab 72560484SobrienRead in the symbol table. This is called via 72660484Sobrien@samp{bfd_canonicalize_symtab}. The corresponding field in the target 72760484Sobrienvector is named @samp{_bfd_canonicalize_symtab}. 72860484Sobrien 72960484Sobrien@item _make_empty_symbol 73060484SobrienCreate an empty symbol for the BFD. This is needed because most targets 73160484Sobrienstore extra information with each symbol by allocating a structure 73260484Sobrienlarger than an @samp{asymbol} and storing the extra information at the 73360484Sobrienend. This function will allocate the right amount of memory, and return 73460484Sobrienwhat looks like a pointer to an empty @samp{asymbol}. This is called 73560484Sobrienvia @samp{bfd_make_empty_symbol}. The corresponding field in the target 73660484Sobrienvector is named @samp{_bfd_make_empty_symbol}. 73760484Sobrien 73860484Sobrien@item _print_symbol 73960484SobrienPrint information about the symbol. This is called via 74060484Sobrien@samp{bfd_print_symbol}. One of the arguments indicates what sort of 74160484Sobrieninformation should be printed: 74260484Sobrien 74360484Sobrien@table @samp 74460484Sobrien@item bfd_print_symbol_name 74560484SobrienJust print the symbol name. 74660484Sobrien@item bfd_print_symbol_more 74760484SobrienPrint the symbol name and some interesting flags. I don't think 74860484Sobrienanything actually uses this. 74960484Sobrien@item bfd_print_symbol_all 75060484SobrienPrint all information about the symbol. This is used by @samp{objdump} 75160484Sobrienwhen run with the @samp{-t} option. 75260484Sobrien@end table 75360484SobrienThe corresponding field in the target vector is named 75460484Sobrien@samp{_bfd_print_symbol}. 75560484Sobrien 75660484Sobrien@item _get_symbol_info 75760484SobrienReturn a standard set of information about the symbol. This is called 75860484Sobrienvia @samp{bfd_symbol_info}. The corresponding field in the target 75960484Sobrienvector is named @samp{_bfd_get_symbol_info}. 76060484Sobrien 76160484Sobrien@item _bfd_is_local_label_name 76260484SobrienReturn whether the given string would normally represent the name of a 76360484Sobrienlocal label. This is called via @samp{bfd_is_local_label} and 76460484Sobrien@samp{bfd_is_local_label_name}. Local labels are normally discarded by 76560484Sobrienthe assembler. In the linker, this defines the difference between the 76660484Sobrien@samp{-x} and @samp{-X} options. 76760484Sobrien 76860484Sobrien@item _get_lineno 76960484SobrienReturn line number information for a symbol. This is only meaningful 77060484Sobrienfor a COFF target. This is called when writing out COFF line numbers. 77160484Sobrien 77260484Sobrien@item _find_nearest_line 77360484SobrienGiven an address within a section, use the debugging information to find 77460484Sobrienthe matching file name, function name, and line number, if any. This is 77560484Sobriencalled via @samp{bfd_find_nearest_line}. The corresponding field in the 77660484Sobrientarget vector is named @samp{_bfd_find_nearest_line}. 77760484Sobrien 77860484Sobrien@item _bfd_make_debug_symbol 77960484SobrienMake a debugging symbol. This is only meaningful for a COFF target, 78060484Sobrienwhere it simply returns a symbol which will be placed in the 78160484Sobrien@samp{N_DEBUG} section when it is written out. This is called via 78260484Sobrien@samp{bfd_make_debug_symbol}. 78360484Sobrien 78460484Sobrien@item _read_minisymbols 78560484SobrienMinisymbols are used to reduce the memory requirements of programs like 78660484Sobrien@samp{nm}. A minisymbol is a cookie pointing to internal symbol 78760484Sobrieninformation which the caller can use to extract complete symbol 78860484Sobrieninformation. This permits BFD to not convert all the symbols into 78960484Sobriengeneric form, but to instead convert them one at a time. This is called 79060484Sobrienvia @samp{bfd_read_minisymbols}. Most targets do not implement this, 79160484Sobrienand just use generic support which is based on using standard 79260484Sobrien@samp{asymbol} structures. 79360484Sobrien 79460484Sobrien@item _minisymbol_to_symbol 79560484SobrienConvert a minisymbol to a standard @samp{asymbol}. This is called via 79660484Sobrien@samp{bfd_minisymbol_to_symbol}. 79760484Sobrien@end table 79860484Sobrien 79960484Sobrien@node BFD target vector relocs 80060484Sobrien@subsection Relocation support 80160484Sobrien@cindex @samp{BFD_JUMP_TABLE_RELOCS} 80260484Sobrien 80360484SobrienThe @samp{BFD_JUMP_TABLE_RELOCS} macro is used for functions which deal 80460484Sobrienwith relocations. 80560484Sobrien 80660484Sobrien@table @samp 80760484Sobrien@item _get_reloc_upper_bound 80860484SobrienReturn a sensible upper bound on the amount of memory which will be 80960484Sobrienrequired to read the relocations for a section. In practice most 81060484Sobrientargets return the amount of memory required to hold @samp{arelent} 81160484Sobrienpointers for all the relocations plus a trailing @samp{NULL} entry, and 81260484Sobrienstore the actual relocation information in BFD private data. This is 81360484Sobriencalled via @samp{bfd_get_reloc_upper_bound}. 81460484Sobrien 81560484Sobrien@item _canonicalize_reloc 81660484SobrienReturn the relocation information for a section. This is called via 81760484Sobrien@samp{bfd_canonicalize_reloc}. The corresponding field in the target 81860484Sobrienvector is named @samp{_bfd_canonicalize_reloc}. 81960484Sobrien 82060484Sobrien@item _bfd_reloc_type_lookup 82160484SobrienGiven a relocation code, return the corresponding howto structure 82260484Sobrien(@pxref{BFD relocation codes}). This is called via 82360484Sobrien@samp{bfd_reloc_type_lookup}. The corresponding field in the target 82460484Sobrienvector is named @samp{reloc_type_lookup}. 82560484Sobrien@end table 82660484Sobrien 82760484Sobrien@node BFD target vector write 82860484Sobrien@subsection Output functions 82960484Sobrien@cindex @samp{BFD_JUMP_TABLE_WRITE} 83060484Sobrien 83160484SobrienThe @samp{BFD_JUMP_TABLE_WRITE} macro is used for functions which deal 83260484Sobrienwith writing out a BFD. 83360484Sobrien 83460484Sobrien@table @samp 83560484Sobrien@item _set_arch_mach 83660484SobrienSet the architecture and machine number for a BFD. This is called via 83760484Sobrien@samp{bfd_set_arch_mach}. Most targets implement this by calling 83860484Sobrien@samp{bfd_default_set_arch_mach}. The corresponding field in the target 83960484Sobrienvector is named @samp{_bfd_set_arch_mach}. 84060484Sobrien 84160484Sobrien@item _set_section_contents 84260484SobrienWrite out the contents of a section. This is called via 84360484Sobrien@samp{bfd_set_section_contents}. The corresponding field in the target 84460484Sobrienvector is named @samp{_bfd_set_section_contents}. 84560484Sobrien@end table 84660484Sobrien 84760484Sobrien@node BFD target vector link 84860484Sobrien@subsection Linker functions 84960484Sobrien@cindex @samp{BFD_JUMP_TABLE_LINK} 85060484Sobrien 85160484SobrienThe @samp{BFD_JUMP_TABLE_LINK} macro is used for functions called by the 85260484Sobrienlinker. 85360484Sobrien 85460484Sobrien@table @samp 85560484Sobrien@item _sizeof_headers 85660484SobrienReturn the size of the header information required for a BFD. This is 85760484Sobrienused to implement the @samp{SIZEOF_HEADERS} linker script function. It 85860484Sobrienis normally used to align the first section at an efficient position on 85960484Sobrienthe page. This is called via @samp{bfd_sizeof_headers}. The 86060484Sobriencorresponding field in the target vector is named 86160484Sobrien@samp{_bfd_sizeof_headers}. 86260484Sobrien 86360484Sobrien@item _bfd_get_relocated_section_contents 86460484SobrienRead the contents of a section and apply the relocation information. 865130561SobrienThis handles both a final link and a relocatable link; in the latter 86660484Sobriencase, it adjust the relocation information as well. This is called via 86760484Sobrien@samp{bfd_get_relocated_section_contents}. Most targets implement it by 86860484Sobriencalling @samp{bfd_generic_get_relocated_section_contents}. 86960484Sobrien 87060484Sobrien@item _bfd_relax_section 87160484SobrienTry to use relaxation to shrink the size of a section. This is called 87260484Sobrienby the linker when the @samp{-relax} option is used. This is called via 87360484Sobrien@samp{bfd_relax_section}. Most targets do not support any sort of 87460484Sobrienrelaxation. 87560484Sobrien 87660484Sobrien@item _bfd_link_hash_table_create 87760484SobrienCreate the symbol hash table to use for the linker. This linker hook 87860484Sobrienpermits the backend to control the size and information of the elements 87960484Sobrienin the linker symbol hash table. This is called via 88060484Sobrien@samp{bfd_link_hash_table_create}. 88160484Sobrien 88260484Sobrien@item _bfd_link_add_symbols 88360484SobrienGiven an object file or an archive, add all symbols into the linker 88460484Sobriensymbol hash table. Use callbacks to the linker to include archive 88560484Sobrienelements in the link. This is called via @samp{bfd_link_add_symbols}. 88660484Sobrien 88760484Sobrien@item _bfd_final_link 88860484SobrienFinish the linking process. The linker calls this hook after all of the 88960484Sobrieninput files have been read, when it is ready to finish the link and 89060484Sobriengenerate the output file. This is called via @samp{bfd_final_link}. 89160484Sobrien 89260484Sobrien@item _bfd_link_split_section 89360484SobrienI don't know what this is for. Nothing seems to call it. The only 89460484Sobriennon-trivial definition is in @file{som.c}. 89560484Sobrien@end table 89660484Sobrien 89760484Sobrien@node BFD target vector dynamic 89860484Sobrien@subsection Dynamic linking information functions 89960484Sobrien@cindex @samp{BFD_JUMP_TABLE_DYNAMIC} 90060484Sobrien 90160484SobrienThe @samp{BFD_JUMP_TABLE_DYNAMIC} macro is used for functions which read 90260484Sobriendynamic linking information. 90360484Sobrien 90460484Sobrien@table @samp 90560484Sobrien@item _get_dynamic_symtab_upper_bound 90660484SobrienReturn a sensible upper bound on the amount of memory which will be 90760484Sobrienrequired to read the dynamic symbol table. In practice most targets 90860484Sobrienreturn the amount of memory required to hold @samp{asymbol} pointers for 90960484Sobrienall the symbols plus a trailing @samp{NULL} entry, and store the actual 91060484Sobriensymbol information in BFD private data. This is called via 91160484Sobrien@samp{bfd_get_dynamic_symtab_upper_bound}. The corresponding field in 91260484Sobrienthe target vector is named @samp{_bfd_get_dynamic_symtab_upper_bound}. 91360484Sobrien 91460484Sobrien@item _canonicalize_dynamic_symtab 91560484SobrienRead the dynamic symbol table. This is called via 91660484Sobrien@samp{bfd_canonicalize_dynamic_symtab}. The corresponding field in the 91760484Sobrientarget vector is named @samp{_bfd_canonicalize_dynamic_symtab}. 91860484Sobrien 91960484Sobrien@item _get_dynamic_reloc_upper_bound 92060484SobrienReturn a sensible upper bound on the amount of memory which will be 92160484Sobrienrequired to read the dynamic relocations. In practice most targets 92260484Sobrienreturn the amount of memory required to hold @samp{arelent} pointers for 92360484Sobrienall the relocations plus a trailing @samp{NULL} entry, and store the 92460484Sobrienactual relocation information in BFD private data. This is called via 92560484Sobrien@samp{bfd_get_dynamic_reloc_upper_bound}. The corresponding field in 92660484Sobrienthe target vector is named @samp{_bfd_get_dynamic_reloc_upper_bound}. 92760484Sobrien 92860484Sobrien@item _canonicalize_dynamic_reloc 92960484SobrienRead the dynamic relocations. This is called via 93060484Sobrien@samp{bfd_canonicalize_dynamic_reloc}. The corresponding field in the 93160484Sobrientarget vector is named @samp{_bfd_canonicalize_dynamic_reloc}. 93260484Sobrien@end table 93360484Sobrien 93460484Sobrien@node BFD generated files 93560484Sobrien@section BFD generated files 93660484Sobrien@cindex generated files in bfd 93760484Sobrien@cindex bfd generated files 93860484Sobrien 93960484SobrienBFD contains several automatically generated files. This section 94060484Sobriendescribes them. Some files are created at configure time, when you 94160484Sobrienconfigure BFD. Some files are created at make time, when you build 94260484SobrienBFD. Some files are automatically rebuilt at make time, but only if 94360484Sobrienyou configure with the @samp{--enable-maintainer-mode} option. Some 94460484Sobrienfiles live in the object directory---the directory from which you run 94560484Sobrienconfigure---and some live in the source directory. All files that live 94660484Sobrienin the source directory are checked into the CVS repository. 94760484Sobrien 94860484Sobrien@table @file 94960484Sobrien@item bfd.h 95060484Sobrien@cindex @file{bfd.h} 95160484Sobrien@cindex @file{bfd-in3.h} 95260484SobrienLives in the object directory. Created at make time from 95360484Sobrien@file{bfd-in2.h} via @file{bfd-in3.h}. @file{bfd-in3.h} is created at 95460484Sobrienconfigure time from @file{bfd-in2.h}. There are automatic dependencies 95560484Sobriento rebuild @file{bfd-in3.h} and hence @file{bfd.h} if @file{bfd-in2.h} 95660484Sobrienchanges, so you can normally ignore @file{bfd-in3.h}, and just think 95760484Sobrienabout @file{bfd-in2.h} and @file{bfd.h}. 95860484Sobrien 95960484Sobrien@file{bfd.h} is built by replacing a few strings in @file{bfd-in2.h}. 96060484SobrienTo see them, search for @samp{@@} in @file{bfd-in2.h}. They mainly 96160484Sobriencontrol whether BFD is built for a 32 bit target or a 64 bit target. 96260484Sobrien 96360484Sobrien@item bfd-in2.h 96460484Sobrien@cindex @file{bfd-in2.h} 96560484SobrienLives in the source directory. Created from @file{bfd-in.h} and several 96660484Sobrienother BFD source files. If you configure with the 96760484Sobrien@samp{--enable-maintainer-mode} option, @file{bfd-in2.h} is rebuilt 96860484Sobrienautomatically when a source file changes. 96960484Sobrien 97060484Sobrien@item elf32-target.h 97160484Sobrien@itemx elf64-target.h 97260484Sobrien@cindex @file{elf32-target.h} 97360484Sobrien@cindex @file{elf64-target.h} 97460484SobrienLive in the object directory. Created from @file{elfxx-target.h}. 97560484SobrienThese files are versions of @file{elfxx-target.h} customized for either 97660484Sobriena 32 bit ELF target or a 64 bit ELF target. 97760484Sobrien 97860484Sobrien@item libbfd.h 97960484Sobrien@cindex @file{libbfd.h} 98060484SobrienLives in the source directory. Created from @file{libbfd-in.h} and 98160484Sobrienseveral other BFD source files. If you configure with the 98260484Sobrien@samp{--enable-maintainer-mode} option, @file{libbfd.h} is rebuilt 98360484Sobrienautomatically when a source file changes. 98460484Sobrien 98560484Sobrien@item libcoff.h 98660484Sobrien@cindex @file{libcoff.h} 98760484SobrienLives in the source directory. Created from @file{libcoff-in.h} and 98860484Sobrien@file{coffcode.h}. If you configure with the 98960484Sobrien@samp{--enable-maintainer-mode} option, @file{libcoff.h} is rebuilt 99060484Sobrienautomatically when a source file changes. 99160484Sobrien 99260484Sobrien@item targmatch.h 99360484Sobrien@cindex @file{targmatch.h} 99460484SobrienLives in the object directory. Created at make time from 99560484Sobrien@file{config.bfd}. This file is used to map configuration triplets into 99660484SobrienBFD target vector variable names at run time. 99760484Sobrien@end table 99860484Sobrien 99960484Sobrien@node BFD multiple compilations 100060484Sobrien@section Files compiled multiple times in BFD 100160484SobrienSeveral files in BFD are compiled multiple times. By this I mean that 100260484Sobrienthere are header files which contain function definitions. These header 100360484Sobrienfiles are included by other files, and thus the functions are compiled 100460484Sobrienonce per file which includes them. 100560484Sobrien 100660484SobrienPreprocessor macros are used to control the compilation, so that each 100760484Sobrientime the files are compiled the resulting functions are slightly 100860484Sobriendifferent. Naturally, if they weren't different, there would be no 100960484Sobrienreason to compile them multiple times. 101060484Sobrien 101160484SobrienThis is a not a particularly good programming technique, and future BFD 101260484Sobrienwork should avoid it. 101360484Sobrien 101460484Sobrien@itemize @bullet 101560484Sobrien@item 101660484SobrienSince this technique is rarely used, even experienced C programmers find 101760484Sobrienit confusing. 101860484Sobrien 101960484Sobrien@item 102060484SobrienIt is difficult to debug programs which use BFD, since there is no way 102160484Sobriento describe which version of a particular function you are looking at. 102260484Sobrien 102360484Sobrien@item 102460484SobrienPrograms which use BFD wind up incorporating two or more slightly 102560484Sobriendifferent versions of the same function, which wastes space in the 102660484Sobrienexecutable. 102760484Sobrien 102860484Sobrien@item 102960484SobrienThis technique is never required nor is it especially efficient. It is 103060484Sobrienalways possible to use statically initialized structures holding 103160484Sobrienfunction pointers and magic constants instead. 103260484Sobrien@end itemize 103360484Sobrien 103460484SobrienThe following is a list of the files which are compiled multiple times. 103560484Sobrien 103660484Sobrien@table @file 103760484Sobrien@item aout-target.h 103860484Sobrien@cindex @file{aout-target.h} 103960484SobrienDescribes a few functions and the target vector for a.out targets. This 104060484Sobrienis used by individual a.out targets with different definitions of 104160484Sobrien@samp{N_TXTADDR} and similar a.out macros. 104260484Sobrien 104360484Sobrien@item aoutf1.h 104460484Sobrien@cindex @file{aoutf1.h} 104560484SobrienImplements standard SunOS a.out files. In principle it supports 64 bit 104660484Sobriena.out targets based on the preprocessor macro @samp{ARCH_SIZE}, but 104760484Sobriensince all known a.out targets are 32 bits, this code may or may not 104860484Sobrienwork. This file is only included by a few other files, and it is 104960484Sobriendifficult to justify its existence. 105060484Sobrien 105160484Sobrien@item aoutx.h 105260484Sobrien@cindex @file{aoutx.h} 105360484SobrienImplements basic a.out support routines. This file can be compiled for 105460484Sobrieneither 32 or 64 bit support. Since all known a.out targets are 32 bits, 105560484Sobrienthe 64 bit support may or may not work. I believe the original 105660484Sobrienintention was that this file would only be included by @samp{aout32.c} 105760484Sobrienand @samp{aout64.c}, and that other a.out targets would simply refer to 105860484Sobrienthe functions it defined. Unfortunately, some other a.out targets 105960484Sobrienstarted including it directly, leading to a somewhat confused state of 106060484Sobrienaffairs. 106160484Sobrien 106260484Sobrien@item coffcode.h 106360484Sobrien@cindex @file{coffcode.h} 106460484SobrienImplements basic COFF support routines. This file is included by every 106560484SobrienCOFF target. It implements code which handles COFF magic numbers as 106660484Sobrienwell as various hook functions called by the generic COFF functions in 106760484Sobrien@file{coffgen.c}. This file is controlled by a number of different 106860484Sobrienmacros, and more are added regularly. 106960484Sobrien 107060484Sobrien@item coffswap.h 107160484Sobrien@cindex @file{coffswap.h} 107260484SobrienImplements COFF swapping routines. This file is included by 107360484Sobrien@file{coffcode.h}, and thus by every COFF target. It implements the 107460484Sobrienroutines which swap COFF structures between internal and external 107560484Sobrienformat. The main control for this file is the external structure 107660484Sobriendefinitions in the files in the @file{include/coff} directory. A COFF 107760484Sobrientarget file will include one of those files before including 107860484Sobrien@file{coffcode.h} and thus @file{coffswap.h}. There are a few other 107960484Sobrienmacros which affect @file{coffswap.h} as well, mostly describing whether 108060484Sobriencertain fields are present in the external structures. 108160484Sobrien 108260484Sobrien@item ecoffswap.h 108360484Sobrien@cindex @file{ecoffswap.h} 108460484SobrienImplements ECOFF swapping routines. This is like @file{coffswap.h}, but 108560484Sobrienfor ECOFF. It is included by the ECOFF target files (of which there are 108660484Sobrienonly two). The control is the preprocessor macro @samp{ECOFF_32} or 108760484Sobrien@samp{ECOFF_64}. 108860484Sobrien 108960484Sobrien@item elfcode.h 109060484Sobrien@cindex @file{elfcode.h} 109160484SobrienImplements ELF functions that use external structure definitions. This 109260484Sobrienfile is included by two other files: @file{elf32.c} and @file{elf64.c}. 109360484SobrienIt is controlled by the @samp{ARCH_SIZE} macro which is defined to be 109460484Sobrien@samp{32} or @samp{64} before including it. The @samp{NAME} macro is 109560484Sobrienused internally to give the functions different names for the two target 109660484Sobriensizes. 109760484Sobrien 109860484Sobrien@item elfcore.h 109960484Sobrien@cindex @file{elfcore.h} 110060484SobrienLike @file{elfcode.h}, but for functions that are specific to ELF core 110160484Sobrienfiles. This is included only by @file{elfcode.h}. 110260484Sobrien 110360484Sobrien@item elfxx-target.h 110460484Sobrien@cindex @file{elfxx-target.h} 110560484SobrienThis file is the source for the generated files @file{elf32-target.h} 110660484Sobrienand @file{elf64-target.h}, one of which is included by every ELF target. 110760484SobrienIt defines the ELF target vector. 110860484Sobrien 110960484Sobrien@item freebsd.h 111060484Sobrien@cindex @file{freebsd.h} 111160484SobrienPresumably intended to be included by all FreeBSD targets, but in fact 111260484Sobrienthere is only one such target, @samp{i386-freebsd}. This defines a 111360484Sobrienfunction used to set the right magic number for FreeBSD, as well as 111460484Sobrienvarious macros, and includes @file{aout-target.h}. 111560484Sobrien 111660484Sobrien@item netbsd.h 111760484Sobrien@cindex @file{netbsd.h} 111860484SobrienLike @file{freebsd.h}, except that there are several files which include 111960484Sobrienit. 112060484Sobrien 112160484Sobrien@item nlm-target.h 112260484Sobrien@cindex @file{nlm-target.h} 112360484SobrienDefines the target vector for a standard NLM target. 112460484Sobrien 112560484Sobrien@item nlmcode.h 112660484Sobrien@cindex @file{nlmcode.h} 112760484SobrienLike @file{elfcode.h}, but for NLM targets. This is only included by 112860484Sobrien@file{nlm32.c} and @file{nlm64.c}, both of which define the macro 112960484Sobrien@samp{ARCH_SIZE} to an appropriate value. There are no 64 bit NLM 113060484Sobrientargets anyhow, so this is sort of useless. 113160484Sobrien 113260484Sobrien@item nlmswap.h 113360484Sobrien@cindex @file{nlmswap.h} 113460484SobrienLike @file{coffswap.h}, but for NLM targets. This is included by each 113560484SobrienNLM target, but I think it winds up compiling to the exact same code for 113660484Sobrienevery target, and as such is fairly useless. 113760484Sobrien 113860484Sobrien@item peicode.h 113960484Sobrien@cindex @file{peicode.h} 114060484SobrienProvides swapping routines and other hooks for PE targets. 114160484Sobrien@file{coffcode.h} will include this rather than @file{coffswap.h} for a 114260484SobrienPE target. This defines PE specific versions of the COFF swapping 114360484Sobrienroutines, and also defines some macros which control @file{coffcode.h} 114460484Sobrienitself. 114560484Sobrien@end table 114660484Sobrien 114760484Sobrien@node BFD relocation handling 114860484Sobrien@section BFD relocation handling 114960484Sobrien@cindex bfd relocation handling 115060484Sobrien@cindex relocations in bfd 115160484Sobrien 115260484SobrienThe handling of relocations is one of the more confusing aspects of BFD. 115360484SobrienRelocation handling has been implemented in various different ways, all 115460484Sobriensomewhat incompatible, none perfect. 115560484Sobrien 115660484Sobrien@menu 115760484Sobrien* BFD relocation concepts:: BFD relocation concepts 115860484Sobrien* BFD relocation functions:: BFD relocation functions 115960484Sobrien* BFD relocation codes:: BFD relocation codes 116060484Sobrien* BFD relocation future:: BFD relocation future 116160484Sobrien@end menu 116260484Sobrien 116360484Sobrien@node BFD relocation concepts 116460484Sobrien@subsection BFD relocation concepts 116560484Sobrien 116660484SobrienA relocation is an action which the linker must take when linking. It 116760484Sobriendescribes a change to the contents of a section. The change is normally 116860484Sobrienbased on the final value of one or more symbols. Relocations are 116960484Sobriencreated by the assembler when it creates an object file. 117060484Sobrien 117160484SobrienMost relocations are simple. A typical simple relocation is to set 32 117260484Sobrienbits at a given offset in a section to the value of a symbol. This type 117360484Sobrienof relocation would be generated for code like @code{int *p = &i;} where 117460484Sobrien@samp{p} and @samp{i} are global variables. A relocation for the symbol 117560484Sobrien@samp{i} would be generated such that the linker would initialize the 117660484Sobrienarea of memory which holds the value of @samp{p} to the value of the 117760484Sobriensymbol @samp{i}. 117860484Sobrien 117960484SobrienSlightly more complex relocations may include an addend, which is a 118060484Sobrienconstant to add to the symbol value before using it. In some cases a 118160484Sobrienrelocation will require adding the symbol value to the existing contents 118260484Sobrienof the section in the object file. In others the relocation will simply 118360484Sobrienreplace the contents of the section with the symbol value. Some 118460484Sobrienrelocations are PC relative, so that the value to be stored in the 118560484Sobriensection is the difference between the value of a symbol and the final 118660484Sobrienaddress of the section contents. 118760484Sobrien 118860484SobrienIn general, relocations can be arbitrarily complex. For example, 118960484Sobrienrelocations used in dynamic linking systems often require the linker to 119060484Sobrienallocate space in a different section and use the offset within that 119160484Sobriensection as the value to store. In the IEEE object file format, 119260484Sobrienrelocations may involve arbitrary expressions. 119360484Sobrien 1194130561SobrienWhen doing a relocatable link, the linker may or may not have to do 119560484Sobrienanything with a relocation, depending upon the definition of the 119660484Sobrienrelocation. Simple relocations generally do not require any special 119760484Sobrienaction. 119860484Sobrien 119960484Sobrien@node BFD relocation functions 120060484Sobrien@subsection BFD relocation functions 120160484Sobrien 120260484SobrienIn BFD, each section has an array of @samp{arelent} structures. Each 120360484Sobrienstructure has a pointer to a symbol, an address within the section, an 120460484Sobrienaddend, and a pointer to a @samp{reloc_howto_struct} structure. The 120560484Sobrienhowto structure has a bunch of fields describing the reloc, including a 120660484Sobrientype field. The type field is specific to the object file format 120760484Sobrienbackend; none of the generic code in BFD examines it. 120860484Sobrien 120960484SobrienOriginally, the function @samp{bfd_perform_relocation} was supposed to 121060484Sobrienhandle all relocations. In theory, many relocations would be simple 121160484Sobrienenough to be described by the fields in the howto structure. For those 121260484Sobrienthat weren't, the howto structure included a @samp{special_function} 121360484Sobrienfield to use as an escape. 121460484Sobrien 121560484SobrienWhile this seems plausible, a look at @samp{bfd_perform_relocation} 121660484Sobrienshows that it failed. The function has odd special cases. Some of the 121760484Sobrienfields in the howto structure, such as @samp{pcrel_offset}, were not 121860484Sobrienadequately documented. 121960484Sobrien 122060484SobrienThe linker uses @samp{bfd_perform_relocation} to do all relocations when 122160484Sobrienthe input and output file have different formats (e.g., when generating 122260484SobrienS-records). The generic linker code, which is used by all targets which 122360484Sobriendo not define their own special purpose linker, uses 122460484Sobrien@samp{bfd_get_relocated_section_contents}, which for most targets turns 122560484Sobrieninto a call to @samp{bfd_generic_get_relocated_section_contents}, which 122660484Sobriencalls @samp{bfd_perform_relocation}. So @samp{bfd_perform_relocation} 122760484Sobrienis still widely used, which makes it difficult to change, since it is 122860484Sobriendifficult to test all possible cases. 122960484Sobrien 123060484SobrienThe assembler used @samp{bfd_perform_relocation} for a while. This 123160484Sobrienturned out to be the wrong thing to do, since 123260484Sobrien@samp{bfd_perform_relocation} was written to handle relocations on an 123360484Sobrienexisting object file, while the assembler needed to create relocations 123460484Sobrienin a new object file. The assembler was changed to use the new function 123560484Sobrien@samp{bfd_install_relocation} instead, and @samp{bfd_install_relocation} 123660484Sobrienwas created as a copy of @samp{bfd_perform_relocation}. 123760484Sobrien 123860484SobrienUnfortunately, the work did not progress any farther, so 123960484Sobrien@samp{bfd_install_relocation} remains a simple copy of 124060484Sobrien@samp{bfd_perform_relocation}, with all the odd special cases and 124160484Sobrienconfusing code. This again is difficult to change, because again any 124260484Sobrienchange can affect any assembler target, and so is difficult to test. 124360484Sobrien 124460484SobrienThe new linker, when using the same object file format for all input 124560484Sobrienfiles and the output file, does not convert relocations into 124660484Sobrien@samp{arelent} structures, so it can not use 124760484Sobrien@samp{bfd_perform_relocation} at all. Instead, users of the new linker 124860484Sobrienare expected to write a @samp{relocate_section} function which will 124960484Sobrienhandle relocations in a target specific fashion. 125060484Sobrien 125160484SobrienThere are two helper functions for target specific relocation: 125260484Sobrien@samp{_bfd_final_link_relocate} and @samp{_bfd_relocate_contents}. 125360484SobrienThese functions use a howto structure, but they @emph{do not} use the 125460484Sobrien@samp{special_function} field. Since the functions are normally called 125560484Sobrienfrom target specific code, the @samp{special_function} field adds 125660484Sobrienlittle; any relocations which require special handling can be handled 125760484Sobrienwithout calling those functions. 125860484Sobrien 125960484SobrienSo, if you want to add a new target, or add a new relocation to an 126060484Sobrienexisting target, you need to do the following: 126160484Sobrien 126260484Sobrien@itemize @bullet 126360484Sobrien@item 126460484SobrienMake sure you clearly understand what the contents of the section should 1265130561Sobrienlook like after assembly, after a relocatable link, and after a final 126660484Sobrienlink. Make sure you clearly understand the operations the linker must 1267130561Sobrienperform during a relocatable link and during a final link. 126860484Sobrien 126960484Sobrien@item 127060484SobrienWrite a howto structure for the relocation. The howto structure is 127160484Sobrienflexible enough to represent any relocation which should be handled by 127260484Sobriensetting a contiguous bitfield in the destination to the value of a 127360484Sobriensymbol, possibly with an addend, possibly adding the symbol value to the 127460484Sobrienvalue already present in the destination. 127560484Sobrien 127660484Sobrien@item 127760484SobrienChange the assembler to generate your relocation. The assembler will 127860484Sobriencall @samp{bfd_install_relocation}, so your howto structure has to be 127960484Sobrienable to handle that. You may need to set the @samp{special_function} 128060484Sobrienfield to handle assembly correctly. Be careful to ensure that any code 128160484Sobrienyou write to handle the assembler will also work correctly when doing a 1282130561Sobrienrelocatable link. For example, see @samp{bfd_elf_generic_reloc}. 128360484Sobrien 128460484Sobrien@item 128560484SobrienTest the assembler. Consider the cases of relocation against an 128660484Sobrienundefined symbol, a common symbol, a symbol defined in the object file 128760484Sobrienin the same section, and a symbol defined in the object file in a 128860484Sobriendifferent section. These cases may not all be applicable for your 128960484Sobrienreloc. 129060484Sobrien 129160484Sobrien@item 129260484SobrienIf your target uses the new linker, which is recommended, add any 129360484Sobrienrequired handling to the target specific relocation function. In simple 129460484Sobriencases this will just involve a call to @samp{_bfd_final_link_relocate} 129560484Sobrienor @samp{_bfd_relocate_contents}, depending upon the definition of the 1296130561Sobrienrelocation and whether the link is relocatable or not. 129760484Sobrien 129860484Sobrien@item 129960484SobrienTest the linker. Test the case of a final link. If the relocation can 130060484Sobrienoverflow, use a linker script to force an overflow and make sure the 1301130561Sobrienerror is reported correctly. Test a relocatable link, whether the 1302130561Sobriensymbol is defined or undefined in the relocatable output. For both the 1303130561Sobrienfinal and relocatable link, test the case when the symbol is a common 130460484Sobriensymbol, when the symbol looked like a common symbol but became a defined 130560484Sobriensymbol, when the symbol is defined in a different object file, and when 130660484Sobrienthe symbol is defined in the same object file. 130760484Sobrien 130860484Sobrien@item 130960484SobrienIn order for linking to another object file format, such as S-records, 131060484Sobriento work correctly, @samp{bfd_perform_relocation} has to do the right 131160484Sobrienthing for the relocation. You may need to set the 131260484Sobrien@samp{special_function} field to handle this correctly. Test this by 131360484Sobriendoing a link in which the output object file format is S-records. 131460484Sobrien 131560484Sobrien@item 1316130561SobrienUsing the linker to generate relocatable output in a different object 131760484Sobrienfile format is impossible in the general case, so you generally don't 131889857Sobrienhave to worry about that. The GNU linker makes sure to stop that from 131989857Sobrienhappening when an input file in a different format has relocations. 132089857Sobrien 132189857SobrienLinking input files of different object file formats together is quite 132289857Sobrienunusual, but if you're really dedicated you may want to consider testing 132389857Sobrienthis case, both when the output object file format is the same as your 132489857Sobrienformat, and when it is different. 132560484Sobrien@end itemize 132660484Sobrien 132760484Sobrien@node BFD relocation codes 132860484Sobrien@subsection BFD relocation codes 132960484Sobrien 133060484SobrienBFD has another way of describing relocations besides the howto 133160484Sobrienstructures described above: the enum @samp{bfd_reloc_code_real_type}. 133260484Sobrien 133360484SobrienEvery known relocation type can be described as a value in this 133460484Sobrienenumeration. The enumeration contains many target specific relocations, 133560484Sobrienbut where two or more targets have the same relocation, a single code is 133660484Sobrienused. For example, the single value @samp{BFD_RELOC_32} is used for all 133760484Sobriensimple 32 bit relocation types. 133860484Sobrien 133960484SobrienThe main purpose of this relocation code is to give the assembler some 134060484Sobrienmechanism to create @samp{arelent} structures. In order for the 134160484Sobrienassembler to create an @samp{arelent} structure, it has to be able to 134260484Sobrienobtain a howto structure. The function @samp{bfd_reloc_type_lookup}, 134360484Sobrienwhich simply calls the target vector entry point 134460484Sobrien@samp{reloc_type_lookup}, takes a relocation code and returns a howto 134560484Sobrienstructure. 134660484Sobrien 134760484SobrienThe function @samp{bfd_get_reloc_code_name} returns the name of a 134860484Sobrienrelocation code. This is mainly used in error messages. 134960484Sobrien 135060484SobrienUsing both howto structures and relocation codes can be somewhat 135160484Sobrienconfusing. There are many processor specific relocation codes. 135260484SobrienHowever, the relocation is only fully defined by the howto structure. 135360484SobrienThe same relocation code will map to different howto structures in 135460484Sobriendifferent object file formats. For example, the addend handling may be 135560484Sobriendifferent. 135660484Sobrien 135760484SobrienMost of the relocation codes are not really general. The assembler can 135860484Sobriennot use them without already understanding what sorts of relocations can 135960484Sobrienbe used for a particular target. It might be possible to replace the 136060484Sobrienrelocation codes with something simpler. 136160484Sobrien 136260484Sobrien@node BFD relocation future 136360484Sobrien@subsection BFD relocation future 136460484Sobrien 136560484SobrienClearly the current BFD relocation support is in bad shape. A 136660484Sobrienwholescale rewrite would be very difficult, because it would require 136760484Sobrienthorough testing of every BFD target. So some sort of incremental 136860484Sobrienchange is required. 136960484Sobrien 137060484SobrienMy vague thoughts on this would involve defining a new, clearly defined, 137160484Sobrienhowto structure. Some mechanism would be used to determine which type 137260484Sobrienof howto structure was being used by a particular format. 137360484Sobrien 137460484SobrienThe new howto structure would clearly define the relocation behaviour in 1375130561Sobrienthe case of an assembly, a relocatable link, and a final link. At 137660484Sobrienleast one special function would be defined as an escape, and it might 137760484Sobrienmake sense to define more. 137860484Sobrien 137960484SobrienOne or more generic functions similar to @samp{bfd_perform_relocation} 138060484Sobrienwould be written to handle the new howto structure. 138160484Sobrien 138260484SobrienThis should make it possible to write a generic version of the relocate 138360484Sobriensection functions used by the new linker. The target specific code 138460484Sobrienwould provide some mechanism (a function pointer or an initial 138560484Sobrienconversion) to convert target specific relocations into howto 138660484Sobrienstructures. 138760484Sobrien 138860484SobrienIdeally it would be possible to use this generic relocate section 138960484Sobrienfunction for the generic linker as well. That is, it would replace the 139060484Sobrien@samp{bfd_generic_get_relocated_section_contents} function which is 139160484Sobriencurrently normally used. 139260484Sobrien 139360484SobrienFor the special case of ELF dynamic linking, more consideration needs to 139460484Sobrienbe given to writing ELF specific but ELF target generic code to handle 139560484Sobrienspecial relocation types such as GOT and PLT. 139660484Sobrien 139760484Sobrien@node BFD ELF support 139860484Sobrien@section BFD ELF support 139960484Sobrien@cindex elf support in bfd 140060484Sobrien@cindex bfd elf support 140160484Sobrien 140260484SobrienThe ELF object file format is defined in two parts: a generic ABI and a 140360484Sobrienprocessor specific supplement. The ELF support in BFD is split in a 140460484Sobriensimilar fashion. The processor specific support is largely kept within 140560484Sobriena single file. The generic support is provided by several other files. 140660484SobrienThe processor specific support provides a set of function pointers and 140760484Sobrienconstants used by the generic support. 140860484Sobrien 140960484Sobrien@menu 141060484Sobrien* BFD ELF sections and segments:: ELF sections and segments 141160484Sobrien* BFD ELF generic support:: BFD ELF generic support 141260484Sobrien* BFD ELF processor specific support:: BFD ELF processor specific support 141360484Sobrien* BFD ELF core files:: BFD ELF core files 141460484Sobrien* BFD ELF future:: BFD ELF future 141560484Sobrien@end menu 141660484Sobrien 141760484Sobrien@node BFD ELF sections and segments 141860484Sobrien@subsection ELF sections and segments 141960484Sobrien 142060484SobrienThe ELF ABI permits a file to have either sections or segments or both. 1421218822SdimRelocatable object files conventionally have only sections. 142260484SobrienExecutables conventionally have both. Core files conventionally have 142360484Sobrienonly program segments. 142460484Sobrien 142560484SobrienELF sections are similar to sections in other object file formats: they 142660484Sobrienhave a name, a VMA, file contents, flags, and other miscellaneous 142760484Sobrieninformation. ELF relocations are stored in sections of a particular 142860484Sobrientype; BFD automatically converts these sections into internal relocation 142960484Sobrieninformation. 143060484Sobrien 143160484SobrienELF program segments are intended for fast interpretation by a system 143260484Sobrienloader. They have a type, a VMA, an LMA, file contents, and a couple of 143360484Sobrienother fields. When an ELF executable is run on a Unix system, the 143460484Sobriensystem loader will examine the program segments to decide how to load 143560484Sobrienit. The loader will ignore the section information. Loadable program 143660484Sobriensegments (type @samp{PT_LOAD}) are directly loaded into memory. Other 143760484Sobrienprogram segments are interpreted by the loader, and generally provide 143860484Sobriendynamic linking information. 143960484Sobrien 144060484SobrienWhen an ELF file has both program segments and sections, an ELF program 144160484Sobriensegment may encompass one or more ELF sections, in the sense that the 144260484Sobrienportion of the file which corresponds to the program segment may include 144360484Sobrienthe portions of the file corresponding to one or more sections. When 144460484Sobrienthere is more than one section in a loadable program segment, the 144560484Sobrienrelative positions of the section contents in the file must correspond 144660484Sobriento the relative positions they should hold when the program segment is 144760484Sobrienloaded. This requirement should be obvious if you consider that the 144860484Sobriensystem loader will load an entire program segment at a time. 144960484Sobrien 145060484SobrienOn a system which supports dynamic paging, such as any native Unix 145160484Sobriensystem, the contents of a loadable program segment must be at the same 145260484Sobrienoffset in the file as in memory, modulo the memory page size used on the 145360484Sobriensystem. This is because the system loader will map the file into memory 145460484Sobrienstarting at the start of a page. The system loader can easily remap 145560484Sobrienentire pages to the correct load address. However, if the contents of 145660484Sobrienthe file were not correctly aligned within the page, the system loader 145760484Sobrienwould have to shift the contents around within the page, which is too 145860484Sobrienexpensive. For example, if the LMA of a loadable program segment is 145960484Sobrien@samp{0x40080} and the page size is @samp{0x1000}, then the position of 146060484Sobrienthe segment contents within the file must equal @samp{0x80} modulo 146160484Sobrien@samp{0x1000}. 146260484Sobrien 146360484SobrienBFD has only a single set of sections. It does not provide any generic 146460484Sobrienway to examine both sections and segments. When BFD is used to open an 146560484Sobrienobject file or executable, the BFD sections will represent ELF sections. 146660484SobrienWhen BFD is used to open a core file, the BFD sections will represent 146760484SobrienELF program segments. 146860484Sobrien 146960484SobrienWhen BFD is used to examine an object file or executable, any program 147060484Sobriensegments will be read to set the LMA of the sections. This is because 147160484SobrienELF sections only have a VMA, while ELF program segments have both a VMA 147260484Sobrienand an LMA. Any program segments will be copied by the 147360484Sobrien@samp{copy_private} entry points. They will be printed by the 147460484Sobrien@samp{print_private} entry point. Otherwise, the program segments are 147560484Sobrienignored. In particular, programs which use BFD currently have no direct 147660484Sobrienaccess to the program segments. 147760484Sobrien 147860484SobrienWhen BFD is used to create an executable, the program segments will be 147960484Sobriencreated automatically based on the section information. This is done in 148060484Sobrienthe function @samp{assign_file_positions_for_segments} in @file{elf.c}. 148160484SobrienThis function has been tweaked many times, and probably still has 148260484Sobrienproblems that arise in particular cases. 148360484Sobrien 148460484SobrienThere is a hook which may be used to explicitly define the program 148560484Sobriensegments when creating an executable: the @samp{bfd_record_phdr} 148660484Sobrienfunction in @file{bfd.c}. If this function is called, BFD will not 148760484Sobriencreate program segments itself, but will only create the program 148860484Sobriensegments specified by the caller. The linker uses this function to 148960484Sobrienimplement the @samp{PHDRS} linker script command. 149060484Sobrien 149160484Sobrien@node BFD ELF generic support 149260484Sobrien@subsection BFD ELF generic support 149360484Sobrien 149460484SobrienIn general, functions which do not read external data from the ELF file 149560484Sobrienare found in @file{elf.c}. They operate on the internal forms of the 149660484SobrienELF structures, which are defined in @file{include/elf/internal.h}. The 149760484Sobrieninternal structures are defined in terms of @samp{bfd_vma}, and so may 149860484Sobrienbe used for both 32 bit and 64 bit ELF targets. 149960484Sobrien 150060484SobrienThe file @file{elfcode.h} contains functions which operate on the 150160484Sobrienexternal data. @file{elfcode.h} is compiled twice, once via 150260484Sobrien@file{elf32.c} with @samp{ARCH_SIZE} defined as @samp{32}, and once via 150360484Sobrien@file{elf64.c} with @samp{ARCH_SIZE} defined as @samp{64}. 150460484Sobrien@file{elfcode.h} includes functions to swap the ELF structures in and 150560484Sobrienout of external form, as well as a few more complex functions. 150660484Sobrien 1507130561SobrienLinker support is found in @file{elflink.c}. The 150860484Sobrienlinker support is only used if the processor specific file defines 150960484Sobrien@samp{elf_backend_relocate_section}, which is required to relocate the 151060484Sobriensection contents. If that macro is not defined, the generic linker code 151160484Sobrienis used, and relocations are handled via @samp{bfd_perform_relocation}. 151260484Sobrien 151360484SobrienThe core file support is in @file{elfcore.h}, which is compiled twice, 151460484Sobrienfor both 32 and 64 bit support. The more interesting cases of core file 151560484Sobriensupport only work on a native system which has the @file{sys/procfs.h} 151660484Sobrienheader file. Without that file, the core file support does little more 151760484Sobrienthan read the ELF program segments as BFD sections. 151860484Sobrien 151960484SobrienThe BFD internal header file @file{elf-bfd.h} is used for communication 152060484Sobrienamong these files and the processor specific files. 152160484Sobrien 152260484SobrienThe default entries for the BFD ELF target vector are found mainly in 152360484Sobrien@file{elf.c}. Some functions are found in @file{elfcode.h}. 152460484Sobrien 152560484SobrienThe processor specific files may override particular entries in the 152660484Sobrientarget vector, but most do not, with one exception: the 152760484Sobrien@samp{bfd_reloc_type_lookup} entry point is always processor specific. 152860484Sobrien 152960484Sobrien@node BFD ELF processor specific support 153060484Sobrien@subsection BFD ELF processor specific support 153160484Sobrien 153260484SobrienBy convention, the processor specific support for a particular processor 153360484Sobrienwill be found in @file{elf@var{nn}-@var{cpu}.c}, where @var{nn} is 153460484Sobrieneither 32 or 64, and @var{cpu} is the name of the processor. 153560484Sobrien 153660484Sobrien@menu 153760484Sobrien* BFD ELF processor required:: Required processor specific support 153860484Sobrien* BFD ELF processor linker:: Processor specific linker support 153960484Sobrien* BFD ELF processor other:: Other processor specific support options 154060484Sobrien@end menu 154160484Sobrien 154260484Sobrien@node BFD ELF processor required 154360484Sobrien@subsubsection Required processor specific support 154460484Sobrien 154560484SobrienWhen writing a @file{elf@var{nn}-@var{cpu}.c} file, you must do the 154660484Sobrienfollowing: 154760484Sobrien 154860484Sobrien@itemize @bullet 154960484Sobrien@item 155060484SobrienDefine either @samp{TARGET_BIG_SYM} or @samp{TARGET_LITTLE_SYM}, or 155160484Sobrienboth, to a unique C name to use for the target vector. This name should 155260484Sobrienappear in the list of target vectors in @file{targets.c}, and will also 155360484Sobrienhave to appear in @file{config.bfd} and @file{configure.in}. Define 155460484Sobrien@samp{TARGET_BIG_SYM} for a big-endian processor, 155560484Sobrien@samp{TARGET_LITTLE_SYM} for a little-endian processor, and define both 155660484Sobrienfor a bi-endian processor. 155760484Sobrien@item 155860484SobrienDefine either @samp{TARGET_BIG_NAME} or @samp{TARGET_LITTLE_NAME}, or 155960484Sobrienboth, to a string used as the name of the target vector. This is the 156060484Sobrienname which a user of the BFD tool would use to specify the object file 156160484Sobrienformat. It would normally appear in a linker emulation parameters 156260484Sobrienfile. 156360484Sobrien@item 156460484SobrienDefine @samp{ELF_ARCH} to the BFD architecture (an element of the 156560484Sobrien@samp{bfd_architecture} enum, typically @samp{bfd_arch_@var{cpu}}). 156660484Sobrien@item 156760484SobrienDefine @samp{ELF_MACHINE_CODE} to the magic number which should appear 156860484Sobrienin the @samp{e_machine} field of the ELF header. As of this writing, 1569104834Sobrienthese magic numbers are assigned by Caldera; if you want to get a magic 157060484Sobriennumber for a particular processor, try sending a note to 1571104834Sobrien@email{registry@@caldera.com}. In the BFD sources, the magic numbers are 157260484Sobrienfound in @file{include/elf/common.h}; they have names beginning with 157360484Sobrien@samp{EM_}. 157460484Sobrien@item 157560484SobrienDefine @samp{ELF_MAXPAGESIZE} to the maximum size of a virtual page in 157660484Sobrienmemory. This can normally be found at the start of chapter 5 in the 157760484Sobrienprocessor specific supplement. For a processor which will only be used 157860484Sobrienin an embedded system, or which has no memory management hardware, this 157960484Sobriencan simply be @samp{1}. 158060484Sobrien@item 158160484SobrienIf the format should use @samp{Rel} rather than @samp{Rela} relocations, 158260484Sobriendefine @samp{USE_REL}. This is normally defined in chapter 4 of the 158360484Sobrienprocessor specific supplement. 158460484Sobrien 158560484SobrienIn the absence of a supplement, it's easier to work with @samp{Rela} 158660484Sobrienrelocations. @samp{Rela} relocations will require more space in object 158760484Sobrienfiles (but not in executables, except when using dynamic linking). 158860484SobrienHowever, this is outweighed by the simplicity of addend handling when 158960484Sobrienusing @samp{Rela} relocations. With @samp{Rel} relocations, the addend 1590130561Sobrienmust be stored in the section contents, which makes relocatable links 159160484Sobrienmore complex. 159260484Sobrien 159360484SobrienFor example, consider C code like @code{i = a[1000];} where @samp{a} is 159460484Sobriena global array. The instructions which load the value of @samp{a[1000]} 159560484Sobrienwill most likely use a relocation which refers to the symbol 159660484Sobrienrepresenting @samp{a}, with an addend that gives the offset from the 159760484Sobrienstart of @samp{a} to element @samp{1000}. When using @samp{Rel} 159860484Sobrienrelocations, that addend must be stored in the instructions themselves. 159960484SobrienIf you are adding support for a RISC chip which uses two or more 160060484Sobrieninstructions to load an address, then the addend may not fit in a single 160160484Sobrieninstruction, and will have to be somehow split among the instructions. 1602130561SobrienThis makes linking awkward, particularly when doing a relocatable link 160360484Sobrienin which the addend may have to be updated. It can be done---the MIPS 160460484SobrienELF support does it---but it should be avoided when possible. 160560484Sobrien 160660484SobrienIt is possible, though somewhat awkward, to support both @samp{Rel} and 160760484Sobrien@samp{Rela} relocations for a single target; @file{elf64-mips.c} does it 160860484Sobrienby overriding the relocation reading and writing routines. 160960484Sobrien@item 161060484SobrienDefine howto structures for all the relocation types. 161160484Sobrien@item 161260484SobrienDefine a @samp{bfd_reloc_type_lookup} routine. This must be named 161360484Sobrien@samp{bfd_elf@var{nn}_bfd_reloc_type_lookup}, and may be either a 161460484Sobrienfunction or a macro. It must translate a BFD relocation code into a 161560484Sobrienhowto structure. This is normally a table lookup or a simple switch. 161660484Sobrien@item 161760484SobrienIf using @samp{Rel} relocations, define @samp{elf_info_to_howto_rel}. 161860484SobrienIf using @samp{Rela} relocations, define @samp{elf_info_to_howto}. 161960484SobrienEither way, this is a macro defined as the name of a function which 162060484Sobrientakes an @samp{arelent} and a @samp{Rel} or @samp{Rela} structure, and 162160484Sobriensets the @samp{howto} field of the @samp{arelent} based on the 162260484Sobrien@samp{Rel} or @samp{Rela} structure. This is normally uses 162360484Sobrien@samp{ELF@var{nn}_R_TYPE} to get the ELF relocation type and uses it as 162460484Sobrienan index into a table of howto structures. 162560484Sobrien@end itemize 162660484Sobrien 162760484SobrienYou must also add the magic number for this processor to the 162860484Sobrien@samp{prep_headers} function in @file{elf.c}. 162960484Sobrien 163060484SobrienYou must also create a header file in the @file{include/elf} directory 163160484Sobriencalled @file{@var{cpu}.h}. This file should define any target specific 163260484Sobrieninformation which may be needed outside of the BFD code. In particular 163360484Sobrienit should use the @samp{START_RELOC_NUMBERS}, @samp{RELOC_NUMBER}, 163460484Sobrien@samp{FAKE_RELOC}, @samp{EMPTY_RELOC} and @samp{END_RELOC_NUMBERS} 1635130561Sobrienmacros to create a table mapping the number used to identify a 163660484Sobrienrelocation to a name describing that relocation. 163760484Sobrien 163877298SobrienWhile not a BFD component, you probably also want to make the binutils 163977298Sobrienprogram @samp{readelf} parse your ELF objects. For this, you need to add 164077298Sobriencode for @code{EM_@var{cpu}} as appropriate in @file{binutils/readelf.c}. 164177298Sobrien 164260484Sobrien@node BFD ELF processor linker 164360484Sobrien@subsubsection Processor specific linker support 164460484Sobrien 164560484SobrienThe linker will be much more efficient if you define a relocate section 164660484Sobrienfunction. This will permit BFD to use the ELF specific linker support. 164760484Sobrien 164860484SobrienIf you do not define a relocate section function, BFD must use the 164960484Sobriengeneric linker support, which requires converting all symbols and 165060484Sobrienrelocations into BFD @samp{asymbol} and @samp{arelent} structures. In 165160484Sobrienthis case, relocations will be handled by calling 165260484Sobrien@samp{bfd_perform_relocation}, which will use the howto structures you 165360484Sobrienhave defined. @xref{BFD relocation handling}. 165460484Sobrien 165560484SobrienIn order to support linking into a different object file format, such as 165660484SobrienS-records, @samp{bfd_perform_relocation} must work correctly with your 165760484Sobrienhowto structures, so you can't skip that step. However, if you define 165860484Sobrienthe relocate section function, then in the normal case of linking into 165960484Sobrienan ELF file the linker will not need to convert symbols and relocations, 166060484Sobrienand will be much more efficient. 166160484Sobrien 166260484SobrienTo use a relocation section function, define the macro 166360484Sobrien@samp{elf_backend_relocate_section} as the name of a function which will 166460484Sobrientake the contents of a section, as well as relocation, symbol, and other 166560484Sobrieninformation, and modify the section contents according to the relocation 166660484Sobrieninformation. In simple cases, this is little more than a loop over the 166760484Sobrienrelocations which computes the value of each relocation and calls 166860484Sobrien@samp{_bfd_final_link_relocate}. The function must check for a 1669130561Sobrienrelocatable link, and in that case normally needs to do nothing other 167060484Sobrienthan adjust the addend for relocations against a section symbol. 167160484Sobrien 167260484SobrienThe complex cases generally have to do with dynamic linker support. GOT 167360484Sobrienand PLT relocations must be handled specially, and the linker normally 167460484Sobrienarranges to set up the GOT and PLT sections while handling relocations. 167560484SobrienWhen generating a shared library, random relocations must normally be 167660484Sobriencopied into the shared library, or converted to RELATIVE relocations 167760484Sobrienwhen possible. 167860484Sobrien 167960484Sobrien@node BFD ELF processor other 168060484Sobrien@subsubsection Other processor specific support options 168160484Sobrien 168260484SobrienThere are many other macros which may be defined in 168360484Sobrien@file{elf@var{nn}-@var{cpu}.c}. These macros may be found in 168460484Sobrien@file{elfxx-target.h}. 168560484Sobrien 168660484SobrienMacros may be used to override some of the generic ELF target vector 168760484Sobrienfunctions. 168860484Sobrien 168960484SobrienSeveral processor specific hook functions which may be defined as 169060484Sobrienmacros. These functions are found as function pointers in the 169160484Sobrien@samp{elf_backend_data} structure defined in @file{elf-bfd.h}. In 169260484Sobriengeneral, a hook function is set by defining a macro 169360484Sobrien@samp{elf_backend_@var{name}}. 169460484Sobrien 169560484SobrienThere are a few processor specific constants which may also be defined. 169660484SobrienThese are again found in the @samp{elf_backend_data} structure. 169760484Sobrien 169860484SobrienI will not define the various functions and constants here; see the 169960484Sobriencomments in @file{elf-bfd.h}. 170060484Sobrien 170160484SobrienNormally any odd characteristic of a particular ELF processor is handled 170260484Sobrienvia a hook function. For example, the special @samp{SHN_MIPS_SCOMMON} 170360484Sobriensection number found in MIPS ELF is handled via the hooks 170460484Sobrien@samp{section_from_bfd_section}, @samp{symbol_processing}, 170560484Sobrien@samp{add_symbol_hook}, and @samp{output_symbol_hook}. 170660484Sobrien 170760484SobrienDynamic linking support, which involves processor specific relocations 170860484Sobrienrequiring special handling, is also implemented via hook functions. 170960484Sobrien 171060484Sobrien@node BFD ELF core files 171160484Sobrien@subsection BFD ELF core files 171260484Sobrien@cindex elf core files 171360484Sobrien 171460484SobrienOn native ELF Unix systems, core files are generated without any 171560484Sobriensections. Instead, they only have program segments. 171660484Sobrien 171760484SobrienWhen BFD is used to read an ELF core file, the BFD sections will 171860484Sobrienactually represent program segments. Since ELF program segments do not 171960484Sobrienhave names, BFD will invent names like @samp{segment@var{n}} where 172060484Sobrien@var{n} is a number. 172160484Sobrien 172260484SobrienA single ELF program segment may include both an initialized part and an 172360484Sobrienuninitialized part. The size of the initialized part is given by the 172460484Sobrien@samp{p_filesz} field. The total size of the segment is given by the 172560484Sobrien@samp{p_memsz} field. If @samp{p_memsz} is larger than @samp{p_filesz}, 172660484Sobrienthen the extra space is uninitialized, or, more precisely, initialized 172760484Sobriento zero. 172860484Sobrien 172960484SobrienBFD will represent such a program segment as two different sections. 173060484SobrienThe first, named @samp{segment@var{n}a}, will represent the initialized 173160484Sobrienpart of the program segment. The second, named @samp{segment@var{n}b}, 173260484Sobrienwill represent the uninitialized part. 173360484Sobrien 173460484SobrienELF core files store special information such as register values in 173560484Sobrienprogram segments with the type @samp{PT_NOTE}. BFD will attempt to 173660484Sobrieninterpret the information in these segments, and will create additional 173760484Sobriensections holding the information. Some of this interpretation requires 173860484Sobrieninformation found in the host header file @file{sys/procfs.h}, and so 173960484Sobrienwill only work when BFD is built on a native system. 174060484Sobrien 174160484SobrienBFD does not currently provide any way to create an ELF core file. In 174260484Sobriengeneral, BFD does not provide a way to create core files. The way to 174360484Sobrienimplement this would be to write @samp{bfd_set_format} and 174460484Sobrien@samp{bfd_write_contents} routines for the @samp{bfd_core} type; see 174560484Sobrien@ref{BFD target vector format}. 174660484Sobrien 174760484Sobrien@node BFD ELF future 174860484Sobrien@subsection BFD ELF future 174960484Sobrien 175060484SobrienThe current dynamic linking support has too much code duplication. 175160484SobrienWhile each processor has particular differences, much of the dynamic 175260484Sobrienlinking support is quite similar for each processor. The GOT and PLT 175360484Sobrienare handled in fairly similar ways, the details of -Bsymbolic linking 175460484Sobrienare generally similar, etc. This code should be reworked to use more 175560484Sobriengeneric functions, eliminating the duplication. 175660484Sobrien 175760484SobrienSimilarly, the relocation handling has too much duplication. Many of 175860484Sobrienthe @samp{reloc_type_lookup} and @samp{info_to_howto} functions are 175960484Sobrienquite similar. The relocate section functions are also often quite 176060484Sobriensimilar, both in the standard linker handling and the dynamic linker 176160484Sobrienhandling. Many of the COFF processor specific backends share a single 176260484Sobrienrelocate section function (@samp{_bfd_coff_generic_relocate_section}), 176360484Sobrienand it should be possible to do something like this for the ELF targets 176460484Sobrienas well. 176560484Sobrien 176660484SobrienThe appearance of the processor specific magic number in 176760484Sobrien@samp{prep_headers} in @file{elf.c} is somewhat bogus. It should be 176860484Sobrienpossible to add support for a new processor without changing the generic 176960484Sobriensupport. 177060484Sobrien 177160484SobrienThe processor function hooks and constants are ad hoc and need better 177260484Sobriendocumentation. 177360484Sobrien 177460484Sobrien@node BFD glossary 177560484Sobrien@section BFD glossary 177660484Sobrien@cindex glossary for bfd 177760484Sobrien@cindex bfd glossary 177860484Sobrien 177960484SobrienThis is a short glossary of some BFD terms. 178060484Sobrien 178160484Sobrien@table @asis 178260484Sobrien@item a.out 178360484SobrienThe a.out object file format. The original Unix object file format. 178460484SobrienStill used on SunOS, though not Solaris. Supports only three sections. 178560484Sobrien 178660484Sobrien@item archive 178760484SobrienA collection of object files produced and manipulated by the @samp{ar} 178860484Sobrienprogram. 178960484Sobrien 179060484Sobrien@item backend 179160484SobrienThe implementation within BFD of a particular object file format. The 179260484Sobrienset of functions which appear in a particular target vector. 179360484Sobrien 179460484Sobrien@item BFD 1795130561SobrienThe BFD library itself. Also, each object file, archive, or executable 179660484Sobrienopened by the BFD library has the type @samp{bfd *}, and is sometimes 179760484Sobrienreferred to as a bfd. 179860484Sobrien 179960484Sobrien@item COFF 180060484SobrienThe Common Object File Format. Used on Unix SVR3. Used by some 180160484Sobrienembedded targets, although ELF is normally better. 180260484Sobrien 180360484Sobrien@item DLL 180460484SobrienA shared library on Windows. 180560484Sobrien 180660484Sobrien@item dynamic linker 180760484SobrienWhen a program linked against a shared library is run, the dynamic 180860484Sobrienlinker will locate the appropriate shared library and arrange to somehow 180960484Sobrieninclude it in the running image. 181060484Sobrien 181160484Sobrien@item dynamic object 181260484SobrienAnother name for an ELF shared library. 181360484Sobrien 181460484Sobrien@item ECOFF 181560484SobrienThe Extended Common Object File Format. Used on Alpha Digital Unix 181660484Sobrien(formerly OSF/1), as well as Ultrix and Irix 4. A variant of COFF. 181760484Sobrien 181860484Sobrien@item ELF 181960484SobrienThe Executable and Linking Format. The object file format used on most 182060484Sobrienmodern Unix systems, including GNU/Linux, Solaris, Irix, and SVR4. Also 182160484Sobrienused on many embedded systems. 182260484Sobrien 182360484Sobrien@item executable 182460484SobrienA program, with instructions and symbols, and perhaps dynamic linking 182560484Sobrieninformation. Normally produced by a linker. 182660484Sobrien 182760484Sobrien@item LMA 182860484SobrienLoad Memory Address. This is the address at which a section will be 182960484Sobrienloaded. Compare with VMA, below. 183060484Sobrien 183160484Sobrien@item NLM 183260484SobrienNetWare Loadable Module. Used to describe the format of an object which 183360484Sobrienbe loaded into NetWare, which is some kind of PC based network server 183460484Sobrienprogram. 183560484Sobrien 183660484Sobrien@item object file 183760484SobrienA binary file including machine instructions, symbols, and relocation 183860484Sobrieninformation. Normally produced by an assembler. 183960484Sobrien 184060484Sobrien@item object file format 184160484SobrienThe format of an object file. Typically object files and executables 184260484Sobrienfor a particular system are in the same format, although executables 184360484Sobrienwill not contain any relocation information. 184460484Sobrien 184560484Sobrien@item PE 184660484SobrienThe Portable Executable format. This is the object file format used for 184760484SobrienWindows (specifically, Win32) object files. It is based closely on 184860484SobrienCOFF, but has a few significant differences. 184960484Sobrien 185060484Sobrien@item PEI 185160484SobrienThe Portable Executable Image format. This is the object file format 185260484Sobrienused for Windows (specifically, Win32) executables. It is very similar 185360484Sobriento PE, but includes some additional header information. 185460484Sobrien 185560484Sobrien@item relocations 185660484SobrienInformation used by the linker to adjust section contents. Also called 185760484Sobrienrelocs. 185860484Sobrien 185960484Sobrien@item section 186060484SobrienObject files and executable are composed of sections. Sections have 186160484Sobrienoptional data and optional relocation information. 186260484Sobrien 186360484Sobrien@item shared library 186460484SobrienA library of functions which may be used by many executables without 186560484Sobrienactually being linked into each executable. There are several different 186660484Sobrienimplementations of shared libraries, each having slightly different 186760484Sobrienfeatures. 186860484Sobrien 186960484Sobrien@item symbol 187060484SobrienEach object file and executable may have a list of symbols, often 187160484Sobrienreferred to as the symbol table. A symbol is basically a name and an 187260484Sobrienaddress. There may also be some additional information like the type of 187360484Sobriensymbol, although the type of a symbol is normally something simple like 187460484Sobrienfunction or object, and should be confused with the more complex C 187560484Sobriennotion of type. Typically every global function and variable in a C 187660484Sobrienprogram will have an associated symbol. 187760484Sobrien 187860484Sobrien@item target vector 187960484SobrienA set of functions which implement support for a particular object file 188060484Sobrienformat. The @samp{bfd_target} structure. 188160484Sobrien 188260484Sobrien@item Win32 188360484SobrienThe current Windows API, implemented by Windows 95 and later and Windows 188460484SobrienNT 3.51 and later, but not by Windows 3.1. 188560484Sobrien 188660484Sobrien@item XCOFF 188760484SobrienThe eXtended Common Object File Format. Used on AIX. A variant of 188860484SobrienCOFF, with a completely different symbol table implementation. 188960484Sobrien 189060484Sobrien@item VMA 189160484SobrienVirtual Memory Address. This is the address a section will have when 189260484Sobrienan executable is run. Compare with LMA, above. 189360484Sobrien@end table 189460484Sobrien 189560484Sobrien@node Index 189660484Sobrien@unnumberedsec Index 189760484Sobrien@printindex cp 189860484Sobrien 189960484Sobrien@contents 190060484Sobrien@bye 1901