--- /dev/null
+.TH "ACK.OUT" 5ACK "July 29, 1986"
+.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
+#define ushort unsigned\ short
+.PP
+.nf
+struct outhead {
+ ushort oh_magic; /* magic number */
+ ushort oh_stamp; /* version stamp */
+ ushort oh_flags; /* several format flags */
+ ushort oh_nsect; /* number of outsect structures */
+ ushort oh_nrelo; /* number of outrelo structures */
+ ushort 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 */
+ ushort 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 /* last user section */
+.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
+ ushort on_type; /* symbol type */
+ ushort 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.
+.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)
public / ack.git / commitdiff