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     optimization meta data (with level and flag info)
  10         .level         -1 flags nasm 0.98 compatible operation;
  11                             offsets usually are explicit (short/near)
  12                             no optimization passes
  13                         0 flags non-optimized assembly; forward
  14                             references generate long offsets; always
  15                             assembles
  16                             no optimization passes
  17                         2 or more specifies optmization passes.  5 is
  18                             the actual recommended minimum setting
  19                             optimization passes (2 or more, plus
  20                             passes 1 and 2 will be required)
  21         .flag           0 allow all optimizations
  22                         1 disallow jump match optimization
  23
  24         pass0           0 flags an optimizer pass (multiple passes)
  25                         1 flags pass1 (define labels)
  26                         2 flags pass2 (spit out code)
  27
  28
  29 LOCAL variables:        local to 'assemble_file' (nasm.c)
  30
  31         pass_max        2 for non-optimized assembly
  32                         4 or more for optimized assembly
  33
  34         pass            index of the FOR loop (1..pass_max)
  35                         with optimized assembly, this variable is
  36                             advanced to 'pass_max - 1' in the logic
  37                             at the end of the loop to terminate
  38                             an optimized assembly before all passes
  39                             are used; i.e., when convergence has
  40                             occurred
  41
  42
  43         pass1           flag for making parts of the assembler do
  44                             pass 1 behaviors on optimizer passes
  45
  46         pass2           flag for making parts of the assembler do
  47                             pass 2 behaviors on optimizer passes
  48
  49         pass_cnt        benign counter for counting the actual
  50                             number of passes taken.  Since 'pass'
  51                             may be jerked upward early on optimized
  52                             assembly, it does not accurately reflect
  53                             the number of passes taken.
  54                         always ends at 2 for non-optimized assembly
  55
  56
  57
  58         How the variables sequence:
  59
  60
  61 NON-OPTIMIZED assembly:
  62
  63
  64         pass0           1  2        all indicate, pass 1 and pass 2
  65         pass1           1  2
  66         pass2           1  2
  67
  68         pass            1  2
  69    ----------------------------------------
  70
  71         pass_max        pre-set to 2
  72         pass_cnt        ends at 2
  73
  74
  75 OPTIMIZED assembly:
  76
  77         optimizing      set to 2 or greater
  78
  79         pass0           0  0  0  0  0 ... 0  0  1  2
  80         pass1           1  1  1  1  1 ... 1  1  1  2
  81         pass2           1  2  2  2  2 ... 2  2  2  2
  82
  83         pass            1  2  3  4  5 ... 7  8  9  12
  84
  85         pass_max        pre-set to, say, 12
  86         pass_cnt        ends at 10 for this assembly
  87
  88 >From pass_cnt, the reported number of passes will be 1+8+1, meaning
  89 8 optimization passes, plus pass 1, plus pass 2.
  90
  91 Subroutines may check 'pass0' to see if an optimizer pass is in
  92 progress (pass0==0).  Many have arguments to tell what pass is in
  93 progress.  But these variables are passed in as 'pass1' or 'pass2'.
  94
  95 >From the sequences above, 'pass' bears no relation to the desired
  96 pass 1 or pass 2 behavior of the assembler.  'pass1' is used to tell
  97 parts of the assembler, on multiple occasions, that pass 1 is in
  98 progress, and only once that pass 2 is being performed.  Other parts
  99 of the assembler need to be told only once that pass 1 is being
 100 performed, but may be told multiple times that pass 2 is being done.
 101
 102 For instance, the preprocessor reset operation looks at pass1, and it
 103 thinks many pass 1 resets are being done, but only one pass 2 reset
 104 is done.  Also, certain errors are non-fatal on pass 1, but fatal on
 105 pass 2; hence, they are tied to the 'pass1' variable to determine the
 106 assembler pass number.
 107
 108 Further, segment definitions look at the 'pass2' variable, since they
 109 do some initialization on pass 1, but are pretty much no-ops on pass
 110 2.  Hence, they should see pass 1 only once, but may see pass 2
 111 multiple times.
 112
 113
 114
 115 [end]
 116