bfd/doc/coffcode.texi

   1 @section coff backends
   2 BFD supports a number of different flavours of coff format.
   3 The major differences between formats are the sizes and
   4 alignments of fields in structures on disk, and the occasional
   5 extra field.
   6
   7 Coff in all its varieties is implemented with a few common
   8 files and a number of implementation specific files. For
   9 example, The 88k bcs coff format is implemented in the file
  10 @file{coff-m88k.c}. This file @code{#include}s
  11 @file{coff/m88k.h} which defines the external structure of the
  12 coff format for the 88k, and @file{coff/internal.h} which
  13 defines the internal structure. @file{coff-m88k.c} also
  14 defines the relocations used by the 88k format
  15 @xref{Relocations}.
  16
  17 The Intel i960 processor version of coff is implemented in
  18 @file{coff-i960.c}. This file has the same structure as
  19 @file{coff-m88k.c}, except that it includes @file{coff/i960.h}
  20 rather than @file{coff-m88k.h}.
  21
  22 @subsection Porting to a new version of coff
  23 The recommended method is to select from the existing
  24 implementations the version of coff which is most like the one
  25 you want to use.  For example, we'll say that i386 coff is
  26 the one you select, and that your coff flavour is called foo.
  27 Copy @file{i386coff.c} to @file{foocoff.c}, copy
  28 @file{../include/coff/i386.h} to @file{../include/coff/foo.h},
  29 and add the lines to @file{targets.c} and @file{Makefile.in}
  30 so that your new back end is used. Alter the shapes of the
  31 structures in @file{../include/coff/foo.h} so that they match
  32 what you need. You will probably also have to add
  33 @code{#ifdef}s to the code in @file{coff/internal.h} and
  34 @file{coffcode.h} if your version of coff is too wild.
  35
  36 You can verify that your new BFD backend works quite simply by
  37 building @file{objdump} from the @file{binutils} directory,
  38 and making sure that its version of what's going on and your
  39 host system's idea (assuming it has the pretty standard coff
  40 dump utility, usually called @code{att-dump} or just
  41 @code{dump}) are the same.  Then clean up your code, and send
  42 what you've done to Cygnus. Then your stuff will be in the
  43 next release, and you won't have to keep integrating it.
  44
  45 @subsection How the coff backend works
  46
  47
  48 @subsubsection File layout
  49 The Coff backend is split into generic routines that are
  50 applicable to any Coff target and routines that are specific
  51 to a particular target.  The target-specific routines are
  52 further split into ones which are basically the same for all
  53 Coff targets except that they use the external symbol format
  54 or use different values for certain constants.
  55
  56 The generic routines are in @file{coffgen.c}.  These routines
  57 work for any Coff target.  They use some hooks into the target
  58 specific code; the hooks are in a @code{bfd_coff_backend_data}
  59 structure, one of which exists for each target.
  60
  61 The essentially similar target-specific routines are in
  62 @file{coffcode.h}.  This header file includes executable C code.
  63 The various Coff targets first include the appropriate Coff
  64 header file, make any special defines that are needed, and
  65 then include @file{coffcode.h}.
  66
  67 Some of the Coff targets then also have additional routines in
  68 the target source file itself.
  69
  70 For example, @file{coff-i960.c} includes
  71 @file{coff/internal.h} and @file{coff/i960.h}.  It then
  72 defines a few constants, such as @code{I960}, and includes
  73 @file{coffcode.h}.  Since the i960 has complex relocation
  74 types, @file{coff-i960.c} also includes some code to
  75 manipulate the i960 relocs.  This code is not in
  76 @file{coffcode.h} because it would not be used by any other
  77 target.
  78
  79 @subsubsection Coff long section names
  80 In the standard Coff object format, section names are limited to
  81 the eight bytes available in the @code{s_name} field of the
  82 @code{SCNHDR} section header structure.  The format requires the
  83 field to be NUL-padded, but not necessarily NUL-terminated, so
  84 the longest section names permitted are a full eight characters.
  85
  86 The Microsoft PE variants of the Coff object file format add
  87 an extension to support the use of long section names.  This
  88 extension is defined in section 4 of the Microsoft PE/COFF
  89 specification (rev 8.1).  If a section name is too long to fit
  90 into the section header's @code{s_name} field, it is instead
  91 placed into the string table, and the @code{s_name} field is
  92 filled with a slash ("/") followed by the ASCII decimal
  93 representation of the offset of the full name relative to the
  94 string table base.
  95
  96 Note that this implies that the extension can only be used in object
  97 files, as executables do not contain a string table.  The standard
  98 specifies that long section names from objects emitted into executable
  99 images are to be truncated.
 100
 101 However, as a GNU extension, BFD can generate executable images
 102 that contain a string table and long section names.  This
 103 would appear to be technically valid, as the standard only says
 104 that Coff debugging information is deprecated, not forbidden,
 105 and in practice it works, although some tools that parse PE files
 106 expecting the MS standard format may become confused; @file{PEview} is
 107 one known example.
 108
 109 The functionality is supported in BFD by code implemented under
 110 the control of the macro @code{COFF_LONG_SECTION_NAMES}.  If not
 111 defined, the format does not support long section names in any way.
 112 If defined, it is used to initialise a flag,
 113 @code{_bfd_coff_long_section_names}, and a hook function pointer,
 114 @code{_bfd_coff_set_long_section_names}, in the Coff backend data
 115 structure.  The flag controls the generation of long section names
 116 in output BFDs at runtime; if it is false, as it will be by default
 117 when generating an executable image, long section names are truncated;
 118 if true, the long section names extension is employed.  The hook
 119 points to a function that allows the value of the flag to be altered
 120 at runtime, on formats that support long section names at all; on
 121 other formats it points to a stub that returns an error indication.
 122 With input BFDs, the flag is set according to whether any long section
 123 names are detected while reading the section headers.  For a completely
 124 new BFD, the flag is set to the default for the target format.  This
 125 information can be used by a client of the BFD library when deciding
 126 what output format to generate, and means that a BFD that is opened
 127 for read and subsequently converted to a writeable BFD and modified
 128 in-place will retain whatever format it had on input.
 129
 130 If @code{COFF_LONG_SECTION_NAMES} is simply defined (blank), or is
 131 defined to the value "1", then long section names are enabled by
 132 default; if it is defined to the value zero, they are disabled by
 133 default (but still accepted in input BFDs).  The header @file{coffcode.h}
 134 defines a macro, @code{COFF_DEFAULT_LONG_SECTION_NAMES}, which is
 135 used in the backends to initialise the backend data structure fields
 136 appropriately; see the comments for further detail.
 137
 138 @subsubsection Bit twiddling
 139 Each flavour of coff supported in BFD has its own header file
 140 describing the external layout of the structures. There is also
 141 an internal description of the coff layout, in
 142 @file{coff/internal.h}. A major function of the
 143 coff backend is swapping the bytes and twiddling the bits to
 144 translate the external form of the structures into the normal
 145 internal form. This is all performed in the
 146 @code{bfd_swap}_@i{thing}_@i{direction} routines. Some
 147 elements are different sizes between different versions of
 148 coff; it is the duty of the coff version specific include file
 149 to override the definitions of various packing routines in
 150 @file{coffcode.h}. E.g., the size of line number entry in coff is
 151 sometimes 16 bits, and sometimes 32 bits. @code{#define}ing
 152 @code{PUT_LNSZ_LNNO} and @code{GET_LNSZ_LNNO} will select the
 153 correct one. No doubt, some day someone will find a version of
 154 coff which has a varying field size not catered to at the
 155 moment. To port BFD, that person will have to add more @code{#defines}.
 156 Three of the bit twiddling routines are exported to
 157 @code{gdb}; @code{coff_swap_aux_in}, @code{coff_swap_sym_in}
 158 and @code{coff_swap_lineno_in}. @code{GDB} reads the symbol
 159 table on its own, but uses BFD to fix things up.  More of the
 160 bit twiddlers are exported for @code{gas};
 161 @code{coff_swap_aux_out}, @code{coff_swap_sym_out},
 162 @code{coff_swap_lineno_out}, @code{coff_swap_reloc_out},
 163 @code{coff_swap_filehdr_out}, @code{coff_swap_aouthdr_out},
 164 @code{coff_swap_scnhdr_out}. @code{Gas} currently keeps track
 165 of all the symbol table and reloc drudgery itself, thereby
 166 saving the internal BFD overhead, but uses BFD to swap things
 167 on the way out, making cross ports much safer.  Doing so also
 168 allows BFD (and thus the linker) to use the same header files
 169 as @code{gas}, which makes one avenue to disaster disappear.
 170
 171 @subsubsection Symbol reading
 172 The simple canonical form for symbols used by BFD is not rich
 173 enough to keep all the information available in a coff symbol
 174 table. The back end gets around this problem by keeping the original
 175 symbol table around, "behind the scenes".
 176
 177 When a symbol table is requested (through a call to
 178 @code{bfd_canonicalize_symtab}), a request gets through to
 179 @code{coff_get_normalized_symtab}. This reads the symbol table from
 180 the coff file and swaps all the structures inside into the
 181 internal form. It also fixes up all the pointers in the table
 182 (represented in the file by offsets from the first symbol in
 183 the table) into physical pointers to elements in the new
 184 internal table. This involves some work since the meanings of
 185 fields change depending upon context: a field that is a
 186 pointer to another structure in the symbol table at one moment
 187 may be the size in bytes of a structure at the next.  Another
 188 pass is made over the table. All symbols which mark file names
 189 (@code{C_FILE} symbols) are modified so that the internal
 190 string points to the value in the auxent (the real filename)
 191 rather than the normal text associated with the symbol
 192 (@code{".file"}).
 193
 194 At this time the symbol names are moved around. Coff stores
 195 all symbols less than nine characters long physically
 196 within the symbol table; longer strings are kept at the end of
 197 the file in the string table. This pass moves all strings
 198 into memory and replaces them with pointers to the strings.
 199
 200 The symbol table is massaged once again, this time to create
 201 the canonical table used by the BFD application. Each symbol
 202 is inspected in turn, and a decision made (using the
 203 @code{sclass} field) about the various flags to set in the
 204 @code{asymbol}.  @xref{Symbols}. The generated canonical table
 205 shares strings with the hidden internal symbol table.
 206
 207 Any linenumbers are read from the coff file too, and attached
 208 to the symbols which own the functions the linenumbers belong to.
 209
 210 @subsubsection Symbol writing
 211 Writing a symbol to a coff file which didn't come from a coff
 212 file will lose any debugging information. The @code{asymbol}
 213 structure remembers the BFD from which the symbol was taken, and on
 214 output the back end makes sure that the same destination target as
 215 source target is present.
 216
 217 When the symbols have come from a coff file then all the
 218 debugging information is preserved.
 219
 220 Symbol tables are provided for writing to the back end in a
 221 vector of pointers to pointers. This allows applications like
 222 the linker to accumulate and output large symbol tables
 223 without having to do too much byte copying.
 224
 225 This function runs through the provided symbol table and
 226 patches each symbol marked as a file place holder
 227 (@code{C_FILE}) to point to the next file place holder in the
 228 list. It also marks each @code{offset} field in the list with
 229 the offset from the first symbol of the current symbol.
 230
 231 Another function of this procedure is to turn the canonical
 232 value form of BFD into the form used by coff. Internally, BFD
 233 expects symbol values to be offsets from a section base; so a
 234 symbol physically at 0x120, but in a section starting at
 235 0x100, would have the value 0x20. Coff expects symbols to
 236 contain their final value, so symbols have their values
 237 changed at this point to reflect their sum with their owning
 238 section.  This transformation uses the
 239 @code{output_section} field of the @code{asymbol}'s
 240 @code{asection} @xref{Sections}.
 241
 242 @itemize @bullet
 243
 244 @item
 245 @code{coff_mangle_symbols}
 246 @end itemize
 247 This routine runs though the provided symbol table and uses
 248 the offsets generated by the previous pass and the pointers
 249 generated when the symbol table was read in to create the
 250 structured hierarchy required by coff. It changes each pointer
 251 to a symbol into the index into the symbol table of the asymbol.
 252
 253 @itemize @bullet
 254
 255 @item
 256 @code{coff_write_symbols}
 257 @end itemize
 258 This routine runs through the symbol table and patches up the
 259 symbols from their internal form into the coff way, calls the
 260 bit twiddlers, and writes out the table to the file.
 261
 262 @findex coff_symbol_type
 263 @subsubsection @code{coff_symbol_type}
 264 @strong{Description}@*
 265 The hidden information for an @code{asymbol} is described in a
 266 @code{combined_entry_type}:
 267
 268
 269 @example
 270
 271 typedef struct coff_ptr_struct
 272 @{
 273   /* Remembers the offset from the first symbol in the file for
 274      this symbol. Generated by coff_renumber_symbols. */
 275   unsigned int offset;
 276
 277   /* Should the value of this symbol be renumbered.  Used for
 278      XCOFF C_BSTAT symbols.  Set by coff_slurp_symbol_table.  */
 279   unsigned int fix_value : 1;
 280
 281   /* Should the tag field of this symbol be renumbered.
 282      Created by coff_pointerize_aux. */
 283   unsigned int fix_tag : 1;
 284
 285   /* Should the endidx field of this symbol be renumbered.
 286      Created by coff_pointerize_aux. */
 287   unsigned int fix_end : 1;
 288
 289   /* Should the x_csect.x_scnlen field be renumbered.
 290      Created by coff_pointerize_aux. */
 291   unsigned int fix_scnlen : 1;
 292
 293   /* Fix up an XCOFF C_BINCL/C_EINCL symbol.  The value is the
 294      index into the line number entries.  Set by coff_slurp_symbol_table.  */
 295   unsigned int fix_line : 1;
 296
 297   /* The container for the symbol structure as read and translated
 298      from the file. */
 299   union
 300   @{
 301     union internal_auxent auxent;
 302     struct internal_syment syment;
 303   @} u;
 304 @} combined_entry_type;
 305
 306
 307 /* Each canonical asymbol really looks like this: */
 308
 309 typedef struct coff_symbol_struct
 310 @{
 311   /* The actual symbol which the rest of BFD works with */
 312   asymbol symbol;
 313
 314   /* A pointer to the hidden information for this symbol */
 315   combined_entry_type *native;
 316
 317   /* A pointer to the linenumber information for this symbol */
 318   struct lineno_cache_entry *lineno;
 319
 320   /* Have the line numbers been relocated yet ? */
 321   bfd_boolean done_lineno;
 322 @} coff_symbol_type;
 323 @end example
 324 @findex bfd_coff_backend_data
 325 @subsubsection @code{bfd_coff_backend_data}
 326
 327 @example
 328 /* COFF symbol classifications.  */
 329
 330 enum coff_symbol_classification
 331 @{
 332   /* Global symbol.  */
 333   COFF_SYMBOL_GLOBAL,
 334   /* Common symbol.  */
 335   COFF_SYMBOL_COMMON,
 336   /* Undefined symbol.  */
 337   COFF_SYMBOL_UNDEFINED,
 338   /* Local symbol.  */
 339   COFF_SYMBOL_LOCAL,
 340   /* PE section symbol.  */
 341   COFF_SYMBOL_PE_SECTION
 342 @};
 343
 344 @end example
 345 Special entry points for gdb to swap in coff symbol table parts:
 346 @example
 347 typedef struct
 348 @{
 349   void (*_bfd_coff_swap_aux_in)
 350     (bfd *, void *, int, int, int, int, void *);
 351
 352   void (*_bfd_coff_swap_sym_in)
 353     (bfd *, void *, void *);
 354
 355   void (*_bfd_coff_swap_lineno_in)
 356     (bfd *, void *, void *);
 357
 358   unsigned int (*_bfd_coff_swap_aux_out)
 359     (bfd *, void *, int, int, int, int, void *);
 360
 361   unsigned int (*_bfd_coff_swap_sym_out)
 362     (bfd *, void *, void *);
 363
 364   unsigned int (*_bfd_coff_swap_lineno_out)
 365     (bfd *, void *, void *);
 366
 367   unsigned int (*_bfd_coff_swap_reloc_out)
 368     (bfd *, void *, void *);
 369
 370   unsigned int (*_bfd_coff_swap_filehdr_out)
 371     (bfd *, void *, void *);
 372
 373   unsigned int (*_bfd_coff_swap_aouthdr_out)
 374     (bfd *, void *, void *);
 375
 376   unsigned int (*_bfd_coff_swap_scnhdr_out)
 377     (bfd *, void *, void *);
 378
 379   unsigned int _bfd_filhsz;
 380   unsigned int _bfd_aoutsz;
 381   unsigned int _bfd_scnhsz;
 382   unsigned int _bfd_symesz;
 383   unsigned int _bfd_auxesz;
 384   unsigned int _bfd_relsz;
 385   unsigned int _bfd_linesz;
 386   unsigned int _bfd_filnmlen;
 387   bfd_boolean _bfd_coff_long_filenames;
 388
 389   bfd_boolean _bfd_coff_long_section_names;
 390   bfd_boolean (*_bfd_coff_set_long_section_names)
 391     (bfd *, int);
 392
 393   unsigned int _bfd_coff_default_section_alignment_power;
 394   bfd_boolean _bfd_coff_force_symnames_in_strings;
 395   unsigned int _bfd_coff_debug_string_prefix_length;
 396
 397   void (*_bfd_coff_swap_filehdr_in)
 398     (bfd *, void *, void *);
 399
 400   void (*_bfd_coff_swap_aouthdr_in)
 401     (bfd *, void *, void *);
 402
 403   void (*_bfd_coff_swap_scnhdr_in)
 404     (bfd *, void *, void *);
 405
 406   void (*_bfd_coff_swap_reloc_in)
 407     (bfd *abfd, void *, void *);
 408
 409   bfd_boolean (*_bfd_coff_bad_format_hook)
 410     (bfd *, void *);
 411
 412   bfd_boolean (*_bfd_coff_set_arch_mach_hook)
 413     (bfd *, void *);
 414
 415   void * (*_bfd_coff_mkobject_hook)
 416     (bfd *, void *, void *);
 417
 418   bfd_boolean (*_bfd_styp_to_sec_flags_hook)
 419     (bfd *, void *, const char *, asection *, flagword *);
 420
 421   void (*_bfd_set_alignment_hook)
 422     (bfd *, asection *, void *);
 423
 424   bfd_boolean (*_bfd_coff_slurp_symbol_table)
 425     (bfd *);
 426
 427   bfd_boolean (*_bfd_coff_symname_in_debug)
 428     (bfd *, struct internal_syment *);
 429
 430   bfd_boolean (*_bfd_coff_pointerize_aux_hook)
 431     (bfd *, combined_entry_type *, combined_entry_type *,
 432             unsigned int, combined_entry_type *);
 433
 434   bfd_boolean (*_bfd_coff_print_aux)
 435     (bfd *, FILE *, combined_entry_type *, combined_entry_type *,
 436             combined_entry_type *, unsigned int);
 437
 438   void (*_bfd_coff_reloc16_extra_cases)
 439     (bfd *, struct bfd_link_info *, struct bfd_link_order *, arelent *,
 440            bfd_byte *, unsigned int *, unsigned int *);
 441
 442   int (*_bfd_coff_reloc16_estimate)
 443     (bfd *, asection *, arelent *, unsigned int,
 444             struct bfd_link_info *);
 445
 446   enum coff_symbol_classification (*_bfd_coff_classify_symbol)
 447     (bfd *, struct internal_syment *);
 448
 449   bfd_boolean (*_bfd_coff_compute_section_file_positions)
 450     (bfd *);
 451
 452   bfd_boolean (*_bfd_coff_start_final_link)
 453     (bfd *, struct bfd_link_info *);
 454
 455   bfd_boolean (*_bfd_coff_relocate_section)
 456     (bfd *, struct bfd_link_info *, bfd *, asection *, bfd_byte *,
 457             struct internal_reloc *, struct internal_syment *, asection **);
 458
 459   reloc_howto_type *(*_bfd_coff_rtype_to_howto)
 460     (bfd *, asection *, struct internal_reloc *,
 461             struct coff_link_hash_entry *, struct internal_syment *,
 462             bfd_vma *);
 463
 464   bfd_boolean (*_bfd_coff_adjust_symndx)
 465     (bfd *, struct bfd_link_info *, bfd *, asection *,
 466             struct internal_reloc *, bfd_boolean *);
 467
 468   bfd_boolean (*_bfd_coff_link_add_one_symbol)
 469     (struct bfd_link_info *, bfd *, const char *, flagword,
 470             asection *, bfd_vma, const char *, bfd_boolean, bfd_boolean,
 471             struct bfd_link_hash_entry **);
 472
 473   bfd_boolean (*_bfd_coff_link_output_has_begun)
 474     (bfd *, struct coff_final_link_info *);
 475
 476   bfd_boolean (*_bfd_coff_final_link_postscript)
 477     (bfd *, struct coff_final_link_info *);
 478
 479   bfd_boolean (*_bfd_coff_print_pdata)
 480     (bfd *, void *);
 481
 482 @} bfd_coff_backend_data;
 483
 484 #define coff_backend_info(abfd) \
 485   ((bfd_coff_backend_data *) (abfd)->xvec->backend_data)
 486
 487 #define bfd_coff_swap_aux_in(a,e,t,c,ind,num,i) \
 488   ((coff_backend_info (a)->_bfd_coff_swap_aux_in) (a,e,t,c,ind,num,i))
 489
 490 #define bfd_coff_swap_sym_in(a,e,i) \
 491   ((coff_backend_info (a)->_bfd_coff_swap_sym_in) (a,e,i))
 492
 493 #define bfd_coff_swap_lineno_in(a,e,i) \
 494   ((coff_backend_info ( a)->_bfd_coff_swap_lineno_in) (a,e,i))
 495
 496 #define bfd_coff_swap_reloc_out(abfd, i, o) \
 497   ((coff_backend_info (abfd)->_bfd_coff_swap_reloc_out) (abfd, i, o))
 498
 499 #define bfd_coff_swap_lineno_out(abfd, i, o) \
 500   ((coff_backend_info (abfd)->_bfd_coff_swap_lineno_out) (abfd, i, o))
 501
 502 #define bfd_coff_swap_aux_out(a,i,t,c,ind,num,o) \
 503   ((coff_backend_info (a)->_bfd_coff_swap_aux_out) (a,i,t,c,ind,num,o))
 504
 505 #define bfd_coff_swap_sym_out(abfd, i,o) \
 506   ((coff_backend_info (abfd)->_bfd_coff_swap_sym_out) (abfd, i, o))
 507
 508 #define bfd_coff_swap_scnhdr_out(abfd, i,o) \
 509   ((coff_backend_info (abfd)->_bfd_coff_swap_scnhdr_out) (abfd, i, o))
 510
 511 #define bfd_coff_swap_filehdr_out(abfd, i,o) \
 512   ((coff_backend_info (abfd)->_bfd_coff_swap_filehdr_out) (abfd, i, o))
 513
 514 #define bfd_coff_swap_aouthdr_out(abfd, i,o) \
 515   ((coff_backend_info (abfd)->_bfd_coff_swap_aouthdr_out) (abfd, i, o))
 516
 517 #define bfd_coff_filhsz(abfd) (coff_backend_info (abfd)->_bfd_filhsz)
 518 #define bfd_coff_aoutsz(abfd) (coff_backend_info (abfd)->_bfd_aoutsz)
 519 #define bfd_coff_scnhsz(abfd) (coff_backend_info (abfd)->_bfd_scnhsz)
 520 #define bfd_coff_symesz(abfd) (coff_backend_info (abfd)->_bfd_symesz)
 521 #define bfd_coff_auxesz(abfd) (coff_backend_info (abfd)->_bfd_auxesz)
 522 #define bfd_coff_relsz(abfd)  (coff_backend_info (abfd)->_bfd_relsz)
 523 #define bfd_coff_linesz(abfd) (coff_backend_info (abfd)->_bfd_linesz)
 524 #define bfd_coff_filnmlen(abfd) (coff_backend_info (abfd)->_bfd_filnmlen)
 525 #define bfd_coff_long_filenames(abfd) \
 526   (coff_backend_info (abfd)->_bfd_coff_long_filenames)
 527 #define bfd_coff_long_section_names(abfd) \
 528   (coff_backend_info (abfd)->_bfd_coff_long_section_names)
 529 #define bfd_coff_set_long_section_names(abfd, enable) \
 530   ((coff_backend_info (abfd)->_bfd_coff_set_long_section_names) (abfd, enable))
 531 #define bfd_coff_default_section_alignment_power(abfd) \
 532   (coff_backend_info (abfd)->_bfd_coff_default_section_alignment_power)
 533 #define bfd_coff_swap_filehdr_in(abfd, i,o) \
 534   ((coff_backend_info (abfd)->_bfd_coff_swap_filehdr_in) (abfd, i, o))
 535
 536 #define bfd_coff_swap_aouthdr_in(abfd, i,o) \
 537   ((coff_backend_info (abfd)->_bfd_coff_swap_aouthdr_in) (abfd, i, o))
 538
 539 #define bfd_coff_swap_scnhdr_in(abfd, i,o) \
 540   ((coff_backend_info (abfd)->_bfd_coff_swap_scnhdr_in) (abfd, i, o))
 541
 542 #define bfd_coff_swap_reloc_in(abfd, i, o) \
 543   ((coff_backend_info (abfd)->_bfd_coff_swap_reloc_in) (abfd, i, o))
 544
 545 #define bfd_coff_bad_format_hook(abfd, filehdr) \
 546   ((coff_backend_info (abfd)->_bfd_coff_bad_format_hook) (abfd, filehdr))
 547
 548 #define bfd_coff_set_arch_mach_hook(abfd, filehdr)\
 549   ((coff_backend_info (abfd)->_bfd_coff_set_arch_mach_hook) (abfd, filehdr))
 550 #define bfd_coff_mkobject_hook(abfd, filehdr, aouthdr)\
 551   ((coff_backend_info (abfd)->_bfd_coff_mkobject_hook)\
 552    (abfd, filehdr, aouthdr))
 553
 554 #define bfd_coff_styp_to_sec_flags_hook(abfd, scnhdr, name, section, flags_ptr)\
 555   ((coff_backend_info (abfd)->_bfd_styp_to_sec_flags_hook)\
 556    (abfd, scnhdr, name, section, flags_ptr))
 557
 558 #define bfd_coff_set_alignment_hook(abfd, sec, scnhdr)\
 559   ((coff_backend_info (abfd)->_bfd_set_alignment_hook) (abfd, sec, scnhdr))
 560
 561 #define bfd_coff_slurp_symbol_table(abfd)\
 562   ((coff_backend_info (abfd)->_bfd_coff_slurp_symbol_table) (abfd))
 563
 564 #define bfd_coff_symname_in_debug(abfd, sym)\
 565   ((coff_backend_info (abfd)->_bfd_coff_symname_in_debug) (abfd, sym))
 566
 567 #define bfd_coff_force_symnames_in_strings(abfd)\
 568   (coff_backend_info (abfd)->_bfd_coff_force_symnames_in_strings)
 569
 570 #define bfd_coff_debug_string_prefix_length(abfd)\
 571   (coff_backend_info (abfd)->_bfd_coff_debug_string_prefix_length)
 572
 573 #define bfd_coff_print_aux(abfd, file, base, symbol, aux, indaux)\
 574   ((coff_backend_info (abfd)->_bfd_coff_print_aux)\
 575    (abfd, file, base, symbol, aux, indaux))
 576
 577 #define bfd_coff_reloc16_extra_cases(abfd, link_info, link_order,\
 578                                      reloc, data, src_ptr, dst_ptr)\
 579   ((coff_backend_info (abfd)->_bfd_coff_reloc16_extra_cases)\
 580    (abfd, link_info, link_order, reloc, data, src_ptr, dst_ptr))
 581
 582 #define bfd_coff_reloc16_estimate(abfd, section, reloc, shrink, link_info)\
 583   ((coff_backend_info (abfd)->_bfd_coff_reloc16_estimate)\
 584    (abfd, section, reloc, shrink, link_info))
 585
 586 #define bfd_coff_classify_symbol(abfd, sym)\
 587   ((coff_backend_info (abfd)->_bfd_coff_classify_symbol)\
 588    (abfd, sym))
 589
 590 #define bfd_coff_compute_section_file_positions(abfd)\
 591   ((coff_backend_info (abfd)->_bfd_coff_compute_section_file_positions)\
 592    (abfd))
 593
 594 #define bfd_coff_start_final_link(obfd, info)\
 595   ((coff_backend_info (obfd)->_bfd_coff_start_final_link)\
 596    (obfd, info))
 597 #define bfd_coff_relocate_section(obfd,info,ibfd,o,con,rel,isyms,secs)\
 598   ((coff_backend_info (ibfd)->_bfd_coff_relocate_section)\
 599    (obfd, info, ibfd, o, con, rel, isyms, secs))
 600 #define bfd_coff_rtype_to_howto(abfd, sec, rel, h, sym, addendp)\
 601   ((coff_backend_info (abfd)->_bfd_coff_rtype_to_howto)\
 602    (abfd, sec, rel, h, sym, addendp))
 603 #define bfd_coff_adjust_symndx(obfd, info, ibfd, sec, rel, adjustedp)\
 604   ((coff_backend_info (abfd)->_bfd_coff_adjust_symndx)\
 605    (obfd, info, ibfd, sec, rel, adjustedp))
 606 #define bfd_coff_link_add_one_symbol(info, abfd, name, flags, section,\
 607                                      value, string, cp, coll, hashp)\
 608   ((coff_backend_info (abfd)->_bfd_coff_link_add_one_symbol)\
 609    (info, abfd, name, flags, section, value, string, cp, coll, hashp))
 610
 611 #define bfd_coff_link_output_has_begun(a,p) \
 612   ((coff_backend_info (a)->_bfd_coff_link_output_has_begun) (a, p))
 613 #define bfd_coff_final_link_postscript(a,p) \
 614   ((coff_backend_info (a)->_bfd_coff_final_link_postscript) (a, p))
 615
 616 #define bfd_coff_have_print_pdata(a) \
 617   (coff_backend_info (a)->_bfd_coff_print_pdata)
 618 #define bfd_coff_print_pdata(a,p) \
 619   ((coff_backend_info (a)->_bfd_coff_print_pdata) (a, p))
 620
 621 /* Macro: Returns true if the bfd is a PE executable as opposed to a
 622    PE object file.  */
 623 #define bfd_pei_p(abfd) \
 624   (CONST_STRNEQ ((abfd)->xvec->name, "pei-"))
 625 @end example
 626 @subsubsection Writing relocations
 627 To write relocations, the back end steps though the
 628 canonical relocation table and create an
 629 @code{internal_reloc}. The symbol index to use is removed from
 630 the @code{offset} field in the symbol table supplied.  The
 631 address comes directly from the sum of the section base
 632 address and the relocation offset; the type is dug directly
 633 from the howto field.  Then the @code{internal_reloc} is
 634 swapped into the shape of an @code{external_reloc} and written
 635 out to disk.
 636
 637 @subsubsection Reading linenumbers
 638 Creating the linenumber table is done by reading in the entire
 639 coff linenumber table, and creating another table for internal use.
 640
 641 A coff linenumber table is structured so that each function
 642 is marked as having a line number of 0. Each line within the
 643 function is an offset from the first line in the function. The
 644 base of the line number information for the table is stored in
 645 the symbol associated with the function.
 646
 647 Note: The PE format uses line number 0 for a flag indicating a
 648 new source file.
 649
 650 The information is copied from the external to the internal
 651 table, and each symbol which marks a function is marked by
 652 pointing its...
 653
 654 How does this work ?
 655
 656 @subsubsection Reading relocations
 657 Coff relocations are easily transformed into the internal BFD form
 658 (@code{arelent}).
 659
 660 Reading a coff relocation table is done in the following stages:
 661
 662 @itemize @bullet
 663
 664 @item
 665 Read the entire coff relocation table into memory.
 666
 667 @item
 668 Process each relocation in turn; first swap it from the
 669 external to the internal form.
 670
 671 @item
 672 Turn the symbol referenced in the relocation's symbol index
 673 into a pointer into the canonical symbol table.
 674 This table is the same as the one returned by a call to
 675 @code{bfd_canonicalize_symtab}. The back end will call that
 676 routine and save the result if a canonicalization hasn't been done.
 677
 678 @item
 679 The reloc index is turned into a pointer to a howto
 680 structure, in a back end specific way. For instance, the 386
 681 and 960 use the @code{r_type} to directly produce an index
 682 into a howto table vector; the 88k subtracts a number from the
 683 @code{r_type} field and creates an addend field.
 684 @end itemize
 685