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