diff options
Diffstat (limited to 'contrib/binutils/bfd/doc/aoutx.texi')
| -rw-r--r-- | contrib/binutils/bfd/doc/aoutx.texi | 211 |
1 files changed, 211 insertions, 0 deletions
diff --git a/contrib/binutils/bfd/doc/aoutx.texi b/contrib/binutils/bfd/doc/aoutx.texi new file mode 100644 index 0000000..a35fe9b --- /dev/null +++ b/contrib/binutils/bfd/doc/aoutx.texi @@ -0,0 +1,211 @@ +@section a.out backends + +@* +@strong{Description}@* +BFD supports a number of different flavours of a.out format, +though the major differences are only the sizes of the +structures on disk, and the shape of the relocation +information. + +The support is split into a basic support file @file{aoutx.h} +and other files which derive functions from the base. One +derivation file is @file{aoutf1.h} (for a.out flavour 1), and +adds to the basic a.out functions support for sun3, sun4, 386 +and 29k a.out files, to create a target jump vector for a +specific target. + +This information is further split out into more specific files +for each machine, including @file{sunos.c} for sun3 and sun4, +@file{newsos3.c} for the Sony NEWS, and @file{demo64.c} for a +demonstration of a 64 bit a.out format. + +The base file @file{aoutx.h} defines general mechanisms for +reading and writing records to and from disk and various +other methods which BFD requires. It is included by +@file{aout32.c} and @file{aout64.c} to form the names +@code{aout_32_swap_exec_header_in}, @code{aout_64_swap_exec_header_in}, etc. + +As an example, this is what goes on to make the back end for a +sun4, from @file{aout32.c}: + +@example + #define ARCH_SIZE 32 + #include "aoutx.h" +@end example + +Which exports names: + +@example + ... + aout_32_canonicalize_reloc + aout_32_find_nearest_line + aout_32_get_lineno + aout_32_get_reloc_upper_bound + ... +@end example + +from @file{sunos.c}: + +@example + #define TARGET_NAME "a.out-sunos-big" + #define VECNAME sunos_big_vec + #include "aoutf1.h" +@end example + +requires all the names from @file{aout32.c}, and produces the jump vector + +@example + sunos_big_vec +@end example + +The file @file{host-aout.c} is a special case. It is for a large set +of hosts that use ``more or less standard'' a.out files, and +for which cross-debugging is not interesting. It uses the +standard 32-bit a.out support routines, but determines the +file offsets and addresses of the text, data, and BSS +sections, the machine architecture and machine type, and the +entry point address, in a host-dependent manner. Once these +values have been determined, generic code is used to handle +the object file. + +When porting it to run on a new system, you must supply: + +@example + HOST_PAGE_SIZE + HOST_SEGMENT_SIZE + HOST_MACHINE_ARCH (optional) + HOST_MACHINE_MACHINE (optional) + HOST_TEXT_START_ADDR + HOST_STACK_END_ADDR +@end example + +in the file @file{../include/sys/h-@var{XXX}.h} (for your host). These +values, plus the structures and macros defined in @file{a.out.h} on +your host system, will produce a BFD target that will access +ordinary a.out files on your host. To configure a new machine +to use @file{host-aout.c}, specify: + +@example + TDEFAULTS = -DDEFAULT_VECTOR=host_aout_big_vec + TDEPFILES= host-aout.o trad-core.o +@end example + +in the @file{config/@var{XXX}.mt} file, and modify @file{configure.in} +to use the +@file{@var{XXX}.mt} file (by setting "@code{bfd_target=XXX}") when your +configuration is selected. +@* +@subsection Relocations + +@* +@strong{Description}@* +The file @file{aoutx.h} provides for both the @emph{standard} +and @emph{extended} forms of a.out relocation records. + +The standard records contain only an +address, a symbol index, and a type field. The extended records +(used on 29ks and sparcs) also have a full integer for an +addend. +@* +@subsection Internal entry points + +@* +@strong{Description}@* +@file{aoutx.h} exports several routines for accessing the +contents of an a.out file, which are gathered and exported in +turn by various format specific files (eg sunos.c). +@* +@findex aout_@var{size}_swap_exec_header_in +@subsubsection @code{aout_@var{size}_swap_exec_header_in} +@strong{Synopsis} +@example +void aout_@var{size}_swap_exec_header_in, + (bfd *abfd, + struct external_exec *raw_bytes, + struct internal_exec *execp); +@end example +@strong{Description}@* +Swap the information in an executable header @var{raw_bytes} taken +from a raw byte stream memory image into the internal exec header +structure @var{execp}. +@* +@findex aout_@var{size}_swap_exec_header_out +@subsubsection @code{aout_@var{size}_swap_exec_header_out} +@strong{Synopsis} +@example +void aout_@var{size}_swap_exec_header_out + (bfd *abfd, + struct internal_exec *execp, + struct external_exec *raw_bytes); +@end example +@strong{Description}@* +Swap the information in an internal exec header structure +@var{execp} into the buffer @var{raw_bytes} ready for writing to disk. +@* +@findex aout_@var{size}_some_aout_object_p +@subsubsection @code{aout_@var{size}_some_aout_object_p} +@strong{Synopsis} +@example +const bfd_target *aout_@var{size}_some_aout_object_p + (bfd *abfd, + const bfd_target *(*callback_to_real_object_p)()); +@end example +@strong{Description}@* +Some a.out variant thinks that the file open in @var{abfd} +checking is an a.out file. Do some more checking, and set up +for access if it really is. Call back to the calling +environment's "finish up" function just before returning, to +handle any last-minute setup. +@* +@findex aout_@var{size}_mkobject +@subsubsection @code{aout_@var{size}_mkobject} +@strong{Synopsis} +@example +boolean aout_@var{size}_mkobject, (bfd *abfd); +@end example +@strong{Description}@* +Initialize BFD @var{abfd} for use with a.out files. +@* +@findex aout_@var{size}_machine_type +@subsubsection @code{aout_@var{size}_machine_type} +@strong{Synopsis} +@example +enum machine_type aout_@var{size}_machine_type + (enum bfd_architecture arch, + unsigned long machine)); + @end example +@strong{Description}@* +Keep track of machine architecture and machine type for +a.out's. Return the @code{machine_type} for a particular +architecture and machine, or @code{M_UNKNOWN} if that exact architecture +and machine can't be represented in a.out format. + +If the architecture is understood, machine type 0 (default) +is always understood. +@* +@findex aout_@var{size}_set_arch_mach +@subsubsection @code{aout_@var{size}_set_arch_mach} +@strong{Synopsis} +@example +boolean aout_@var{size}_set_arch_mach, + (bfd *, + enum bfd_architecture arch, + unsigned long machine)); + @end example +@strong{Description}@* +Set the architecture and the machine of the BFD @var{abfd} to the +values @var{arch} and @var{machine}. Verify that @var{abfd}'s format +can support the architecture required. +@* +@findex aout_@var{size}_new_section_hook +@subsubsection @code{aout_@var{size}_new_section_hook} +@strong{Synopsis} +@example +boolean aout_@var{size}_new_section_hook, + (bfd *abfd, + asection *newsect)); + @end example +@strong{Description}@* +Called by the BFD in response to a @code{bfd_make_section} +request. +@* |
