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 Bit twiddling
  80 Each flavour of coff supported in BFD has its own header file
  81 describing the external layout of the structures. There is also
  82 an internal description of the coff layout, in
  83 @file{coff/internal.h}. A major function of the
  84 coff backend is swapping the bytes and twiddling the bits to
  85 translate the external form of the structures into the normal
  86 internal form. This is all performed in the
  87 @code{bfd_swap}_@i{thing}_@i{direction} routines. Some
  88 elements are different sizes between different versions of
  89 coff; it is the duty of the coff version specific include file
  90 to override the definitions of various packing routines in
  91 @file{coffcode.h}. E.g., the size of line number entry in coff is
  92 sometimes 16 bits, and sometimes 32 bits. @code{#define}ing
  93 @code{PUT_LNSZ_LNNO} and @code{GET_LNSZ_LNNO} will select the
  94 correct one. No doubt, some day someone will find a version of
  95 coff which has a varying field size not catered to at the
  96 moment. To port BFD, that person will have to add more @code{#defines}.
  97 Three of the bit twiddling routines are exported to
  98 @code{gdb}; @code{coff_swap_aux_in}, @code{coff_swap_sym_in}
  99 and @code{coff_swap_lineno_in}. @code{GDB} reads the symbol
 100 table on its own, but uses BFD to fix things up.  More of the
 101 bit twiddlers are exported for @code{gas};
 102 @code{coff_swap_aux_out}, @code{coff_swap_sym_out},
 103 @code{coff_swap_lineno_out}, @code{coff_swap_reloc_out},
 104 @code{coff_swap_filehdr_out}, @code{coff_swap_aouthdr_out},
 105 @code{coff_swap_scnhdr_out}. @code{Gas} currently keeps track
 106 of all the symbol table and reloc drudgery itself, thereby
 107 saving the internal BFD overhead, but uses BFD to swap things
 108 on the way out, making cross ports much safer.  Doing so also
 109 allows BFD (and thus the linker) to use the same header files
 110 as @code{gas}, which makes one avenue to disaster disappear.
 111
 112 @subsubsection Symbol reading
 113 The simple canonical form for symbols used by BFD is not rich
 114 enough to keep all the information available in a coff symbol
 115 table. The back end gets around this problem by keeping the original
 116 symbol table around, "behind the scenes".
 117
 118 When a symbol table is requested (through a call to
 119 @code{bfd_canonicalize_symtab}), a request gets through to
 120 @code{coff_get_normalized_symtab}. This reads the symbol table from
 121 the coff file and swaps all the structures inside into the
 122 internal form. It also fixes up all the pointers in the table
 123 (represented in the file by offsets from the first symbol in
 124 the table) into physical pointers to elements in the new
 125 internal table. This involves some work since the meanings of
 126 fields change depending upon context: a field that is a
 127 pointer to another structure in the symbol table at one moment
 128 may be the size in bytes of a structure at the next.  Another
 129 pass is made over the table. All symbols which mark file names
 130 (@code{C_FILE} symbols) are modified so that the internal
 131 string points to the value in the auxent (the real filename)
 132 rather than the normal text associated with the symbol
 133 (@code{".file"}).
 134
 135 At this time the symbol names are moved around. Coff stores
 136 all symbols less than nine characters long physically
 137 within the symbol table; longer strings are kept at the end of
 138 the file in the string  table. This pass moves all strings
 139 into memory and replaces them with pointers to the strings.
 140
 141 The symbol table is massaged once again, this time to create
 142 the canonical table used by the BFD application. Each symbol
 143 is inspected in turn, and a decision made (using the
 144 @code{sclass} field) about the various flags to set in the
 145 @code{asymbol}.  @xref{Symbols}. The generated canonical table
 146 shares strings with the hidden internal symbol table.
 147
 148 Any linenumbers are read from the coff file too, and attached
 149 to the symbols which own the functions the linenumbers belong to.
 150
 151 @subsubsection Symbol writing
 152 Writing a symbol to a coff file which didn't come from a coff
 153 file will lose any debugging information. The @code{asymbol}
 154 structure remembers the BFD from which the symbol was taken, and on
 155 output the back end makes sure that the same destination target as
 156 source target is present.
 157
 158 When the symbols have come from a coff file then all the
 159 debugging information is preserved.
 160
 161 Symbol tables are provided for writing to the back end in a
 162 vector of pointers to pointers. This allows applications like
 163 the linker to accumulate and output large symbol tables
 164 without having to do too much byte copying.
 165
 166 This function runs through the provided symbol table and
 167 patches each symbol marked as a file place holder
 168 (@code{C_FILE}) to point to the next file place holder in the
 169 list. It also marks each @code{offset} field in the list with
 170 the offset from the first symbol of the current symbol.
 171
 172 Another function of this procedure is to turn the canonical
 173 value form of BFD into the form used by coff. Internally, BFD
 174 expects symbol values to be offsets from a section base; so a
 175 symbol physically at 0x120, but in a section starting at
 176 0x100, would have the value 0x20. Coff expects symbols to
 177 contain their final value, so symbols have their values
 178 changed at this point to reflect their sum with their owning
 179 section.  This transformation uses the
 180 @code{output_section} field of the @code{asymbol}'s
 181 @code{asection} @xref{Sections}.
 182
 183 @itemize @bullet
 184
 185 @item
 186 @code{coff_mangle_symbols}
 187 @end itemize
 188 This routine runs though the provided symbol table and uses
 189 the offsets generated by the previous pass and the pointers
 190 generated when the symbol table was read in to create the
 191 structured hierarchy required by coff. It changes each pointer
 192 to a symbol into the index into the symbol table of the asymbol.
 193
 194 @itemize @bullet
 195
 196 @item
 197 @code{coff_write_symbols}
 198 @end itemize
 199 This routine runs through the symbol table and patches up the
 200 symbols from their internal form into the coff way, calls the
 201 bit twiddlers, and writes out the table to the file.
 202
 203 @findex coff_symbol_type
 204 @subsubsection @code{coff_symbol_type}
 205 @strong{Description}@*
 206 The hidden information for an @code{asymbol} is described in a
 207 @code{combined_entry_type}:
 208
 209
 210 @example
 211
 212 typedef struct coff_ptr_struct
 213 @{
 214   /* Remembers the offset from the first symbol in the file for
 215      this symbol. Generated by coff_renumber_symbols. */
 216   unsigned int offset;
 217
 218   /* Should the value of this symbol be renumbered.  Used for
 219      XCOFF C_BSTAT symbols.  Set by coff_slurp_symbol_table.  */
 220   unsigned int fix_value : 1;
 221
 222   /* Should the tag field of this symbol be renumbered.
 223      Created by coff_pointerize_aux. */
 224   unsigned int fix_tag : 1;
 225
 226   /* Should the endidx field of this symbol be renumbered.
 227      Created by coff_pointerize_aux. */
 228   unsigned int fix_end : 1;
 229
 230   /* Should the x_csect.x_scnlen field be renumbered.
 231      Created by coff_pointerize_aux. */
 232   unsigned int fix_scnlen : 1;
 233
 234   /* Fix up an XCOFF C_BINCL/C_EINCL symbol.  The value is the
 235      index into the line number entries.  Set by coff_slurp_symbol_table.  */
 236   unsigned int fix_line : 1;
 237
 238   /* The container for the symbol structure as read and translated
 239      from the file. */
 240   union
 241   @{
 242     union internal_auxent auxent;
 243     struct internal_syment syment;
 244   @} u;
 245 @} combined_entry_type;
 246
 247
 248 /* Each canonical asymbol really looks like this: */
 249
 250 typedef struct coff_symbol_struct
 251 @{
 252   /* The actual symbol which the rest of BFD works with */
 253   asymbol symbol;
 254
 255   /* A pointer to the hidden information for this symbol */
 256   combined_entry_type *native;
 257
 258   /* A pointer to the linenumber information for this symbol */
 259   struct lineno_cache_entry *lineno;
 260
 261   /* Have the line numbers been relocated yet ? */
 262   bfd_boolean done_lineno;
 263 @} coff_symbol_type;
 264 @end example
 265 @findex bfd_coff_backend_data
 266 @subsubsection @code{bfd_coff_backend_data}
 267
 268 @example
 269 /* COFF symbol classifications.  */
 270
 271 enum coff_symbol_classification
 272 @{
 273   /* Global symbol.  */
 274   COFF_SYMBOL_GLOBAL,
 275   /* Common symbol.  */
 276   COFF_SYMBOL_COMMON,
 277   /* Undefined symbol.  */
 278   COFF_SYMBOL_UNDEFINED,
 279   /* Local symbol.  */
 280   COFF_SYMBOL_LOCAL,
 281   /* PE section symbol.  */
 282   COFF_SYMBOL_PE_SECTION
 283 @};
 284
 285 @end example
 286 Special entry points for gdb to swap in coff symbol table parts:
 287 @example
 288 typedef struct
 289 @{
 290   void (*_bfd_coff_swap_aux_in)
 291     (bfd *, void *, int, int, int, int, void *);
 292
 293   void (*_bfd_coff_swap_sym_in)
 294     (bfd *, void *, void *);
 295
 296   void (*_bfd_coff_swap_lineno_in)
 297     (bfd *, void *, void *);
 298
 299   unsigned int (*_bfd_coff_swap_aux_out)
 300     (bfd *, void *, int, int, int, int, void *);
 301
 302   unsigned int (*_bfd_coff_swap_sym_out)
 303     (bfd *, void *, void *);
 304
 305   unsigned int (*_bfd_coff_swap_lineno_out)
 306     (bfd *, void *, void *);
 307
 308   unsigned int (*_bfd_coff_swap_reloc_out)
 309     (bfd *, void *, void *);
 310
 311   unsigned int (*_bfd_coff_swap_filehdr_out)
 312     (bfd *, void *, void *);
 313
 314   unsigned int (*_bfd_coff_swap_aouthdr_out)
 315     (bfd *, void *, void *);
 316
 317   unsigned int (*_bfd_coff_swap_scnhdr_out)
 318     (bfd *, void *, void *);
 319
 320   unsigned int _bfd_filhsz;
 321   unsigned int _bfd_aoutsz;
 322   unsigned int _bfd_scnhsz;
 323   unsigned int _bfd_symesz;
 324   unsigned int _bfd_auxesz;
 325   unsigned int _bfd_relsz;
 326   unsigned int _bfd_linesz;
 327   unsigned int _bfd_filnmlen;
 328   bfd_boolean _bfd_coff_long_filenames;
 329   bfd_boolean _bfd_coff_long_section_names;
 330   unsigned int _bfd_coff_default_section_alignment_power;
 331   bfd_boolean _bfd_coff_force_symnames_in_strings;
 332   unsigned int _bfd_coff_debug_string_prefix_length;
 333
 334   void (*_bfd_coff_swap_filehdr_in)
 335     (bfd *, void *, void *);
 336
 337   void (*_bfd_coff_swap_aouthdr_in)
 338     (bfd *, void *, void *);
 339
 340   void (*_bfd_coff_swap_scnhdr_in)
 341     (bfd *, void *, void *);
 342
 343   void (*_bfd_coff_swap_reloc_in)
 344     (bfd *abfd, void *, void *);
 345
 346   bfd_boolean (*_bfd_coff_bad_format_hook)
 347     (bfd *, void *);
 348
 349   bfd_boolean (*_bfd_coff_set_arch_mach_hook)
 350     (bfd *, void *);
 351
 352   void * (*_bfd_coff_mkobject_hook)
 353     (bfd *, void *, void *);
 354
 355   bfd_boolean (*_bfd_styp_to_sec_flags_hook)
 356     (bfd *, void *, const char *, asection *, flagword *);
 357
 358   void (*_bfd_set_alignment_hook)
 359     (bfd *, asection *, void *);
 360
 361   bfd_boolean (*_bfd_coff_slurp_symbol_table)
 362     (bfd *);
 363
 364   bfd_boolean (*_bfd_coff_symname_in_debug)
 365     (bfd *, struct internal_syment *);
 366
 367   bfd_boolean (*_bfd_coff_pointerize_aux_hook)
 368     (bfd *, combined_entry_type *, combined_entry_type *,
 369             unsigned int, combined_entry_type *);
 370
 371   bfd_boolean (*_bfd_coff_print_aux)
 372     (bfd *, FILE *, combined_entry_type *, combined_entry_type *,
 373             combined_entry_type *, unsigned int);
 374
 375   void (*_bfd_coff_reloc16_extra_cases)
 376     (bfd *, struct bfd_link_info *, struct bfd_link_order *, arelent *,
 377            bfd_byte *, unsigned int *, unsigned int *);
 378
 379   int (*_bfd_coff_reloc16_estimate)
 380     (bfd *, asection *, arelent *, unsigned int,
 381             struct bfd_link_info *);
 382
 383   enum coff_symbol_classification (*_bfd_coff_classify_symbol)
 384     (bfd *, struct internal_syment *);
 385
 386   bfd_boolean (*_bfd_coff_compute_section_file_positions)
 387     (bfd *);
 388
 389   bfd_boolean (*_bfd_coff_start_final_link)
 390     (bfd *, struct bfd_link_info *);
 391
 392   bfd_boolean (*_bfd_coff_relocate_section)
 393     (bfd *, struct bfd_link_info *, bfd *, asection *, bfd_byte *,
 394             struct internal_reloc *, struct internal_syment *, asection **);
 395
 396   reloc_howto_type *(*_bfd_coff_rtype_to_howto)
 397     (bfd *, asection *, struct internal_reloc *,
 398             struct coff_link_hash_entry *, struct internal_syment *,
 399             bfd_vma *);
 400
 401   bfd_boolean (*_bfd_coff_adjust_symndx)
 402     (bfd *, struct bfd_link_info *, bfd *, asection *,
 403             struct internal_reloc *, bfd_boolean *);
 404
 405   bfd_boolean (*_bfd_coff_link_add_one_symbol)
 406     (struct bfd_link_info *, bfd *, const char *, flagword,
 407             asection *, bfd_vma, const char *, bfd_boolean, bfd_boolean,
 408             struct bfd_link_hash_entry **);
 409
 410   bfd_boolean (*_bfd_coff_link_output_has_begun)
 411     (bfd *, struct coff_final_link_info *);
 412
 413   bfd_boolean (*_bfd_coff_final_link_postscript)
 414     (bfd *, struct coff_final_link_info *);
 415
 416 @} bfd_coff_backend_data;
 417
 418 #define coff_backend_info(abfd) \
 419   ((bfd_coff_backend_data *) (abfd)->xvec->backend_data)
 420
 421 #define bfd_coff_swap_aux_in(a,e,t,c,ind,num,i) \
 422   ((coff_backend_info (a)->_bfd_coff_swap_aux_in) (a,e,t,c,ind,num,i))
 423
 424 #define bfd_coff_swap_sym_in(a,e,i) \
 425   ((coff_backend_info (a)->_bfd_coff_swap_sym_in) (a,e,i))
 426
 427 #define bfd_coff_swap_lineno_in(a,e,i) \
 428   ((coff_backend_info ( a)->_bfd_coff_swap_lineno_in) (a,e,i))
 429
 430 #define bfd_coff_swap_reloc_out(abfd, i, o) \
 431   ((coff_backend_info (abfd)->_bfd_coff_swap_reloc_out) (abfd, i, o))
 432
 433 #define bfd_coff_swap_lineno_out(abfd, i, o) \
 434   ((coff_backend_info (abfd)->_bfd_coff_swap_lineno_out) (abfd, i, o))
 435
 436 #define bfd_coff_swap_aux_out(a,i,t,c,ind,num,o) \
 437   ((coff_backend_info (a)->_bfd_coff_swap_aux_out) (a,i,t,c,ind,num,o))
 438
 439 #define bfd_coff_swap_sym_out(abfd, i,o) \
 440   ((coff_backend_info (abfd)->_bfd_coff_swap_sym_out) (abfd, i, o))
 441
 442 #define bfd_coff_swap_scnhdr_out(abfd, i,o) \
 443   ((coff_backend_info (abfd)->_bfd_coff_swap_scnhdr_out) (abfd, i, o))
 444
 445 #define bfd_coff_swap_filehdr_out(abfd, i,o) \
 446   ((coff_backend_info (abfd)->_bfd_coff_swap_filehdr_out) (abfd, i, o))
 447
 448 #define bfd_coff_swap_aouthdr_out(abfd, i,o) \
 449   ((coff_backend_info (abfd)->_bfd_coff_swap_aouthdr_out) (abfd, i, o))
 450
 451 #define bfd_coff_filhsz(abfd) (coff_backend_info (abfd)->_bfd_filhsz)
 452 #define bfd_coff_aoutsz(abfd) (coff_backend_info (abfd)->_bfd_aoutsz)
 453 #define bfd_coff_scnhsz(abfd) (coff_backend_info (abfd)->_bfd_scnhsz)
 454 #define bfd_coff_symesz(abfd) (coff_backend_info (abfd)->_bfd_symesz)
 455 #define bfd_coff_auxesz(abfd) (coff_backend_info (abfd)->_bfd_auxesz)
 456 #define bfd_coff_relsz(abfd)  (coff_backend_info (abfd)->_bfd_relsz)
 457 #define bfd_coff_linesz(abfd) (coff_backend_info (abfd)->_bfd_linesz)
 458 #define bfd_coff_filnmlen(abfd) (coff_backend_info (abfd)->_bfd_filnmlen)
 459 #define bfd_coff_long_filenames(abfd) \
 460   (coff_backend_info (abfd)->_bfd_coff_long_filenames)
 461 #define bfd_coff_long_section_names(abfd) \
 462   (coff_backend_info (abfd)->_bfd_coff_long_section_names)
 463 #define bfd_coff_default_section_alignment_power(abfd) \
 464   (coff_backend_info (abfd)->_bfd_coff_default_section_alignment_power)
 465 #define bfd_coff_swap_filehdr_in(abfd, i,o) \
 466   ((coff_backend_info (abfd)->_bfd_coff_swap_filehdr_in) (abfd, i, o))
 467
 468 #define bfd_coff_swap_aouthdr_in(abfd, i,o) \
 469   ((coff_backend_info (abfd)->_bfd_coff_swap_aouthdr_in) (abfd, i, o))
 470
 471 #define bfd_coff_swap_scnhdr_in(abfd, i,o) \
 472   ((coff_backend_info (abfd)->_bfd_coff_swap_scnhdr_in) (abfd, i, o))
 473
 474 #define bfd_coff_swap_reloc_in(abfd, i, o) \
 475   ((coff_backend_info (abfd)->_bfd_coff_swap_reloc_in) (abfd, i, o))
 476
 477 #define bfd_coff_bad_format_hook(abfd, filehdr) \
 478   ((coff_backend_info (abfd)->_bfd_coff_bad_format_hook) (abfd, filehdr))
 479
 480 #define bfd_coff_set_arch_mach_hook(abfd, filehdr)\
 481   ((coff_backend_info (abfd)->_bfd_coff_set_arch_mach_hook) (abfd, filehdr))
 482 #define bfd_coff_mkobject_hook(abfd, filehdr, aouthdr)\
 483   ((coff_backend_info (abfd)->_bfd_coff_mkobject_hook)\
 484    (abfd, filehdr, aouthdr))
 485
 486 #define bfd_coff_styp_to_sec_flags_hook(abfd, scnhdr, name, section, flags_ptr)\
 487   ((coff_backend_info (abfd)->_bfd_styp_to_sec_flags_hook)\
 488    (abfd, scnhdr, name, section, flags_ptr))
 489
 490 #define bfd_coff_set_alignment_hook(abfd, sec, scnhdr)\
 491   ((coff_backend_info (abfd)->_bfd_set_alignment_hook) (abfd, sec, scnhdr))
 492
 493 #define bfd_coff_slurp_symbol_table(abfd)\
 494   ((coff_backend_info (abfd)->_bfd_coff_slurp_symbol_table) (abfd))
 495
 496 #define bfd_coff_symname_in_debug(abfd, sym)\
 497   ((coff_backend_info (abfd)->_bfd_coff_symname_in_debug) (abfd, sym))
 498
 499 #define bfd_coff_force_symnames_in_strings(abfd)\
 500   (coff_backend_info (abfd)->_bfd_coff_force_symnames_in_strings)
 501
 502 #define bfd_coff_debug_string_prefix_length(abfd)\
 503   (coff_backend_info (abfd)->_bfd_coff_debug_string_prefix_length)
 504
 505 #define bfd_coff_print_aux(abfd, file, base, symbol, aux, indaux)\
 506   ((coff_backend_info (abfd)->_bfd_coff_print_aux)\
 507    (abfd, file, base, symbol, aux, indaux))
 508
 509 #define bfd_coff_reloc16_extra_cases(abfd, link_info, link_order,\
 510                                      reloc, data, src_ptr, dst_ptr)\
 511   ((coff_backend_info (abfd)->_bfd_coff_reloc16_extra_cases)\
 512    (abfd, link_info, link_order, reloc, data, src_ptr, dst_ptr))
 513
 514 #define bfd_coff_reloc16_estimate(abfd, section, reloc, shrink, link_info)\
 515   ((coff_backend_info (abfd)->_bfd_coff_reloc16_estimate)\
 516    (abfd, section, reloc, shrink, link_info))
 517
 518 #define bfd_coff_classify_symbol(abfd, sym)\
 519   ((coff_backend_info (abfd)->_bfd_coff_classify_symbol)\
 520    (abfd, sym))
 521
 522 #define bfd_coff_compute_section_file_positions(abfd)\
 523   ((coff_backend_info (abfd)->_bfd_coff_compute_section_file_positions)\
 524    (abfd))
 525
 526 #define bfd_coff_start_final_link(obfd, info)\
 527   ((coff_backend_info (obfd)->_bfd_coff_start_final_link)\
 528    (obfd, info))
 529 #define bfd_coff_relocate_section(obfd,info,ibfd,o,con,rel,isyms,secs)\
 530   ((coff_backend_info (ibfd)->_bfd_coff_relocate_section)\
 531    (obfd, info, ibfd, o, con, rel, isyms, secs))
 532 #define bfd_coff_rtype_to_howto(abfd, sec, rel, h, sym, addendp)\
 533   ((coff_backend_info (abfd)->_bfd_coff_rtype_to_howto)\
 534    (abfd, sec, rel, h, sym, addendp))
 535 #define bfd_coff_adjust_symndx(obfd, info, ibfd, sec, rel, adjustedp)\
 536   ((coff_backend_info (abfd)->_bfd_coff_adjust_symndx)\
 537    (obfd, info, ibfd, sec, rel, adjustedp))
 538 #define bfd_coff_link_add_one_symbol(info, abfd, name, flags, section,\
 539                                      value, string, cp, coll, hashp)\
 540   ((coff_backend_info (abfd)->_bfd_coff_link_add_one_symbol)\
 541    (info, abfd, name, flags, section, value, string, cp, coll, hashp))
 542
 543 #define bfd_coff_link_output_has_begun(a,p) \
 544   ((coff_backend_info (a)->_bfd_coff_link_output_has_begun) (a, p))
 545 #define bfd_coff_final_link_postscript(a,p) \
 546   ((coff_backend_info (a)->_bfd_coff_final_link_postscript) (a, p))
 547
 548 @end example
 549 @subsubsection Writing relocations
 550 To write relocations, the back end steps though the
 551 canonical relocation table and create an
 552 @code{internal_reloc}. The symbol index to use is removed from
 553 the @code{offset} field in the symbol table supplied.  The
 554 address comes directly from the sum of the section base
 555 address and the relocation offset; the type is dug directly
 556 from the howto field.  Then the @code{internal_reloc} is
 557 swapped into the shape of an @code{external_reloc} and written
 558 out to disk.
 559
 560 @subsubsection Reading linenumbers
 561 Creating the linenumber table is done by reading in the entire
 562 coff linenumber table, and creating another table for internal use.
 563
 564 A coff linenumber table is structured so that each function
 565 is marked as having a line number of 0. Each line within the
 566 function is an offset from the first line in the function. The
 567 base of the line number information for the table is stored in
 568 the symbol associated with the function.
 569
 570 Note: The PE format uses line number 0 for a flag indicating a
 571 new source file.
 572
 573 The information is copied from the external to the internal
 574 table, and each symbol which marks a function is marked by
 575 pointing its...
 576
 577 How does this work ?
 578
 579 @subsubsection Reading relocations
 580 Coff relocations are easily transformed into the internal BFD form
 581 (@code{arelent}).
 582
 583 Reading a coff relocation table is done in the following stages:
 584
 585 @itemize @bullet
 586
 587 @item
 588 Read the entire coff relocation table into memory.
 589
 590 @item
 591 Process each relocation in turn; first swap it from the
 592 external to the internal form.
 593
 594 @item
 595 Turn the symbol referenced in the relocation's symbol index
 596 into a pointer into the canonical symbol table.
 597 This table is the same as the one returned by a call to
 598 @code{bfd_canonicalize_symtab}. The back end will call that
 599 routine and save the result if a canonicalization hasn't been done.
 600
 601 @item
 602 The reloc index is turned into a pointer to a howto
 603 structure, in a back end specific way. For instance, the 386
 604 and 960 use the @code{r_type} to directly produce an index
 605 into a howto table vector; the 88k subtracts a number from the
 606 @code{r_type} field and creates an addend field.
 607 @end itemize
 608