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.

Pass 2
------

This pass assigns instruction sizes to all invariate instructions. Invariate
instructions are any instructions with a fixed size, including those with
forced addressing modes.

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.