Initial revision
This commit is contained in:
ceriel
parent
3c60c1918e
commit
4b489cd254
1 changed files with 316 additions and 0 deletions
316
util/led/ack.out.5
Normal file
316
util/led/ack.out.5
Normal file
|
|
@ -0,0 +1,316 @@
|
|||
.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)
|
||||
Loading…
Reference in a new issue