Try again to fix our handling of MOVD/MOVQ
[nasm/sigaren-mirror.git] / doc / opt_var.txt
blob4482e5d898695af2a505635806d063d3f747519c
1                      NASM Optimizer Usage of
2               Certain Variables to Control Assembly
4                   prepared by:  John R Coffman
5                        date:  07-Mar-2005
8 GLOBAL variables:
9         optimizing      -1 flags nasm 0.98 compatible operation;
10                             offsets usually are explicit (short/near)
11                             no optimization passes
12                         0 flags non-optimized assembly; forward
13                             references generate long offsets; always
14                             assembles
15                             no optimization passes
16                         2 or more specifies optmization passes.  5 is
17                             the actual recommended minimum setting
18                             optimization passes (2 or more, plus
19                             passes 1 and 2 will be required)
22         pass0           0 flags an optimizer pass (multiple passes)
23                         1 flags pass1 (define labels)
24                         2 flags pass2 (spit out code)
27 LOCAL variables:        local to 'assemble_file' (nasm.c)
29         pass_max        2 for non-optimized assembly
30                         4 or more for optimized assembly
32         pass            index of the FOR loop (1..pass_max)
33                         with optimized assembly, this variable is
34                             advanced to 'pass_max - 1' in the logic
35                             at the end of the loop to terminate
36                             an optimized assembly before all passes
37                             are used; i.e., when convergence has 
38                             occurred
39                 
41         pass1           flag for making parts of the assembler do
42                             pass 1 behaviors on optimizer passes
44         pass2           flag for making parts of the assembler do
45                             pass 2 behaviors on optimizer passes
47         pass_cnt        benign counter for counting the actual
48                             number of passes taken.  Since 'pass'
49                             may be jerked upward early on optimized
50                             assembly, it does not accurately reflect
51                             the number of passes taken.
52                         always ends at 2 for non-optimized assembly
56         How the variables sequence:
59 NON-OPTIMIZED assembly:
61                 
62         pass0           1  2        all indicate, pass 1 and pass 2
63         pass1           1  2
64         pass2           1  2
66         pass            1  2
67    ----------------------------------------
69         pass_max        pre-set to 2
70         pass_cnt        ends at 2
73 OPTIMIZED assembly:
75         optimizing      set to 2 or greater
77         pass0           0  0  0  0  0 ... 0  0  1  2
78         pass1           1  1  1  1  1 ... 1  1  1  2
79         pass2           1  2  2  2  2 ... 2  2  2  2
81         pass            1  2  3  4  5 ... 7  8  9  12
83         pass_max        pre-set to, say, 12
84         pass_cnt        ends at 10 for this assembly
86 >From pass_cnt, the reported number of passes will be 1+8+1, meaning 
87 8 optimization passes, plus pass 1, plus pass 2.
89 Subroutines may check 'pass0' to see if an optimizer pass is in
90 progress (pass0==0).  Many have arguments to tell what pass is in
91 progress.  But these variables are passed in as 'pass1' or 'pass2'.
93 >From the sequences above, 'pass' bears no relation to the desired
94 pass 1 or pass 2 behavior of the assembler.  'pass1' is used to tell
95 parts of the assembler, on multiple occasions, that pass 1 is in
96 progress, and only once that pass 2 is being performed.  Other parts
97 of the assembler need to be told only once that pass 1 is being
98 performed, but may be told multiple times that pass 2 is being done.
100 For instance, the preprocessor reset operation looks at pass1, and it
101 thinks many pass 1 resets are being done, but only one pass 2 reset
102 is done.  Also, certain errors are non-fatal on pass 1, but fatal on
103 pass 2; hence, they are tied to the 'pass1' variable to determine the
104 assembler pass number.
106 Further, segment definitions look at the 'pass2' variable, since they
107 do some initialization on pass 1, but are pretty much no-ops on pass
108 2.  Hence, they should see pass 1 only once, but may see pass 2
109 multiple times.
113 [end]