123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317 |
- .TH "ACK.OUT" 5 "$Revision$"
- .ad
- .SH NAME
- ack.out\ \-\ ACK-assembler and link editor output
- .SH SYNOPSIS
- .B #include <out.h>
- .SH DESCRIPTION
- This manual page discusses the format of object files, as generated by ACK
- assemblers and the link editor LED.
- The format is designed to be compact, machine independent, and
- portable from one machine to another,
- so that an object file can be produced on one machine, and
- further processed on another.
- .ta \w'#define x'u +\w'XXXXXXXX'u +\w'XXXXXXXXXXX'u
- .PP
- In the following discussion, some structures are defined using
- \fBlong\fR and \fBshort\fR as type indicators.
- It is assumed that the size of a short is 2 bytes (chars) and that the
- size of a long is 4 bytes.
- However, these types
- have a machine dependent byte and word order.
- Therefore, a machine independent representation is chosen for the
- object format:
- a long consists of two shorts, of which the least significant one
- comes first, and a short consists of two bytes, of which the
- least significant one comes first.
- There is no alignment between various parts and structures in the object
- file.
- .PP
- In general, an object file consists of the following parts:
- .PP
- .nf
- \- a file header
- \- a number of section headers
- \- the sections themselves
- \- a number of relocation structures
- \- a symbol table
- \- a string area containing the names from the symbol table
- .fi
- .PP
- .B The header.
- .br
- The header of an object file has the following structure:
- .PP
- .nf
- struct outhead {
- unsigned short oh_magic; /* magic number */
- unsigned short oh_stamp; /* version stamp */
- unsigned short oh_flags; /* several format flags */
- unsigned short oh_nsect; /* number of outsect structures */
- unsigned short oh_nrelo; /* number of outrelo structures */
- unsigned short oh_nname; /* number of outname structures */
- long oh_nemit; /* length of sections */
- long oh_nchar; /* size of string area */
- };
- .fi
- .PP
- #define HF_LINK 0x0004 /* unresolved references left */
- .PP
- The fields of this structure have the following purpose:
- .nr x \w'oh_magic\ \ \ 'u
- .IP oh_magic \nxu
- A magic number, indicating that this is an object file.
- .IP oh_stamp \nxu
- A version stamp, used to detect obsolete versions of object files.
- .IP oh_flags \nxu
- Currently only used for the HF_LINK flag. When this flag is set, the
- object file contains unresolved references.
- .IP oh_nsect \nxu
- The number of sections and section description structures, later on
- referred to as \fIoutsect\fR structures.
- Usually, there are only a few sections, f.i. a TEXT section,
- a ROM section, a DATA section and a BSS section.
- Notice that neither the assemblers nor LED know more about them than their
- names.
- .IP oh_nrelo \nxu
- The number of relocation structures, later on referred to as \fIoutrelo\fR
- structures.
- .IP oh_nname \nxu
- The number of symbol table structures, later on referred to as \fIoutname\fR
- structures.
- .IP oh_nemit \nxu
- The total number of bytes in this object file used for the sections themselves.
- This field is used to find the relocation and symbol table structures fast.
- .IP oh_nchar \nxu
- The size of the string area (the number of bytes).
- .PP
- .B The section descriptions.
- .br
- The next part of an object file contains the outsect-structures.
- An outsect structure has the following layout:
- .PP
- .nf
- struct outsect {
- long os_base; /* start address in machine */
- long os_size; /* section size in machine */
- long os_foff; /* start address in file */
- long os_flen; /* section size in file */
- long os_lign; /* section alignment */
- };
- .fi
- .PP
- The fields in this structure have the following purpose:
- .IP os_base \nxu
- The start address of this section in the target machine.
- This address is determined by LED,
- when producing a non-relocatable object file.
- It is ignored for relocatable object files.
- .IP os_size \nxu
- The size of this section on the target machine.
- .IP os_foff \nxu
- The start address of this section in this file.
- .IP os_flen \nxu
- The size of this section in this file.
- This field does not have to have
- the same value as the \fIos_size\fR field!
- For instance, an uninitialized
- data section probably has \fIos_flen\fR set to 0.
- Notice that
- the \fIoh_nemit\fR field of the header contains
- the sum of all the \fIos_flen\fR fields.
- .IP os_lign \nxu
- The alignment requirement for this section. The requirement is that
- the loader must leave
- .IP "" \nxu
- \ \ \ \ \ \ \ \fIos_base\fR \fBmod\fR \fIos_lign\fR = 0
- .IP "" \nxu
- in tact.
- .PP
- .B The sections.
- .br
- The next part of an object file contains the sections themselves.
- Usually, the LED program places the sections right behind one another in the
- target machine, taking the
- alignment requirements into account. However, the user is allowed to give
- the start addresses of each section. But if the user gave a start address for
- say section 2, but not for section 3, section 3 will be put
- right behind section 2.
- .PP
- .B The relocation structures.
- .br
- Relocation information is information that allows a program like LED
- to combine several object files and produce an executable binary
- if there are no unresolved references.
- If relocation information is present, it amounts to 8 bytes per
- relocatable datum. The information has the following structure:
- .PP
- .nf
- struct outrelo {
- char or_type; /* type of reference */
- char or_sect; /* referencing section */
- unsigned short or_nami; /* referenced symbol index */
- long or_addr; /* referencing address */
- };
- .fi
- .PP
- .nf
- /*
- * relocation type bits
- */
- #define RELSZ 0x07 /* relocation length */
- #define RELO1 0x01 /* 1 byte */
- #define RELO2 0x02 /* 2 bytes */
- #define RELO4 0x04 /* 4 bytes */
- #define RELPC 0x08 /* pc relative */
- #define RELBR 0x10 /* High order byte lowest address. */
- #define RELWR 0x20 /* High order word lowest address. */
- .fi
- .PP
- .nf
- /*
- * section type bits and fields
- */
- #define S_TYP 0x007F /* undefined, absolute or relative */
- #define S_EXT 0x0080 /* external flag */
- #define S_ETC 0x7F00 /* for symbolic debug, bypassing 'as' */
- .fi
- .PP
- .nf
- /*
- * S_TYP field values
- */
- #define S_UND 0x0000 /* undefined item */
- #define S_ABS 0x0001 /* absolute item */
- #define S_MIN 0x0002 /* first user section */
- #define S_MAX (S_TYP-1) /* last user section */
- #define S_CRS S_TYP /* reference to other namelist item */
- .fi
- .PP
- The fields of this structure have the following purpose:
- .IP or_type \nxu
- Contains several flags: One of RELO1, RELO2 and RELO4 is set, indicating the
- size of the relocatable datum, RELPC is set when the datum is
- relocated pc relative, RELBR and RELWR indicate byte and word order of
- the relocatable datum. RELBR and RELWR are needed here. It is not sufficient
- to have flags for them in the header of the object file, because some
- machines (NS 32016) use several of the possible combinations in their
- instruction encoding.
- .IP or_sect \nxu
- Contains the section number of the referenc\fIing\fR section. This is a number
- that lies between S_MIN and S_MAX. The section indicated with number S_MIN
- is the first section in the sections-section, etc.
- .IP or_addr \nxu
- Contains the address of the relocatable datum, in the form of an
- offset from the base of the section indicated in the \fIor_sect\fR field.
- .IP or_nami \nxu
- Usually contains the index of the referenced symbol in the symbol table,
- starting at 0.
- In this case, the reference is to an undefined external symbol, a common
- symbol, or a section name. The relocatable datum then contains
- an offset from the indicated symbol or the start of the indicated section.
- It may, however, also have the same value as
- the \fIoh_nname\fR field of the header. In this case the relocatable datum
- is an absolute number, and the datum is relocated pc relative.
- The relocatable datum must then be relocated with respect to the
- base address of its section.
- .PP
- .B The symbol table.
- .br
- This table contains definitions of symbols. It is referred to by
- outrelo-structures, and can be used by debuggers.
- Entries in this table have the following structure:
- .PP
- .nf
- struct outname {
- union {
- char *on_ptr; /* symbol name (in core) */
- long on_off; /* symbol name (in file) */
- } on_u;
- #define on_mptr on_u.on_ptr
- #define on_foff on_u.on_off
- unsigned short on_type; /* symbol type */
- unsigned short on_desc; /* debug info */
- long on_valu; /* symbol value */
- };
- .fi
- .PP
- .nf
- /*
- * S_ETC field values
- */
- #define S_SCT 0x0100 /* section names */
- #define S_LIN 0x0200 /* hll source line item */
- #define S_FIL 0x0300 /* hll source file item */
- #define S_MOD 0x0400 /* ass source file item */
- #define S_COM 0x1000 /* Common name */
- .fi
- .PP
- The members of this structure have the following purpose:
- .IP on_foff \nxu
- Contains the offset of the name from the beginning of the file. The name
- extends from the offset to the next null byte.
- .IP on_type \nxu
- The S_TYP field of this member contains the section number of the symbol.
- Here, this number may be S_ABS for an absolute item, or S_UND, for an
- undefined item. The S_EXT flag is set in this member if the symbol is external.
- The S_ETC field has the following flags:
- S_SCT is set if the symbol represents a section name,
- S_COM is set if the symbol represents a common name,
- S_LIN is set if the symbol refers to a high level language source line item,
- S_FIL is set if the symbol refers to a high level language source file item,
- and S_MOD is set if the symbol refers to an assembler source file item.
- .IP on_desc \nxu
- Currently not used.
- .IP on_valu \nxu
- Is not used if the symbol refers to an undefined item. For absolute items
- it contains the value, for common names it contains the size, and
- for anything else it contains the offset from the beginning of the section.
- In a fully linked binary, the beginning of the section is added.
- .PP
- .B The string area.
- .br
- The last part of an object file contains the name list. This is just a
- sequence of null-terminated strings.
- .PP
- The relocation information, the symbol table, and the name list do not
- have to be present, but then of course we do not have a relocatable
- object file.
- .PP
- .B Miscellaneous defines
- .br
- The following miscellaneous defines might come in handy when reading
- object files:
- .PP
- .nf
- /*
- * structure format strings
- */
- #define SF_HEAD "22222244"
- #define SF_SECT "44444"
- #define SF_RELO "1124"
- #define SF_NAME "4224"
- .fi
- .PP
- .nf
- /*
- * structure sizes (bytes in file; add digits in SF_*)
- */
- #define SZ_HEAD 20
- #define SZ_SECT 20
- #define SZ_RELO 8
- #define SZ_NAME 12
- .fi
- .PP
- .nf
- /*
- * file access macros
- */
- #define BADMAGIC(x) ((x).oh_magic!=O_MAGIC)
- #define OFF_SECT(x) SZ_HEAD
- #define OFF_EMIT(x) (OFF_SECT(x) + ((long)(x).oh_nsect * SZ_SECT))
- #define OFF_RELO(x) (OFF_EMIT(x) + (x).oh_nemit)
- #define OFF_NAME(x) (OFF_RELO(x) + ((long)(x).oh_nrelo * SZ_RELO))
- #define OFF_CHAR(x) (OFF_NAME(x) + ((long)(x).oh_nname * SZ_NAME))
- .fi
- .SH "SEE ALSO"
- led(6), object(3)
|