--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/object files.txt	Sat Jan 17 07:09:02 2009 +0000
@@ -0,0 +1,79 @@
+An object file consists of a series of sections each of which contains a
+list of exported symbols, a list of incomplete references, and a list of
+"local" symbols which may be used in calculating incomplete references. Each
+section will obviously also contain the object code.
+
+Exported symbols must be completely resolved to an address within the
+section it is exported from.
+
+Each object file starts with a magic number and version number. The magic
+number is the string "LWOBJ16" for this 16 bit object file format. The only
+defined version number is currently 0. Thus, the first 8 bytes of the object
+file are:
+
+4C574F424A313600
+
+Each section has the following items in order:
+
+* section name
+* flags
+* list of local symbols (and addresses within the section)
+* list of exported symbols (and addresses within the section)
+* list of incomplete references along with the expressions to calculate them
+* the actual object code
+
+The section starts with the name of the section with a NUL termination
+followed by a series of flag bytes terminated by NUL. The following flag
+bytes are defined:
+
+Byte	Meaning
+00		no more flags
+01		section is BSS - no actual code is present
+
+Either a NULL section name or end of file indicate the presence of no more
+sections.
+
+Each entry in the exported and local symbols table consists of the symbol
+(NUL terminated) followed by two bytes which contain the value in big endian
+order. The end of a symbol table is indicated by a NULL symbol name.
+
+Each entry in the incomplete references table consists of an expression
+followed by a 16 bit offset where the reference goes. Expressions are
+defined as a series of terms up to an "end of expression" term. Each term
+consists of a single byte which identifies the type of term (see below)
+followed by any data required by the term. Then end of the list is flagged
+by a NULL expression (only an end of expression term).
+
+TERMTYPE	Meaning
+00			end of expression
+01			integer (16 bit in big endian order follows)
+02			external symbol reference (NUL term symbol)
+03			local symbol reference (NUL term symbol)
+04			operator (1 byte operator number - see below)
+05			section base address reference
+
+External references are resolved using other object files while local
+references are resolved using the local symbol table(s) from this file. This
+allows local symbols that are not exported to have the same names as
+exported symbols or external references.
+
+The operator numbers are:
+
+NUM	OP
+01	+ (plus)
+02	- (minus)
+03	* (times)
+04	/ (divide)
+05	% (modulus)
+06	\ (integer division)
+07	bitwise and
+08	bitwise or
+09	bitwise xor
+0A	boolean and
+0B	boolean or
+0C	- (unary negation, 2's complement)
+0D	^ (unary 1's complement)
+
+An expression is represented in a postfix manner with both operands for
+binary operators preceding the operator and the single operand for unary
+operators preceding the operator.