[PATCH] optimization docs part 3

[Jerome L Quinn <jlquinn at us dot ibm dot com>]

This patch adds a list of the -O levels that each flag is active at.  As
with the previous patch, I tried to get it right, but there may still be
bugs in the lists.

2002-08-30 Jerry Quinn <jlquinn@us.ibm.com>
      * gcc/gcc/doc/invoke.texi (Optimization Options): List -O levels for
each optimization flag.
      List the ports that permit debugging without frame pointers.

--- gcc/gcc/doc/invoke.texi.safe           2002-08-25 01:24:16.000000000
-0400
+++ gcc/gcc/doc/invoke.texi          2002-08-25 01:27:05.000000000 -0400
@@ -3305,6 +3305,8 @@
 the compiler normally lets arguments accumulate on the stack for several
 function calls and pops them all at once.

+Disabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
+
 @item -fforce-mem
 @opindex fforce-mem
 Force memory operands to be copied into registers before doing
@@ -3313,6 +3315,8 @@
 subexpressions, instruction combination should eliminate the separate
 register-load.  The @option{-O2} option turns on this option.

+Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
+
 @item -fforce-addr
 @opindex fforce-addr
 Force memory address constants to be copied into registers before
@@ -3327,6 +3331,10 @@
 in many functions.  @strong{It also makes debugging impossible on
 some machines.}

+Currently the following ports permit debugging without frame
+pointers: alpha, arm, avr, d30v, dsp16xx, fr30, ia64, m32r, m88k, mips,
+mn10200, mn10300, pa, rs6000, s390, sh, sparc, stormy16, and xtensa.
+
 On some machines, such as the VAX, this flag has no effect, because
 the standard calling sequence automatically handles the frame pointer
 and nothing is saved by pretending it doesn't exist.  The
@@ -3334,10 +3342,14 @@
 whether a target machine supports this flag.  @xref{Registers,,Register
 Usage, gccint, GNU Compiler Collection (GCC) Internals}.

+Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
+
 @item -foptimize-sibling-calls
 @opindex foptimize-sibling-calls
 Optimize sibling and tail recursive calls.

+Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
+
 @item -ftrapv
 @opindex ftrapv
 This option generates traps for signed overflow on addition, subtraction,
@@ -3359,6 +3371,8 @@
 declared @code{static}, then the function is normally not output as
 assembler code in its own right.

+Enabled at level @option{-O3}.
+
 @item -finline-limit=@var{n}
 @opindex finline-limit
 By default, gcc limits the size of functions that can be inlined.  This
flag
@@ -3402,6 +3416,8 @@
 linker support it.  Use @option{-fno-merge-constants} to inhibit this
 behavior.

+Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
+
 @item -fmerge-all-constants
 Attempt to merge identical constants and identical variables.

@@ -3427,6 +3443,8 @@
 that alter the assembler output may be confused by the optimizations
 performed when this option is not used.

+The default is @option{-ffunction-cse}
+
 @item -ffast-math
 @opindex ffast-math
 Sets @option{-fno-math-errno}, @option{-funsafe-math-optimizations}, @*
@@ -3542,6 +3560,8 @@
 Perform the optimizations of loop strength reduction and
 elimination of iteration variables.

+Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
+
 @item -fthread-jumps
 @opindex fthread-jumps
 Perform optimizations where we check to see if a jump branches to a
@@ -3550,6 +3570,8 @@
 second branch or a point immediately following it, depending on whether
 the condition is known to be true or false.

+Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
+
 @item -fcse-follow-jumps
 @opindex fcse-follow-jumps
 In common subexpression elimination, scan through jump instructions
@@ -3558,6 +3580,8 @@
 @code{else} clause, CSE will follow the jump when the condition
 tested is false.

+Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
+
 @item -fcse-skip-blocks
 @opindex fcse-skip-blocks
 This is similar to @option{-fcse-follow-jumps}, but causes CSE to
@@ -3566,15 +3590,21 @@
 @option{-fcse-skip-blocks} causes CSE to follow the jump around the
 body of the @code{if}.

+Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
+
 @item -frerun-cse-after-loop
 @opindex frerun-cse-after-loop
 Re-run common subexpression elimination after loop optimizations has been
 performed.

+Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
+
 @item -frerun-loop-opt
 @opindex frerun-loop-opt
 Run the loop optimizer twice.

+Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
+
 @item -fgcse
 @opindex fgcse
 Perform a global common subexpression elimination pass.
@@ -3585,6 +3615,8 @@
 the global common subexpression elimination pass by adding
 @option{-fno-gcse} to the command line.

+Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
+
 @item -fgcse-lm
 @opindex fgcse-lm
 When @option{-fgcse-lm} is enabled, global common subexpression
elimination will
@@ -3592,6 +3624,8 @@
 allows a loop containing a load/store sequence to be changed to a load
outside
 the loop, and a copy/store within the loop.

+Enabled by default when gcse is enabled.
+
 @item -fgcse-sm
 @opindex fgcse-sm
 When @option{-fgcse-sm} is enabled, A store motion pass is run after
global common
@@ -3599,17 +3633,23 @@
 When used in conjunction with @option{-fgcse-lm}, loops containing a
load/store sequence
 can be changed to a load before the loop and a store after the loop.

+Enabled by default when gcse is enabled.
+
 @item -floop-optimize
 @opindex floop-optimize
 Perform loop optimizations: move constant expressions out of loops,
simplify
 exit test conditions and optionally do strength-reduction and loop
unrolling as
 well.

+Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
+
 @item -fcrossjumping
 @opindex crossjumping
 Perform cross-jumping transformation. This transformation unifies
equivalent code and save code size. The
 resulting code may or may not perform better than without cross-jumping.

+Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
+
 @item -fif-conversion
 @opindex if-conversion
 Attempt to transform conditional jumps into branch-less equivalents.  This
@@ -3617,11 +3657,15 @@
 some tricks doable by standard arithmetics.  The use of conditional
execution
 on chips where it is available is controlled by @code{if-conversion2}.

+Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
+
 @item -fif-conversion2
 @opindex if-conversion2
 Use conditional execution (where available) to transform conditional jumps
into
 branch-less equivalents.

+Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
+
 @item -fdelete-null-pointer-checks
 @opindex fdelete-null-pointer-checks
 Use global dataflow analysis to identify and eliminate useless checks
@@ -3634,10 +3678,14 @@
 @option{-fno-delete-null-pointer-checks} to disable this optimization
 for programs which depend on that behavior.

+Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
+
 @item -fexpensive-optimizations
 @opindex fexpensive-optimizations
 Perform a number of minor optimizations that are relatively expensive.

+Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
+
 @item -foptimize-register-move
 @itemx -fregmove
 @opindex foptimize-register-move
@@ -3651,12 +3699,16 @@
 Note @option{-fregmove} and @option{-foptimize-register-move} are the same
 optimization.

+Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
+
 @item -fdelayed-branch
 @opindex fdelayed-branch
 If supported for the target machine, attempt to reorder instructions
 to exploit instruction slots available after delayed branch
 instructions.

+Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
+
 @item -fschedule-insns
 @opindex fschedule-insns
 If supported for the target machine, attempt to reorder instructions to
@@ -3665,6 +3717,8 @@
 by allowing other instructions to be issued until the result of the load
 or floating point instruction is required.

+Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
+
 @item -fschedule-insns2
 @opindex fschedule-insns2
 Similar to @option{-fschedule-insns}, but requests an additional pass of
@@ -3672,6 +3726,8 @@
 especially useful on machines with a relatively small number of
 registers and where memory load instructions take more than one cycle.

+Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
+
 @item -ffunction-sections
 @itemx -fdata-sections
 @opindex ffunction-sections
@@ -3707,6 +3763,8 @@
 For all machines, optimization level 2 and higher enables this flag by
 default.

+Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
+
 @item -ftracer
 @opindex ftracer
 Perform tail duplication to enlarge superblock size. This transformation
@@ -3732,6 +3790,8 @@
 If supported by the target machine, generate instructions to prefetch
 memory to improve the performance of loops that access large arrays.

+Disabled at level @option{-Os}.
+
 @item -fmove-all-movables
 @opindex fmove-all-movables
 Forces all invariant computations in loops to be moved
@@ -3768,6 +3828,9 @@
 are implemented in the compiler; some targets use one, some use the
 other, a few use both.

+@option{-fpeephole} is enabled by default.
+@option{-fpeephole2} enabled at levels @option{-O2}, @option{-O3},
@option{-Os}.
+
 @item -fbranch-probabilities
 @opindex fbranch-probabilities
 After running a program compiled with @option{-fprofile-arcs}
@@ -3805,11 +3868,16 @@
 reduce non-determinism, possibly at the expense of inferior
 optimization.

+The default is @option{-fguess-branch-probability} at levels
+@option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
+
 @item -freorder-blocks
 @opindex freorder-blocks
 Reorder basic blocks in the compiled function in order to reduce number of
 taken branches and improve code locality.

+Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
+
 @item -freorder-functions
 @opindex freorder-functions
 Reorder basic blocks in the compiled function in order to reduce number of
@@ -3822,6 +3890,8 @@
 Also profile feedback must be available in to make this option effective.
See
 @option{-fprofile-arcs} for details.

+Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
+
 @item -fstrict-aliasing
 @opindex fstrict-aliasing
 Allows the compiler to assume the strictest aliasing rules applicable to
@@ -3867,8 +3937,7 @@
 allowed to alias.  For an example, see the C front-end function
 @code{c_get_alias_set}.

-For all machines, optimization level 2 and higher enables this flag by
-default.
+Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.

 @item -falign-functions
 @itemx -falign-functions=@var{n}
@@ -3887,6 +3956,8 @@

 If @var{n} is not specified, use a machine-dependent default.

+Enabled at levels @option{-O2}, @option{-O3}.
+
 @item -falign-labels
 @itemx -falign-labels=@var{n}
 @opindex falign-labels
@@ -3901,6 +3972,8 @@
 If @var{n} is not specified, use a machine-dependent default which is
 very likely to be @samp{1}, meaning no alignment.

+Enabled at levels @option{-O2}, @option{-O3}.
+
 @item -falign-loops
 @itemx -falign-loops=@var{n}
 @opindex falign-loops
@@ -3911,6 +3984,8 @@

 If @var{n} is not specified, use a machine-dependent default.

+Enabled at levels @option{-O2}, @option{-O3}.
+
 @item -falign-jumps
 @itemx -falign-jumps=@var{n}
 @opindex falign-jumps
@@ -3921,6 +3996,8 @@

 If @var{n} is not specified, use a machine-dependent default.

+Enabled at levels @option{-O2}, @option{-O3}.
+
 @item -fssa
 @opindex fssa
 Perform optimizations in static single assignment form.  Each function's
@@ -3951,12 +4028,16 @@
 make debugging impossible, since variables will no longer stay in
 a ``home register''.

-@item -fno-cprop-registers
-@opindex fno-cprop-registers
+Enabled at levels @option{-O3}.
+
+@item -fcprop-registers
+@opindex fcprop-registers
 After register allocation and post-register allocation instruction
splitting,
 we perform a copy-propagation pass to try to reduce scheduling
dependencies
 and occasionally eliminate the copy.

+Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
+
 @item --param @var{name}=@var{value}
 @opindex param
 In some places, GCC uses various constants to control the amount of