contrib/binutils/bfd/doc/targets.texi

   1 @section Targets
   2
   3
   4 @strong{Description}@*
   5 Each port of BFD to a different machine requries 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 @end example
 105 This is the structure which defines the type of BFD this is.  The
 106 @code{xvec} member of the struct @code{bfd} itself points here.  Each
 107 module that implements access to a different target under BFD,
 108 defines one of these.
 109
 110 FIXME, these names should be rationalised with the names of
 111 the entry points which call them. Too bad we can't have one
 112 macro to define them both!
 113 @example
 114 enum bfd_flavour @{
 115   bfd_target_unknown_flavour,
 116   bfd_target_aout_flavour,
 117   bfd_target_coff_flavour,
 118   bfd_target_ecoff_flavour,
 119   bfd_target_elf_flavour,
 120   bfd_target_ieee_flavour,
 121   bfd_target_nlm_flavour,
 122   bfd_target_oasys_flavour,
 123   bfd_target_tekhex_flavour,
 124   bfd_target_srec_flavour,
 125   bfd_target_ihex_flavour,
 126   bfd_target_som_flavour,
 127   bfd_target_os9k_flavour,
 128   bfd_target_versados_flavour,
 129   bfd_target_msdos_flavour,
 130   bfd_target_evax_flavour
 131 @};
 132
 133 enum bfd_endian @{ BFD_ENDIAN_BIG, BFD_ENDIAN_LITTLE, BFD_ENDIAN_UNKNOWN @};
 134
 135  /* Forward declaration.  */
 136 typedef struct bfd_link_info _bfd_link_info;
 137
 138 typedef struct bfd_target
 139 @{
 140 @end example
 141 Identifies the kind of target, e.g., SunOS4, Ultrix, etc.
 142 @example
 143   char *name;
 144 @end example
 145 The "flavour" of a back end is a general indication about the contents
 146 of a file.
 147 @example
 148   enum bfd_flavour flavour;
 149 @end example
 150 The order of bytes within the data area of a file.
 151 @example
 152   enum bfd_endian byteorder;
 153 @end example
 154 The order of bytes within the header parts of a file.
 155 @example
 156   enum bfd_endian header_byteorder;
 157 @end example
 158 A mask of all the flags which an executable may have set -
 159 from the set @code{BFD_NO_FLAGS}, @code{HAS_RELOC}, ...@code{D_PAGED}.
 160 @example
 161   flagword object_flags;
 162 @end example
 163 A mask of all the flags which a section may have set - from
 164 the set @code{SEC_NO_FLAGS}, @code{SEC_ALLOC}, ...@code{SET_NEVER_LOAD}.
 165 @example
 166   flagword section_flags;
 167 @end example
 168 The character normally found at the front of a symbol
 169 (if any), perhaps `_'.
 170 @example
 171   char symbol_leading_char;
 172 @end example
 173 The pad character for file names within an archive header.
 174 @example
 175   char ar_pad_char;
 176 @end example
 177 The maximum number of characters in an archive header.
 178 @example
 179   unsigned short ar_max_namelen;
 180 @end example
 181 Entries for byte swapping for data. These are different from the other
 182 entry points, since they don't take a BFD asthe first argument.
 183 Certain other handlers could do the same.
 184 @example
 185   bfd_vma      (*bfd_getx64) PARAMS ((const bfd_byte *));
 186   bfd_signed_vma (*bfd_getx_signed_64) PARAMS ((const bfd_byte *));
 187   void         (*bfd_putx64) PARAMS ((bfd_vma, bfd_byte *));
 188   bfd_vma      (*bfd_getx32) PARAMS ((const bfd_byte *));
 189   bfd_signed_vma (*bfd_getx_signed_32) PARAMS ((const bfd_byte *));
 190   void         (*bfd_putx32) PARAMS ((bfd_vma, bfd_byte *));
 191   bfd_vma      (*bfd_getx16) PARAMS ((const bfd_byte *));
 192   bfd_signed_vma (*bfd_getx_signed_16) PARAMS ((const bfd_byte *));
 193   void         (*bfd_putx16) PARAMS ((bfd_vma, bfd_byte *));
 194 @end example
 195 Byte swapping for the headers
 196 @example
 197   bfd_vma      (*bfd_h_getx64) PARAMS ((const bfd_byte *));
 198   bfd_signed_vma (*bfd_h_getx_signed_64) PARAMS ((const bfd_byte *));
 199   void         (*bfd_h_putx64) PARAMS ((bfd_vma, bfd_byte *));
 200   bfd_vma      (*bfd_h_getx32) PARAMS ((const bfd_byte *));
 201   bfd_signed_vma (*bfd_h_getx_signed_32) PARAMS ((const bfd_byte *));
 202   void         (*bfd_h_putx32) PARAMS ((bfd_vma, bfd_byte *));
 203   bfd_vma      (*bfd_h_getx16) PARAMS ((const bfd_byte *));
 204   bfd_signed_vma (*bfd_h_getx_signed_16) PARAMS ((const bfd_byte *));
 205   void         (*bfd_h_putx16) PARAMS ((bfd_vma, bfd_byte *));
 206 @end example
 207 Format dependent routines: these are vectors of entry points
 208 within the target vector structure, one for each format to check.
 209
 210 Check the format of a file being read.  Return a @code{bfd_target *} or zero.
 211 @example
 212   const struct bfd_target *(*_bfd_check_format[bfd_type_end]) PARAMS ((bfd *));
 213 @end example
 214 Set the format of a file being written.
 215 @example
 216   boolean             (*_bfd_set_format[bfd_type_end]) PARAMS ((bfd *));
 217 @end example
 218 Write cached information into a file being written, at @code{bfd_close}.
 219 @example
 220   boolean             (*_bfd_write_contents[bfd_type_end]) PARAMS ((bfd *));
 221 @end example
 222 The general target vector.
 223 @example
 224
 225    /* Generic entry points.  */
 226 #define BFD_JUMP_TABLE_GENERIC(NAME)\
 227 CAT(NAME,_close_and_cleanup),\
 228 CAT(NAME,_bfd_free_cached_info),\
 229 CAT(NAME,_new_section_hook),\
 230 CAT(NAME,_get_section_contents),\
 231 CAT(NAME,_get_section_contents_in_window)
 232
 233    /* Called when the BFD is being closed to do any necessary cleanup.  */
 234   boolean       (*_close_and_cleanup) PARAMS ((bfd *));
 235    /* Ask the BFD to free all cached information.  */
 236   boolean (*_bfd_free_cached_info) PARAMS ((bfd *));
 237    /* Called when a new section is created.  */
 238   boolean       (*_new_section_hook) PARAMS ((bfd *, sec_ptr));
 239    /* Read the contents of a section.  */
 240   boolean       (*_bfd_get_section_contents) PARAMS ((bfd *, sec_ptr, PTR,
 241                                             file_ptr, bfd_size_type));
 242   boolean       (*_bfd_get_section_contents_in_window)
 243                           PARAMS ((bfd *, sec_ptr, bfd_window *,
 244                                    file_ptr, bfd_size_type));
 245
 246    /* Entry points to copy private data.  */
 247 #define BFD_JUMP_TABLE_COPY(NAME)\
 248 CAT(NAME,_bfd_copy_private_bfd_data),\
 249 CAT(NAME,_bfd_merge_private_bfd_data),\
 250 CAT(NAME,_bfd_copy_private_section_data),\
 251 CAT(NAME,_bfd_copy_private_symbol_data),\
 252 CAT(NAME,_bfd_set_private_flags),\
 253 CAT(NAME,_bfd_print_private_bfd_data)\
 254    /* Called to copy BFD general private data from one object file
 255      to another.  */
 256   boolean       (*_bfd_copy_private_bfd_data) PARAMS ((bfd *, bfd *));
 257    /* Called to merge BFD general private data from one object file
 258      to a common output file when linking.  */
 259   boolean       (*_bfd_merge_private_bfd_data) PARAMS ((bfd *, bfd *));
 260    /* Called to copy BFD private section data from one object file
 261      to another.  */
 262   boolean       (*_bfd_copy_private_section_data) PARAMS ((bfd *, sec_ptr,
 263                                                        bfd *, sec_ptr));
 264    /* Called to copy BFD private symbol data from one symbol
 265      to another.  */
 266   boolean       (*_bfd_copy_private_symbol_data) PARAMS ((bfd *, asymbol *,
 267                                                           bfd *, asymbol *));
 268    /* Called to set private backend flags */
 269   boolean       (*_bfd_set_private_flags) PARAMS ((bfd *, flagword));
 270
 271    /* Called to print private BFD data */
 272   boolean       (*_bfd_print_private_bfd_data) PARAMS ((bfd *, PTR));
 273
 274    /* Core file entry points.  */
 275 #define BFD_JUMP_TABLE_CORE(NAME)\
 276 CAT(NAME,_core_file_failing_command),\
 277 CAT(NAME,_core_file_failing_signal),\
 278 CAT(NAME,_core_file_matches_executable_p)
 279   char *   (*_core_file_failing_command) PARAMS ((bfd *));
 280   int      (*_core_file_failing_signal) PARAMS ((bfd *));
 281   boolean  (*_core_file_matches_executable_p) PARAMS ((bfd *, bfd *));
 282
 283    /* Archive entry points.  */
 284 #define BFD_JUMP_TABLE_ARCHIVE(NAME)\
 285 CAT(NAME,_slurp_armap),\
 286 CAT(NAME,_slurp_extended_name_table),\
 287 CAT(NAME,_construct_extended_name_table),\
 288 CAT(NAME,_truncate_arname),\
 289 CAT(NAME,_write_armap),\
 290 CAT(NAME,_read_ar_hdr),\
 291 CAT(NAME,_openr_next_archived_file),\
 292 CAT(NAME,_get_elt_at_index),\
 293 CAT(NAME,_generic_stat_arch_elt),\
 294 CAT(NAME,_update_armap_timestamp)
 295   boolean  (*_bfd_slurp_armap) PARAMS ((bfd *));
 296   boolean  (*_bfd_slurp_extended_name_table) PARAMS ((bfd *));
 297   boolean  (*_bfd_construct_extended_name_table)
 298              PARAMS ((bfd *, char **, bfd_size_type *, const char **));
 299   void     (*_bfd_truncate_arname) PARAMS ((bfd *, CONST char *, char *));
 300   boolean  (*write_armap) PARAMS ((bfd *arch,
 301                               unsigned int elength,
 302                               struct orl *map,
 303                               unsigned int orl_count,
 304                               int stridx));
 305   PTR (*_bfd_read_ar_hdr_fn) PARAMS ((bfd *));
 306   bfd *    (*openr_next_archived_file) PARAMS ((bfd *arch, bfd *prev));
 307 #define bfd_get_elt_at_index(b,i) BFD_SEND(b, _bfd_get_elt_at_index, (b,i))
 308   bfd *    (*_bfd_get_elt_at_index) PARAMS ((bfd *, symindex));
 309   int      (*_bfd_stat_arch_elt) PARAMS ((bfd *, struct stat *));
 310   boolean  (*_bfd_update_armap_timestamp) PARAMS ((bfd *));
 311
 312    /* Entry points used for symbols.  */
 313 #define BFD_JUMP_TABLE_SYMBOLS(NAME)\
 314 CAT(NAME,_get_symtab_upper_bound),\
 315 CAT(NAME,_get_symtab),\
 316 CAT(NAME,_make_empty_symbol),\
 317 CAT(NAME,_print_symbol),\
 318 CAT(NAME,_get_symbol_info),\
 319 CAT(NAME,_bfd_is_local_label_name),\
 320 CAT(NAME,_get_lineno),\
 321 CAT(NAME,_find_nearest_line),\
 322 CAT(NAME,_bfd_make_debug_symbol),\
 323 CAT(NAME,_read_minisymbols),\
 324 CAT(NAME,_minisymbol_to_symbol)
 325   long  (*_bfd_get_symtab_upper_bound) PARAMS ((bfd *));
 326   long  (*_bfd_canonicalize_symtab) PARAMS ((bfd *,
 327                                              struct symbol_cache_entry **));
 328   struct symbol_cache_entry  *
 329                 (*_bfd_make_empty_symbol) PARAMS ((bfd *));
 330   void          (*_bfd_print_symbol) PARAMS ((bfd *, PTR,
 331                                       struct symbol_cache_entry *,
 332                                       bfd_print_symbol_type));
 333 #define bfd_print_symbol(b,p,s,e) BFD_SEND(b, _bfd_print_symbol, (b,p,s,e))
 334   void          (*_bfd_get_symbol_info) PARAMS ((bfd *,
 335                                       struct symbol_cache_entry *,
 336                                       symbol_info *));
 337 #define bfd_get_symbol_info(b,p,e) BFD_SEND(b, _bfd_get_symbol_info, (b,p,e))
 338   boolean       (*_bfd_is_local_label_name) PARAMS ((bfd *, const char *));
 339
 340   alent *    (*_get_lineno) PARAMS ((bfd *, struct symbol_cache_entry *));
 341   boolean    (*_bfd_find_nearest_line) PARAMS ((bfd *abfd,
 342                     struct sec *section, struct symbol_cache_entry **symbols,
 343                     bfd_vma offset, CONST char **file, CONST char **func,
 344                     unsigned int *line));
 345   /* Back-door to allow format-aware applications to create debug symbols
 346     while using BFD for everything else.  Currently used by the assembler
 347     when creating COFF files.  */
 348   asymbol *  (*_bfd_make_debug_symbol) PARAMS ((
 349        bfd *abfd,
 350        void *ptr,
 351        unsigned long size));
 352 #define bfd_read_minisymbols(b, d, m, s) \
 353   BFD_SEND (b, _read_minisymbols, (b, d, m, s))
 354   long  (*_read_minisymbols) PARAMS ((bfd *, boolean, PTR *,
 355                                       unsigned int *));
 356 #define bfd_minisymbol_to_symbol(b, d, m, f) \
 357   BFD_SEND (b, _minisymbol_to_symbol, (b, d, m, f))
 358   asymbol *(*_minisymbol_to_symbol) PARAMS ((bfd *, boolean, const PTR,
 359                                              asymbol *));
 360
 361    /* Routines for relocs.  */
 362 #define BFD_JUMP_TABLE_RELOCS(NAME)\
 363 CAT(NAME,_get_reloc_upper_bound),\
 364 CAT(NAME,_canonicalize_reloc),\
 365 CAT(NAME,_bfd_reloc_type_lookup)
 366   long  (*_get_reloc_upper_bound) PARAMS ((bfd *, sec_ptr));
 367   long  (*_bfd_canonicalize_reloc) PARAMS ((bfd *, sec_ptr, arelent **,
 368                                             struct symbol_cache_entry **));
 369    /* See documentation on reloc types.  */
 370   reloc_howto_type *
 371        (*reloc_type_lookup) PARAMS ((bfd *abfd,
 372                                      bfd_reloc_code_real_type code));
 373
 374    /* Routines used when writing an object file.  */
 375 #define BFD_JUMP_TABLE_WRITE(NAME)\
 376 CAT(NAME,_set_arch_mach),\
 377 CAT(NAME,_set_section_contents)
 378   boolean    (*_bfd_set_arch_mach) PARAMS ((bfd *, enum bfd_architecture,
 379                     unsigned long));
 380   boolean       (*_bfd_set_section_contents) PARAMS ((bfd *, sec_ptr, PTR,
 381                                             file_ptr, bfd_size_type));
 382
 383    /* Routines used by the linker.  */
 384 #define BFD_JUMP_TABLE_LINK(NAME)\
 385 CAT(NAME,_sizeof_headers),\
 386 CAT(NAME,_bfd_get_relocated_section_contents),\
 387 CAT(NAME,_bfd_relax_section),\
 388 CAT(NAME,_bfd_link_hash_table_create),\
 389 CAT(NAME,_bfd_link_add_symbols),\
 390 CAT(NAME,_bfd_final_link),\
 391 CAT(NAME,_bfd_link_split_section)
 392   int        (*_bfd_sizeof_headers) PARAMS ((bfd *, boolean));
 393   bfd_byte * (*_bfd_get_relocated_section_contents) PARAMS ((bfd *,
 394                     struct bfd_link_info *, struct bfd_link_order *,
 395                     bfd_byte *data, boolean relocateable,
 396                     struct symbol_cache_entry **));
 397
 398   boolean    (*_bfd_relax_section) PARAMS ((bfd *, struct sec *,
 399                     struct bfd_link_info *, boolean *again));
 400
 401    /* Create a hash table for the linker.  Different backends store
 402      different information in this table.  */
 403   struct bfd_link_hash_table *(*_bfd_link_hash_table_create) PARAMS ((bfd *));
 404
 405    /* Add symbols from this object file into the hash table.  */
 406   boolean (*_bfd_link_add_symbols) PARAMS ((bfd *, struct bfd_link_info *));
 407
 408    /* Do a link based on the link_order structures attached to each
 409      section of the BFD.  */
 410   boolean (*_bfd_final_link) PARAMS ((bfd *, struct bfd_link_info *));
 411
 412    /* Should this section be split up into smaller pieces during linking.  */
 413   boolean (*_bfd_link_split_section) PARAMS ((bfd *, struct sec *));
 414
 415   /* Routines to handle dynamic symbols and relocs.  */
 416 #define BFD_JUMP_TABLE_DYNAMIC(NAME)\
 417 CAT(NAME,_get_dynamic_symtab_upper_bound),\
 418 CAT(NAME,_canonicalize_dynamic_symtab),\
 419 CAT(NAME,_get_dynamic_reloc_upper_bound),\
 420 CAT(NAME,_canonicalize_dynamic_reloc)
 421    /* Get the amount of memory required to hold the dynamic symbols. */
 422   long  (*_bfd_get_dynamic_symtab_upper_bound) PARAMS ((bfd *));
 423    /* Read in the dynamic symbols.  */
 424   long  (*_bfd_canonicalize_dynamic_symtab)
 425     PARAMS ((bfd *, struct symbol_cache_entry **));
 426    /* Get the amount of memory required to hold the dynamic relocs.  */
 427   long  (*_bfd_get_dynamic_reloc_upper_bound) PARAMS ((bfd *));
 428    /* Read in the dynamic relocs.  */
 429   long  (*_bfd_canonicalize_dynamic_reloc)
 430     PARAMS ((bfd *, arelent **, struct symbol_cache_entry **));
 431
 432 @end example
 433 Data for use by back-end routines, which isn't generic enough to belong
 434 in this structure.
 435 @example
 436  PTR backend_data;
 437 @} bfd_target;
 438 @end example
 439
 440 @findex bfd_set_default_target
 441 @subsubsection @code{bfd_set_default_target}
 442 @strong{Synopsis}
 443 @example
 444 boolean bfd_set_default_target (const char *name);
 445 @end example
 446 @strong{Description}@*
 447 Set the default target vector to use when recognizing a BFD.
 448 This takes the name of the target, which may be a BFD target
 449 name or a configuration triplet.
 450
 451 @findex bfd_find_target
 452 @subsubsection @code{bfd_find_target}
 453 @strong{Synopsis}
 454 @example
 455 const bfd_target *bfd_find_target(CONST char *target_name, bfd *abfd);
 456 @end example
 457 @strong{Description}@*
 458 Return a pointer to the transfer vector for the object target
 459 named @var{target_name}.  If @var{target_name} is @code{NULL}, choose the
 460 one in the environment variable @code{GNUTARGET}; if that is null or not
 461 defined, then choose the first entry in the target list.
 462 Passing in the string "default" or setting the environment
 463 variable to "default" will cause the first entry in the target
 464 list to be returned, and "target_defaulted" will be set in the
 465 BFD.  This causes @code{bfd_check_format} to loop over all the
 466 targets to find the one that matches the file being read.
 467
 468 @findex bfd_target_list
 469 @subsubsection @code{bfd_target_list}
 470 @strong{Synopsis}
 471 @example
 472 const char **bfd_target_list(void);
 473 @end example
 474 @strong{Description}@*
 475 Return a freshly malloced NULL-terminated
 476 vector of the names of all the valid BFD targets. Do not
 477 modify the names.
 478