--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/internals.txt	Sun Feb 28 05:55:07 2010 +0000
@@ -0,0 +1,49 @@
+LWASM Internals
+===============
+
+LWASM is a table-driven assembler that notionally uses two passes. However,
+it implements its assembly in several passes as follows.
+
+Pass 1 - Preprocessing & Parsing
+--------------------------------
+
+This pass reads the source file and all included source files. It handles
+macro definition and expansion.
+
+As it reads the various lines, it also identifies any symbol associated with
+the line, the operation code, and, based on the operation code, the operand,
+if any. Upon examination of the operand, any expressions are stored in an
+internal postfix notation for later evaluation. During this pass,
+preliminary values are assigned to all symbols using the largest possible
+instruction size. A table of lines that reference every symbol is generated
+to be used in the following pass. Note that any symbols for which the value
+is known with no uncertainty factor will be generated with the smallest
+possible instruction.
+
+At this stage, simple optimizations are performed on expressions. This
+includes coalescing constants (1+2+x => 3+x). It also includes some basic
+algebra (x+x => 2*x, 2*x+4*x => 6*x, x-x => 0).
+
+Pass 2 - Optimization
+---------------------
+
+This pass sweeps the code looking for operations which could use a shorter
+instruction. If it finds one, it must then re-define all symbols defined
+subsequently and all symbols defined in terms of one of those symbols in a
+cascade. This process is repeated until no more possible reductions are
+discovered.
+
+If, in the process of implementing an instruction reduction, a phasing error
+or other conflict is encountered, the reduction is backed out and marked as
+forced. 
+
+The following may be candidates for reduction, depending on assembler
+options:
+
+- extended addressing -> direct addressing (not in obj target)
+- 16 bit offset -> 8 bit offset (indirect indexed)
+- 16 bit offset -> 8 bit or 5 bit offset (direct indexed)
+- 16 bit offset -> no offset (indexed)
+- 16 bit relative -> 8 bit relative (depending on configuration)
+
+