annotate doc/internals.txt @ 333:ebff3a3e8fa6

Updated internals to describe the multi-pass architecture
author lost
date Tue, 02 Mar 2010 00:44:18 +0000
parents ed3553296580
children e7885b3ee266
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
331
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1 LWASM Internals
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2 ===============
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
3
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
4 LWASM is a table-driven assembler that notionally uses two passes. However,
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
5 it implements its assembly in several passes as follows.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
6
333
ebff3a3e8fa6 Updated internals to describe the multi-pass architecture
lost
parents: 331
diff changeset
7 Pass 1
ebff3a3e8fa6 Updated internals to describe the multi-pass architecture
lost
parents: 331
diff changeset
8 ------
331
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
9
333
ebff3a3e8fa6 Updated internals to describe the multi-pass architecture
lost
parents: 331
diff changeset
10 This pass reads the entire source code and parses each line into an internal
ebff3a3e8fa6 Updated internals to describe the multi-pass architecture
lost
parents: 331
diff changeset
11 representation. Macros, file inclusions, and conditional assembly
ebff3a3e8fa6 Updated internals to describe the multi-pass architecture
lost
parents: 331
diff changeset
12 instructions are resolved at this point as well.
ebff3a3e8fa6 Updated internals to describe the multi-pass architecture
lost
parents: 331
diff changeset
13
ebff3a3e8fa6 Updated internals to describe the multi-pass architecture
lost
parents: 331
diff changeset
14 Pass 2
ebff3a3e8fa6 Updated internals to describe the multi-pass architecture
lost
parents: 331
diff changeset
15 ------
331
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
16
333
ebff3a3e8fa6 Updated internals to describe the multi-pass architecture
lost
parents: 331
diff changeset
17 This pass assigns instruction sizes to all invariate instructions. Invariate
ebff3a3e8fa6 Updated internals to describe the multi-pass architecture
lost
parents: 331
diff changeset
18 instructions are any instructions with a fixed size, including those with
ebff3a3e8fa6 Updated internals to describe the multi-pass architecture
lost
parents: 331
diff changeset
19 forced addressing modes.
331
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
20
333
ebff3a3e8fa6 Updated internals to describe the multi-pass architecture
lost
parents: 331
diff changeset
21 Pass 3
ebff3a3e8fa6 Updated internals to describe the multi-pass architecture
lost
parents: 331
diff changeset
22 ------
ebff3a3e8fa6 Updated internals to describe the multi-pass architecture
lost
parents: 331
diff changeset
23
ebff3a3e8fa6 Updated internals to describe the multi-pass architecture
lost
parents: 331
diff changeset
24 This pass resolves all instruction sizes that can be resolved without
ebff3a3e8fa6 Updated internals to describe the multi-pass architecture
lost
parents: 331
diff changeset
25 setting addresses for instructions. This process is repeated until no
ebff3a3e8fa6 Updated internals to describe the multi-pass architecture
lost
parents: 331
diff changeset
26 further instructions sizes are resolved.
331
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
27
333
ebff3a3e8fa6 Updated internals to describe the multi-pass architecture
lost
parents: 331
diff changeset
28 Pass 4
ebff3a3e8fa6 Updated internals to describe the multi-pass architecture
lost
parents: 331
diff changeset
29 ------
331
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
30
333
ebff3a3e8fa6 Updated internals to describe the multi-pass architecture
lost
parents: 331
diff changeset
31 This pass assigns addresses to all symbols where values are known. It does
ebff3a3e8fa6 Updated internals to describe the multi-pass architecture
lost
parents: 331
diff changeset
32 the same for instructions. Then a repeat of similar algorithms as in the
ebff3a3e8fa6 Updated internals to describe the multi-pass architecture
lost
parents: 331
diff changeset
33 previous pass is used to resolve as many operands as possible.
ebff3a3e8fa6 Updated internals to describe the multi-pass architecture
lost
parents: 331
diff changeset
34
ebff3a3e8fa6 Updated internals to describe the multi-pass architecture
lost
parents: 331
diff changeset
35 This pass is repeated multiple times until no further instructions or
ebff3a3e8fa6 Updated internals to describe the multi-pass architecture
lost
parents: 331
diff changeset
36 symbols are resolved.
331
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
37
333
ebff3a3e8fa6 Updated internals to describe the multi-pass architecture
lost
parents: 331
diff changeset
38 Pass 5
ebff3a3e8fa6 Updated internals to describe the multi-pass architecture
lost
parents: 331
diff changeset
39 ------
331
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
40
333
ebff3a3e8fa6 Updated internals to describe the multi-pass architecture
lost
parents: 331
diff changeset
41 Finalization of all instruction sizes by forcing them to the maximum
ebff3a3e8fa6 Updated internals to describe the multi-pass architecture
lost
parents: 331
diff changeset
42 addressing mode. Then all remaining instruction addresses and symbol values
ebff3a3e8fa6 Updated internals to describe the multi-pass architecture
lost
parents: 331
diff changeset
43 are resolved.
331
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
44
333
ebff3a3e8fa6 Updated internals to describe the multi-pass architecture
lost
parents: 331
diff changeset
45 Pass 6
ebff3a3e8fa6 Updated internals to describe the multi-pass architecture
lost
parents: 331
diff changeset
46 ------
ebff3a3e8fa6 Updated internals to describe the multi-pass architecture
lost
parents: 331
diff changeset
47
ebff3a3e8fa6 Updated internals to describe the multi-pass architecture
lost
parents: 331
diff changeset
48 This pass does actual code generation.
331
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
49
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
50
333
ebff3a3e8fa6 Updated internals to describe the multi-pass architecture
lost
parents: 331
diff changeset
51 Expression Evaluation
ebff3a3e8fa6 Updated internals to describe the multi-pass architecture
lost
parents: 331
diff changeset
52 =====================
ebff3a3e8fa6 Updated internals to describe the multi-pass architecture
lost
parents: 331
diff changeset
53
ebff3a3e8fa6 Updated internals to describe the multi-pass architecture
lost
parents: 331
diff changeset
54 Each expression carries a certainty flag. Any expression in which any term
ebff3a3e8fa6 Updated internals to describe the multi-pass architecture
lost
parents: 331
diff changeset
55 is flagged as uncertain is, itself, uncertain. There are a few specific
ebff3a3e8fa6 Updated internals to describe the multi-pass architecture
lost
parents: 331
diff changeset
56 cases where such uncertainty can cancel out. For instance, X-X where X is
ebff3a3e8fa6 Updated internals to describe the multi-pass architecture
lost
parents: 331
diff changeset
57 uncertain is guaranteed to be 0 and so there is no uncertainty.
ebff3a3e8fa6 Updated internals to describe the multi-pass architecture
lost
parents: 331
diff changeset
58