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