doc/opt_var.txt

   1                      NASM Optimizer Usage of
   2               Certain Variables to Control Assembly
   3
   4                   prepared by:  John R Coffman
   5                        date:  07-Mar-2005
   6
   7
   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)
  20
  21
  22         pass0           0 flags an optimizer pass (multiple passes)
  23                         1 flags pass1 (define labels)
  24                         2 flags pass2 (spit out code)
  25
  26
  27 LOCAL variables:        local to 'assemble_file' (nasm.c)
  28
  29         pass_max        2 for non-optimized assembly
  30                         4 or more for optimized assembly
  31
  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
  40
  41         pass1           flag for making parts of the assembler do
  42                             pass 1 behaviors on optimizer passes
  43
  44         pass2           flag for making parts of the assembler do
  45                             pass 2 behaviors on optimizer passes
  46
  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
  53
  54
  55
  56         How the variables sequence:
  57
  58
  59 NON-OPTIMIZED assembly:
  60
  61
  62         pass0           1  2        all indicate, pass 1 and pass 2
  63         pass1           1  2
  64         pass2           1  2
  65
  66         pass            1  2
  67    ----------------------------------------
  68
  69         pass_max        pre-set to 2
  70         pass_cnt        ends at 2
  71
  72
  73 OPTIMIZED assembly:
  74
  75         optimizing      set to 2 or greater
  76
  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
  80
  81         pass            1  2  3  4  5 ... 7  8  9  12
  82
  83         pass_max        pre-set to, say, 12
  84         pass_cnt        ends at 10 for this assembly
  85
  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.
  88
  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'.
  92
  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.
  99
 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.
 105
 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.
 110
 111
 112
 113 [end]
 114