util/led/ack.out.5

   1 .TH "ACK.OUT" 5 "$Revision: 1.7 $"
   2 .ad
   3 .SH NAME
   4 ack.out\ \-\ ACK-assembler and link editor output
   5 .SH SYNOPSIS
   6 .B #include <out.h>
   7 .SH DESCRIPTION
   8 This manual page discusses the format of object files, as generated by ACK
   9 assemblers and the link editor LED.
  10 The format is designed to be compact, machine independent, and
  11 portable from one machine to another,
  12 so that an object file can be produced on one machine, and
  13 further processed on another.
  14 .ta \w'#define x'u +\w'XXXXXXXX'u +\w'XXXXXXXXXXX'u
  15 .PP
  16 In the following discussion, some structures are defined using
  17 \fBlong\fR and \fBshort\fR as type indicators.
  18 It is assumed that the size of a short is 2 bytes (chars) and that the
  19 size of a long is 4 bytes.
  20 However, these types
  21 have a machine dependent byte and word order.
  22 Therefore, a machine independent representation is chosen for the
  23 object format:
  24 a long consists of two shorts, of which the least significant one
  25 comes first, and a short consists of two bytes, of which the
  26 least significant one comes first.
  27 There is no alignment between various parts and structures in the object
  28 file.
  29 .PP
  30 In general, an object file consists of the following parts:
  31 .PP
  32 .nf
  33 \- a file header
  34 \- a number of section headers
  35 \- the sections themselves
  36 \- a number of relocation structures
  37 \- a symbol table
  38 \- a string area containing the names from the symbol table
  39 .fi
  40 .PP
  41 .B The header.
  42 .br
  43 The header of an object file has the following structure:
  44 .PP
  45 .nf
  46 struct outhead {
  47         unsigned short  oh_magic;       /* magic number */
  48         unsigned short  oh_stamp;       /* version stamp */
  49         unsigned short  oh_flags;       /* several format flags */
  50         unsigned short  oh_nsect;       /* number of outsect structures */
  51         unsigned short  oh_nrelo;       /* number of outrelo structures */
  52         unsigned short  oh_nname;       /* number of outname structures */
  53         long    oh_nemit;       /* length of sections */
  54         long    oh_nchar;       /* size of string area */
  55 };
  56 .fi
  57 .PP
  58 #define HF_LINK 0x0004  /* unresolved references left */
  59 .PP
  60 The fields of this structure have the following purpose:
  61 .nr x \w'oh_magic\ \ \ 'u
  62 .IP oh_magic \nxu
  63 A magic number, indicating that this is an object file.
  64 .IP oh_stamp \nxu
  65 A version stamp, used to detect obsolete versions of object files.
  66 .IP oh_flags \nxu
  67 Currently only used for the HF_LINK flag. When this flag is set, the
  68 object file contains unresolved references.
  69 .IP oh_nsect \nxu
  70 The number of sections and section description structures, later on
  71 referred to as \fIoutsect\fR structures.
  72 Usually, there are only a few sections, f.i. a TEXT section,
  73 a ROM section, a DATA section and a BSS section.
  74 Notice that neither the assemblers nor LED know more about them than their
  75 names.
  76 .IP oh_nrelo \nxu
  77 The number of relocation structures, later on referred to as \fIoutrelo\fR
  78 structures.
  79 .IP oh_nname \nxu
  80 The number of symbol table structures, later on referred to as \fIoutname\fR
  81 structures.
  82 .IP oh_nemit \nxu
  83 The total number of bytes in this object file used for the sections themselves.
  84 This field is used to find the relocation and symbol table structures fast.
  85 .IP oh_nchar \nxu
  86 The size of the string area (the number of bytes).
  87 .PP
  88 .B The section descriptions.
  89 .br
  90 The next part of an object file contains the outsect-structures.
  91 An outsect structure has the following layout:
  92 .PP
  93 .nf
  94 struct outsect {
  95         long    os_base;        /* start address in machine */
  96         long    os_size;        /* section size in machine */
  97         long    os_foff;        /* start address in file */
  98         long    os_flen;        /* section size in file */
  99         long    os_lign;        /* section alignment */
 100 };
 101 .fi
 102 .PP
 103 The fields in this structure have the following purpose:
 104 .IP os_base \nxu
 105 The start address of this section in the target machine.
 106 This address is determined by LED,
 107 when producing a non-relocatable object file.
 108 It is ignored for relocatable object files.
 109 .IP os_size \nxu
 110 The size of this section on the target machine.
 111 .IP os_foff \nxu
 112 The start address of this section in this file.
 113 .IP os_flen \nxu
 114 The size of this section in this file.
 115 This field does not have to have
 116 the same value as the \fIos_size\fR field!
 117 For instance, an uninitialized
 118 data section probably has \fIos_flen\fR set to 0.
 119 Notice that
 120 the \fIoh_nemit\fR field of the header contains
 121 the sum of all the \fIos_flen\fR fields.
 122 .IP os_lign \nxu
 123 The alignment requirement for this section. The requirement is that
 124 the loader must leave
 125 .IP "" \nxu
 126 \ \ \ \ \ \ \ \fIos_base\fR \fBmod\fR \fIos_lign\fR = 0
 127 .IP "" \nxu
 128 in tact.
 129 .PP
 130 .B The sections.
 131 .br
 132 The next part of an object file contains the sections themselves.
 133 Usually, the LED program places the sections right behind one another in the
 134 target machine, taking the
 135 alignment requirements into account. However, the user is allowed to give
 136 the start addresses of each section. But if the user gave a start address for
 137 say section 2, but not for section 3, section 3 will be put
 138 right behind section 2.
 139 .PP
 140 .B The relocation structures.
 141 .br
 142 Relocation information is information that allows a program like LED
 143 to combine several object files and produce an executable binary
 144 if there are no unresolved references.
 145 If relocation information is present, it amounts to 8 bytes per
 146 relocatable datum. The information has the following structure:
 147 .PP
 148 .nf
 149 struct outrelo {
 150         char    or_type;        /* type of reference */
 151         char    or_sect;        /* referencing section */
 152         unsigned short  or_nami;        /* referenced symbol index */
 153         long    or_addr;        /* referencing address */
 154 };
 155 .fi
 156 .PP
 157 .nf
 158 /*
 159  * relocation type bits
 160  */
 161 #define RELSZ   0x07            /* relocation length */
 162 #define RELO1   0x01            /* 1 byte */
 163 #define RELO2   0x02            /* 2 bytes */
 164 #define RELO4   0x04            /* 4 bytes */
 165 #define RELPC   0x08            /* pc relative */
 166 #define RELBR   0x10            /* High order byte lowest address. */
 167 #define RELWR   0x20            /* High order word lowest address. */
 168 .fi
 169 .PP
 170 .nf
 171 /*
 172  * section type bits and fields
 173  */
 174 #define S_TYP   0x007F          /* undefined, absolute or relative */
 175 #define S_EXT   0x0080          /* external flag */
 176 #define S_ETC   0x7F00          /* for symbolic debug, bypassing 'as' */
 177 .fi
 178 .PP
 179 .nf
 180 /*
 181  * S_TYP field values
 182  */
 183 #define S_UND   0x0000          /* undefined item */
 184 #define S_ABS   0x0001          /* absolute item */
 185 #define S_MIN   0x0002          /* first user section */
 186 #define S_MAX   (S_TYP-1)       /* last user section */
 187 #define S_CRS   S_TYP           /* reference to other namelist item */
 188 .fi
 189 .PP
 190 The fields of this structure have the following purpose:
 191 .IP or_type \nxu
 192 Contains several flags: One of RELO1, RELO2 and RELO4 is set, indicating the
 193 size of the relocatable datum, RELPC is set when the datum is
 194 relocated pc relative, RELBR and RELWR indicate byte and word order of
 195 the relocatable datum. RELBR and RELWR are needed here. It is not sufficient
 196 to have flags for them in the header of the object file, because some
 197 machines (NS 32016) use several of the possible combinations in their
 198 instruction encoding.
 199 .IP or_sect \nxu
 200 Contains the section number of the referenc\fIing\fR section. This is a number
 201 that lies between S_MIN and S_MAX. The section indicated with number S_MIN
 202 is the first section in the sections-section, etc.
 203 .IP or_addr \nxu
 204 Contains the address of the relocatable datum, in the form of an
 205 offset from the base of the section indicated in the \fIor_sect\fR field.
 206 .IP or_nami \nxu
 207 Usually contains the index of the referenced symbol in the symbol table,
 208 starting at 0.
 209 In this case, the reference is to an undefined external symbol, a common
 210 symbol, or a section name. The relocatable datum then contains
 211 an offset from the indicated symbol or the start of the indicated section.
 212 It may, however, also have the same value as
 213 the \fIoh_nname\fR field of the header. In this case the relocatable datum
 214 is an absolute number, and the datum is relocated pc relative.
 215 The relocatable datum must then be relocated with respect to the
 216 base address of its section.
 217 .PP
 218 .B The symbol table.
 219 .br
 220 This table contains definitions of symbols. It is referred to by
 221 outrelo-structures, and can be used by debuggers.
 222 Entries in this table have the following structure:
 223 .PP
 224 .nf
 225 struct outname {
 226         union {
 227           char  *on_ptr;        /* symbol name (in core) */
 228           long  on_off;         /* symbol name (in file) */
 229         }       on_u;
 230 #define on_mptr on_u.on_ptr
 231 #define on_foff on_u.on_off
 232         unsigned short  on_type;        /* symbol type */
 233         unsigned short  on_desc;        /* debug info */
 234         long    on_valu;        /* symbol value */
 235 };
 236 .fi
 237 .PP
 238 .nf
 239 /*
 240  * S_ETC field values
 241  */
 242 #define S_SCT   0x0100          /* section names */
 243 #define S_LIN   0x0200          /* hll source line item */
 244 #define S_FIL   0x0300          /* hll source file item */
 245 #define S_MOD   0x0400          /* ass source file item */
 246 #define S_COM   0x1000          /* Common name */
 247 .fi
 248 .PP
 249 The members of this structure have the following purpose:
 250 .IP on_foff \nxu
 251 Contains the offset of the name from the beginning of the file. The name
 252 extends from the offset to the next null byte.
 253 .IP on_type \nxu
 254 The S_TYP field of this member contains the section number of the symbol.
 255 Here, this number may be S_ABS for an absolute item, or S_UND, for an
 256 undefined item. The S_EXT flag is set in this member if the symbol is external.
 257 The S_ETC field has the following flags:
 258 S_SCT is set if the symbol represents a section name,
 259 S_COM is set if the symbol represents a common name,
 260 S_LIN is set if the symbol refers to a high level language source line item,
 261 S_FIL is set if the symbol refers to a high level language source file item,
 262 and S_MOD is set if the symbol refers to an assembler source file item.
 263 .IP on_desc \nxu
 264 Currently not used.
 265 .IP on_valu \nxu
 266 Is not used if the symbol refers to an undefined item. For absolute items
 267 it contains the value, for common names it contains the size, and
 268 for anything else it contains the offset from the beginning of the section.
 269 In a fully linked binary, the beginning of the section is added.
 270 .PP
 271 .B The string area.
 272 .br
 273 The last part of an object file contains the name list. This is just a
 274 sequence of null-terminated strings.
 275 .PP
 276 The relocation information, the symbol table, and the name list do not
 277 have to be present, but then of course we do not have a relocatable
 278 object file.
 279 .PP
 280 .B Miscellaneous defines
 281 .br
 282 The following miscellaneous defines might come in handy when reading
 283 object files:
 284 .PP
 285 .nf
 286 /*
 287  * structure format strings
 288  */
 289 #define SF_HEAD "22222244"
 290 #define SF_SECT "44444"
 291 #define SF_RELO "1124"
 292 #define SF_NAME "4224"
 293 .fi
 294 .PP
 295 .nf
 296 /*
 297  * structure sizes (bytes in file; add digits in SF_*)
 298  */
 299 #define SZ_HEAD 20
 300 #define SZ_SECT 20
 301 #define SZ_RELO 8
 302 #define SZ_NAME 12
 303 .fi
 304 .PP
 305 .nf
 306 /*
 307  * file access macros
 308  */
 309 #define BADMAGIC(x)     ((x).oh_magic!=O_MAGIC)
 310 #define OFF_SECT(x)     SZ_HEAD
 311 #define OFF_EMIT(x)     (OFF_SECT(x) + ((long)(x).oh_nsect * SZ_SECT))
 312 #define OFF_RELO(x)     (OFF_EMIT(x) + (x).oh_nemit)
 313 #define OFF_NAME(x)     (OFF_RELO(x) + ((long)(x).oh_nrelo * SZ_RELO))
 314 #define OFF_CHAR(x)     (OFF_NAME(x) + ((long)(x).oh_nname * SZ_NAME))
 315 .fi
 316 .SH "SEE ALSO"
 317 led(6), object(3)