1ed0d50c3Schristos\input texinfo 2*b88e3e88Schristos@c Copyright (C) 1988-2020 Free Software Foundation, Inc. 3ed0d50c3Schristos@setfilename bfdint.info 4ed0d50c3Schristos 5ed0d50c3Schristos@settitle BFD Internals 6ed0d50c3Schristos@iftex 7ed0d50c3Schristos@titlepage 8ed0d50c3Schristos@title{BFD Internals} 9ed0d50c3Schristos@author{Ian Lance Taylor} 10ed0d50c3Schristos@author{Cygnus Solutions} 11ed0d50c3Schristos@page 12ed0d50c3Schristos@end iftex 13ed0d50c3Schristos 14ed0d50c3Schristos@copying 15ed0d50c3SchristosThis file documents the internals of the BFD library. 16ed0d50c3Schristos 17*b88e3e88SchristosCopyright @copyright{} 1988-2020 Free Software Foundation, Inc. 18ed0d50c3SchristosContributed by Cygnus Support. 19ed0d50c3Schristos 20ed0d50c3SchristosPermission is granted to copy, distribute and/or modify this document 21ed0d50c3Schristosunder the terms of the GNU Free Documentation License, Version 1.1 or 22ed0d50c3Schristosany later version published by the Free Software Foundation; with the 23ed0d50c3SchristosInvariant Sections being ``GNU General Public License'' and ``Funding 24ed0d50c3SchristosFree Software'', the Front-Cover texts being (a) (see below), and with 25ed0d50c3Schristosthe Back-Cover Texts being (b) (see below). A copy of the license is 26ed0d50c3Schristosincluded in the section entitled ``GNU Free Documentation License''. 27ed0d50c3Schristos 28ed0d50c3Schristos(a) The FSF's Front-Cover Text is: 29ed0d50c3Schristos 30ed0d50c3Schristos A GNU Manual 31ed0d50c3Schristos 32ed0d50c3Schristos(b) The FSF's Back-Cover Text is: 33ed0d50c3Schristos 34ed0d50c3Schristos You have freedom to copy and modify this GNU Manual, like GNU 35ed0d50c3Schristos software. Copies published by the Free Software Foundation raise 36ed0d50c3Schristos funds for GNU development. 37ed0d50c3Schristos@end copying 38ed0d50c3Schristos 39ed0d50c3Schristos@node Top 40ed0d50c3Schristos@top BFD Internals 41ed0d50c3Schristos@raisesections 42ed0d50c3Schristos@cindex bfd internals 43ed0d50c3Schristos 44ed0d50c3SchristosThis document describes some BFD internal information which may be 45ed0d50c3Schristoshelpful when working on BFD. It is very incomplete. 46ed0d50c3Schristos 47ed0d50c3SchristosThis document is not updated regularly, and may be out of date. 48ed0d50c3Schristos 49ed0d50c3SchristosThe initial version of this document was written by Ian Lance Taylor 50ed0d50c3Schristos@email{ian@@cygnus.com}. 51ed0d50c3Schristos 52ed0d50c3Schristos@menu 53ed0d50c3Schristos* BFD overview:: BFD overview 54ed0d50c3Schristos* BFD guidelines:: BFD programming guidelines 55ed0d50c3Schristos* BFD target vector:: BFD target vector 56ed0d50c3Schristos* BFD generated files:: BFD generated files 57ed0d50c3Schristos* BFD multiple compilations:: Files compiled multiple times in BFD 58ed0d50c3Schristos* BFD relocation handling:: BFD relocation handling 59ed0d50c3Schristos* BFD ELF support:: BFD ELF support 60ed0d50c3Schristos* BFD glossary:: Glossary 61ed0d50c3Schristos* Index:: Index 62ed0d50c3Schristos@end menu 63ed0d50c3Schristos 64ed0d50c3Schristos@node BFD overview 65ed0d50c3Schristos@section BFD overview 66ed0d50c3Schristos 67ed0d50c3SchristosBFD is a library which provides a single interface to read and write 68ed0d50c3Schristosobject files, executables, archive files, and core files in any format. 69ed0d50c3Schristos 70ed0d50c3Schristos@menu 71ed0d50c3Schristos* BFD library interfaces:: BFD library interfaces 72ed0d50c3Schristos* BFD library users:: BFD library users 73ed0d50c3Schristos* BFD view:: The BFD view of a file 74ed0d50c3Schristos* BFD blindness:: BFD loses information 75ed0d50c3Schristos@end menu 76ed0d50c3Schristos 77ed0d50c3Schristos@node BFD library interfaces 78ed0d50c3Schristos@subsection BFD library interfaces 79ed0d50c3Schristos 80ed0d50c3SchristosOne way to look at the BFD library is to divide it into four parts by 81ed0d50c3Schristostype of interface. 82ed0d50c3Schristos 83ed0d50c3SchristosThe first interface is the set of generic functions which programs using 84ed0d50c3Schristosthe BFD library will call. These generic function normally translate 85ed0d50c3Schristosdirectly or indirectly into calls to routines which are specific to a 86ed0d50c3Schristosparticular object file format. Many of these generic functions are 87ed0d50c3Schristosactually defined as macros in @file{bfd.h}. These functions comprise 88ed0d50c3Schristosthe official BFD interface. 89ed0d50c3Schristos 90ed0d50c3SchristosThe second interface is the set of functions which appear in the target 91ed0d50c3Schristosvectors. This is the bulk of the code in BFD. A target vector is a set 92ed0d50c3Schristosof function pointers specific to a particular object file format. The 93ed0d50c3Schristostarget vector is used to implement the generic BFD functions. These 94ed0d50c3Schristosfunctions are always called through the target vector, and are never 95ed0d50c3Schristoscalled directly. The target vector is described in detail in @ref{BFD 96ed0d50c3Schristostarget vector}. The set of functions which appear in a particular 97ed0d50c3Schristostarget vector is often referred to as a BFD backend. 98ed0d50c3Schristos 99ed0d50c3SchristosThe third interface is a set of oddball functions which are typically 100ed0d50c3Schristosspecific to a particular object file format, are not generic functions, 101ed0d50c3Schristosand are called from outside of the BFD library. These are used as hooks 102ed0d50c3Schristosby the linker and the assembler when a particular object file format 103ed0d50c3Schristosrequires some action which the BFD generic interface does not provide. 104ed0d50c3SchristosThese functions are typically declared in @file{bfd.h}, but in many 105ed0d50c3Schristoscases they are only provided when BFD is configured with support for a 106ed0d50c3Schristosparticular object file format. These functions live in a grey area, and 107ed0d50c3Schristosare not really part of the official BFD interface. 108ed0d50c3Schristos 109ed0d50c3SchristosThe fourth interface is the set of BFD support functions which are 110ed0d50c3Schristoscalled by the other BFD functions. These manage issues like memory 111ed0d50c3Schristosallocation, error handling, file access, hash tables, swapping, and the 112ed0d50c3Schristoslike. These functions are never called from outside of the BFD library. 113ed0d50c3Schristos 114ed0d50c3Schristos@node BFD library users 115ed0d50c3Schristos@subsection BFD library users 116ed0d50c3Schristos 117ed0d50c3SchristosAnother way to look at the BFD library is to divide it into three parts 118ed0d50c3Schristosby the manner in which it is used. 119ed0d50c3Schristos 120ed0d50c3SchristosThe first use is to read an object file. The object file readers are 121ed0d50c3Schristosprograms like @samp{gdb}, @samp{nm}, @samp{objdump}, and @samp{objcopy}. 122ed0d50c3SchristosThese programs use BFD to view an object file in a generic form. The 123ed0d50c3Schristosofficial BFD interface is normally fully adequate for these programs. 124ed0d50c3Schristos 125ed0d50c3SchristosThe second use is to write an object file. The object file writers are 126ed0d50c3Schristosprograms like @samp{gas} and @samp{objcopy}. These programs use BFD to 127ed0d50c3Schristoscreate an object file. The official BFD interface is normally adequate 128ed0d50c3Schristosfor these programs, but for some object file formats the assembler needs 129ed0d50c3Schristossome additional hooks in order to set particular flags or other 130ed0d50c3Schristosinformation. The official BFD interface includes functions to copy 131ed0d50c3Schristosprivate information from one object file to another, and these functions 132ed0d50c3Schristosare used by @samp{objcopy} to avoid information loss. 133ed0d50c3Schristos 134ed0d50c3SchristosThe third use is to link object files. There is only one object file 135ed0d50c3Schristoslinker, @samp{ld}. Originally, @samp{ld} was an object file reader and 136ed0d50c3Schristosan object file writer, and it did the link operation using the generic 137ed0d50c3SchristosBFD structures. However, this turned out to be too slow and too memory 138ed0d50c3Schristosintensive. 139ed0d50c3Schristos 140ed0d50c3SchristosThe official BFD linker functions were written to permit specific BFD 141ed0d50c3Schristosbackends to perform the link without translating through the generic 142ed0d50c3Schristosstructures, in the normal case where all the input files and output file 143ed0d50c3Schristoshave the same object file format. Not all of the backends currently 144ed0d50c3Schristosimplement the new interface, and there are default linking functions 145ed0d50c3Schristoswithin BFD which use the generic structures and which work with all 146ed0d50c3Schristosbackends. 147ed0d50c3Schristos 148ed0d50c3SchristosFor several object file formats the linker needs additional hooks which 149ed0d50c3Schristosare not provided by the official BFD interface, particularly for dynamic 150ed0d50c3Schristoslinking support. These functions are typically called from the linker 151ed0d50c3Schristosemulation template. 152ed0d50c3Schristos 153ed0d50c3Schristos@node BFD view 154ed0d50c3Schristos@subsection The BFD view of a file 155ed0d50c3Schristos 156ed0d50c3SchristosBFD uses generic structures to manage information. It translates data 157ed0d50c3Schristosinto the generic form when reading files, and out of the generic form 158ed0d50c3Schristoswhen writing files. 159ed0d50c3Schristos 160ed0d50c3SchristosBFD describes a file as a pointer to the @samp{bfd} type. A @samp{bfd} 161ed0d50c3Schristosis composed of the following elements. The BFD information can be 162ed0d50c3Schristosdisplayed using the @samp{objdump} program with various options. 163ed0d50c3Schristos 164ed0d50c3Schristos@table @asis 165ed0d50c3Schristos@item general information 166ed0d50c3SchristosThe object file format, a few general flags, the start address. 167ed0d50c3Schristos@item architecture 168ed0d50c3SchristosThe architecture, including both a general processor type (m68k, MIPS 169ed0d50c3Schristosetc.) and a specific machine number (m68000, R4000, etc.). 170ed0d50c3Schristos@item sections 171ed0d50c3SchristosA list of sections. 172ed0d50c3Schristos@item symbols 173ed0d50c3SchristosA symbol table. 174ed0d50c3Schristos@end table 175ed0d50c3Schristos 176ed0d50c3SchristosBFD represents a section as a pointer to the @samp{asection} type. Each 177ed0d50c3Schristossection has a name and a size. Most sections also have an associated 178ed0d50c3Schristosblock of data, known as the section contents. Sections also have 179ed0d50c3Schristosassociated flags, a virtual memory address, a load memory address, a 180ed0d50c3Schristosrequired alignment, a list of relocations, and other miscellaneous 181ed0d50c3Schristosinformation. 182ed0d50c3Schristos 183ed0d50c3SchristosBFD represents a relocation as a pointer to the @samp{arelent} type. A 184ed0d50c3Schristosrelocation describes an action which the linker must take to modify the 185ed0d50c3Schristossection contents. Relocations have a symbol, an address, an addend, and 186ed0d50c3Schristosa pointer to a howto structure which describes how to perform the 187ed0d50c3Schristosrelocation. For more information, see @ref{BFD relocation handling}. 188ed0d50c3Schristos 189ed0d50c3SchristosBFD represents a symbol as a pointer to the @samp{asymbol} type. A 190ed0d50c3Schristossymbol has a name, a pointer to a section, an offset within that 191ed0d50c3Schristossection, and some flags. 192ed0d50c3Schristos 193ed0d50c3SchristosArchive files do not have any sections or symbols. Instead, BFD 194ed0d50c3Schristosrepresents an archive file as a file which contains a list of 195ed0d50c3Schristos@samp{bfd}s. BFD also provides access to the archive symbol map, as a 196ed0d50c3Schristoslist of symbol names. BFD provides a function to return the @samp{bfd} 197ed0d50c3Schristoswithin the archive which corresponds to a particular entry in the 198ed0d50c3Schristosarchive symbol map. 199ed0d50c3Schristos 200ed0d50c3Schristos@node BFD blindness 201ed0d50c3Schristos@subsection BFD loses information 202ed0d50c3Schristos 203ed0d50c3SchristosMost object file formats have information which BFD can not represent in 204ed0d50c3Schristosits generic form, at least as currently defined. 205ed0d50c3Schristos 206ed0d50c3SchristosThere is often explicit information which BFD can not represent. For 207ed0d50c3Schristosexample, the COFF version stamp, or the ELF program segments. BFD 208ed0d50c3Schristosprovides special hooks to handle this information when copying, 209ed0d50c3Schristosprinting, or linking an object file. The BFD support for a particular 210ed0d50c3Schristosobject file format will normally store this information in private data 211ed0d50c3Schristosand handle it using the special hooks. 212ed0d50c3Schristos 213ed0d50c3SchristosIn some cases there is also implicit information which BFD can not 214ed0d50c3Schristosrepresent. For example, the MIPS processor distinguishes small and 215ed0d50c3Schristoslarge symbols, and requires that all small symbols be within 32K of the 216ed0d50c3SchristosGP register. This means that the MIPS assembler must be able to mark 217ed0d50c3Schristosvariables as either small or large, and the MIPS linker must know to put 218ed0d50c3Schristossmall symbols within range of the GP register. Since BFD can not 219ed0d50c3Schristosrepresent this information, this means that the assembler and linker 220ed0d50c3Schristosmust have information that is specific to a particular object file 221ed0d50c3Schristosformat which is outside of the BFD library. 222ed0d50c3Schristos 223ed0d50c3SchristosThis loss of information indicates areas where the BFD paradigm breaks 224ed0d50c3Schristosdown. It is not actually possible to represent the myriad differences 225ed0d50c3Schristosamong object file formats using a single generic interface, at least not 226ed0d50c3Schristosin the manner which BFD does it today. 227ed0d50c3Schristos 228ed0d50c3SchristosNevertheless, the BFD library does greatly simplify the task of dealing 229ed0d50c3Schristoswith object files, and particular problems caused by information loss 230ed0d50c3Schristoscan normally be solved using some sort of relatively constrained hook 231ed0d50c3Schristosinto the library. 232ed0d50c3Schristos 233ed0d50c3Schristos 234ed0d50c3Schristos 235ed0d50c3Schristos@node BFD guidelines 236ed0d50c3Schristos@section BFD programming guidelines 237ed0d50c3Schristos@cindex bfd programming guidelines 238ed0d50c3Schristos@cindex programming guidelines for bfd 239ed0d50c3Schristos@cindex guidelines, bfd programming 240ed0d50c3Schristos 241ed0d50c3SchristosThere is a lot of poorly written and confusing code in BFD. New BFD 242ed0d50c3Schristoscode should be written to a higher standard. Merely because some BFD 243ed0d50c3Schristoscode is written in a particular manner does not mean that you should 244ed0d50c3Schristosemulate it. 245ed0d50c3Schristos 246ed0d50c3SchristosHere are some general BFD programming guidelines: 247ed0d50c3Schristos 248ed0d50c3Schristos@itemize @bullet 249ed0d50c3Schristos@item 250ed0d50c3SchristosFollow the GNU coding standards. 251ed0d50c3Schristos 252ed0d50c3Schristos@item 253ed0d50c3SchristosAvoid global variables. We ideally want BFD to be fully reentrant, so 254ed0d50c3Schristosthat it can be used in multiple threads. All uses of global or static 255ed0d50c3Schristosvariables interfere with that. Initialized constant variables are OK, 256ed0d50c3Schristosand they should be explicitly marked with @samp{const}. Instead of global 257ed0d50c3Schristosvariables, use data attached to a BFD or to a linker hash table. 258ed0d50c3Schristos 259ed0d50c3Schristos@item 260ed0d50c3SchristosAll externally visible functions should have names which start with 261ed0d50c3Schristos@samp{bfd_}. All such functions should be declared in some header file, 262ed0d50c3Schristostypically @file{bfd.h}. See, for example, the various declarations near 263ed0d50c3Schristosthe end of @file{bfd-in.h}, which mostly declare functions required by 264ed0d50c3Schristosspecific linker emulations. 265ed0d50c3Schristos 266ed0d50c3Schristos@item 267ed0d50c3SchristosAll functions which need to be visible from one file to another within 268ed0d50c3SchristosBFD, but should not be visible outside of BFD, should start with 269ed0d50c3Schristos@samp{_bfd_}. Although external names beginning with @samp{_} are 270ed0d50c3Schristosprohibited by the ANSI standard, in practice this usage will always 271ed0d50c3Schristoswork, and it is required by the GNU coding standards. 272ed0d50c3Schristos 273ed0d50c3Schristos@item 274ed0d50c3SchristosAlways remember that people can compile using @samp{--enable-targets} to 275ed0d50c3Schristosbuild several, or all, targets at once. It must be possible to link 276ed0d50c3Schristostogether the files for all targets. 277ed0d50c3Schristos 278ed0d50c3Schristos@item 279ed0d50c3SchristosBFD code should compile with few or no warnings using @samp{gcc -Wall}. 280ed0d50c3SchristosSome warnings are OK, like the absence of certain function declarations 281ed0d50c3Schristoswhich may or may not be declared in system header files. Warnings about 282ed0d50c3Schristosambiguous expressions and the like should always be fixed. 283ed0d50c3Schristos@end itemize 284ed0d50c3Schristos 285ed0d50c3Schristos@node BFD target vector 286ed0d50c3Schristos@section BFD target vector 287ed0d50c3Schristos@cindex bfd target vector 288ed0d50c3Schristos@cindex target vector in bfd 289ed0d50c3Schristos 290ed0d50c3SchristosBFD supports multiple object file formats by using the @dfn{target 291ed0d50c3Schristosvector}. This is simply a set of function pointers which implement 292ed0d50c3Schristosbehaviour that is specific to a particular object file format. 293ed0d50c3Schristos 294ed0d50c3SchristosIn this section I list all of the entries in the target vector and 295ed0d50c3Schristosdescribe what they do. 296ed0d50c3Schristos 297ed0d50c3Schristos@menu 298ed0d50c3Schristos* BFD target vector miscellaneous:: Miscellaneous constants 299ed0d50c3Schristos* BFD target vector swap:: Swapping functions 300ed0d50c3Schristos* BFD target vector format:: Format type dependent functions 301ed0d50c3Schristos* BFD_JUMP_TABLE macros:: BFD_JUMP_TABLE macros 302ed0d50c3Schristos* BFD target vector generic:: Generic functions 303ed0d50c3Schristos* BFD target vector copy:: Copy functions 304ed0d50c3Schristos* BFD target vector core:: Core file support functions 305ed0d50c3Schristos* BFD target vector archive:: Archive functions 306ed0d50c3Schristos* BFD target vector symbols:: Symbol table functions 307ed0d50c3Schristos* BFD target vector relocs:: Relocation support 308ed0d50c3Schristos* BFD target vector write:: Output functions 309ed0d50c3Schristos* BFD target vector link:: Linker functions 310ed0d50c3Schristos* BFD target vector dynamic:: Dynamic linking information functions 311ed0d50c3Schristos@end menu 312ed0d50c3Schristos 313ed0d50c3Schristos@node BFD target vector miscellaneous 314ed0d50c3Schristos@subsection Miscellaneous constants 315ed0d50c3Schristos 316ed0d50c3SchristosThe target vector starts with a set of constants. 317ed0d50c3Schristos 318ed0d50c3Schristos@table @samp 319ed0d50c3Schristos@item name 320ed0d50c3SchristosThe name of the target vector. This is an arbitrary string. This is 321*b88e3e88Schristoshow the target vector is named in command-line options for tools which 322ed0d50c3Schristosuse BFD, such as the @samp{--oformat} linker option. 323ed0d50c3Schristos 324ed0d50c3Schristos@item flavour 325ed0d50c3SchristosA general description of the type of target. The following flavours are 326ed0d50c3Schristoscurrently defined: 327ed0d50c3Schristos 328ed0d50c3Schristos@table @samp 329ed0d50c3Schristos@item bfd_target_unknown_flavour 330ed0d50c3SchristosUndefined or unknown. 331ed0d50c3Schristos@item bfd_target_aout_flavour 332ed0d50c3Schristosa.out. 333ed0d50c3Schristos@item bfd_target_coff_flavour 334ed0d50c3SchristosCOFF. 335ed0d50c3Schristos@item bfd_target_ecoff_flavour 336ed0d50c3SchristosECOFF. 337ed0d50c3Schristos@item bfd_target_elf_flavour 338ed0d50c3SchristosELF. 339ed0d50c3Schristos@item bfd_target_tekhex_flavour 340ed0d50c3SchristosTektronix hex format. 341ed0d50c3Schristos@item bfd_target_srec_flavour 342ed0d50c3SchristosMotorola S-record format. 343ed0d50c3Schristos@item bfd_target_ihex_flavour 344ed0d50c3SchristosIntel hex format. 345ed0d50c3Schristos@item bfd_target_som_flavour 346ed0d50c3SchristosSOM (used on HP/UX). 347ed0d50c3Schristos@item bfd_target_verilog_flavour 348ed0d50c3SchristosVerilog memory hex dump format. 349ed0d50c3Schristos@item bfd_target_os9k_flavour 350ed0d50c3Schristosos9000. 351ed0d50c3Schristos@item bfd_target_versados_flavour 352ed0d50c3SchristosVERSAdos. 353ed0d50c3Schristos@item bfd_target_msdos_flavour 354ed0d50c3SchristosMS-DOS. 355ed0d50c3Schristos@item bfd_target_evax_flavour 356ed0d50c3SchristosopenVMS. 357ed0d50c3Schristos@item bfd_target_mmo_flavour 358ed0d50c3SchristosDonald Knuth's MMIXware object format. 359ed0d50c3Schristos@end table 360ed0d50c3Schristos 361ed0d50c3Schristos@item byteorder 362ed0d50c3SchristosThe byte order of data in the object file. One of 363ed0d50c3Schristos@samp{BFD_ENDIAN_BIG}, @samp{BFD_ENDIAN_LITTLE}, or 364ed0d50c3Schristos@samp{BFD_ENDIAN_UNKNOWN}. The latter would be used for a format such 365ed0d50c3Schristosas S-records which do not record the architecture of the data. 366ed0d50c3Schristos 367ed0d50c3Schristos@item header_byteorder 368ed0d50c3SchristosThe byte order of header information in the object file. Normally the 369ed0d50c3Schristossame as the @samp{byteorder} field, but there are certain cases where it 370ed0d50c3Schristosmay be different. 371ed0d50c3Schristos 372ed0d50c3Schristos@item object_flags 373ed0d50c3SchristosFlags which may appear in the @samp{flags} field of a BFD with this 374ed0d50c3Schristosformat. 375ed0d50c3Schristos 376ed0d50c3Schristos@item section_flags 377ed0d50c3SchristosFlags which may appear in the @samp{flags} field of a section within a 378ed0d50c3SchristosBFD with this format. 379ed0d50c3Schristos 380ed0d50c3Schristos@item symbol_leading_char 381ed0d50c3SchristosA character which the C compiler normally puts before a symbol. For 382ed0d50c3Schristosexample, an a.out compiler will typically generate the symbol 383ed0d50c3Schristos@samp{_foo} for a function named @samp{foo} in the C source, in which 384ed0d50c3Schristoscase this field would be @samp{_}. If there is no such character, this 385ed0d50c3Schristosfield will be @samp{0}. 386ed0d50c3Schristos 387ed0d50c3Schristos@item ar_pad_char 388ed0d50c3SchristosThe padding character to use at the end of an archive name. Normally 389ed0d50c3Schristos@samp{/}. 390ed0d50c3Schristos 391ed0d50c3Schristos@item ar_max_namelen 392ed0d50c3SchristosThe maximum length of a short name in an archive. Normally @samp{14}. 393ed0d50c3Schristos 394ed0d50c3Schristos@item backend_data 395ed0d50c3SchristosA pointer to constant backend data. This is used by backends to store 396ed0d50c3Schristoswhatever additional information they need to distinguish similar target 397ed0d50c3Schristosvectors which use the same sets of functions. 398ed0d50c3Schristos@end table 399ed0d50c3Schristos 400ed0d50c3Schristos@node BFD target vector swap 401ed0d50c3Schristos@subsection Swapping functions 402ed0d50c3Schristos 403ed0d50c3SchristosEvery target vector has function pointers used for swapping information 404ed0d50c3Schristosin and out of the target representation. There are two sets of 405ed0d50c3Schristosfunctions: one for data information, and one for header information. 406ed0d50c3SchristosEach set has three sizes: 64-bit, 32-bit, and 16-bit. Each size has 407ed0d50c3Schristosthree actual functions: put, get unsigned, and get signed. 408ed0d50c3Schristos 409ed0d50c3SchristosThese 18 functions are used to convert data between the host and target 410ed0d50c3Schristosrepresentations. 411ed0d50c3Schristos 412ed0d50c3Schristos@node BFD target vector format 413ed0d50c3Schristos@subsection Format type dependent functions 414ed0d50c3Schristos 415ed0d50c3SchristosEvery target vector has three arrays of function pointers which are 416ed0d50c3Schristosindexed by the BFD format type. The BFD format types are as follows: 417ed0d50c3Schristos 418ed0d50c3Schristos@table @samp 419ed0d50c3Schristos@item bfd_unknown 420ed0d50c3SchristosUnknown format. Not used for anything useful. 421ed0d50c3Schristos@item bfd_object 422ed0d50c3SchristosObject file. 423ed0d50c3Schristos@item bfd_archive 424ed0d50c3SchristosArchive file. 425ed0d50c3Schristos@item bfd_core 426ed0d50c3SchristosCore file. 427ed0d50c3Schristos@end table 428ed0d50c3Schristos 429ed0d50c3SchristosThe three arrays of function pointers are as follows: 430ed0d50c3Schristos 431ed0d50c3Schristos@table @samp 432ed0d50c3Schristos@item bfd_check_format 433ed0d50c3SchristosCheck whether the BFD is of a particular format (object file, archive 434ed0d50c3Schristosfile, or core file) corresponding to this target vector. This is called 435ed0d50c3Schristosby the @samp{bfd_check_format} function when examining an existing BFD. 436ed0d50c3SchristosIf the BFD matches the desired format, this function will initialize any 437ed0d50c3Schristosformat specific information such as the @samp{tdata} field of the BFD. 438ed0d50c3SchristosThis function must be called before any other BFD target vector function 439ed0d50c3Schristoson a file opened for reading. 440ed0d50c3Schristos 441ed0d50c3Schristos@item bfd_set_format 442ed0d50c3SchristosSet the format of a BFD which was created for output. This is called by 443ed0d50c3Schristosthe @samp{bfd_set_format} function after creating the BFD with a 444ed0d50c3Schristosfunction such as @samp{bfd_openw}. This function will initialize format 445ed0d50c3Schristosspecific information required to write out an object file or whatever of 446ed0d50c3Schristosthe given format. This function must be called before any other BFD 447ed0d50c3Schristostarget vector function on a file opened for writing. 448ed0d50c3Schristos 449ed0d50c3Schristos@item bfd_write_contents 450ed0d50c3SchristosWrite out the contents of the BFD in the given format. This is called 451ed0d50c3Schristosby @samp{bfd_close} function for a BFD opened for writing. This really 452ed0d50c3Schristosshould not be an array selected by format type, as the 453ed0d50c3Schristos@samp{bfd_set_format} function provides all the required information. 454ed0d50c3SchristosIn fact, BFD will fail if a different format is used when calling 455ed0d50c3Schristosthrough the @samp{bfd_set_format} and the @samp{bfd_write_contents} 456ed0d50c3Schristosarrays; fortunately, since @samp{bfd_close} gets it right, this is a 457ed0d50c3Schristosdifficult error to make. 458ed0d50c3Schristos@end table 459ed0d50c3Schristos 460ed0d50c3Schristos@node BFD_JUMP_TABLE macros 461ed0d50c3Schristos@subsection @samp{BFD_JUMP_TABLE} macros 462ed0d50c3Schristos@cindex @samp{BFD_JUMP_TABLE} 463ed0d50c3Schristos 464ed0d50c3SchristosMost target vectors are defined using @samp{BFD_JUMP_TABLE} macros. 465ed0d50c3SchristosThese macros take a single argument, which is a prefix applied to a set 466ed0d50c3Schristosof functions. The macros are then used to initialize the fields in the 467ed0d50c3Schristostarget vector. 468ed0d50c3Schristos 469ed0d50c3SchristosFor example, the @samp{BFD_JUMP_TABLE_RELOCS} macro defines three 470ed0d50c3Schristosfunctions: @samp{_get_reloc_upper_bound}, @samp{_canonicalize_reloc}, 471ed0d50c3Schristosand @samp{_bfd_reloc_type_lookup}. A reference like 472ed0d50c3Schristos@samp{BFD_JUMP_TABLE_RELOCS (foo)} will expand into three functions 473ed0d50c3Schristosprefixed with @samp{foo}: @samp{foo_get_reloc_upper_bound}, etc. The 474ed0d50c3Schristos@samp{BFD_JUMP_TABLE_RELOCS} macro will be placed such that those three 475ed0d50c3Schristosfunctions initialize the appropriate fields in the BFD target vector. 476ed0d50c3Schristos 477ed0d50c3SchristosThis is done because it turns out that many different target vectors can 478ed0d50c3Schristosshare certain classes of functions. For example, archives are similar 479ed0d50c3Schristoson most platforms, so most target vectors can use the same archive 480ed0d50c3Schristosfunctions. Those target vectors all use @samp{BFD_JUMP_TABLE_ARCHIVE} 481ed0d50c3Schristoswith the same argument, calling a set of functions which is defined in 482ed0d50c3Schristos@file{archive.c}. 483ed0d50c3Schristos 484ed0d50c3SchristosEach of the @samp{BFD_JUMP_TABLE} macros is mentioned below along with 485ed0d50c3Schristosthe description of the function pointers which it defines. The function 486ed0d50c3Schristospointers will be described using the name without the prefix which the 487ed0d50c3Schristos@samp{BFD_JUMP_TABLE} macro defines. This name is normally the same as 488ed0d50c3Schristosthe name of the field in the target vector structure. Any differences 489ed0d50c3Schristoswill be noted. 490ed0d50c3Schristos 491ed0d50c3Schristos@node BFD target vector generic 492ed0d50c3Schristos@subsection Generic functions 493ed0d50c3Schristos@cindex @samp{BFD_JUMP_TABLE_GENERIC} 494ed0d50c3Schristos 495ed0d50c3SchristosThe @samp{BFD_JUMP_TABLE_GENERIC} macro is used for some catch all 496ed0d50c3Schristosfunctions which don't easily fit into other categories. 497ed0d50c3Schristos 498ed0d50c3Schristos@table @samp 499ed0d50c3Schristos@item _close_and_cleanup 500ed0d50c3SchristosFree any target specific information associated with the BFD. This is 501ed0d50c3Schristoscalled when any BFD is closed (the @samp{bfd_write_contents} function 502ed0d50c3Schristosmentioned earlier is only called for a BFD opened for writing). Most 503ed0d50c3Schristostargets use @samp{bfd_alloc} to allocate all target specific 504ed0d50c3Schristosinformation, and therefore don't have to do anything in this function. 505ed0d50c3SchristosThis function pointer is typically set to 506ed0d50c3Schristos@samp{_bfd_generic_close_and_cleanup}, which simply returns true. 507ed0d50c3Schristos 508ed0d50c3Schristos@item _bfd_free_cached_info 509ed0d50c3SchristosFree any cached information associated with the BFD which can be 510ed0d50c3Schristosrecreated later if necessary. This is used to reduce the memory 511ed0d50c3Schristosconsumption required by programs using BFD. This is normally called via 512ed0d50c3Schristosthe @samp{bfd_free_cached_info} macro. It is used by the default 513ed0d50c3Schristosarchive routines when computing the archive map. Most targets do not 514ed0d50c3Schristosdo anything special for this entry point, and just set it to 515ed0d50c3Schristos@samp{_bfd_generic_free_cached_info}, which simply returns true. 516ed0d50c3Schristos 517ed0d50c3Schristos@item _new_section_hook 518ed0d50c3SchristosThis is called from @samp{bfd_make_section_anyway} whenever a new 519ed0d50c3Schristossection is created. Most targets use it to initialize section specific 520ed0d50c3Schristosinformation. This function is called whether or not the section 521ed0d50c3Schristoscorresponds to an actual section in an actual BFD. 522ed0d50c3Schristos 523ed0d50c3Schristos@item _get_section_contents 524ed0d50c3SchristosGet the contents of a section. This is called from 525ed0d50c3Schristos@samp{bfd_get_section_contents}. Most targets set this to 526ed0d50c3Schristos@samp{_bfd_generic_get_section_contents}, which does a @samp{bfd_seek} 527ed0d50c3Schristosbased on the section's @samp{filepos} field and a @samp{bfd_bread}. The 528ed0d50c3Schristoscorresponding field in the target vector is named 529ed0d50c3Schristos@samp{_bfd_get_section_contents}. 530ed0d50c3Schristos 531ed0d50c3Schristos@item _get_section_contents_in_window 532ed0d50c3SchristosSet a @samp{bfd_window} to hold the contents of a section. This is 533ed0d50c3Schristoscalled from @samp{bfd_get_section_contents_in_window}. The 534ed0d50c3Schristos@samp{bfd_window} idea never really caught on, and I don't think this is 535ed0d50c3Schristosever called. Pretty much all targets implement this as 536ed0d50c3Schristos@samp{bfd_generic_get_section_contents_in_window}, which uses 537ed0d50c3Schristos@samp{bfd_get_section_contents} to do the right thing. The 538ed0d50c3Schristoscorresponding field in the target vector is named 539ed0d50c3Schristos@samp{_bfd_get_section_contents_in_window}. 540ed0d50c3Schristos@end table 541ed0d50c3Schristos 542ed0d50c3Schristos@node BFD target vector copy 543ed0d50c3Schristos@subsection Copy functions 544ed0d50c3Schristos@cindex @samp{BFD_JUMP_TABLE_COPY} 545ed0d50c3Schristos 546ed0d50c3SchristosThe @samp{BFD_JUMP_TABLE_COPY} macro is used for functions which are 547ed0d50c3Schristoscalled when copying BFDs, and for a couple of functions which deal with 548ed0d50c3Schristosinternal BFD information. 549ed0d50c3Schristos 550ed0d50c3Schristos@table @samp 551ed0d50c3Schristos@item _bfd_copy_private_bfd_data 552ed0d50c3SchristosThis is called when copying a BFD, via @samp{bfd_copy_private_bfd_data}. 553ed0d50c3SchristosIf the input and output BFDs have the same format, this will copy any 554ed0d50c3Schristosprivate information over. This is called after all the section contents 555ed0d50c3Schristoshave been written to the output file. Only a few targets do anything in 556ed0d50c3Schristosthis function. 557ed0d50c3Schristos 558ed0d50c3Schristos@item _bfd_merge_private_bfd_data 559ed0d50c3SchristosThis is called when linking, via @samp{bfd_merge_private_bfd_data}. It 560ed0d50c3Schristosgives the backend linker code a chance to set any special flags in the 561ed0d50c3Schristosoutput file based on the contents of the input file. Only a few targets 562ed0d50c3Schristosdo anything in this function. 563ed0d50c3Schristos 564ed0d50c3Schristos@item _bfd_copy_private_section_data 565ed0d50c3SchristosThis is similar to @samp{_bfd_copy_private_bfd_data}, but it is called 566ed0d50c3Schristosfor each section, via @samp{bfd_copy_private_section_data}. This 567ed0d50c3Schristosfunction is called before any section contents have been written. Only 568ed0d50c3Schristosa few targets do anything in this function. 569ed0d50c3Schristos 570ed0d50c3Schristos@item _bfd_copy_private_symbol_data 571ed0d50c3SchristosThis is called via @samp{bfd_copy_private_symbol_data}, but I don't 572ed0d50c3Schristosthink anything actually calls it. If it were defined, it could be used 573ed0d50c3Schristosto copy private symbol data from one BFD to another. However, most BFDs 574ed0d50c3Schristosstore extra symbol information by allocating space which is larger than 575ed0d50c3Schristosthe @samp{asymbol} structure and storing private information in the 576ed0d50c3Schristosextra space. Since @samp{objcopy} and other programs copy symbol 577ed0d50c3Schristosinformation by copying pointers to @samp{asymbol} structures, the 578ed0d50c3Schristosprivate symbol information is automatically copied as well. Most 579ed0d50c3Schristostargets do not do anything in this function. 580ed0d50c3Schristos 581ed0d50c3Schristos@item _bfd_set_private_flags 582ed0d50c3SchristosThis is called via @samp{bfd_set_private_flags}. It is basically a hook 583ed0d50c3Schristosfor the assembler to set magic information. For example, the PowerPC 584ed0d50c3SchristosELF assembler uses it to set flags which appear in the e_flags field of 585ed0d50c3Schristosthe ELF header. Most targets do not do anything in this function. 586ed0d50c3Schristos 587ed0d50c3Schristos@item _bfd_print_private_bfd_data 588ed0d50c3SchristosThis is called by @samp{objdump} when the @samp{-p} option is used. It 589ed0d50c3Schristosis called via @samp{bfd_print_private_data}. It prints any interesting 590ed0d50c3Schristosinformation about the BFD which can not be otherwise represented by BFD 591ed0d50c3Schristosand thus can not be printed by @samp{objdump}. Most targets do not do 592ed0d50c3Schristosanything in this function. 593ed0d50c3Schristos@end table 594ed0d50c3Schristos 595ed0d50c3Schristos@node BFD target vector core 596ed0d50c3Schristos@subsection Core file support functions 597ed0d50c3Schristos@cindex @samp{BFD_JUMP_TABLE_CORE} 598ed0d50c3Schristos 599ed0d50c3SchristosThe @samp{BFD_JUMP_TABLE_CORE} macro is used for functions which deal 600ed0d50c3Schristoswith core files. Obviously, these functions only do something 601ed0d50c3Schristosinteresting for targets which have core file support. 602ed0d50c3Schristos 603ed0d50c3Schristos@table @samp 604ed0d50c3Schristos@item _core_file_failing_command 605ed0d50c3SchristosGiven a core file, this returns the command which was run to produce the 606ed0d50c3Schristoscore file. 607ed0d50c3Schristos 608ed0d50c3Schristos@item _core_file_failing_signal 609ed0d50c3SchristosGiven a core file, this returns the signal number which produced the 610ed0d50c3Schristoscore file. 611ed0d50c3Schristos 612ed0d50c3Schristos@item _core_file_matches_executable_p 613ed0d50c3SchristosGiven a core file and a BFD for an executable, this returns whether the 614ed0d50c3Schristoscore file was generated by the executable. 615ed0d50c3Schristos@end table 616ed0d50c3Schristos 617ed0d50c3Schristos@node BFD target vector archive 618ed0d50c3Schristos@subsection Archive functions 619ed0d50c3Schristos@cindex @samp{BFD_JUMP_TABLE_ARCHIVE} 620ed0d50c3Schristos 621ed0d50c3SchristosThe @samp{BFD_JUMP_TABLE_ARCHIVE} macro is used for functions which deal 622ed0d50c3Schristoswith archive files. Most targets use COFF style archive files 623ed0d50c3Schristos(including ELF targets), and these use @samp{_bfd_archive_coff} as the 624ed0d50c3Schristosargument to @samp{BFD_JUMP_TABLE_ARCHIVE}. Some targets use BSD/a.out 625ed0d50c3Schristosstyle archives, and these use @samp{_bfd_archive_bsd}. (The main 626ed0d50c3Schristosdifference between BSD and COFF archives is the format of the archive 627ed0d50c3Schristossymbol table). Targets with no archive support use 628ed0d50c3Schristos@samp{_bfd_noarchive}. Finally, a few targets have unusual archive 629ed0d50c3Schristoshandling. 630ed0d50c3Schristos 631ed0d50c3Schristos@table @samp 632ed0d50c3Schristos@item _slurp_armap 633ed0d50c3SchristosRead in the archive symbol table, storing it in private BFD data. This 634ed0d50c3Schristosis normally called from the archive @samp{check_format} routine. The 635ed0d50c3Schristoscorresponding field in the target vector is named 636ed0d50c3Schristos@samp{_bfd_slurp_armap}. 637ed0d50c3Schristos 638ed0d50c3Schristos@item _slurp_extended_name_table 639ed0d50c3SchristosRead in the extended name table from the archive, if there is one, 640ed0d50c3Schristosstoring it in private BFD data. This is normally called from the 641ed0d50c3Schristosarchive @samp{check_format} routine. The corresponding field in the 642ed0d50c3Schristostarget vector is named @samp{_bfd_slurp_extended_name_table}. 643ed0d50c3Schristos 644ed0d50c3Schristos@item construct_extended_name_table 645ed0d50c3SchristosBuild and return an extended name table if one is needed to write out 646ed0d50c3Schristosthe archive. This also adjusts the archive headers to refer to the 647ed0d50c3Schristosextended name table appropriately. This is normally called from the 648ed0d50c3Schristosarchive @samp{write_contents} routine. The corresponding field in the 649ed0d50c3Schristostarget vector is named @samp{_bfd_construct_extended_name_table}. 650ed0d50c3Schristos 651ed0d50c3Schristos@item _truncate_arname 652ed0d50c3SchristosThis copies a file name into an archive header, truncating it as 653ed0d50c3Schristosrequired. It is normally called from the archive @samp{write_contents} 654ed0d50c3Schristosroutine. This function is more interesting in targets which do not 655ed0d50c3Schristossupport extended name tables, but I think the GNU @samp{ar} program 656ed0d50c3Schristosalways uses extended name tables anyhow. The corresponding field in the 657ed0d50c3Schristostarget vector is named @samp{_bfd_truncate_arname}. 658ed0d50c3Schristos 659ed0d50c3Schristos@item _write_armap 660ed0d50c3SchristosWrite out the archive symbol table using calls to @samp{bfd_bwrite}. 661ed0d50c3SchristosThis is normally called from the archive @samp{write_contents} routine. 662ed0d50c3SchristosThe corresponding field in the target vector is named @samp{write_armap} 663ed0d50c3Schristos(no leading underscore). 664ed0d50c3Schristos 665ed0d50c3Schristos@item _read_ar_hdr 666ed0d50c3SchristosRead and parse an archive header. This handles expanding the archive 667ed0d50c3Schristosheader name into the real file name using the extended name table. This 668ed0d50c3Schristosis called by routines which read the archive symbol table or the archive 669ed0d50c3Schristositself. The corresponding field in the target vector is named 670ed0d50c3Schristos@samp{_bfd_read_ar_hdr_fn}. 671ed0d50c3Schristos 672ed0d50c3Schristos@item _openr_next_archived_file 673ed0d50c3SchristosGiven an archive and a BFD representing a file stored within the 674ed0d50c3Schristosarchive, return a BFD for the next file in the archive. This is called 675ed0d50c3Schristosvia @samp{bfd_openr_next_archived_file}. The corresponding field in the 676ed0d50c3Schristostarget vector is named @samp{openr_next_archived_file} (no leading 677ed0d50c3Schristosunderscore). 678ed0d50c3Schristos 679ed0d50c3Schristos@item _get_elt_at_index 680ed0d50c3SchristosGiven an archive and an index, return a BFD for the file in the archive 681ed0d50c3Schristoscorresponding to that entry in the archive symbol table. This is called 682ed0d50c3Schristosvia @samp{bfd_get_elt_at_index}. The corresponding field in the target 683ed0d50c3Schristosvector is named @samp{_bfd_get_elt_at_index}. 684ed0d50c3Schristos 685ed0d50c3Schristos@item _generic_stat_arch_elt 686ed0d50c3SchristosDo a stat on an element of an archive, returning information read from 687ed0d50c3Schristosthe archive header (modification time, uid, gid, file mode, size). This 688ed0d50c3Schristosis called via @samp{bfd_stat_arch_elt}. The corresponding field in the 689ed0d50c3Schristostarget vector is named @samp{_bfd_stat_arch_elt}. 690ed0d50c3Schristos 691ed0d50c3Schristos@item _update_armap_timestamp 692ed0d50c3SchristosAfter the entire contents of an archive have been written out, update 693ed0d50c3Schristosthe timestamp of the archive symbol table to be newer than that of the 694ed0d50c3Schristosfile. This is required for a.out style archives. This is normally 695ed0d50c3Schristoscalled by the archive @samp{write_contents} routine. The corresponding 696ed0d50c3Schristosfield in the target vector is named @samp{_bfd_update_armap_timestamp}. 697ed0d50c3Schristos@end table 698ed0d50c3Schristos 699ed0d50c3Schristos@node BFD target vector symbols 700ed0d50c3Schristos@subsection Symbol table functions 701ed0d50c3Schristos@cindex @samp{BFD_JUMP_TABLE_SYMBOLS} 702ed0d50c3Schristos 703ed0d50c3SchristosThe @samp{BFD_JUMP_TABLE_SYMBOLS} macro is used for functions which deal 704ed0d50c3Schristoswith symbols. 705ed0d50c3Schristos 706ed0d50c3Schristos@table @samp 707ed0d50c3Schristos@item _get_symtab_upper_bound 708ed0d50c3SchristosReturn a sensible upper bound on the amount of memory which will be 709ed0d50c3Schristosrequired to read the symbol table. In practice most targets return the 710ed0d50c3Schristosamount of memory required to hold @samp{asymbol} pointers for all the 711ed0d50c3Schristossymbols plus a trailing @samp{NULL} entry, and store the actual symbol 712ed0d50c3Schristosinformation in BFD private data. This is called via 713ed0d50c3Schristos@samp{bfd_get_symtab_upper_bound}. The corresponding field in the 714ed0d50c3Schristostarget vector is named @samp{_bfd_get_symtab_upper_bound}. 715ed0d50c3Schristos 716ed0d50c3Schristos@item _canonicalize_symtab 717ed0d50c3SchristosRead in the symbol table. This is called via 718ed0d50c3Schristos@samp{bfd_canonicalize_symtab}. The corresponding field in the target 719ed0d50c3Schristosvector is named @samp{_bfd_canonicalize_symtab}. 720ed0d50c3Schristos 721ed0d50c3Schristos@item _make_empty_symbol 722ed0d50c3SchristosCreate an empty symbol for the BFD. This is needed because most targets 723ed0d50c3Schristosstore extra information with each symbol by allocating a structure 724ed0d50c3Schristoslarger than an @samp{asymbol} and storing the extra information at the 725ed0d50c3Schristosend. This function will allocate the right amount of memory, and return 726ed0d50c3Schristoswhat looks like a pointer to an empty @samp{asymbol}. This is called 727ed0d50c3Schristosvia @samp{bfd_make_empty_symbol}. The corresponding field in the target 728ed0d50c3Schristosvector is named @samp{_bfd_make_empty_symbol}. 729ed0d50c3Schristos 730ed0d50c3Schristos@item _print_symbol 731ed0d50c3SchristosPrint information about the symbol. This is called via 732ed0d50c3Schristos@samp{bfd_print_symbol}. One of the arguments indicates what sort of 733ed0d50c3Schristosinformation should be printed: 734ed0d50c3Schristos 735ed0d50c3Schristos@table @samp 736ed0d50c3Schristos@item bfd_print_symbol_name 737ed0d50c3SchristosJust print the symbol name. 738ed0d50c3Schristos@item bfd_print_symbol_more 739ed0d50c3SchristosPrint the symbol name and some interesting flags. I don't think 740ed0d50c3Schristosanything actually uses this. 741ed0d50c3Schristos@item bfd_print_symbol_all 742ed0d50c3SchristosPrint all information about the symbol. This is used by @samp{objdump} 743ed0d50c3Schristoswhen run with the @samp{-t} option. 744ed0d50c3Schristos@end table 745ed0d50c3SchristosThe corresponding field in the target vector is named 746ed0d50c3Schristos@samp{_bfd_print_symbol}. 747ed0d50c3Schristos 748ed0d50c3Schristos@item _get_symbol_info 749ed0d50c3SchristosReturn a standard set of information about the symbol. This is called 750ed0d50c3Schristosvia @samp{bfd_symbol_info}. The corresponding field in the target 751ed0d50c3Schristosvector is named @samp{_bfd_get_symbol_info}. 752ed0d50c3Schristos 753ed0d50c3Schristos@item _bfd_is_local_label_name 754ed0d50c3SchristosReturn whether the given string would normally represent the name of a 755ed0d50c3Schristoslocal label. This is called via @samp{bfd_is_local_label} and 756ed0d50c3Schristos@samp{bfd_is_local_label_name}. Local labels are normally discarded by 757ed0d50c3Schristosthe assembler. In the linker, this defines the difference between the 758ed0d50c3Schristos@samp{-x} and @samp{-X} options. 759ed0d50c3Schristos 760ed0d50c3Schristos@item _get_lineno 761ed0d50c3SchristosReturn line number information for a symbol. This is only meaningful 762ed0d50c3Schristosfor a COFF target. This is called when writing out COFF line numbers. 763ed0d50c3Schristos 764ed0d50c3Schristos@item _find_nearest_line 765ed0d50c3SchristosGiven an address within a section, use the debugging information to find 766ed0d50c3Schristosthe matching file name, function name, and line number, if any. This is 767ed0d50c3Schristoscalled via @samp{bfd_find_nearest_line}. The corresponding field in the 768ed0d50c3Schristostarget vector is named @samp{_bfd_find_nearest_line}. 769ed0d50c3Schristos 770ed0d50c3Schristos@item _bfd_make_debug_symbol 771ed0d50c3SchristosMake a debugging symbol. This is only meaningful for a COFF target, 772ed0d50c3Schristoswhere it simply returns a symbol which will be placed in the 773ed0d50c3Schristos@samp{N_DEBUG} section when it is written out. This is called via 774ed0d50c3Schristos@samp{bfd_make_debug_symbol}. 775ed0d50c3Schristos 776ed0d50c3Schristos@item _read_minisymbols 777ed0d50c3SchristosMinisymbols are used to reduce the memory requirements of programs like 778ed0d50c3Schristos@samp{nm}. A minisymbol is a cookie pointing to internal symbol 779ed0d50c3Schristosinformation which the caller can use to extract complete symbol 780ed0d50c3Schristosinformation. This permits BFD to not convert all the symbols into 781ed0d50c3Schristosgeneric form, but to instead convert them one at a time. This is called 782ed0d50c3Schristosvia @samp{bfd_read_minisymbols}. Most targets do not implement this, 783ed0d50c3Schristosand just use generic support which is based on using standard 784ed0d50c3Schristos@samp{asymbol} structures. 785ed0d50c3Schristos 786ed0d50c3Schristos@item _minisymbol_to_symbol 787ed0d50c3SchristosConvert a minisymbol to a standard @samp{asymbol}. This is called via 788ed0d50c3Schristos@samp{bfd_minisymbol_to_symbol}. 789ed0d50c3Schristos@end table 790ed0d50c3Schristos 791ed0d50c3Schristos@node BFD target vector relocs 792ed0d50c3Schristos@subsection Relocation support 793ed0d50c3Schristos@cindex @samp{BFD_JUMP_TABLE_RELOCS} 794ed0d50c3Schristos 795ed0d50c3SchristosThe @samp{BFD_JUMP_TABLE_RELOCS} macro is used for functions which deal 796ed0d50c3Schristoswith relocations. 797ed0d50c3Schristos 798ed0d50c3Schristos@table @samp 799ed0d50c3Schristos@item _get_reloc_upper_bound 800ed0d50c3SchristosReturn a sensible upper bound on the amount of memory which will be 801ed0d50c3Schristosrequired to read the relocations for a section. In practice most 802ed0d50c3Schristostargets return the amount of memory required to hold @samp{arelent} 803ed0d50c3Schristospointers for all the relocations plus a trailing @samp{NULL} entry, and 804ed0d50c3Schristosstore the actual relocation information in BFD private data. This is 805ed0d50c3Schristoscalled via @samp{bfd_get_reloc_upper_bound}. 806ed0d50c3Schristos 807ed0d50c3Schristos@item _canonicalize_reloc 808ed0d50c3SchristosReturn the relocation information for a section. This is called via 809ed0d50c3Schristos@samp{bfd_canonicalize_reloc}. The corresponding field in the target 810ed0d50c3Schristosvector is named @samp{_bfd_canonicalize_reloc}. 811ed0d50c3Schristos 812ed0d50c3Schristos@item _bfd_reloc_type_lookup 813ed0d50c3SchristosGiven a relocation code, return the corresponding howto structure 814ed0d50c3Schristos(@pxref{BFD relocation codes}). This is called via 815ed0d50c3Schristos@samp{bfd_reloc_type_lookup}. The corresponding field in the target 816ed0d50c3Schristosvector is named @samp{reloc_type_lookup}. 817ed0d50c3Schristos@end table 818ed0d50c3Schristos 819ed0d50c3Schristos@node BFD target vector write 820ed0d50c3Schristos@subsection Output functions 821ed0d50c3Schristos@cindex @samp{BFD_JUMP_TABLE_WRITE} 822ed0d50c3Schristos 823ed0d50c3SchristosThe @samp{BFD_JUMP_TABLE_WRITE} macro is used for functions which deal 824ed0d50c3Schristoswith writing out a BFD. 825ed0d50c3Schristos 826ed0d50c3Schristos@table @samp 827ed0d50c3Schristos@item _set_arch_mach 828ed0d50c3SchristosSet the architecture and machine number for a BFD. This is called via 829ed0d50c3Schristos@samp{bfd_set_arch_mach}. Most targets implement this by calling 830ed0d50c3Schristos@samp{bfd_default_set_arch_mach}. The corresponding field in the target 831ed0d50c3Schristosvector is named @samp{_bfd_set_arch_mach}. 832ed0d50c3Schristos 833ed0d50c3Schristos@item _set_section_contents 834ed0d50c3SchristosWrite out the contents of a section. This is called via 835ed0d50c3Schristos@samp{bfd_set_section_contents}. The corresponding field in the target 836ed0d50c3Schristosvector is named @samp{_bfd_set_section_contents}. 837ed0d50c3Schristos@end table 838ed0d50c3Schristos 839ed0d50c3Schristos@node BFD target vector link 840ed0d50c3Schristos@subsection Linker functions 841ed0d50c3Schristos@cindex @samp{BFD_JUMP_TABLE_LINK} 842ed0d50c3Schristos 843ed0d50c3SchristosThe @samp{BFD_JUMP_TABLE_LINK} macro is used for functions called by the 844ed0d50c3Schristoslinker. 845ed0d50c3Schristos 846ed0d50c3Schristos@table @samp 847ed0d50c3Schristos@item _sizeof_headers 848ed0d50c3SchristosReturn the size of the header information required for a BFD. This is 849ed0d50c3Schristosused to implement the @samp{SIZEOF_HEADERS} linker script function. It 850ed0d50c3Schristosis normally used to align the first section at an efficient position on 851ed0d50c3Schristosthe page. This is called via @samp{bfd_sizeof_headers}. The 852ed0d50c3Schristoscorresponding field in the target vector is named 853ed0d50c3Schristos@samp{_bfd_sizeof_headers}. 854ed0d50c3Schristos 855ed0d50c3Schristos@item _bfd_get_relocated_section_contents 856ed0d50c3SchristosRead the contents of a section and apply the relocation information. 857ed0d50c3SchristosThis handles both a final link and a relocatable link; in the latter 858ed0d50c3Schristoscase, it adjust the relocation information as well. This is called via 859ed0d50c3Schristos@samp{bfd_get_relocated_section_contents}. Most targets implement it by 860ed0d50c3Schristoscalling @samp{bfd_generic_get_relocated_section_contents}. 861ed0d50c3Schristos 862ed0d50c3Schristos@item _bfd_relax_section 863ed0d50c3SchristosTry to use relaxation to shrink the size of a section. This is called 864ed0d50c3Schristosby the linker when the @samp{-relax} option is used. This is called via 865ed0d50c3Schristos@samp{bfd_relax_section}. Most targets do not support any sort of 866ed0d50c3Schristosrelaxation. 867ed0d50c3Schristos 868ed0d50c3Schristos@item _bfd_link_hash_table_create 869ed0d50c3SchristosCreate the symbol hash table to use for the linker. This linker hook 870ed0d50c3Schristospermits the backend to control the size and information of the elements 871ed0d50c3Schristosin the linker symbol hash table. This is called via 872ed0d50c3Schristos@samp{bfd_link_hash_table_create}. 873ed0d50c3Schristos 874ed0d50c3Schristos@item _bfd_link_add_symbols 875ed0d50c3SchristosGiven an object file or an archive, add all symbols into the linker 876ed0d50c3Schristossymbol hash table. Use callbacks to the linker to include archive 877ed0d50c3Schristoselements in the link. This is called via @samp{bfd_link_add_symbols}. 878ed0d50c3Schristos 879ed0d50c3Schristos@item _bfd_final_link 880ed0d50c3SchristosFinish the linking process. The linker calls this hook after all of the 881ed0d50c3Schristosinput files have been read, when it is ready to finish the link and 882ed0d50c3Schristosgenerate the output file. This is called via @samp{bfd_final_link}. 883ed0d50c3Schristos 884ed0d50c3Schristos@item _bfd_link_split_section 885ed0d50c3SchristosI don't know what this is for. Nothing seems to call it. The only 886ed0d50c3Schristosnon-trivial definition is in @file{som.c}. 887ed0d50c3Schristos@end table 888ed0d50c3Schristos 889ed0d50c3Schristos@node BFD target vector dynamic 890ed0d50c3Schristos@subsection Dynamic linking information functions 891ed0d50c3Schristos@cindex @samp{BFD_JUMP_TABLE_DYNAMIC} 892ed0d50c3Schristos 893ed0d50c3SchristosThe @samp{BFD_JUMP_TABLE_DYNAMIC} macro is used for functions which read 894ed0d50c3Schristosdynamic linking information. 895ed0d50c3Schristos 896ed0d50c3Schristos@table @samp 897ed0d50c3Schristos@item _get_dynamic_symtab_upper_bound 898ed0d50c3SchristosReturn a sensible upper bound on the amount of memory which will be 899ed0d50c3Schristosrequired to read the dynamic symbol table. In practice most targets 900ed0d50c3Schristosreturn the amount of memory required to hold @samp{asymbol} pointers for 901ed0d50c3Schristosall the symbols plus a trailing @samp{NULL} entry, and store the actual 902ed0d50c3Schristossymbol information in BFD private data. This is called via 903ed0d50c3Schristos@samp{bfd_get_dynamic_symtab_upper_bound}. The corresponding field in 904ed0d50c3Schristosthe target vector is named @samp{_bfd_get_dynamic_symtab_upper_bound}. 905ed0d50c3Schristos 906ed0d50c3Schristos@item _canonicalize_dynamic_symtab 907ed0d50c3SchristosRead the dynamic symbol table. This is called via 908ed0d50c3Schristos@samp{bfd_canonicalize_dynamic_symtab}. The corresponding field in the 909ed0d50c3Schristostarget vector is named @samp{_bfd_canonicalize_dynamic_symtab}. 910ed0d50c3Schristos 911ed0d50c3Schristos@item _get_dynamic_reloc_upper_bound 912ed0d50c3SchristosReturn a sensible upper bound on the amount of memory which will be 913ed0d50c3Schristosrequired to read the dynamic relocations. In practice most targets 914ed0d50c3Schristosreturn the amount of memory required to hold @samp{arelent} pointers for 915ed0d50c3Schristosall the relocations plus a trailing @samp{NULL} entry, and store the 916ed0d50c3Schristosactual relocation information in BFD private data. This is called via 917ed0d50c3Schristos@samp{bfd_get_dynamic_reloc_upper_bound}. The corresponding field in 918ed0d50c3Schristosthe target vector is named @samp{_bfd_get_dynamic_reloc_upper_bound}. 919ed0d50c3Schristos 920ed0d50c3Schristos@item _canonicalize_dynamic_reloc 921ed0d50c3SchristosRead the dynamic relocations. This is called via 922ed0d50c3Schristos@samp{bfd_canonicalize_dynamic_reloc}. The corresponding field in the 923ed0d50c3Schristostarget vector is named @samp{_bfd_canonicalize_dynamic_reloc}. 924ed0d50c3Schristos@end table 925ed0d50c3Schristos 926ed0d50c3Schristos@node BFD generated files 927ed0d50c3Schristos@section BFD generated files 928ed0d50c3Schristos@cindex generated files in bfd 929ed0d50c3Schristos@cindex bfd generated files 930ed0d50c3Schristos 931ed0d50c3SchristosBFD contains several automatically generated files. This section 932ed0d50c3Schristosdescribes them. Some files are created at configure time, when you 933ed0d50c3Schristosconfigure BFD. Some files are created at make time, when you build 934ed0d50c3SchristosBFD. Some files are automatically rebuilt at make time, but only if 935ed0d50c3Schristosyou configure with the @samp{--enable-maintainer-mode} option. Some 936ed0d50c3Schristosfiles live in the object directory---the directory from which you run 937ed0d50c3Schristosconfigure---and some live in the source directory. All files that live 938ed0d50c3Schristosin the source directory are checked into the git repository. 939ed0d50c3Schristos 940ed0d50c3Schristos@table @file 941ed0d50c3Schristos@item bfd.h 942ed0d50c3Schristos@cindex @file{bfd.h} 943ed0d50c3Schristos@cindex @file{bfd-in3.h} 944ed0d50c3SchristosLives in the object directory. Created at make time from 945ed0d50c3Schristos@file{bfd-in2.h} via @file{bfd-in3.h}. @file{bfd-in3.h} is created at 946ed0d50c3Schristosconfigure time from @file{bfd-in2.h}. There are automatic dependencies 947ed0d50c3Schristosto rebuild @file{bfd-in3.h} and hence @file{bfd.h} if @file{bfd-in2.h} 948ed0d50c3Schristoschanges, so you can normally ignore @file{bfd-in3.h}, and just think 949ed0d50c3Schristosabout @file{bfd-in2.h} and @file{bfd.h}. 950ed0d50c3Schristos 951ed0d50c3Schristos@file{bfd.h} is built by replacing a few strings in @file{bfd-in2.h}. 952ed0d50c3SchristosTo see them, search for @samp{@@} in @file{bfd-in2.h}. They mainly 953ed0d50c3Schristoscontrol whether BFD is built for a 32 bit target or a 64 bit target. 954ed0d50c3Schristos 955ed0d50c3Schristos@item bfd-in2.h 956ed0d50c3Schristos@cindex @file{bfd-in2.h} 957ed0d50c3SchristosLives in the source directory. Created from @file{bfd-in.h} and several 958ed0d50c3Schristosother BFD source files. If you configure with the 959ed0d50c3Schristos@samp{--enable-maintainer-mode} option, @file{bfd-in2.h} is rebuilt 960ed0d50c3Schristosautomatically when a source file changes. 961ed0d50c3Schristos 962ed0d50c3Schristos@item elf32-target.h 963ed0d50c3Schristos@itemx elf64-target.h 964ed0d50c3Schristos@cindex @file{elf32-target.h} 965ed0d50c3Schristos@cindex @file{elf64-target.h} 966ed0d50c3SchristosLive in the object directory. Created from @file{elfxx-target.h}. 967ed0d50c3SchristosThese files are versions of @file{elfxx-target.h} customized for either 968ed0d50c3Schristosa 32 bit ELF target or a 64 bit ELF target. 969ed0d50c3Schristos 970ed0d50c3Schristos@item libbfd.h 971ed0d50c3Schristos@cindex @file{libbfd.h} 972ed0d50c3SchristosLives in the source directory. Created from @file{libbfd-in.h} and 973ed0d50c3Schristosseveral other BFD source files. If you configure with the 974ed0d50c3Schristos@samp{--enable-maintainer-mode} option, @file{libbfd.h} is rebuilt 975ed0d50c3Schristosautomatically when a source file changes. 976ed0d50c3Schristos 977ed0d50c3Schristos@item libcoff.h 978ed0d50c3Schristos@cindex @file{libcoff.h} 979ed0d50c3SchristosLives in the source directory. Created from @file{libcoff-in.h} and 980ed0d50c3Schristos@file{coffcode.h}. If you configure with the 981ed0d50c3Schristos@samp{--enable-maintainer-mode} option, @file{libcoff.h} is rebuilt 982ed0d50c3Schristosautomatically when a source file changes. 983ed0d50c3Schristos 984ed0d50c3Schristos@item targmatch.h 985ed0d50c3Schristos@cindex @file{targmatch.h} 986ed0d50c3SchristosLives in the object directory. Created at make time from 987ed0d50c3Schristos@file{config.bfd}. This file is used to map configuration triplets into 988ed0d50c3SchristosBFD target vector variable names at run time. 989ed0d50c3Schristos@end table 990ed0d50c3Schristos 991ed0d50c3Schristos@node BFD multiple compilations 992ed0d50c3Schristos@section Files compiled multiple times in BFD 993ed0d50c3SchristosSeveral files in BFD are compiled multiple times. By this I mean that 994ed0d50c3Schristosthere are header files which contain function definitions. These header 995ed0d50c3Schristosfiles are included by other files, and thus the functions are compiled 996ed0d50c3Schristosonce per file which includes them. 997ed0d50c3Schristos 998ed0d50c3SchristosPreprocessor macros are used to control the compilation, so that each 999ed0d50c3Schristostime the files are compiled the resulting functions are slightly 1000ed0d50c3Schristosdifferent. Naturally, if they weren't different, there would be no 1001ed0d50c3Schristosreason to compile them multiple times. 1002ed0d50c3Schristos 1003ed0d50c3SchristosThis is a not a particularly good programming technique, and future BFD 1004ed0d50c3Schristoswork should avoid it. 1005ed0d50c3Schristos 1006ed0d50c3Schristos@itemize @bullet 1007ed0d50c3Schristos@item 1008ed0d50c3SchristosSince this technique is rarely used, even experienced C programmers find 1009ed0d50c3Schristosit confusing. 1010ed0d50c3Schristos 1011ed0d50c3Schristos@item 1012ed0d50c3SchristosIt is difficult to debug programs which use BFD, since there is no way 1013ed0d50c3Schristosto describe which version of a particular function you are looking at. 1014ed0d50c3Schristos 1015ed0d50c3Schristos@item 1016ed0d50c3SchristosPrograms which use BFD wind up incorporating two or more slightly 1017ed0d50c3Schristosdifferent versions of the same function, which wastes space in the 1018ed0d50c3Schristosexecutable. 1019ed0d50c3Schristos 1020ed0d50c3Schristos@item 1021ed0d50c3SchristosThis technique is never required nor is it especially efficient. It is 1022ed0d50c3Schristosalways possible to use statically initialized structures holding 1023ed0d50c3Schristosfunction pointers and magic constants instead. 1024ed0d50c3Schristos@end itemize 1025ed0d50c3Schristos 1026ed0d50c3SchristosThe following is a list of the files which are compiled multiple times. 1027ed0d50c3Schristos 1028ed0d50c3Schristos@table @file 1029ed0d50c3Schristos@item aout-target.h 1030ed0d50c3Schristos@cindex @file{aout-target.h} 1031ed0d50c3SchristosDescribes a few functions and the target vector for a.out targets. This 1032ed0d50c3Schristosis used by individual a.out targets with different definitions of 1033ed0d50c3Schristos@samp{N_TXTADDR} and similar a.out macros. 1034ed0d50c3Schristos 1035ed0d50c3Schristos@item aoutf1.h 1036ed0d50c3Schristos@cindex @file{aoutf1.h} 1037ed0d50c3SchristosImplements standard SunOS a.out files. In principle it supports 64 bit 1038ed0d50c3Schristosa.out targets based on the preprocessor macro @samp{ARCH_SIZE}, but 1039ed0d50c3Schristossince all known a.out targets are 32 bits, this code may or may not 1040ed0d50c3Schristoswork. This file is only included by a few other files, and it is 1041ed0d50c3Schristosdifficult to justify its existence. 1042ed0d50c3Schristos 1043ed0d50c3Schristos@item aoutx.h 1044ed0d50c3Schristos@cindex @file{aoutx.h} 1045ed0d50c3SchristosImplements basic a.out support routines. This file can be compiled for 1046ed0d50c3Schristoseither 32 or 64 bit support. Since all known a.out targets are 32 bits, 1047ed0d50c3Schristosthe 64 bit support may or may not work. I believe the original 1048ed0d50c3Schristosintention was that this file would only be included by @samp{aout32.c} 1049ed0d50c3Schristosand @samp{aout64.c}, and that other a.out targets would simply refer to 1050ed0d50c3Schristosthe functions it defined. Unfortunately, some other a.out targets 1051ed0d50c3Schristosstarted including it directly, leading to a somewhat confused state of 1052ed0d50c3Schristosaffairs. 1053ed0d50c3Schristos 1054ed0d50c3Schristos@item coffcode.h 1055ed0d50c3Schristos@cindex @file{coffcode.h} 1056ed0d50c3SchristosImplements basic COFF support routines. This file is included by every 1057ed0d50c3SchristosCOFF target. It implements code which handles COFF magic numbers as 1058ed0d50c3Schristoswell as various hook functions called by the generic COFF functions in 1059ed0d50c3Schristos@file{coffgen.c}. This file is controlled by a number of different 1060ed0d50c3Schristosmacros, and more are added regularly. 1061ed0d50c3Schristos 1062ed0d50c3Schristos@item coffswap.h 1063ed0d50c3Schristos@cindex @file{coffswap.h} 1064ed0d50c3SchristosImplements COFF swapping routines. This file is included by 1065ed0d50c3Schristos@file{coffcode.h}, and thus by every COFF target. It implements the 1066ed0d50c3Schristosroutines which swap COFF structures between internal and external 1067ed0d50c3Schristosformat. The main control for this file is the external structure 1068ed0d50c3Schristosdefinitions in the files in the @file{include/coff} directory. A COFF 1069ed0d50c3Schristostarget file will include one of those files before including 1070ed0d50c3Schristos@file{coffcode.h} and thus @file{coffswap.h}. There are a few other 1071ed0d50c3Schristosmacros which affect @file{coffswap.h} as well, mostly describing whether 1072ed0d50c3Schristoscertain fields are present in the external structures. 1073ed0d50c3Schristos 1074ed0d50c3Schristos@item ecoffswap.h 1075ed0d50c3Schristos@cindex @file{ecoffswap.h} 1076ed0d50c3SchristosImplements ECOFF swapping routines. This is like @file{coffswap.h}, but 1077ed0d50c3Schristosfor ECOFF. It is included by the ECOFF target files (of which there are 1078ed0d50c3Schristosonly two). The control is the preprocessor macro @samp{ECOFF_32} or 1079ed0d50c3Schristos@samp{ECOFF_64}. 1080ed0d50c3Schristos 1081ed0d50c3Schristos@item elfcode.h 1082ed0d50c3Schristos@cindex @file{elfcode.h} 1083ed0d50c3SchristosImplements ELF functions that use external structure definitions. This 1084ed0d50c3Schristosfile is included by two other files: @file{elf32.c} and @file{elf64.c}. 1085ed0d50c3SchristosIt is controlled by the @samp{ARCH_SIZE} macro which is defined to be 1086ed0d50c3Schristos@samp{32} or @samp{64} before including it. The @samp{NAME} macro is 1087ed0d50c3Schristosused internally to give the functions different names for the two target 1088ed0d50c3Schristossizes. 1089ed0d50c3Schristos 1090ed0d50c3Schristos@item elfcore.h 1091ed0d50c3Schristos@cindex @file{elfcore.h} 1092ed0d50c3SchristosLike @file{elfcode.h}, but for functions that are specific to ELF core 1093ed0d50c3Schristosfiles. This is included only by @file{elfcode.h}. 1094ed0d50c3Schristos 1095ed0d50c3Schristos@item elfxx-target.h 1096ed0d50c3Schristos@cindex @file{elfxx-target.h} 1097ed0d50c3SchristosThis file is the source for the generated files @file{elf32-target.h} 1098ed0d50c3Schristosand @file{elf64-target.h}, one of which is included by every ELF target. 1099ed0d50c3SchristosIt defines the ELF target vector. 1100ed0d50c3Schristos 1101ed0d50c3Schristos@item netbsd.h 1102ed0d50c3Schristos@cindex @file{netbsd.h} 110306324dcfSchristosUsed by all netbsd aout targets. Several other files include it. 1104ed0d50c3Schristos 1105ed0d50c3Schristos@item peicode.h 1106ed0d50c3Schristos@cindex @file{peicode.h} 1107ed0d50c3SchristosProvides swapping routines and other hooks for PE targets. 1108ed0d50c3Schristos@file{coffcode.h} will include this rather than @file{coffswap.h} for a 1109ed0d50c3SchristosPE target. This defines PE specific versions of the COFF swapping 1110ed0d50c3Schristosroutines, and also defines some macros which control @file{coffcode.h} 1111ed0d50c3Schristositself. 1112ed0d50c3Schristos@end table 1113ed0d50c3Schristos 1114ed0d50c3Schristos@node BFD relocation handling 1115ed0d50c3Schristos@section BFD relocation handling 1116ed0d50c3Schristos@cindex bfd relocation handling 1117ed0d50c3Schristos@cindex relocations in bfd 1118ed0d50c3Schristos 1119ed0d50c3SchristosThe handling of relocations is one of the more confusing aspects of BFD. 1120ed0d50c3SchristosRelocation handling has been implemented in various different ways, all 1121ed0d50c3Schristossomewhat incompatible, none perfect. 1122ed0d50c3Schristos 1123ed0d50c3Schristos@menu 1124ed0d50c3Schristos* BFD relocation concepts:: BFD relocation concepts 1125ed0d50c3Schristos* BFD relocation functions:: BFD relocation functions 1126ed0d50c3Schristos* BFD relocation codes:: BFD relocation codes 1127ed0d50c3Schristos* BFD relocation future:: BFD relocation future 1128ed0d50c3Schristos@end menu 1129ed0d50c3Schristos 1130ed0d50c3Schristos@node BFD relocation concepts 1131ed0d50c3Schristos@subsection BFD relocation concepts 1132ed0d50c3Schristos 1133ed0d50c3SchristosA relocation is an action which the linker must take when linking. It 1134ed0d50c3Schristosdescribes a change to the contents of a section. The change is normally 1135ed0d50c3Schristosbased on the final value of one or more symbols. Relocations are 1136ed0d50c3Schristoscreated by the assembler when it creates an object file. 1137ed0d50c3Schristos 1138ed0d50c3SchristosMost relocations are simple. A typical simple relocation is to set 32 1139ed0d50c3Schristosbits at a given offset in a section to the value of a symbol. This type 1140ed0d50c3Schristosof relocation would be generated for code like @code{int *p = &i;} where 1141ed0d50c3Schristos@samp{p} and @samp{i} are global variables. A relocation for the symbol 1142ed0d50c3Schristos@samp{i} would be generated such that the linker would initialize the 1143ed0d50c3Schristosarea of memory which holds the value of @samp{p} to the value of the 1144ed0d50c3Schristossymbol @samp{i}. 1145ed0d50c3Schristos 1146ed0d50c3SchristosSlightly more complex relocations may include an addend, which is a 1147ed0d50c3Schristosconstant to add to the symbol value before using it. In some cases a 1148ed0d50c3Schristosrelocation will require adding the symbol value to the existing contents 1149ed0d50c3Schristosof the section in the object file. In others the relocation will simply 1150ed0d50c3Schristosreplace the contents of the section with the symbol value. Some 1151ed0d50c3Schristosrelocations are PC relative, so that the value to be stored in the 1152ed0d50c3Schristossection is the difference between the value of a symbol and the final 1153ed0d50c3Schristosaddress of the section contents. 1154ed0d50c3Schristos 1155ed0d50c3SchristosIn general, relocations can be arbitrarily complex. For example, 1156ed0d50c3Schristosrelocations used in dynamic linking systems often require the linker to 1157ed0d50c3Schristosallocate space in a different section and use the offset within that 115806324dcfSchristossection as the value to store. 1159ed0d50c3Schristos 1160ed0d50c3SchristosWhen doing a relocatable link, the linker may or may not have to do 1161ed0d50c3Schristosanything with a relocation, depending upon the definition of the 1162ed0d50c3Schristosrelocation. Simple relocations generally do not require any special 1163ed0d50c3Schristosaction. 1164ed0d50c3Schristos 1165ed0d50c3Schristos@node BFD relocation functions 1166ed0d50c3Schristos@subsection BFD relocation functions 1167ed0d50c3Schristos 1168ed0d50c3SchristosIn BFD, each section has an array of @samp{arelent} structures. Each 1169ed0d50c3Schristosstructure has a pointer to a symbol, an address within the section, an 1170ed0d50c3Schristosaddend, and a pointer to a @samp{reloc_howto_struct} structure. The 1171ed0d50c3Schristoshowto structure has a bunch of fields describing the reloc, including a 1172ed0d50c3Schristostype field. The type field is specific to the object file format 1173ed0d50c3Schristosbackend; none of the generic code in BFD examines it. 1174ed0d50c3Schristos 1175ed0d50c3SchristosOriginally, the function @samp{bfd_perform_relocation} was supposed to 1176ed0d50c3Schristoshandle all relocations. In theory, many relocations would be simple 1177ed0d50c3Schristosenough to be described by the fields in the howto structure. For those 1178ed0d50c3Schristosthat weren't, the howto structure included a @samp{special_function} 1179ed0d50c3Schristosfield to use as an escape. 1180ed0d50c3Schristos 1181ed0d50c3SchristosWhile this seems plausible, a look at @samp{bfd_perform_relocation} 1182ed0d50c3Schristosshows that it failed. The function has odd special cases. Some of the 1183ed0d50c3Schristosfields in the howto structure, such as @samp{pcrel_offset}, were not 1184ed0d50c3Schristosadequately documented. 1185ed0d50c3Schristos 1186ed0d50c3SchristosThe linker uses @samp{bfd_perform_relocation} to do all relocations when 1187ed0d50c3Schristosthe input and output file have different formats (e.g., when generating 1188ed0d50c3SchristosS-records). The generic linker code, which is used by all targets which 1189ed0d50c3Schristosdo not define their own special purpose linker, uses 1190ed0d50c3Schristos@samp{bfd_get_relocated_section_contents}, which for most targets turns 1191ed0d50c3Schristosinto a call to @samp{bfd_generic_get_relocated_section_contents}, which 1192ed0d50c3Schristoscalls @samp{bfd_perform_relocation}. So @samp{bfd_perform_relocation} 1193ed0d50c3Schristosis still widely used, which makes it difficult to change, since it is 1194ed0d50c3Schristosdifficult to test all possible cases. 1195ed0d50c3Schristos 1196ed0d50c3SchristosThe assembler used @samp{bfd_perform_relocation} for a while. This 1197ed0d50c3Schristosturned out to be the wrong thing to do, since 1198ed0d50c3Schristos@samp{bfd_perform_relocation} was written to handle relocations on an 1199ed0d50c3Schristosexisting object file, while the assembler needed to create relocations 1200ed0d50c3Schristosin a new object file. The assembler was changed to use the new function 1201ed0d50c3Schristos@samp{bfd_install_relocation} instead, and @samp{bfd_install_relocation} 1202ed0d50c3Schristoswas created as a copy of @samp{bfd_perform_relocation}. 1203ed0d50c3Schristos 1204ed0d50c3SchristosUnfortunately, the work did not progress any farther, so 1205ed0d50c3Schristos@samp{bfd_install_relocation} remains a simple copy of 1206ed0d50c3Schristos@samp{bfd_perform_relocation}, with all the odd special cases and 1207ed0d50c3Schristosconfusing code. This again is difficult to change, because again any 1208ed0d50c3Schristoschange can affect any assembler target, and so is difficult to test. 1209ed0d50c3Schristos 1210ed0d50c3SchristosThe new linker, when using the same object file format for all input 1211ed0d50c3Schristosfiles and the output file, does not convert relocations into 1212ed0d50c3Schristos@samp{arelent} structures, so it can not use 1213ed0d50c3Schristos@samp{bfd_perform_relocation} at all. Instead, users of the new linker 1214ed0d50c3Schristosare expected to write a @samp{relocate_section} function which will 1215ed0d50c3Schristoshandle relocations in a target specific fashion. 1216ed0d50c3Schristos 1217ed0d50c3SchristosThere are two helper functions for target specific relocation: 1218ed0d50c3Schristos@samp{_bfd_final_link_relocate} and @samp{_bfd_relocate_contents}. 1219ed0d50c3SchristosThese functions use a howto structure, but they @emph{do not} use the 1220ed0d50c3Schristos@samp{special_function} field. Since the functions are normally called 1221ed0d50c3Schristosfrom target specific code, the @samp{special_function} field adds 1222ed0d50c3Schristoslittle; any relocations which require special handling can be handled 1223ed0d50c3Schristoswithout calling those functions. 1224ed0d50c3Schristos 1225ed0d50c3SchristosSo, if you want to add a new target, or add a new relocation to an 1226ed0d50c3Schristosexisting target, you need to do the following: 1227ed0d50c3Schristos 1228ed0d50c3Schristos@itemize @bullet 1229ed0d50c3Schristos@item 1230ed0d50c3SchristosMake sure you clearly understand what the contents of the section should 1231ed0d50c3Schristoslook like after assembly, after a relocatable link, and after a final 1232ed0d50c3Schristoslink. Make sure you clearly understand the operations the linker must 1233ed0d50c3Schristosperform during a relocatable link and during a final link. 1234ed0d50c3Schristos 1235ed0d50c3Schristos@item 1236ed0d50c3SchristosWrite a howto structure for the relocation. The howto structure is 1237ed0d50c3Schristosflexible enough to represent any relocation which should be handled by 1238ed0d50c3Schristossetting a contiguous bitfield in the destination to the value of a 1239ed0d50c3Schristossymbol, possibly with an addend, possibly adding the symbol value to the 1240ed0d50c3Schristosvalue already present in the destination. 1241ed0d50c3Schristos 1242ed0d50c3Schristos@item 1243ed0d50c3SchristosChange the assembler to generate your relocation. The assembler will 1244ed0d50c3Schristoscall @samp{bfd_install_relocation}, so your howto structure has to be 1245ed0d50c3Schristosable to handle that. You may need to set the @samp{special_function} 1246ed0d50c3Schristosfield to handle assembly correctly. Be careful to ensure that any code 1247ed0d50c3Schristosyou write to handle the assembler will also work correctly when doing a 1248ed0d50c3Schristosrelocatable link. For example, see @samp{bfd_elf_generic_reloc}. 1249ed0d50c3Schristos 1250ed0d50c3Schristos@item 1251ed0d50c3SchristosTest the assembler. Consider the cases of relocation against an 1252ed0d50c3Schristosundefined symbol, a common symbol, a symbol defined in the object file 1253ed0d50c3Schristosin the same section, and a symbol defined in the object file in a 1254ed0d50c3Schristosdifferent section. These cases may not all be applicable for your 1255ed0d50c3Schristosreloc. 1256ed0d50c3Schristos 1257ed0d50c3Schristos@item 1258ed0d50c3SchristosIf your target uses the new linker, which is recommended, add any 1259ed0d50c3Schristosrequired handling to the target specific relocation function. In simple 1260ed0d50c3Schristoscases this will just involve a call to @samp{_bfd_final_link_relocate} 1261ed0d50c3Schristosor @samp{_bfd_relocate_contents}, depending upon the definition of the 1262ed0d50c3Schristosrelocation and whether the link is relocatable or not. 1263ed0d50c3Schristos 1264ed0d50c3Schristos@item 1265ed0d50c3SchristosTest the linker. Test the case of a final link. If the relocation can 1266ed0d50c3Schristosoverflow, use a linker script to force an overflow and make sure the 1267ed0d50c3Schristoserror is reported correctly. Test a relocatable link, whether the 1268ed0d50c3Schristossymbol is defined or undefined in the relocatable output. For both the 1269ed0d50c3Schristosfinal and relocatable link, test the case when the symbol is a common 1270ed0d50c3Schristossymbol, when the symbol looked like a common symbol but became a defined 1271ed0d50c3Schristossymbol, when the symbol is defined in a different object file, and when 1272ed0d50c3Schristosthe symbol is defined in the same object file. 1273ed0d50c3Schristos 1274ed0d50c3Schristos@item 1275ed0d50c3SchristosIn order for linking to another object file format, such as S-records, 1276ed0d50c3Schristosto work correctly, @samp{bfd_perform_relocation} has to do the right 1277ed0d50c3Schristosthing for the relocation. You may need to set the 1278ed0d50c3Schristos@samp{special_function} field to handle this correctly. Test this by 1279ed0d50c3Schristosdoing a link in which the output object file format is S-records. 1280ed0d50c3Schristos 1281ed0d50c3Schristos@item 1282ed0d50c3SchristosUsing the linker to generate relocatable output in a different object 1283ed0d50c3Schristosfile format is impossible in the general case, so you generally don't 1284ed0d50c3Schristoshave to worry about that. The GNU linker makes sure to stop that from 1285ed0d50c3Schristoshappening when an input file in a different format has relocations. 1286ed0d50c3Schristos 1287ed0d50c3SchristosLinking input files of different object file formats together is quite 1288ed0d50c3Schristosunusual, but if you're really dedicated you may want to consider testing 1289ed0d50c3Schristosthis case, both when the output object file format is the same as your 1290ed0d50c3Schristosformat, and when it is different. 1291ed0d50c3Schristos@end itemize 1292ed0d50c3Schristos 1293ed0d50c3Schristos@node BFD relocation codes 1294ed0d50c3Schristos@subsection BFD relocation codes 1295ed0d50c3Schristos 1296ed0d50c3SchristosBFD has another way of describing relocations besides the howto 1297ed0d50c3Schristosstructures described above: the enum @samp{bfd_reloc_code_real_type}. 1298ed0d50c3Schristos 1299ed0d50c3SchristosEvery known relocation type can be described as a value in this 1300ed0d50c3Schristosenumeration. The enumeration contains many target specific relocations, 1301ed0d50c3Schristosbut where two or more targets have the same relocation, a single code is 1302ed0d50c3Schristosused. For example, the single value @samp{BFD_RELOC_32} is used for all 1303ed0d50c3Schristossimple 32 bit relocation types. 1304ed0d50c3Schristos 1305ed0d50c3SchristosThe main purpose of this relocation code is to give the assembler some 1306ed0d50c3Schristosmechanism to create @samp{arelent} structures. In order for the 1307ed0d50c3Schristosassembler to create an @samp{arelent} structure, it has to be able to 1308ed0d50c3Schristosobtain a howto structure. The function @samp{bfd_reloc_type_lookup}, 1309ed0d50c3Schristoswhich simply calls the target vector entry point 1310ed0d50c3Schristos@samp{reloc_type_lookup}, takes a relocation code and returns a howto 1311ed0d50c3Schristosstructure. 1312ed0d50c3Schristos 1313ed0d50c3SchristosThe function @samp{bfd_get_reloc_code_name} returns the name of a 1314ed0d50c3Schristosrelocation code. This is mainly used in error messages. 1315ed0d50c3Schristos 1316ed0d50c3SchristosUsing both howto structures and relocation codes can be somewhat 1317ed0d50c3Schristosconfusing. There are many processor specific relocation codes. 1318ed0d50c3SchristosHowever, the relocation is only fully defined by the howto structure. 1319ed0d50c3SchristosThe same relocation code will map to different howto structures in 1320ed0d50c3Schristosdifferent object file formats. For example, the addend handling may be 1321ed0d50c3Schristosdifferent. 1322ed0d50c3Schristos 1323ed0d50c3SchristosMost of the relocation codes are not really general. The assembler can 1324ed0d50c3Schristosnot use them without already understanding what sorts of relocations can 1325ed0d50c3Schristosbe used for a particular target. It might be possible to replace the 1326ed0d50c3Schristosrelocation codes with something simpler. 1327ed0d50c3Schristos 1328ed0d50c3Schristos@node BFD relocation future 1329ed0d50c3Schristos@subsection BFD relocation future 1330ed0d50c3Schristos 1331ed0d50c3SchristosClearly the current BFD relocation support is in bad shape. A 1332ed0d50c3Schristoswholescale rewrite would be very difficult, because it would require 1333ed0d50c3Schristosthorough testing of every BFD target. So some sort of incremental 1334ed0d50c3Schristoschange is required. 1335ed0d50c3Schristos 1336ed0d50c3SchristosMy vague thoughts on this would involve defining a new, clearly defined, 1337ed0d50c3Schristoshowto structure. Some mechanism would be used to determine which type 1338ed0d50c3Schristosof howto structure was being used by a particular format. 1339ed0d50c3Schristos 1340ed0d50c3SchristosThe new howto structure would clearly define the relocation behaviour in 1341ed0d50c3Schristosthe case of an assembly, a relocatable link, and a final link. At 1342ed0d50c3Schristosleast one special function would be defined as an escape, and it might 1343ed0d50c3Schristosmake sense to define more. 1344ed0d50c3Schristos 1345ed0d50c3SchristosOne or more generic functions similar to @samp{bfd_perform_relocation} 1346ed0d50c3Schristoswould be written to handle the new howto structure. 1347ed0d50c3Schristos 1348ed0d50c3SchristosThis should make it possible to write a generic version of the relocate 1349ed0d50c3Schristossection functions used by the new linker. The target specific code 1350ed0d50c3Schristoswould provide some mechanism (a function pointer or an initial 1351ed0d50c3Schristosconversion) to convert target specific relocations into howto 1352ed0d50c3Schristosstructures. 1353ed0d50c3Schristos 1354ed0d50c3SchristosIdeally it would be possible to use this generic relocate section 1355ed0d50c3Schristosfunction for the generic linker as well. That is, it would replace the 1356ed0d50c3Schristos@samp{bfd_generic_get_relocated_section_contents} function which is 1357ed0d50c3Schristoscurrently normally used. 1358ed0d50c3Schristos 1359ed0d50c3SchristosFor the special case of ELF dynamic linking, more consideration needs to 1360ed0d50c3Schristosbe given to writing ELF specific but ELF target generic code to handle 1361ed0d50c3Schristosspecial relocation types such as GOT and PLT. 1362ed0d50c3Schristos 1363ed0d50c3Schristos@node BFD ELF support 1364ed0d50c3Schristos@section BFD ELF support 1365ed0d50c3Schristos@cindex elf support in bfd 1366ed0d50c3Schristos@cindex bfd elf support 1367ed0d50c3Schristos 1368ed0d50c3SchristosThe ELF object file format is defined in two parts: a generic ABI and a 1369ed0d50c3Schristosprocessor specific supplement. The ELF support in BFD is split in a 1370ed0d50c3Schristossimilar fashion. The processor specific support is largely kept within 1371ed0d50c3Schristosa single file. The generic support is provided by several other files. 1372ed0d50c3SchristosThe processor specific support provides a set of function pointers and 1373ed0d50c3Schristosconstants used by the generic support. 1374ed0d50c3Schristos 1375ed0d50c3Schristos@menu 1376ed0d50c3Schristos* BFD ELF sections and segments:: ELF sections and segments 1377ed0d50c3Schristos* BFD ELF generic support:: BFD ELF generic support 1378ed0d50c3Schristos* BFD ELF processor specific support:: BFD ELF processor specific support 1379ed0d50c3Schristos* BFD ELF core files:: BFD ELF core files 1380ed0d50c3Schristos* BFD ELF future:: BFD ELF future 1381ed0d50c3Schristos@end menu 1382ed0d50c3Schristos 1383ed0d50c3Schristos@node BFD ELF sections and segments 1384ed0d50c3Schristos@subsection ELF sections and segments 1385ed0d50c3Schristos 1386ed0d50c3SchristosThe ELF ABI permits a file to have either sections or segments or both. 1387ed0d50c3SchristosRelocatable object files conventionally have only sections. 1388ed0d50c3SchristosExecutables conventionally have both. Core files conventionally have 1389ed0d50c3Schristosonly program segments. 1390ed0d50c3Schristos 1391ed0d50c3SchristosELF sections are similar to sections in other object file formats: they 1392ed0d50c3Schristoshave a name, a VMA, file contents, flags, and other miscellaneous 1393ed0d50c3Schristosinformation. ELF relocations are stored in sections of a particular 1394ed0d50c3Schristostype; BFD automatically converts these sections into internal relocation 1395ed0d50c3Schristosinformation. 1396ed0d50c3Schristos 1397ed0d50c3SchristosELF program segments are intended for fast interpretation by a system 1398ed0d50c3Schristosloader. They have a type, a VMA, an LMA, file contents, and a couple of 1399ed0d50c3Schristosother fields. When an ELF executable is run on a Unix system, the 1400ed0d50c3Schristossystem loader will examine the program segments to decide how to load 1401ed0d50c3Schristosit. The loader will ignore the section information. Loadable program 1402ed0d50c3Schristossegments (type @samp{PT_LOAD}) are directly loaded into memory. Other 1403ed0d50c3Schristosprogram segments are interpreted by the loader, and generally provide 1404ed0d50c3Schristosdynamic linking information. 1405ed0d50c3Schristos 1406ed0d50c3SchristosWhen an ELF file has both program segments and sections, an ELF program 1407ed0d50c3Schristossegment may encompass one or more ELF sections, in the sense that the 1408ed0d50c3Schristosportion of the file which corresponds to the program segment may include 1409ed0d50c3Schristosthe portions of the file corresponding to one or more sections. When 1410ed0d50c3Schristosthere is more than one section in a loadable program segment, the 1411ed0d50c3Schristosrelative positions of the section contents in the file must correspond 1412ed0d50c3Schristosto the relative positions they should hold when the program segment is 1413ed0d50c3Schristosloaded. This requirement should be obvious if you consider that the 1414ed0d50c3Schristossystem loader will load an entire program segment at a time. 1415ed0d50c3Schristos 1416ed0d50c3SchristosOn a system which supports dynamic paging, such as any native Unix 1417ed0d50c3Schristossystem, the contents of a loadable program segment must be at the same 1418ed0d50c3Schristosoffset in the file as in memory, modulo the memory page size used on the 1419ed0d50c3Schristossystem. This is because the system loader will map the file into memory 1420ed0d50c3Schristosstarting at the start of a page. The system loader can easily remap 1421ed0d50c3Schristosentire pages to the correct load address. However, if the contents of 1422ed0d50c3Schristosthe file were not correctly aligned within the page, the system loader 1423ed0d50c3Schristoswould have to shift the contents around within the page, which is too 1424ed0d50c3Schristosexpensive. For example, if the LMA of a loadable program segment is 1425ed0d50c3Schristos@samp{0x40080} and the page size is @samp{0x1000}, then the position of 1426ed0d50c3Schristosthe segment contents within the file must equal @samp{0x80} modulo 1427ed0d50c3Schristos@samp{0x1000}. 1428ed0d50c3Schristos 1429ed0d50c3SchristosBFD has only a single set of sections. It does not provide any generic 1430ed0d50c3Schristosway to examine both sections and segments. When BFD is used to open an 1431ed0d50c3Schristosobject file or executable, the BFD sections will represent ELF sections. 1432ed0d50c3SchristosWhen BFD is used to open a core file, the BFD sections will represent 1433ed0d50c3SchristosELF program segments. 1434ed0d50c3Schristos 1435ed0d50c3SchristosWhen BFD is used to examine an object file or executable, any program 1436ed0d50c3Schristossegments will be read to set the LMA of the sections. This is because 1437ed0d50c3SchristosELF sections only have a VMA, while ELF program segments have both a VMA 1438ed0d50c3Schristosand an LMA. Any program segments will be copied by the 1439ed0d50c3Schristos@samp{copy_private} entry points. They will be printed by the 1440ed0d50c3Schristos@samp{print_private} entry point. Otherwise, the program segments are 1441ed0d50c3Schristosignored. In particular, programs which use BFD currently have no direct 1442ed0d50c3Schristosaccess to the program segments. 1443ed0d50c3Schristos 1444ed0d50c3SchristosWhen BFD is used to create an executable, the program segments will be 1445ed0d50c3Schristoscreated automatically based on the section information. This is done in 1446ed0d50c3Schristosthe function @samp{assign_file_positions_for_segments} in @file{elf.c}. 1447ed0d50c3SchristosThis function has been tweaked many times, and probably still has 1448ed0d50c3Schristosproblems that arise in particular cases. 1449ed0d50c3Schristos 1450ed0d50c3SchristosThere is a hook which may be used to explicitly define the program 1451ed0d50c3Schristossegments when creating an executable: the @samp{bfd_record_phdr} 1452ed0d50c3Schristosfunction in @file{bfd.c}. If this function is called, BFD will not 1453ed0d50c3Schristoscreate program segments itself, but will only create the program 1454ed0d50c3Schristossegments specified by the caller. The linker uses this function to 1455ed0d50c3Schristosimplement the @samp{PHDRS} linker script command. 1456ed0d50c3Schristos 1457ed0d50c3Schristos@node BFD ELF generic support 1458ed0d50c3Schristos@subsection BFD ELF generic support 1459ed0d50c3Schristos 1460ed0d50c3SchristosIn general, functions which do not read external data from the ELF file 1461ed0d50c3Schristosare found in @file{elf.c}. They operate on the internal forms of the 1462ed0d50c3SchristosELF structures, which are defined in @file{include/elf/internal.h}. The 1463ed0d50c3Schristosinternal structures are defined in terms of @samp{bfd_vma}, and so may 1464ed0d50c3Schristosbe used for both 32 bit and 64 bit ELF targets. 1465ed0d50c3Schristos 1466ed0d50c3SchristosThe file @file{elfcode.h} contains functions which operate on the 1467ed0d50c3Schristosexternal data. @file{elfcode.h} is compiled twice, once via 1468ed0d50c3Schristos@file{elf32.c} with @samp{ARCH_SIZE} defined as @samp{32}, and once via 1469ed0d50c3Schristos@file{elf64.c} with @samp{ARCH_SIZE} defined as @samp{64}. 1470ed0d50c3Schristos@file{elfcode.h} includes functions to swap the ELF structures in and 1471ed0d50c3Schristosout of external form, as well as a few more complex functions. 1472ed0d50c3Schristos 1473ed0d50c3SchristosLinker support is found in @file{elflink.c}. The 1474ed0d50c3Schristoslinker support is only used if the processor specific file defines 1475ed0d50c3Schristos@samp{elf_backend_relocate_section}, which is required to relocate the 1476ed0d50c3Schristossection contents. If that macro is not defined, the generic linker code 1477ed0d50c3Schristosis used, and relocations are handled via @samp{bfd_perform_relocation}. 1478ed0d50c3Schristos 1479ed0d50c3SchristosThe core file support is in @file{elfcore.h}, which is compiled twice, 1480ed0d50c3Schristosfor both 32 and 64 bit support. The more interesting cases of core file 1481ed0d50c3Schristossupport only work on a native system which has the @file{sys/procfs.h} 1482ed0d50c3Schristosheader file. Without that file, the core file support does little more 1483ed0d50c3Schristosthan read the ELF program segments as BFD sections. 1484ed0d50c3Schristos 1485ed0d50c3SchristosThe BFD internal header file @file{elf-bfd.h} is used for communication 1486ed0d50c3Schristosamong these files and the processor specific files. 1487ed0d50c3Schristos 1488ed0d50c3SchristosThe default entries for the BFD ELF target vector are found mainly in 1489ed0d50c3Schristos@file{elf.c}. Some functions are found in @file{elfcode.h}. 1490ed0d50c3Schristos 1491ed0d50c3SchristosThe processor specific files may override particular entries in the 1492ed0d50c3Schristostarget vector, but most do not, with one exception: the 1493ed0d50c3Schristos@samp{bfd_reloc_type_lookup} entry point is always processor specific. 1494ed0d50c3Schristos 1495ed0d50c3Schristos@node BFD ELF processor specific support 1496ed0d50c3Schristos@subsection BFD ELF processor specific support 1497ed0d50c3Schristos 1498ed0d50c3SchristosBy convention, the processor specific support for a particular processor 1499ed0d50c3Schristoswill be found in @file{elf@var{nn}-@var{cpu}.c}, where @var{nn} is 1500ed0d50c3Schristoseither 32 or 64, and @var{cpu} is the name of the processor. 1501ed0d50c3Schristos 1502ed0d50c3Schristos@menu 1503ed0d50c3Schristos* BFD ELF processor required:: Required processor specific support 1504ed0d50c3Schristos* BFD ELF processor linker:: Processor specific linker support 1505ed0d50c3Schristos* BFD ELF processor other:: Other processor specific support options 1506ed0d50c3Schristos@end menu 1507ed0d50c3Schristos 1508ed0d50c3Schristos@node BFD ELF processor required 1509ed0d50c3Schristos@subsubsection Required processor specific support 1510ed0d50c3Schristos 1511ed0d50c3SchristosWhen writing a @file{elf@var{nn}-@var{cpu}.c} file, you must do the 1512ed0d50c3Schristosfollowing: 1513ed0d50c3Schristos 1514ed0d50c3Schristos@itemize @bullet 1515ed0d50c3Schristos@item 1516ed0d50c3SchristosDefine either @samp{TARGET_BIG_SYM} or @samp{TARGET_LITTLE_SYM}, or 1517ed0d50c3Schristosboth, to a unique C name to use for the target vector. This name should 1518ed0d50c3Schristosappear in the list of target vectors in @file{targets.c}, and will also 1519ed0d50c3Schristoshave to appear in @file{config.bfd} and @file{configure.ac}. Define 1520ed0d50c3Schristos@samp{TARGET_BIG_SYM} for a big-endian processor, 1521ed0d50c3Schristos@samp{TARGET_LITTLE_SYM} for a little-endian processor, and define both 1522ed0d50c3Schristosfor a bi-endian processor. 1523ed0d50c3Schristos@item 1524ed0d50c3SchristosDefine either @samp{TARGET_BIG_NAME} or @samp{TARGET_LITTLE_NAME}, or 1525ed0d50c3Schristosboth, to a string used as the name of the target vector. This is the 1526ed0d50c3Schristosname which a user of the BFD tool would use to specify the object file 1527ed0d50c3Schristosformat. It would normally appear in a linker emulation parameters 1528ed0d50c3Schristosfile. 1529ed0d50c3Schristos@item 1530ed0d50c3SchristosDefine @samp{ELF_ARCH} to the BFD architecture (an element of the 1531ed0d50c3Schristos@samp{bfd_architecture} enum, typically @samp{bfd_arch_@var{cpu}}). 1532ed0d50c3Schristos@item 1533ed0d50c3SchristosDefine @samp{ELF_MACHINE_CODE} to the magic number which should appear 1534ed0d50c3Schristosin the @samp{e_machine} field of the ELF header. As of this writing, 1535ed0d50c3Schristosthese magic numbers are assigned by Caldera; if you want to get a magic 1536ed0d50c3Schristosnumber for a particular processor, try sending a note to 1537ed0d50c3Schristos@email{registry@@caldera.com}. In the BFD sources, the magic numbers are 1538ed0d50c3Schristosfound in @file{include/elf/common.h}; they have names beginning with 1539ed0d50c3Schristos@samp{EM_}. 1540ed0d50c3Schristos@item 1541ed0d50c3SchristosDefine @samp{ELF_MAXPAGESIZE} to the maximum size of a virtual page in 1542ed0d50c3Schristosmemory. This can normally be found at the start of chapter 5 in the 1543ed0d50c3Schristosprocessor specific supplement. For a processor which will only be used 1544ed0d50c3Schristosin an embedded system, or which has no memory management hardware, this 1545ed0d50c3Schristoscan simply be @samp{1}. 1546ed0d50c3Schristos@item 1547ed0d50c3SchristosIf the format should use @samp{Rel} rather than @samp{Rela} relocations, 1548ed0d50c3Schristosdefine @samp{USE_REL}. This is normally defined in chapter 4 of the 1549ed0d50c3Schristosprocessor specific supplement. 1550ed0d50c3Schristos 1551ed0d50c3SchristosIn the absence of a supplement, it's easier to work with @samp{Rela} 1552ed0d50c3Schristosrelocations. @samp{Rela} relocations will require more space in object 1553ed0d50c3Schristosfiles (but not in executables, except when using dynamic linking). 1554ed0d50c3SchristosHowever, this is outweighed by the simplicity of addend handling when 1555ed0d50c3Schristosusing @samp{Rela} relocations. With @samp{Rel} relocations, the addend 1556ed0d50c3Schristosmust be stored in the section contents, which makes relocatable links 1557ed0d50c3Schristosmore complex. 1558ed0d50c3Schristos 1559ed0d50c3SchristosFor example, consider C code like @code{i = a[1000];} where @samp{a} is 1560ed0d50c3Schristosa global array. The instructions which load the value of @samp{a[1000]} 1561ed0d50c3Schristoswill most likely use a relocation which refers to the symbol 1562ed0d50c3Schristosrepresenting @samp{a}, with an addend that gives the offset from the 1563ed0d50c3Schristosstart of @samp{a} to element @samp{1000}. When using @samp{Rel} 1564ed0d50c3Schristosrelocations, that addend must be stored in the instructions themselves. 1565ed0d50c3SchristosIf you are adding support for a RISC chip which uses two or more 1566ed0d50c3Schristosinstructions to load an address, then the addend may not fit in a single 1567ed0d50c3Schristosinstruction, and will have to be somehow split among the instructions. 1568ed0d50c3SchristosThis makes linking awkward, particularly when doing a relocatable link 1569ed0d50c3Schristosin which the addend may have to be updated. It can be done---the MIPS 1570ed0d50c3SchristosELF support does it---but it should be avoided when possible. 1571ed0d50c3Schristos 1572ed0d50c3SchristosIt is possible, though somewhat awkward, to support both @samp{Rel} and 1573ed0d50c3Schristos@samp{Rela} relocations for a single target; @file{elf64-mips.c} does it 1574ed0d50c3Schristosby overriding the relocation reading and writing routines. 1575ed0d50c3Schristos@item 1576ed0d50c3SchristosDefine howto structures for all the relocation types. 1577ed0d50c3Schristos@item 1578ed0d50c3SchristosDefine a @samp{bfd_reloc_type_lookup} routine. This must be named 1579ed0d50c3Schristos@samp{bfd_elf@var{nn}_bfd_reloc_type_lookup}, and may be either a 1580ed0d50c3Schristosfunction or a macro. It must translate a BFD relocation code into a 1581ed0d50c3Schristoshowto structure. This is normally a table lookup or a simple switch. 1582ed0d50c3Schristos@item 1583ed0d50c3SchristosIf using @samp{Rel} relocations, define @samp{elf_info_to_howto_rel}. 1584ed0d50c3SchristosIf using @samp{Rela} relocations, define @samp{elf_info_to_howto}. 1585ed0d50c3SchristosEither way, this is a macro defined as the name of a function which 1586ed0d50c3Schristostakes an @samp{arelent} and a @samp{Rel} or @samp{Rela} structure, and 1587ed0d50c3Schristossets the @samp{howto} field of the @samp{arelent} based on the 1588ed0d50c3Schristos@samp{Rel} or @samp{Rela} structure. This is normally uses 1589ed0d50c3Schristos@samp{ELF@var{nn}_R_TYPE} to get the ELF relocation type and uses it as 1590ed0d50c3Schristosan index into a table of howto structures. 1591ed0d50c3Schristos@end itemize 1592ed0d50c3Schristos 1593ed0d50c3SchristosYou must also add the magic number for this processor to the 1594ed0d50c3Schristos@samp{prep_headers} function in @file{elf.c}. 1595ed0d50c3Schristos 1596ed0d50c3SchristosYou must also create a header file in the @file{include/elf} directory 1597ed0d50c3Schristoscalled @file{@var{cpu}.h}. This file should define any target specific 1598ed0d50c3Schristosinformation which may be needed outside of the BFD code. In particular 1599ed0d50c3Schristosit should use the @samp{START_RELOC_NUMBERS}, @samp{RELOC_NUMBER}, 1600ed0d50c3Schristos@samp{FAKE_RELOC}, @samp{EMPTY_RELOC} and @samp{END_RELOC_NUMBERS} 1601ed0d50c3Schristosmacros to create a table mapping the number used to identify a 1602ed0d50c3Schristosrelocation to a name describing that relocation. 1603ed0d50c3Schristos 1604ed0d50c3SchristosWhile not a BFD component, you probably also want to make the binutils 1605ed0d50c3Schristosprogram @samp{readelf} parse your ELF objects. For this, you need to add 1606ed0d50c3Schristoscode for @code{EM_@var{cpu}} as appropriate in @file{binutils/readelf.c}. 1607ed0d50c3Schristos 1608ed0d50c3Schristos@node BFD ELF processor linker 1609ed0d50c3Schristos@subsubsection Processor specific linker support 1610ed0d50c3Schristos 1611ed0d50c3SchristosThe linker will be much more efficient if you define a relocate section 1612ed0d50c3Schristosfunction. This will permit BFD to use the ELF specific linker support. 1613ed0d50c3Schristos 1614ed0d50c3SchristosIf you do not define a relocate section function, BFD must use the 1615ed0d50c3Schristosgeneric linker support, which requires converting all symbols and 1616ed0d50c3Schristosrelocations into BFD @samp{asymbol} and @samp{arelent} structures. In 1617ed0d50c3Schristosthis case, relocations will be handled by calling 1618ed0d50c3Schristos@samp{bfd_perform_relocation}, which will use the howto structures you 1619ed0d50c3Schristoshave defined. @xref{BFD relocation handling}. 1620ed0d50c3Schristos 1621ed0d50c3SchristosIn order to support linking into a different object file format, such as 1622ed0d50c3SchristosS-records, @samp{bfd_perform_relocation} must work correctly with your 1623ed0d50c3Schristoshowto structures, so you can't skip that step. However, if you define 1624ed0d50c3Schristosthe relocate section function, then in the normal case of linking into 1625ed0d50c3Schristosan ELF file the linker will not need to convert symbols and relocations, 1626ed0d50c3Schristosand will be much more efficient. 1627ed0d50c3Schristos 1628ed0d50c3SchristosTo use a relocation section function, define the macro 1629ed0d50c3Schristos@samp{elf_backend_relocate_section} as the name of a function which will 1630ed0d50c3Schristostake the contents of a section, as well as relocation, symbol, and other 1631ed0d50c3Schristosinformation, and modify the section contents according to the relocation 1632ed0d50c3Schristosinformation. In simple cases, this is little more than a loop over the 1633ed0d50c3Schristosrelocations which computes the value of each relocation and calls 1634ed0d50c3Schristos@samp{_bfd_final_link_relocate}. The function must check for a 1635ed0d50c3Schristosrelocatable link, and in that case normally needs to do nothing other 1636ed0d50c3Schristosthan adjust the addend for relocations against a section symbol. 1637ed0d50c3Schristos 1638ed0d50c3SchristosThe complex cases generally have to do with dynamic linker support. GOT 1639ed0d50c3Schristosand PLT relocations must be handled specially, and the linker normally 1640ed0d50c3Schristosarranges to set up the GOT and PLT sections while handling relocations. 1641ed0d50c3SchristosWhen generating a shared library, random relocations must normally be 1642ed0d50c3Schristoscopied into the shared library, or converted to RELATIVE relocations 1643ed0d50c3Schristoswhen possible. 1644ed0d50c3Schristos 1645ed0d50c3Schristos@node BFD ELF processor other 1646ed0d50c3Schristos@subsubsection Other processor specific support options 1647ed0d50c3Schristos 1648ed0d50c3SchristosThere are many other macros which may be defined in 1649ed0d50c3Schristos@file{elf@var{nn}-@var{cpu}.c}. These macros may be found in 1650ed0d50c3Schristos@file{elfxx-target.h}. 1651ed0d50c3Schristos 1652ed0d50c3SchristosMacros may be used to override some of the generic ELF target vector 1653ed0d50c3Schristosfunctions. 1654ed0d50c3Schristos 1655ed0d50c3SchristosSeveral processor specific hook functions which may be defined as 1656ed0d50c3Schristosmacros. These functions are found as function pointers in the 1657ed0d50c3Schristos@samp{elf_backend_data} structure defined in @file{elf-bfd.h}. In 1658ed0d50c3Schristosgeneral, a hook function is set by defining a macro 1659ed0d50c3Schristos@samp{elf_backend_@var{name}}. 1660ed0d50c3Schristos 1661ed0d50c3SchristosThere are a few processor specific constants which may also be defined. 1662ed0d50c3SchristosThese are again found in the @samp{elf_backend_data} structure. 1663ed0d50c3Schristos 1664ed0d50c3SchristosI will not define the various functions and constants here; see the 1665ed0d50c3Schristoscomments in @file{elf-bfd.h}. 1666ed0d50c3Schristos 1667ed0d50c3SchristosNormally any odd characteristic of a particular ELF processor is handled 1668ed0d50c3Schristosvia a hook function. For example, the special @samp{SHN_MIPS_SCOMMON} 1669ed0d50c3Schristossection number found in MIPS ELF is handled via the hooks 1670ed0d50c3Schristos@samp{section_from_bfd_section}, @samp{symbol_processing}, 1671ed0d50c3Schristos@samp{add_symbol_hook}, and @samp{output_symbol_hook}. 1672ed0d50c3Schristos 1673ed0d50c3SchristosDynamic linking support, which involves processor specific relocations 1674ed0d50c3Schristosrequiring special handling, is also implemented via hook functions. 1675ed0d50c3Schristos 1676ed0d50c3Schristos@node BFD ELF core files 1677ed0d50c3Schristos@subsection BFD ELF core files 1678ed0d50c3Schristos@cindex elf core files 1679ed0d50c3Schristos 1680ed0d50c3SchristosOn native ELF Unix systems, core files are generated without any 1681ed0d50c3Schristossections. Instead, they only have program segments. 1682ed0d50c3Schristos 1683ed0d50c3SchristosWhen BFD is used to read an ELF core file, the BFD sections will 1684ed0d50c3Schristosactually represent program segments. Since ELF program segments do not 1685ed0d50c3Schristoshave names, BFD will invent names like @samp{segment@var{n}} where 1686ed0d50c3Schristos@var{n} is a number. 1687ed0d50c3Schristos 1688ed0d50c3SchristosA single ELF program segment may include both an initialized part and an 1689ed0d50c3Schristosuninitialized part. The size of the initialized part is given by the 1690ed0d50c3Schristos@samp{p_filesz} field. The total size of the segment is given by the 1691ed0d50c3Schristos@samp{p_memsz} field. If @samp{p_memsz} is larger than @samp{p_filesz}, 1692ed0d50c3Schristosthen the extra space is uninitialized, or, more precisely, initialized 1693ed0d50c3Schristosto zero. 1694ed0d50c3Schristos 1695ed0d50c3SchristosBFD will represent such a program segment as two different sections. 1696ed0d50c3SchristosThe first, named @samp{segment@var{n}a}, will represent the initialized 1697ed0d50c3Schristospart of the program segment. The second, named @samp{segment@var{n}b}, 1698ed0d50c3Schristoswill represent the uninitialized part. 1699ed0d50c3Schristos 1700ed0d50c3SchristosELF core files store special information such as register values in 1701ed0d50c3Schristosprogram segments with the type @samp{PT_NOTE}. BFD will attempt to 1702ed0d50c3Schristosinterpret the information in these segments, and will create additional 1703ed0d50c3Schristossections holding the information. Some of this interpretation requires 1704ed0d50c3Schristosinformation found in the host header file @file{sys/procfs.h}, and so 1705ed0d50c3Schristoswill only work when BFD is built on a native system. 1706ed0d50c3Schristos 1707ed0d50c3SchristosBFD does not currently provide any way to create an ELF core file. In 1708ed0d50c3Schristosgeneral, BFD does not provide a way to create core files. The way to 1709ed0d50c3Schristosimplement this would be to write @samp{bfd_set_format} and 1710ed0d50c3Schristos@samp{bfd_write_contents} routines for the @samp{bfd_core} type; see 1711ed0d50c3Schristos@ref{BFD target vector format}. 1712ed0d50c3Schristos 1713ed0d50c3Schristos@node BFD ELF future 1714ed0d50c3Schristos@subsection BFD ELF future 1715ed0d50c3Schristos 1716ed0d50c3SchristosThe current dynamic linking support has too much code duplication. 1717ed0d50c3SchristosWhile each processor has particular differences, much of the dynamic 1718ed0d50c3Schristoslinking support is quite similar for each processor. The GOT and PLT 1719ed0d50c3Schristosare handled in fairly similar ways, the details of -Bsymbolic linking 1720ed0d50c3Schristosare generally similar, etc. This code should be reworked to use more 1721ed0d50c3Schristosgeneric functions, eliminating the duplication. 1722ed0d50c3Schristos 1723ed0d50c3SchristosSimilarly, the relocation handling has too much duplication. Many of 1724ed0d50c3Schristosthe @samp{reloc_type_lookup} and @samp{info_to_howto} functions are 1725ed0d50c3Schristosquite similar. The relocate section functions are also often quite 1726ed0d50c3Schristossimilar, both in the standard linker handling and the dynamic linker 1727ed0d50c3Schristoshandling. Many of the COFF processor specific backends share a single 1728ed0d50c3Schristosrelocate section function (@samp{_bfd_coff_generic_relocate_section}), 1729ed0d50c3Schristosand it should be possible to do something like this for the ELF targets 1730ed0d50c3Schristosas well. 1731ed0d50c3Schristos 1732ed0d50c3SchristosThe appearance of the processor specific magic number in 1733ed0d50c3Schristos@samp{prep_headers} in @file{elf.c} is somewhat bogus. It should be 1734ed0d50c3Schristospossible to add support for a new processor without changing the generic 1735ed0d50c3Schristossupport. 1736ed0d50c3Schristos 1737ed0d50c3SchristosThe processor function hooks and constants are ad hoc and need better 1738ed0d50c3Schristosdocumentation. 1739ed0d50c3Schristos 1740ed0d50c3Schristos@node BFD glossary 1741ed0d50c3Schristos@section BFD glossary 1742ed0d50c3Schristos@cindex glossary for bfd 1743ed0d50c3Schristos@cindex bfd glossary 1744ed0d50c3Schristos 1745ed0d50c3SchristosThis is a short glossary of some BFD terms. 1746ed0d50c3Schristos 1747ed0d50c3Schristos@table @asis 1748ed0d50c3Schristos@item a.out 1749ed0d50c3SchristosThe a.out object file format. The original Unix object file format. 1750ed0d50c3SchristosStill used on SunOS, though not Solaris. Supports only three sections. 1751ed0d50c3Schristos 1752ed0d50c3Schristos@item archive 1753ed0d50c3SchristosA collection of object files produced and manipulated by the @samp{ar} 1754ed0d50c3Schristosprogram. 1755ed0d50c3Schristos 1756ed0d50c3Schristos@item backend 1757ed0d50c3SchristosThe implementation within BFD of a particular object file format. The 1758ed0d50c3Schristosset of functions which appear in a particular target vector. 1759ed0d50c3Schristos 1760ed0d50c3Schristos@item BFD 1761ed0d50c3SchristosThe BFD library itself. Also, each object file, archive, or executable 1762ed0d50c3Schristosopened by the BFD library has the type @samp{bfd *}, and is sometimes 1763ed0d50c3Schristosreferred to as a bfd. 1764ed0d50c3Schristos 1765ed0d50c3Schristos@item COFF 1766ed0d50c3SchristosThe Common Object File Format. Used on Unix SVR3. Used by some 1767ed0d50c3Schristosembedded targets, although ELF is normally better. 1768ed0d50c3Schristos 1769ed0d50c3Schristos@item DLL 1770ed0d50c3SchristosA shared library on Windows. 1771ed0d50c3Schristos 1772ed0d50c3Schristos@item dynamic linker 1773ed0d50c3SchristosWhen a program linked against a shared library is run, the dynamic 1774ed0d50c3Schristoslinker will locate the appropriate shared library and arrange to somehow 1775ed0d50c3Schristosinclude it in the running image. 1776ed0d50c3Schristos 1777ed0d50c3Schristos@item dynamic object 1778ed0d50c3SchristosAnother name for an ELF shared library. 1779ed0d50c3Schristos 1780ed0d50c3Schristos@item ECOFF 1781ed0d50c3SchristosThe Extended Common Object File Format. Used on Alpha Digital Unix 1782ed0d50c3Schristos(formerly OSF/1), as well as Ultrix and Irix 4. A variant of COFF. 1783ed0d50c3Schristos 1784ed0d50c3Schristos@item ELF 1785ed0d50c3SchristosThe Executable and Linking Format. The object file format used on most 1786ed0d50c3Schristosmodern Unix systems, including GNU/Linux, Solaris, Irix, and SVR4. Also 1787ed0d50c3Schristosused on many embedded systems. 1788ed0d50c3Schristos 1789ed0d50c3Schristos@item executable 1790ed0d50c3SchristosA program, with instructions and symbols, and perhaps dynamic linking 1791ed0d50c3Schristosinformation. Normally produced by a linker. 1792ed0d50c3Schristos 1793ed0d50c3Schristos@item LMA 1794ed0d50c3SchristosLoad Memory Address. This is the address at which a section will be 1795ed0d50c3Schristosloaded. Compare with VMA, below. 1796ed0d50c3Schristos 1797ed0d50c3Schristos@item object file 1798ed0d50c3SchristosA binary file including machine instructions, symbols, and relocation 1799ed0d50c3Schristosinformation. Normally produced by an assembler. 1800ed0d50c3Schristos 1801ed0d50c3Schristos@item object file format 1802ed0d50c3SchristosThe format of an object file. Typically object files and executables 1803ed0d50c3Schristosfor a particular system are in the same format, although executables 1804ed0d50c3Schristoswill not contain any relocation information. 1805ed0d50c3Schristos 1806ed0d50c3Schristos@item PE 1807ed0d50c3SchristosThe Portable Executable format. This is the object file format used for 1808ed0d50c3SchristosWindows (specifically, Win32) object files. It is based closely on 1809ed0d50c3SchristosCOFF, but has a few significant differences. 1810ed0d50c3Schristos 1811ed0d50c3Schristos@item PEI 1812ed0d50c3SchristosThe Portable Executable Image format. This is the object file format 1813ed0d50c3Schristosused for Windows (specifically, Win32) executables. It is very similar 1814ed0d50c3Schristosto PE, but includes some additional header information. 1815ed0d50c3Schristos 1816ed0d50c3Schristos@item relocations 1817ed0d50c3SchristosInformation used by the linker to adjust section contents. Also called 1818ed0d50c3Schristosrelocs. 1819ed0d50c3Schristos 1820ed0d50c3Schristos@item section 1821ed0d50c3SchristosObject files and executable are composed of sections. Sections have 1822ed0d50c3Schristosoptional data and optional relocation information. 1823ed0d50c3Schristos 1824ed0d50c3Schristos@item shared library 1825ed0d50c3SchristosA library of functions which may be used by many executables without 1826ed0d50c3Schristosactually being linked into each executable. There are several different 1827ed0d50c3Schristosimplementations of shared libraries, each having slightly different 1828ed0d50c3Schristosfeatures. 1829ed0d50c3Schristos 1830ed0d50c3Schristos@item symbol 1831ed0d50c3SchristosEach object file and executable may have a list of symbols, often 1832ed0d50c3Schristosreferred to as the symbol table. A symbol is basically a name and an 1833ed0d50c3Schristosaddress. There may also be some additional information like the type of 1834ed0d50c3Schristossymbol, although the type of a symbol is normally something simple like 1835ed0d50c3Schristosfunction or object, and should be confused with the more complex C 1836ed0d50c3Schristosnotion of type. Typically every global function and variable in a C 1837ed0d50c3Schristosprogram will have an associated symbol. 1838ed0d50c3Schristos 1839ed0d50c3Schristos@item target vector 1840ed0d50c3SchristosA set of functions which implement support for a particular object file 1841ed0d50c3Schristosformat. The @samp{bfd_target} structure. 1842ed0d50c3Schristos 1843ed0d50c3Schristos@item Win32 1844ed0d50c3SchristosThe current Windows API, implemented by Windows 95 and later and Windows 1845ed0d50c3SchristosNT 3.51 and later, but not by Windows 3.1. 1846ed0d50c3Schristos 1847ed0d50c3Schristos@item XCOFF 1848ed0d50c3SchristosThe eXtended Common Object File Format. Used on AIX. A variant of 1849ed0d50c3SchristosCOFF, with a completely different symbol table implementation. 1850ed0d50c3Schristos 1851ed0d50c3Schristos@item VMA 1852ed0d50c3SchristosVirtual Memory Address. This is the address a section will have when 1853ed0d50c3Schristosan executable is run. Compare with LMA, above. 1854ed0d50c3Schristos@end table 1855ed0d50c3Schristos 1856ed0d50c3Schristos@node Index 1857ed0d50c3Schristos@unnumberedsec Index 1858ed0d50c3Schristos@printindex cp 1859ed0d50c3Schristos 1860ed0d50c3Schristos@contents 1861ed0d50c3Schristos@bye 1862