1@section Targets 2 3 4@strong{Description}@* 5Each port of BFD to a different machine requires the creation 6of a target back end. All the back end provides to the root 7part of BFD is a structure containing pointers to functions 8which perform certain low level operations on files. BFD 9translates the applications's requests through a pointer into 10calls to the back end routines. 11 12When a file is opened with @code{bfd_openr}, its format and 13target are unknown. BFD uses various mechanisms to determine 14how to interpret the file. The operations performed are: 15 16@itemize @bullet 17 18@item 19Create a BFD by calling the internal routine 20@code{_bfd_new_bfd}, then call @code{bfd_find_target} with the 21target string supplied to @code{bfd_openr} and the new BFD pointer. 22 23@item 24If a null target string was provided to @code{bfd_find_target}, 25look up the environment variable @code{GNUTARGET} and use 26that as the target string. 27 28@item 29If the target string is still @code{NULL}, or the target string is 30@code{default}, then use the first item in the target vector 31as the target type, and set @code{target_defaulted} in the BFD to 32cause @code{bfd_check_format} to loop through all the targets. 33@xref{bfd_target}. @xref{Formats}. 34 35@item 36Otherwise, inspect the elements in the target vector 37one by one, until a match on target name is found. When found, 38use it. 39 40@item 41Otherwise return the error @code{bfd_error_invalid_target} to 42@code{bfd_openr}. 43 44@item 45@code{bfd_openr} attempts to open the file using 46@code{bfd_open_file}, and returns the BFD. 47@end itemize 48Once the BFD has been opened and the target selected, the file 49format may be determined. This is done by calling 50@code{bfd_check_format} on the BFD with a suggested format. 51If @code{target_defaulted} has been set, each possible target 52type is tried to see if it recognizes the specified format. 53@code{bfd_check_format} returns @code{TRUE} when the caller guesses right. 54@menu 55* bfd_target:: 56@end menu 57 58@node bfd_target, , Targets, Targets 59 60@subsection bfd_target 61 62 63@strong{Description}@* 64This structure contains everything that BFD knows about a 65target. It includes things like its byte order, name, and which 66routines to call to do various operations. 67 68Every BFD points to a target structure with its @code{xvec} 69member. 70 71The macros below are used to dispatch to functions through the 72@code{bfd_target} vector. They are used in a number of macros further 73down in @file{bfd.h}, and are also used when calling various 74routines by hand inside the BFD implementation. The @var{arglist} 75argument must be parenthesized; it contains all the arguments 76to the called function. 77 78They make the documentation (more) unpleasant to read, so if 79someone wants to fix this and not break the above, please do. 80@example 81#define BFD_SEND(bfd, message, arglist) \ 82 ((*((bfd)->xvec->message)) arglist) 83 84#ifdef DEBUG_BFD_SEND 85#undef BFD_SEND 86#define BFD_SEND(bfd, message, arglist) \ 87 (((bfd) && (bfd)->xvec && (bfd)->xvec->message) ? \ 88 ((*((bfd)->xvec->message)) arglist) : \ 89 (bfd_assert (__FILE__,__LINE__), NULL)) 90#endif 91@end example 92For operations which index on the BFD format: 93@example 94#define BFD_SEND_FMT(bfd, message, arglist) \ 95 (((bfd)->xvec->message[(int) ((bfd)->format)]) arglist) 96 97#ifdef DEBUG_BFD_SEND 98#undef BFD_SEND_FMT 99#define BFD_SEND_FMT(bfd, message, arglist) \ 100 (((bfd) && (bfd)->xvec && (bfd)->xvec->message) ? \ 101 (((bfd)->xvec->message[(int) ((bfd)->format)]) arglist) : \ 102 (bfd_assert (__FILE__,__LINE__), NULL)) 103#endif 104 105@end example 106This is the structure which defines the type of BFD this is. The 107@code{xvec} member of the struct @code{bfd} itself points here. Each 108module that implements access to a different target under BFD, 109defines one of these. 110 111FIXME, these names should be rationalised with the names of 112the entry points which call them. Too bad we can't have one 113macro to define them both! 114@example 115enum bfd_flavour 116@{ 117 bfd_target_unknown_flavour, 118 bfd_target_aout_flavour, 119 bfd_target_coff_flavour, 120 bfd_target_ecoff_flavour, 121 bfd_target_xcoff_flavour, 122 bfd_target_elf_flavour, 123 bfd_target_ieee_flavour, 124 bfd_target_nlm_flavour, 125 bfd_target_oasys_flavour, 126 bfd_target_tekhex_flavour, 127 bfd_target_srec_flavour, 128 bfd_target_ihex_flavour, 129 bfd_target_som_flavour, 130 bfd_target_os9k_flavour, 131 bfd_target_versados_flavour, 132 bfd_target_msdos_flavour, 133 bfd_target_ovax_flavour, 134 bfd_target_evax_flavour, 135 bfd_target_mmo_flavour, 136 bfd_target_mach_o_flavour, 137 bfd_target_pef_flavour, 138 bfd_target_pef_xlib_flavour, 139 bfd_target_sym_flavour 140@}; 141 142enum bfd_endian @{ BFD_ENDIAN_BIG, BFD_ENDIAN_LITTLE, BFD_ENDIAN_UNKNOWN @}; 143 144/* Forward declaration. */ 145typedef struct bfd_link_info _bfd_link_info; 146 147typedef struct bfd_target 148@{ 149 /* Identifies the kind of target, e.g., SunOS4, Ultrix, etc. */ 150 char *name; 151 152 /* The "flavour" of a back end is a general indication about 153 the contents of a file. */ 154 enum bfd_flavour flavour; 155 156 /* The order of bytes within the data area of a file. */ 157 enum bfd_endian byteorder; 158 159 /* The order of bytes within the header parts of a file. */ 160 enum bfd_endian header_byteorder; 161 162 /* A mask of all the flags which an executable may have set - 163 from the set @code{BFD_NO_FLAGS}, @code{HAS_RELOC}, ...@code{D_PAGED}. */ 164 flagword object_flags; 165 166 /* A mask of all the flags which a section may have set - from 167 the set @code{SEC_NO_FLAGS}, @code{SEC_ALLOC}, ...@code{SET_NEVER_LOAD}. */ 168 flagword section_flags; 169 170 /* The character normally found at the front of a symbol. 171 (if any), perhaps `_'. */ 172 char symbol_leading_char; 173 174 /* The pad character for file names within an archive header. */ 175 char ar_pad_char; 176 177 /* The maximum number of characters in an archive header. */ 178 unsigned short ar_max_namelen; 179 180 /* Entries for byte swapping for data. These are different from the 181 other entry points, since they don't take a BFD as the first argument. 182 Certain other handlers could do the same. */ 183 bfd_uint64_t (*bfd_getx64) (const void *); 184 bfd_int64_t (*bfd_getx_signed_64) (const void *); 185 void (*bfd_putx64) (bfd_uint64_t, void *); 186 bfd_vma (*bfd_getx32) (const void *); 187 bfd_signed_vma (*bfd_getx_signed_32) (const void *); 188 void (*bfd_putx32) (bfd_vma, void *); 189 bfd_vma (*bfd_getx16) (const void *); 190 bfd_signed_vma (*bfd_getx_signed_16) (const void *); 191 void (*bfd_putx16) (bfd_vma, void *); 192 193 /* Byte swapping for the headers. */ 194 bfd_uint64_t (*bfd_h_getx64) (const void *); 195 bfd_int64_t (*bfd_h_getx_signed_64) (const void *); 196 void (*bfd_h_putx64) (bfd_uint64_t, void *); 197 bfd_vma (*bfd_h_getx32) (const void *); 198 bfd_signed_vma (*bfd_h_getx_signed_32) (const void *); 199 void (*bfd_h_putx32) (bfd_vma, void *); 200 bfd_vma (*bfd_h_getx16) (const void *); 201 bfd_signed_vma (*bfd_h_getx_signed_16) (const void *); 202 void (*bfd_h_putx16) (bfd_vma, void *); 203 204 /* Format dependent routines: these are vectors of entry points 205 within the target vector structure, one for each format to check. */ 206 207 /* Check the format of a file being read. Return a @code{bfd_target *} or zero. */ 208 const struct bfd_target *(*_bfd_check_format[bfd_type_end]) (bfd *); 209 210 /* Set the format of a file being written. */ 211 bfd_boolean (*_bfd_set_format[bfd_type_end]) (bfd *); 212 213 /* Write cached information into a file being written, at @code{bfd_close}. */ 214 bfd_boolean (*_bfd_write_contents[bfd_type_end]) (bfd *); 215 216@end example 217The general target vector. These vectors are initialized using the 218BFD_JUMP_TABLE macros. 219@example 220 221 /* Generic entry points. */ 222#define BFD_JUMP_TABLE_GENERIC(NAME) \ 223 NAME##_close_and_cleanup, \ 224 NAME##_bfd_free_cached_info, \ 225 NAME##_new_section_hook, \ 226 NAME##_get_section_contents, \ 227 NAME##_get_section_contents_in_window 228 229 /* Called when the BFD is being closed to do any necessary cleanup. */ 230 bfd_boolean (*_close_and_cleanup) (bfd *); 231 /* Ask the BFD to free all cached information. */ 232 bfd_boolean (*_bfd_free_cached_info) (bfd *); 233 /* Called when a new section is created. */ 234 bfd_boolean (*_new_section_hook) (bfd *, sec_ptr); 235 /* Read the contents of a section. */ 236 bfd_boolean (*_bfd_get_section_contents) 237 (bfd *, sec_ptr, void *, file_ptr, bfd_size_type); 238 bfd_boolean (*_bfd_get_section_contents_in_window) 239 (bfd *, sec_ptr, bfd_window *, file_ptr, bfd_size_type); 240 241 /* Entry points to copy private data. */ 242#define BFD_JUMP_TABLE_COPY(NAME) \ 243 NAME##_bfd_copy_private_bfd_data, \ 244 NAME##_bfd_merge_private_bfd_data, \ 245 _bfd_generic_init_private_section_data, \ 246 NAME##_bfd_copy_private_section_data, \ 247 NAME##_bfd_copy_private_symbol_data, \ 248 NAME##_bfd_copy_private_header_data, \ 249 NAME##_bfd_set_private_flags, \ 250 NAME##_bfd_print_private_bfd_data 251 252 /* Called to copy BFD general private data from one object file 253 to another. */ 254 bfd_boolean (*_bfd_copy_private_bfd_data) (bfd *, bfd *); 255 /* Called to merge BFD general private data from one object file 256 to a common output file when linking. */ 257 bfd_boolean (*_bfd_merge_private_bfd_data) (bfd *, bfd *); 258 /* Called to initialize BFD private section data from one object file 259 to another. */ 260#define bfd_init_private_section_data(ibfd, isec, obfd, osec, link_info) \ 261 BFD_SEND (obfd, _bfd_init_private_section_data, (ibfd, isec, obfd, osec, link_info)) 262 bfd_boolean (*_bfd_init_private_section_data) 263 (bfd *, sec_ptr, bfd *, sec_ptr, struct bfd_link_info *); 264 /* Called to copy BFD private section data from one object file 265 to another. */ 266 bfd_boolean (*_bfd_copy_private_section_data) 267 (bfd *, sec_ptr, bfd *, sec_ptr); 268 /* Called to copy BFD private symbol data from one symbol 269 to another. */ 270 bfd_boolean (*_bfd_copy_private_symbol_data) 271 (bfd *, asymbol *, bfd *, asymbol *); 272 /* Called to copy BFD private header data from one object file 273 to another. */ 274 bfd_boolean (*_bfd_copy_private_header_data) 275 (bfd *, bfd *); 276 /* Called to set private backend flags. */ 277 bfd_boolean (*_bfd_set_private_flags) (bfd *, flagword); 278 279 /* Called to print private BFD data. */ 280 bfd_boolean (*_bfd_print_private_bfd_data) (bfd *, void *); 281 282 /* Core file entry points. */ 283#define BFD_JUMP_TABLE_CORE(NAME) \ 284 NAME##_core_file_failing_command, \ 285 NAME##_core_file_failing_signal, \ 286 NAME##_core_file_matches_executable_p 287 288 char * (*_core_file_failing_command) (bfd *); 289 int (*_core_file_failing_signal) (bfd *); 290 bfd_boolean (*_core_file_matches_executable_p) (bfd *, bfd *); 291 292 /* Archive entry points. */ 293#define BFD_JUMP_TABLE_ARCHIVE(NAME) \ 294 NAME##_slurp_armap, \ 295 NAME##_slurp_extended_name_table, \ 296 NAME##_construct_extended_name_table, \ 297 NAME##_truncate_arname, \ 298 NAME##_write_armap, \ 299 NAME##_read_ar_hdr, \ 300 NAME##_openr_next_archived_file, \ 301 NAME##_get_elt_at_index, \ 302 NAME##_generic_stat_arch_elt, \ 303 NAME##_update_armap_timestamp 304 305 bfd_boolean (*_bfd_slurp_armap) (bfd *); 306 bfd_boolean (*_bfd_slurp_extended_name_table) (bfd *); 307 bfd_boolean (*_bfd_construct_extended_name_table) 308 (bfd *, char **, bfd_size_type *, const char **); 309 void (*_bfd_truncate_arname) (bfd *, const char *, char *); 310 bfd_boolean (*write_armap) 311 (bfd *, unsigned int, struct orl *, unsigned int, int); 312 void * (*_bfd_read_ar_hdr_fn) (bfd *); 313 bfd * (*openr_next_archived_file) (bfd *, bfd *); 314#define bfd_get_elt_at_index(b,i) BFD_SEND (b, _bfd_get_elt_at_index, (b,i)) 315 bfd * (*_bfd_get_elt_at_index) (bfd *, symindex); 316 int (*_bfd_stat_arch_elt) (bfd *, struct stat *); 317 bfd_boolean (*_bfd_update_armap_timestamp) (bfd *); 318 319 /* Entry points used for symbols. */ 320#define BFD_JUMP_TABLE_SYMBOLS(NAME) \ 321 NAME##_get_symtab_upper_bound, \ 322 NAME##_canonicalize_symtab, \ 323 NAME##_make_empty_symbol, \ 324 NAME##_print_symbol, \ 325 NAME##_get_symbol_info, \ 326 NAME##_bfd_is_local_label_name, \ 327 NAME##_bfd_is_target_special_symbol, \ 328 NAME##_get_lineno, \ 329 NAME##_find_nearest_line, \ 330 _bfd_generic_find_line, \ 331 NAME##_find_inliner_info, \ 332 NAME##_bfd_make_debug_symbol, \ 333 NAME##_read_minisymbols, \ 334 NAME##_minisymbol_to_symbol 335 336 long (*_bfd_get_symtab_upper_bound) (bfd *); 337 long (*_bfd_canonicalize_symtab) 338 (bfd *, struct bfd_symbol **); 339 struct bfd_symbol * 340 (*_bfd_make_empty_symbol) (bfd *); 341 void (*_bfd_print_symbol) 342 (bfd *, void *, struct bfd_symbol *, bfd_print_symbol_type); 343#define bfd_print_symbol(b,p,s,e) BFD_SEND (b, _bfd_print_symbol, (b,p,s,e)) 344 void (*_bfd_get_symbol_info) 345 (bfd *, struct bfd_symbol *, symbol_info *); 346#define bfd_get_symbol_info(b,p,e) BFD_SEND (b, _bfd_get_symbol_info, (b,p,e)) 347 bfd_boolean (*_bfd_is_local_label_name) (bfd *, const char *); 348 bfd_boolean (*_bfd_is_target_special_symbol) (bfd *, asymbol *); 349 alent * (*_get_lineno) (bfd *, struct bfd_symbol *); 350 bfd_boolean (*_bfd_find_nearest_line) 351 (bfd *, struct bfd_section *, struct bfd_symbol **, bfd_vma, 352 const char **, const char **, unsigned int *); 353 bfd_boolean (*_bfd_find_line) 354 (bfd *, struct bfd_symbol **, struct bfd_symbol *, 355 const char **, unsigned int *); 356 bfd_boolean (*_bfd_find_inliner_info) 357 (bfd *, const char **, const char **, unsigned int *); 358 /* Back-door to allow format-aware applications to create debug symbols 359 while using BFD for everything else. Currently used by the assembler 360 when creating COFF files. */ 361 asymbol * (*_bfd_make_debug_symbol) 362 (bfd *, void *, unsigned long size); 363#define bfd_read_minisymbols(b, d, m, s) \ 364 BFD_SEND (b, _read_minisymbols, (b, d, m, s)) 365 long (*_read_minisymbols) 366 (bfd *, bfd_boolean, void **, unsigned int *); 367#define bfd_minisymbol_to_symbol(b, d, m, f) \ 368 BFD_SEND (b, _minisymbol_to_symbol, (b, d, m, f)) 369 asymbol * (*_minisymbol_to_symbol) 370 (bfd *, bfd_boolean, const void *, asymbol *); 371 372 /* Routines for relocs. */ 373#define BFD_JUMP_TABLE_RELOCS(NAME) \ 374 NAME##_get_reloc_upper_bound, \ 375 NAME##_canonicalize_reloc, \ 376 NAME##_bfd_reloc_type_lookup, \ 377 NAME##_bfd_reloc_name_lookup 378 379 long (*_get_reloc_upper_bound) (bfd *, sec_ptr); 380 long (*_bfd_canonicalize_reloc) 381 (bfd *, sec_ptr, arelent **, struct bfd_symbol **); 382 /* See documentation on reloc types. */ 383 reloc_howto_type * 384 (*reloc_type_lookup) (bfd *, bfd_reloc_code_real_type); 385 reloc_howto_type * 386 (*reloc_name_lookup) (bfd *, const char *); 387 388 389 /* Routines used when writing an object file. */ 390#define BFD_JUMP_TABLE_WRITE(NAME) \ 391 NAME##_set_arch_mach, \ 392 NAME##_set_section_contents 393 394 bfd_boolean (*_bfd_set_arch_mach) 395 (bfd *, enum bfd_architecture, unsigned long); 396 bfd_boolean (*_bfd_set_section_contents) 397 (bfd *, sec_ptr, const void *, file_ptr, bfd_size_type); 398 399 /* Routines used by the linker. */ 400#define BFD_JUMP_TABLE_LINK(NAME) \ 401 NAME##_sizeof_headers, \ 402 NAME##_bfd_get_relocated_section_contents, \ 403 NAME##_bfd_relax_section, \ 404 NAME##_bfd_link_hash_table_create, \ 405 NAME##_bfd_link_hash_table_free, \ 406 NAME##_bfd_link_add_symbols, \ 407 NAME##_bfd_link_just_syms, \ 408 NAME##_bfd_final_link, \ 409 NAME##_bfd_link_split_section, \ 410 NAME##_bfd_gc_sections, \ 411 NAME##_bfd_merge_sections, \ 412 NAME##_bfd_is_group_section, \ 413 NAME##_bfd_discard_group, \ 414 NAME##_section_already_linked \ 415 416 int (*_bfd_sizeof_headers) (bfd *, struct bfd_link_info *); 417 bfd_byte * (*_bfd_get_relocated_section_contents) 418 (bfd *, struct bfd_link_info *, struct bfd_link_order *, 419 bfd_byte *, bfd_boolean, struct bfd_symbol **); 420 421 bfd_boolean (*_bfd_relax_section) 422 (bfd *, struct bfd_section *, struct bfd_link_info *, bfd_boolean *); 423 424 /* Create a hash table for the linker. Different backends store 425 different information in this table. */ 426 struct bfd_link_hash_table * 427 (*_bfd_link_hash_table_create) (bfd *); 428 429 /* Release the memory associated with the linker hash table. */ 430 void (*_bfd_link_hash_table_free) (struct bfd_link_hash_table *); 431 432 /* Add symbols from this object file into the hash table. */ 433 bfd_boolean (*_bfd_link_add_symbols) (bfd *, struct bfd_link_info *); 434 435 /* Indicate that we are only retrieving symbol values from this section. */ 436 void (*_bfd_link_just_syms) (asection *, struct bfd_link_info *); 437 438 /* Do a link based on the link_order structures attached to each 439 section of the BFD. */ 440 bfd_boolean (*_bfd_final_link) (bfd *, struct bfd_link_info *); 441 442 /* Should this section be split up into smaller pieces during linking. */ 443 bfd_boolean (*_bfd_link_split_section) (bfd *, struct bfd_section *); 444 445 /* Remove sections that are not referenced from the output. */ 446 bfd_boolean (*_bfd_gc_sections) (bfd *, struct bfd_link_info *); 447 448 /* Attempt to merge SEC_MERGE sections. */ 449 bfd_boolean (*_bfd_merge_sections) (bfd *, struct bfd_link_info *); 450 451 /* Is this section a member of a group? */ 452 bfd_boolean (*_bfd_is_group_section) (bfd *, const struct bfd_section *); 453 454 /* Discard members of a group. */ 455 bfd_boolean (*_bfd_discard_group) (bfd *, struct bfd_section *); 456 457 /* Check if SEC has been already linked during a reloceatable or 458 final link. */ 459 void (*_section_already_linked) (bfd *, struct bfd_section *, 460 struct bfd_link_info *); 461 462 /* Routines to handle dynamic symbols and relocs. */ 463#define BFD_JUMP_TABLE_DYNAMIC(NAME) \ 464 NAME##_get_dynamic_symtab_upper_bound, \ 465 NAME##_canonicalize_dynamic_symtab, \ 466 NAME##_get_synthetic_symtab, \ 467 NAME##_get_dynamic_reloc_upper_bound, \ 468 NAME##_canonicalize_dynamic_reloc 469 470 /* Get the amount of memory required to hold the dynamic symbols. */ 471 long (*_bfd_get_dynamic_symtab_upper_bound) (bfd *); 472 /* Read in the dynamic symbols. */ 473 long (*_bfd_canonicalize_dynamic_symtab) 474 (bfd *, struct bfd_symbol **); 475 /* Create synthetized symbols. */ 476 long (*_bfd_get_synthetic_symtab) 477 (bfd *, long, struct bfd_symbol **, long, struct bfd_symbol **, 478 struct bfd_symbol **); 479 /* Get the amount of memory required to hold the dynamic relocs. */ 480 long (*_bfd_get_dynamic_reloc_upper_bound) (bfd *); 481 /* Read in the dynamic relocs. */ 482 long (*_bfd_canonicalize_dynamic_reloc) 483 (bfd *, arelent **, struct bfd_symbol **); 484 485@end example 486A pointer to an alternative bfd_target in case the current one is not 487satisfactory. This can happen when the target cpu supports both big 488and little endian code, and target chosen by the linker has the wrong 489endianness. The function open_output() in ld/ldlang.c uses this field 490to find an alternative output format that is suitable. 491@example 492 /* Opposite endian version of this target. */ 493 const struct bfd_target * alternative_target; 494 495 /* Data for use by back-end routines, which isn't 496 generic enough to belong in this structure. */ 497 const void *backend_data; 498 499@} bfd_target; 500 501@end example 502 503@findex bfd_set_default_target 504@subsubsection @code{bfd_set_default_target} 505@strong{Synopsis} 506@example 507bfd_boolean bfd_set_default_target (const char *name); 508@end example 509@strong{Description}@* 510Set the default target vector to use when recognizing a BFD. 511This takes the name of the target, which may be a BFD target 512name or a configuration triplet. 513 514@findex bfd_find_target 515@subsubsection @code{bfd_find_target} 516@strong{Synopsis} 517@example 518const bfd_target *bfd_find_target (const char *target_name, bfd *abfd); 519@end example 520@strong{Description}@* 521Return a pointer to the transfer vector for the object target 522named @var{target_name}. If @var{target_name} is @code{NULL}, 523choose the one in the environment variable @code{GNUTARGET}; if 524that is null or not defined, then choose the first entry in the 525target list. Passing in the string "default" or setting the 526environment variable to "default" will cause the first entry in 527the target list to be returned, and "target_defaulted" will be 528set in the BFD if @var{abfd} isn't @code{NULL}. This causes 529@code{bfd_check_format} to loop over all the targets to find the 530one that matches the file being read. 531 532@findex bfd_target_list 533@subsubsection @code{bfd_target_list} 534@strong{Synopsis} 535@example 536const char ** bfd_target_list (void); 537@end example 538@strong{Description}@* 539Return a freshly malloced NULL-terminated 540vector of the names of all the valid BFD targets. Do not 541modify the names. 542 543@findex bfd_seach_for_target 544@subsubsection @code{bfd_seach_for_target} 545@strong{Synopsis} 546@example 547const bfd_target *bfd_search_for_target 548 (int (*search_func) (const bfd_target *, void *), 549 void *); 550@end example 551@strong{Description}@* 552Return a pointer to the first transfer vector in the list of 553transfer vectors maintained by BFD that produces a non-zero 554result when passed to the function @var{search_func}. The 555parameter @var{data} is passed, unexamined, to the search 556function. 557 558