3.2 a.out backends

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 aoutx.h and other files which derive functions from the base. One derivation file is 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 sunos.c for sun3 and sun4, newsos3.c for the Sony NEWS, and demo64.c for a demonstration of a 64 bit a.out format.

The base 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 aout32.c and aout64.c to form the names aout_32_swap_exec_header_in, aout_64_swap_exec_header_in, etc.

As an example, this is what goes on to make the back end for a sun4, from aout32.c:

       #define ARCH_SIZE 32
       #include "aoutx.h"

Which exports names:

       ...
       aout_32_canonicalize_reloc
       aout_32_find_nearest_line
       aout_32_get_lineno
       aout_32_get_reloc_upper_bound
       ...

from sunos.c:

       #define TARGET_NAME "a.out-sunos-big"
       #define VECNAME    sparc_aout_sunos_be_vec
       #include "aoutf1.h"

requires all the names from aout32.c, and produces the jump vector

       sparc_aout_sunos_be_vec

The 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:

        HOST_PAGE_SIZE
        HOST_SEGMENT_SIZE
        HOST_MACHINE_ARCH       (optional)
        HOST_MACHINE_MACHINE    (optional)
        HOST_TEXT_START_ADDR
        HOST_STACK_END_ADDR

in the file ../include/sys/h-XXX.h (for your host). These values, plus the structures and macros defined in 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 host-aout.c, specify:

       TDEFAULTS = -DDEFAULT_VECTOR=host_aout_big_vec
       TDEPFILES= host-aout.o trad-core.o

in the config/XXX.mt file, and modify configure.ac to use the XXX.mt file (by setting "bfd_target=XXX") when your configuration is selected.

3.2.1 Relocations

Description
The file aoutx.h provides for both the standard and 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.

3.2.2 Internal entry points

Description
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).

3.2.2.1 aout_size_swap_exec_header_in

Synopsis

void aout_size_swap_exec_header_in,
   (bfd *abfd,
    struct external_exec *bytes,
    struct internal_exec *execp);

Description
Swap the information in an executable header raw_bytes taken from a raw byte stream memory image into the internal exec header structure execp.

3.2.2.2 aout_size_swap_exec_header_out

Synopsis

void aout_size_swap_exec_header_out
   (bfd *abfd,
    struct internal_exec *execp,
    struct external_exec *raw_bytes);

Description
Swap the information in an internal exec header structure execp into the buffer raw_bytes ready for writing to disk.

3.2.2.3 aout_size_some_aout_object_p

Synopsis

const bfd_target *aout_size_some_aout_object_p
   (bfd *abfd,
    struct internal_exec *execp,
    const bfd_target *(*callback_to_real_object_p) (bfd *));

Description
Some a.out variant thinks that the file open in 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.

3.2.2.4 aout_size_mkobject

Synopsis

bfd_boolean aout_size_mkobject, (bfd *abfd);

Description
Initialize BFD abfd for use with a.out files.

3.2.2.5 aout_size_machine_type

Synopsis

enum machine_type  aout_size_machine_type
   (enum bfd_architecture arch,
    unsigned long machine,
    bfd_boolean *unknown);

Description
Keep track of machine architecture and machine type for a.out’s. Return the machine_type for a particular architecture and machine, or 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.

3.2.2.6 aout_size_set_arch_mach

Synopsis

bfd_boolean aout_size_set_arch_mach,
   (bfd *,
    enum bfd_architecture arch,
    unsigned long machine);

Description
Set the architecture and the machine of the BFD abfd to the values arch and machine. Verify that abfd’s format can support the architecture required.

3.2.2.7 aout_size_new_section_hook

Synopsis

bfd_boolean aout_size_new_section_hook,
   (bfd *abfd,
    asection *newsect);

Description
Called by the BFD in response to a bfd_make_section request.