contrib/binutils-2.17/bfd/doc/aoutx.texi

   1 @section a.out backends
   2
   3
   4 @strong{Description}@*
   5 BFD supports a number of different flavours of a.out format,
   6 though the major differences are only the sizes of the
   7 structures on disk, and the shape of the relocation
   8 information.
   9
  10 The support is split into a basic support file @file{aoutx.h}
  11 and other files which derive functions from the base. One
  12 derivation file is @file{aoutf1.h} (for a.out flavour 1), and
  13 adds to the basic a.out functions support for sun3, sun4, 386
  14 and 29k a.out files, to create a target jump vector for a
  15 specific target.
  16
  17 This information is further split out into more specific files
  18 for each machine, including @file{sunos.c} for sun3 and sun4,
  19 @file{newsos3.c} for the Sony NEWS, and @file{demo64.c} for a
  20 demonstration of a 64 bit a.out format.
  21
  22 The base file @file{aoutx.h} defines general mechanisms for
  23 reading and writing records to and from disk and various
  24 other methods which BFD requires. It is included by
  25 @file{aout32.c} and @file{aout64.c} to form the names
  26 @code{aout_32_swap_exec_header_in}, @code{aout_64_swap_exec_header_in}, etc.
  27
  28 As an example, this is what goes on to make the back end for a
  29 sun4, from @file{aout32.c}:
  30
  31 @example
  32        #define ARCH_SIZE 32
  33        #include "aoutx.h"
  34 @end example
  35
  36 Which exports names:
  37
  38 @example
  39        ...
  40        aout_32_canonicalize_reloc
  41        aout_32_find_nearest_line
  42        aout_32_get_lineno
  43        aout_32_get_reloc_upper_bound
  44        ...
  45 @end example
  46
  47 from @file{sunos.c}:
  48
  49 @example
  50        #define TARGET_NAME "a.out-sunos-big"
  51        #define VECNAME    sunos_big_vec
  52        #include "aoutf1.h"
  53 @end example
  54
  55 requires all the names from @file{aout32.c}, and produces the jump vector
  56
  57 @example
  58        sunos_big_vec
  59 @end example
  60
  61 The file @file{host-aout.c} is a special case.  It is for a large set
  62 of hosts that use ``more or less standard'' a.out files, and
  63 for which cross-debugging is not interesting.  It uses the
  64 standard 32-bit a.out support routines, but determines the
  65 file offsets and addresses of the text, data, and BSS
  66 sections, the machine architecture and machine type, and the
  67 entry point address, in a host-dependent manner.  Once these
  68 values have been determined, generic code is used to handle
  69 the  object file.
  70
  71 When porting it to run on a new system, you must supply:
  72
  73 @example
  74         HOST_PAGE_SIZE
  75         HOST_SEGMENT_SIZE
  76         HOST_MACHINE_ARCH       (optional)
  77         HOST_MACHINE_MACHINE    (optional)
  78         HOST_TEXT_START_ADDR
  79         HOST_STACK_END_ADDR
  80 @end example
  81
  82 in the file @file{../include/sys/h-@var{XXX}.h} (for your host).  These
  83 values, plus the structures and macros defined in @file{a.out.h} on
  84 your host system, will produce a BFD target that will access
  85 ordinary a.out files on your host. To configure a new machine
  86 to use @file{host-aout.c}, specify:
  87
  88 @example
  89        TDEFAULTS = -DDEFAULT_VECTOR=host_aout_big_vec
  90        TDEPFILES= host-aout.o trad-core.o
  91 @end example
  92
  93 in the @file{config/@var{XXX}.mt} file, and modify @file{configure.in}
  94 to use the
  95 @file{@var{XXX}.mt} file (by setting "@code{bfd_target=XXX}") when your
  96 configuration is selected.
  97
  98 @subsection Relocations
  99
 100
 101 @strong{Description}@*
 102 The file @file{aoutx.h} provides for both the @emph{standard}
 103 and @emph{extended} forms of a.out relocation records.
 104
 105 The standard records contain only an
 106 address, a symbol index, and a type field. The extended records
 107 (used on 29ks and sparcs) also have a full integer for an
 108 addend.
 109
 110 @subsection Internal entry points
 111
 112
 113 @strong{Description}@*
 114 @file{aoutx.h} exports several routines for accessing the
 115 contents of an a.out file, which are gathered and exported in
 116 turn by various format specific files (eg sunos.c).
 117
 118 @findex aout_@var{size}_swap_exec_header_in
 119 @subsubsection @code{aout_@var{size}_swap_exec_header_in}
 120 @strong{Synopsis}
 121 @example
 122 void aout_@var{size}_swap_exec_header_in,
 123    (bfd *abfd,
 124     struct external_exec *bytes,
 125     struct internal_exec *execp);
 126 @end example
 127 @strong{Description}@*
 128 Swap the information in an executable header @var{raw_bytes} taken
 129 from a raw byte stream memory image into the internal exec header
 130 structure @var{execp}.
 131
 132 @findex aout_@var{size}_swap_exec_header_out
 133 @subsubsection @code{aout_@var{size}_swap_exec_header_out}
 134 @strong{Synopsis}
 135 @example
 136 void aout_@var{size}_swap_exec_header_out
 137    (bfd *abfd,
 138     struct internal_exec *execp,
 139     struct external_exec *raw_bytes);
 140 @end example
 141 @strong{Description}@*
 142 Swap the information in an internal exec header structure
 143 @var{execp} into the buffer @var{raw_bytes} ready for writing to disk.
 144
 145 @findex aout_@var{size}_some_aout_object_p
 146 @subsubsection @code{aout_@var{size}_some_aout_object_p}
 147 @strong{Synopsis}
 148 @example
 149 const bfd_target *aout_@var{size}_some_aout_object_p
 150    (bfd *abfd,
 151     struct internal_exec *execp,
 152     const bfd_target *(*callback_to_real_object_p) (bfd *));
 153 @end example
 154 @strong{Description}@*
 155 Some a.out variant thinks that the file open in @var{abfd}
 156 checking is an a.out file.  Do some more checking, and set up
 157 for access if it really is.  Call back to the calling
 158 environment's "finish up" function just before returning, to
 159 handle any last-minute setup.
 160
 161 @findex aout_@var{size}_mkobject
 162 @subsubsection @code{aout_@var{size}_mkobject}
 163 @strong{Synopsis}
 164 @example
 165 bfd_boolean aout_@var{size}_mkobject, (bfd *abfd);
 166 @end example
 167 @strong{Description}@*
 168 Initialize BFD @var{abfd} for use with a.out files.
 169
 170 @findex aout_@var{size}_machine_type
 171 @subsubsection @code{aout_@var{size}_machine_type}
 172 @strong{Synopsis}
 173 @example
 174 enum machine_type  aout_@var{size}_machine_type
 175    (enum bfd_architecture arch,
 176     unsigned long machine,
 177     bfd_boolean *unknown);
 178 @end example
 179 @strong{Description}@*
 180 Keep track of machine architecture and machine type for
 181 a.out's. Return the @code{machine_type} for a particular
 182 architecture and machine, or @code{M_UNKNOWN} if that exact architecture
 183 and machine can't be represented in a.out format.
 184
 185 If the architecture is understood, machine type 0 (default)
 186 is always understood.
 187
 188 @findex aout_@var{size}_set_arch_mach
 189 @subsubsection @code{aout_@var{size}_set_arch_mach}
 190 @strong{Synopsis}
 191 @example
 192 bfd_boolean aout_@var{size}_set_arch_mach,
 193    (bfd *,
 194     enum bfd_architecture arch,
 195     unsigned long machine);
 196 @end example
 197 @strong{Description}@*
 198 Set the architecture and the machine of the BFD @var{abfd} to the
 199 values @var{arch} and @var{machine}.  Verify that @var{abfd}'s format
 200 can support the architecture required.
 201
 202 @findex aout_@var{size}_new_section_hook
 203 @subsubsection @code{aout_@var{size}_new_section_hook}
 204 @strong{Synopsis}
 205 @example
 206 bfd_boolean aout_@var{size}_new_section_hook,
 207    (bfd *abfd,
 208     asection *newsect);
 209 @end example
 210 @strong{Description}@*
 211 Called by the BFD in response to a @code{bfd_make_section}
 212 request.
 213