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
------

This pass reads the entire source code and parses each line into an internal
representation. Macros, file inclusions, and conditional assembly
instructions are resolved at this point as well. Instructions with known
sizes will have their sizes resolved at this point.

Pass 2
------

Check all exported symbols for validity and set them as imports if the
assembler state says so. Also resolve all symbol references in all
expressions to be direct references either to the symbol table or
to the import list.

Pass 3
------

This pass resolves all instruction sizes that can be resolved without
setting addresses for instructions. This process is repeated until no
further instructions sizes are resolved.

Pass 4
------

This pass assigns addresses to all symbols where values are known. It does
the same for instructions. Then a repeat of similar algorithms as in the
previous pass is used to resolve as many operands as possible.

This pass is repeated multiple times until no further instructions or
symbols are resolved.

Pass 5
------

Finalization of all instruction sizes by forcing them to the maximum
addressing mode. Then all remaining instruction addresses and symbol values
are resolved.

Pass 6
------

This pass does actual code generation. This is the notional second pass. All
other passes are the notional first pass.


Expression Evaluation
=====================

Each expression carries a certainty flag. Any expression in which any term
is flagged as uncertain is, itself, uncertain. There are a few specific
cases where such uncertainty can cancel out. For instance, X-X where X is
uncertain is guaranteed to be 0 and so there is no uncertainty.