contrib/binutils/bfd/doc/targets.texi

   1 @section Targets
   2
   3
   4 @strong{Description}@*
   5 Each port of BFD to a different machine requires the creation
   6 of a target back end. All the back end provides to the root
   7 part of BFD is a structure containing pointers to functions
   8 which perform certain low level operations on files. BFD
   9 translates the applications's requests through a pointer into
  10 calls to the back end routines.
  11
  12 When a file is opened with @code{bfd_openr}, its format and
  13 target are unknown. BFD uses various mechanisms to determine
  14 how to interpret the file. The operations performed are:
  15
  16 @itemize @bullet
  17
  18 @item
  19 Create a BFD by calling the internal routine
  20 @code{_bfd_new_bfd}, then call @code{bfd_find_target} with the
  21 target string supplied to @code{bfd_openr} and the new BFD pointer.
  22
  23 @item
  24 If a null target string was provided to @code{bfd_find_target},
  25 look up the environment variable @code{GNUTARGET} and use
  26 that as the target string.
  27
  28 @item
  29 If the target string is still @code{NULL}, or the target string is
  30 @code{default}, then use the first item in the target vector
  31 as the target type, and set @code{target_defaulted} in the BFD to
  32 cause @code{bfd_check_format} to loop through all the targets.
  33 @xref{bfd_target}.  @xref{Formats}.
  34
  35 @item
  36 Otherwise, inspect the elements in the target vector
  37 one by one, until a match on target name is found. When found,
  38 use it.
  39
  40 @item
  41 Otherwise 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
  48 Once the BFD has been opened and the target selected, the file
  49 format may be determined. This is done by calling
  50 @code{bfd_check_format} on the BFD with a suggested format.
  51 If @code{target_defaulted} has been set, each possible target
  52 type 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}@*
  64 This structure contains everything that BFD knows about a
  65 target. It includes things like its byte order, name, and which
  66 routines to call to do various operations.
  67
  68 Every BFD points to a target structure with its @code{xvec}
  69 member.
  70
  71 The macros below are used to dispatch to functions through the
  72 @code{bfd_target} vector. They are used in a number of macros further
  73 down in @file{bfd.h}, and are also used when calling various
  74 routines by hand inside the BFD implementation.  The @var{arglist}
  75 argument must be parenthesized; it contains all the arguments
  76 to the called function.
  77
  78 They make the documentation (more) unpleasant to read, so if
  79 someone 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
  92 For 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
 106 This 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
 108 module that implements access to a different target under BFD,
 109 defines one of these.
 110
 111 FIXME, these names should be rationalised with the names of
 112 the entry points which call them. Too bad we can't have one
 113 macro to define them both!
 114 @example
 115 enum 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
 142 enum bfd_endian @{ BFD_ENDIAN_BIG, BFD_ENDIAN_LITTLE, BFD_ENDIAN_UNKNOWN @};
 143
 144 /* Forward declaration.  */
 145 typedef struct bfd_link_info _bfd_link_info;
 146
 147 typedef 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 asthe 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
 217 The general target vector.  These vectors are initialized using the
 218 BFD_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   NAME##_bfd_copy_private_section_data, \
 246   NAME##_bfd_copy_private_symbol_data, \
 247   NAME##_bfd_set_private_flags, \
 248   NAME##_bfd_print_private_bfd_data
 249
 250   /* Called to copy BFD general private data from one object file
 251      to another.  */
 252   bfd_boolean (*_bfd_copy_private_bfd_data) (bfd *, bfd *);
 253   /* Called to merge BFD general private data from one object file
 254      to a common output file when linking.  */
 255   bfd_boolean (*_bfd_merge_private_bfd_data) (bfd *, bfd *);
 256   /* Called to copy BFD private section data from one object file
 257      to another.  */
 258   bfd_boolean (*_bfd_copy_private_section_data)
 259     (bfd *, sec_ptr, bfd *, sec_ptr);
 260   /* Called to copy BFD private symbol data from one symbol
 261      to another.  */
 262   bfd_boolean (*_bfd_copy_private_symbol_data)
 263     (bfd *, asymbol *, bfd *, asymbol *);
 264   /* Called to set private backend flags.  */
 265   bfd_boolean (*_bfd_set_private_flags) (bfd *, flagword);
 266
 267   /* Called to print private BFD data.  */
 268   bfd_boolean (*_bfd_print_private_bfd_data) (bfd *, void *);
 269
 270   /* Core file entry points.  */
 271 #define BFD_JUMP_TABLE_CORE(NAME) \
 272   NAME##_core_file_failing_command, \
 273   NAME##_core_file_failing_signal, \
 274   NAME##_core_file_matches_executable_p
 275
 276   char *      (*_core_file_failing_command) (bfd *);
 277   int         (*_core_file_failing_signal) (bfd *);
 278   bfd_boolean (*_core_file_matches_executable_p) (bfd *, bfd *);
 279
 280   /* Archive entry points.  */
 281 #define BFD_JUMP_TABLE_ARCHIVE(NAME) \
 282   NAME##_slurp_armap, \
 283   NAME##_slurp_extended_name_table, \
 284   NAME##_construct_extended_name_table, \
 285   NAME##_truncate_arname, \
 286   NAME##_write_armap, \
 287   NAME##_read_ar_hdr, \
 288   NAME##_openr_next_archived_file, \
 289   NAME##_get_elt_at_index, \
 290   NAME##_generic_stat_arch_elt, \
 291   NAME##_update_armap_timestamp
 292
 293   bfd_boolean (*_bfd_slurp_armap) (bfd *);
 294   bfd_boolean (*_bfd_slurp_extended_name_table) (bfd *);
 295   bfd_boolean (*_bfd_construct_extended_name_table)
 296     (bfd *, char **, bfd_size_type *, const char **);
 297   void        (*_bfd_truncate_arname) (bfd *, const char *, char *);
 298   bfd_boolean (*write_armap)
 299     (bfd *, unsigned int, struct orl *, unsigned int, int);
 300   void *      (*_bfd_read_ar_hdr_fn) (bfd *);
 301   bfd *       (*openr_next_archived_file) (bfd *, bfd *);
 302 #define bfd_get_elt_at_index(b,i) BFD_SEND (b, _bfd_get_elt_at_index, (b,i))
 303   bfd *       (*_bfd_get_elt_at_index) (bfd *, symindex);
 304   int         (*_bfd_stat_arch_elt) (bfd *, struct stat *);
 305   bfd_boolean (*_bfd_update_armap_timestamp) (bfd *);
 306
 307   /* Entry points used for symbols.  */
 308 #define BFD_JUMP_TABLE_SYMBOLS(NAME) \
 309   NAME##_get_symtab_upper_bound, \
 310   NAME##_canonicalize_symtab, \
 311   NAME##_make_empty_symbol, \
 312   NAME##_print_symbol, \
 313   NAME##_get_symbol_info, \
 314   NAME##_bfd_is_local_label_name, \
 315   NAME##_get_lineno, \
 316   NAME##_find_nearest_line, \
 317   NAME##_bfd_make_debug_symbol, \
 318   NAME##_read_minisymbols, \
 319   NAME##_minisymbol_to_symbol
 320
 321   long        (*_bfd_get_symtab_upper_bound) (bfd *);
 322   long        (*_bfd_canonicalize_symtab)
 323     (bfd *, struct bfd_symbol **);
 324   struct bfd_symbol *
 325               (*_bfd_make_empty_symbol) (bfd *);
 326   void        (*_bfd_print_symbol)
 327     (bfd *, void *, struct bfd_symbol *, bfd_print_symbol_type);
 328 #define bfd_print_symbol(b,p,s,e) BFD_SEND (b, _bfd_print_symbol, (b,p,s,e))
 329   void        (*_bfd_get_symbol_info)
 330     (bfd *, struct bfd_symbol *, symbol_info *);
 331 #define bfd_get_symbol_info(b,p,e) BFD_SEND (b, _bfd_get_symbol_info, (b,p,e))
 332   bfd_boolean (*_bfd_is_local_label_name) (bfd *, const char *);
 333
 334   alent *     (*_get_lineno) (bfd *, struct bfd_symbol *);
 335   bfd_boolean (*_bfd_find_nearest_line)
 336     (bfd *, struct bfd_section *, struct bfd_symbol **, bfd_vma,
 337      const char **, const char **, unsigned int *);
 338  /* Back-door to allow format-aware applications to create debug symbols
 339     while using BFD for everything else.  Currently used by the assembler
 340     when creating COFF files.  */
 341   asymbol *   (*_bfd_make_debug_symbol)
 342     (bfd *, void *, unsigned long size);
 343 #define bfd_read_minisymbols(b, d, m, s) \
 344   BFD_SEND (b, _read_minisymbols, (b, d, m, s))
 345   long        (*_read_minisymbols)
 346     (bfd *, bfd_boolean, void **, unsigned int *);
 347 #define bfd_minisymbol_to_symbol(b, d, m, f) \
 348   BFD_SEND (b, _minisymbol_to_symbol, (b, d, m, f))
 349   asymbol *   (*_minisymbol_to_symbol)
 350     (bfd *, bfd_boolean, const void *, asymbol *);
 351
 352   /* Routines for relocs.  */
 353 #define BFD_JUMP_TABLE_RELOCS(NAME) \
 354   NAME##_get_reloc_upper_bound, \
 355   NAME##_canonicalize_reloc, \
 356   NAME##_bfd_reloc_type_lookup
 357
 358   long        (*_get_reloc_upper_bound) (bfd *, sec_ptr);
 359   long        (*_bfd_canonicalize_reloc)
 360     (bfd *, sec_ptr, arelent **, struct bfd_symbol **);
 361   /* See documentation on reloc types.  */
 362   reloc_howto_type *
 363               (*reloc_type_lookup) (bfd *, bfd_reloc_code_real_type);
 364
 365   /* Routines used when writing an object file.  */
 366 #define BFD_JUMP_TABLE_WRITE(NAME) \
 367   NAME##_set_arch_mach, \
 368   NAME##_set_section_contents
 369
 370   bfd_boolean (*_bfd_set_arch_mach)
 371     (bfd *, enum bfd_architecture, unsigned long);
 372   bfd_boolean (*_bfd_set_section_contents)
 373     (bfd *, sec_ptr, const void *, file_ptr, bfd_size_type);
 374
 375   /* Routines used by the linker.  */
 376 #define BFD_JUMP_TABLE_LINK(NAME) \
 377   NAME##_sizeof_headers, \
 378   NAME##_bfd_get_relocated_section_contents, \
 379   NAME##_bfd_relax_section, \
 380   NAME##_bfd_link_hash_table_create, \
 381   NAME##_bfd_link_hash_table_free, \
 382   NAME##_bfd_link_add_symbols, \
 383   NAME##_bfd_link_just_syms, \
 384   NAME##_bfd_final_link, \
 385   NAME##_bfd_link_split_section, \
 386   NAME##_bfd_gc_sections, \
 387   NAME##_bfd_merge_sections, \
 388   NAME##_bfd_discard_group
 389
 390   int         (*_bfd_sizeof_headers) (bfd *, bfd_boolean);
 391   bfd_byte *  (*_bfd_get_relocated_section_contents)
 392     (bfd *, struct bfd_link_info *, struct bfd_link_order *,
 393      bfd_byte *, bfd_boolean, struct bfd_symbol **);
 394
 395   bfd_boolean (*_bfd_relax_section)
 396     (bfd *, struct bfd_section *, struct bfd_link_info *, bfd_boolean *);
 397
 398   /* Create a hash table for the linker.  Different backends store
 399      different information in this table.  */
 400   struct bfd_link_hash_table *
 401               (*_bfd_link_hash_table_create) (bfd *);
 402
 403   /* Release the memory associated with the linker hash table.  */
 404   void        (*_bfd_link_hash_table_free) (struct bfd_link_hash_table *);
 405
 406   /* Add symbols from this object file into the hash table.  */
 407   bfd_boolean (*_bfd_link_add_symbols) (bfd *, struct bfd_link_info *);
 408
 409   /* Indicate that we are only retrieving symbol values from this section.  */
 410   void        (*_bfd_link_just_syms) (asection *, struct bfd_link_info *);
 411
 412   /* Do a link based on the link_order structures attached to each
 413      section of the BFD.  */
 414   bfd_boolean (*_bfd_final_link) (bfd *, struct bfd_link_info *);
 415
 416   /* Should this section be split up into smaller pieces during linking.  */
 417   bfd_boolean (*_bfd_link_split_section) (bfd *, struct bfd_section *);
 418
 419   /* Remove sections that are not referenced from the output.  */
 420   bfd_boolean (*_bfd_gc_sections) (bfd *, struct bfd_link_info *);
 421
 422   /* Attempt to merge SEC_MERGE sections.  */
 423   bfd_boolean (*_bfd_merge_sections) (bfd *, struct bfd_link_info *);
 424
 425   /* Discard members of a group.  */
 426   bfd_boolean (*_bfd_discard_group) (bfd *, struct bfd_section *);
 427
 428   /* Routines to handle dynamic symbols and relocs.  */
 429 #define BFD_JUMP_TABLE_DYNAMIC(NAME) \
 430   NAME##_get_dynamic_symtab_upper_bound, \
 431   NAME##_canonicalize_dynamic_symtab, \
 432   NAME##_get_dynamic_reloc_upper_bound, \
 433   NAME##_canonicalize_dynamic_reloc
 434
 435   /* Get the amount of memory required to hold the dynamic symbols.  */
 436   long        (*_bfd_get_dynamic_symtab_upper_bound) (bfd *);
 437   /* Read in the dynamic symbols.  */
 438   long        (*_bfd_canonicalize_dynamic_symtab)
 439     (bfd *, struct bfd_symbol **);
 440   /* Get the amount of memory required to hold the dynamic relocs.  */
 441   long        (*_bfd_get_dynamic_reloc_upper_bound) (bfd *);
 442   /* Read in the dynamic relocs.  */
 443   long        (*_bfd_canonicalize_dynamic_reloc)
 444     (bfd *, arelent **, struct bfd_symbol **);
 445
 446 @end example
 447 A pointer to an alternative bfd_target in case the current one is not
 448 satisfactory.  This can happen when the target cpu supports both big
 449 and little endian code, and target chosen by the linker has the wrong
 450 endianness.  The function open_output() in ld/ldlang.c uses this field
 451 to find an alternative output format that is suitable.
 452 @example
 453   /* Opposite endian version of this target.  */
 454   const struct bfd_target * alternative_target;
 455
 456   /* Data for use by back-end routines, which isn't
 457      generic enough to belong in this structure.  */
 458   const void *backend_data;
 459
 460 @} bfd_target;
 461
 462 @end example
 463
 464 @findex bfd_set_default_target
 465 @subsubsection @code{bfd_set_default_target}
 466 @strong{Synopsis}
 467 @example
 468 bfd_boolean bfd_set_default_target (const char *name);
 469 @end example
 470 @strong{Description}@*
 471 Set the default target vector to use when recognizing a BFD.
 472 This takes the name of the target, which may be a BFD target
 473 name or a configuration triplet.
 474
 475 @findex bfd_find_target
 476 @subsubsection @code{bfd_find_target}
 477 @strong{Synopsis}
 478 @example
 479 const bfd_target *bfd_find_target (const char *target_name, bfd *abfd);
 480 @end example
 481 @strong{Description}@*
 482 Return a pointer to the transfer vector for the object target
 483 named @var{target_name}.  If @var{target_name} is @code{NULL}, choose the
 484 one in the environment variable @code{GNUTARGET}; if that is null or not
 485 defined, then choose the first entry in the target list.
 486 Passing in the string "default" or setting the environment
 487 variable to "default" will cause the first entry in the target
 488 list to be returned, and "target_defaulted" will be set in the
 489 BFD.  This causes @code{bfd_check_format} to loop over all the
 490 targets to find the one that matches the file being read.
 491
 492 @findex bfd_target_list
 493 @subsubsection @code{bfd_target_list}
 494 @strong{Synopsis}
 495 @example
 496 const char ** bfd_target_list (void);
 497 @end example
 498 @strong{Description}@*
 499 Return a freshly malloced NULL-terminated
 500 vector of the names of all the valid BFD targets. Do not
 501 modify the names.
 502
 503 @findex bfd_seach_for_target
 504 @subsubsection @code{bfd_seach_for_target}
 505 @strong{Synopsis}
 506 @example
 507 const bfd_target *bfd_search_for_target
 508    (int (*search_func) (const bfd_target *, void *),
 509     void *);
 510 @end example
 511 @strong{Description}@*
 512 Return a pointer to the first transfer vector in the list of
 513 transfer vectors maintained by BFD that produces a non-zero
 514 result when passed to the function @var{search_func}.  The
 515 parameter @var{data} is passed, unexamined, to the search
 516 function.
 517