[PATCH] Optimization docs part 4

[Jerry Quinn <jlquinn at optonline dot net>]

This patch groups together optimization flags that are never enabled
by default and may be experimental.  I left alone flags that are
closely related to ones that are enabled at various -O levels.

Also, I moved -ftrapv and -fbounds-check to the code gen section,
which makes more sense to me, since neither are optimizations.

The previous version was okay'd by Geoff Keating in
http://gcc.gnu.org/ml/gcc-patches/2002-09/msg00957.html.  This version
also relocates trapv, bounds-check, and branch-probabilities.


2002-12-17  Jerry Quinn  <jlquinn@optonline.net>

	* gcc/doc/invoke.texi (Optimization Options): Group together
	  optional and experimental flags.  Move trapv and
	  bounds-check out of this section.
	* gcc/doc/invoke.texi (Code Gen Options): Move trapv and
	  bounds-check to here.


--- invoke.texi.p4	Tue Dec 17 01:55:31 2002
+++ invoke.texi	Tue Dec 17 01:50:11 2002
@@ -264,7 +264,6 @@
 @gccoptlist{
 -falign-functions=@var{n}  -falign-jumps=@var{n} @gol
 -falign-labels=@var{n}  -falign-loops=@var{n}  @gol
--fbounds-check @gol
 -fbranch-probabilities  -fcaller-saves -fcprop-registers @gol
 -fcse-follow-jumps  -fcse-skip-blocks  -fdata-sections @gol
 -fdelayed-branch  -fdelete-null-pointer-checks @gol
@@ -290,7 +289,7 @@
 -fsched-spec-load-dangerous  -fsignaling-nans @gol
 -fsingle-precision-constant  -fssa -fssa-ccp -fssa-dce @gol
 -fstrength-reduce  -fstrict-aliasing  -ftracer -fthread-jumps @gol
--ftrapv -funroll-all-loops  -funroll-loops  @gol
+-funroll-all-loops  -funroll-loops  @gol
 --param @var{name}=@var{value}
 -O  -O0  -O1  -O2  -O3  -Os}
 
@@ -730,7 +729,8 @@
 -fstack-limit-register=@var{reg}  -fstack-limit-symbol=@var{sym} @gol
 -fargument-alias  -fargument-noalias @gol
 -fargument-noalias-global  -fleading-underscore @gol
--ftls-model=@var{model}}
+-ftls-model=@var{model} @gol
+-ftrapv -fbounds-check}
 @end table
 
 @menu
@@ -3543,11 +3543,6 @@
 
 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
 
-@item -ftrapv
-@opindex ftrapv
-This option generates traps for signed overflow on addition, subtraction,
-multiplication operations.
-
 @item -fno-inline
 @opindex fno-inline
 Don't pay attention to the @code{inline} keyword.  Normally this option
@@ -3621,12 +3616,6 @@
 have distinct location, so using this option will result in non-conforming
 behavior.
 
-@item -fnew-ra
-@opindex fnew-ra
-Use a graph coloring register allocator.  Currently this option is meant
-for testing, so we are interested to hear about miscompilations with
-@option{-fnew-ra}.
-
 @item -fno-branch-count-reg
 @opindex fno-branch-count-reg
 Do not use ``decrement and branch'' instructions on a count register,
@@ -3662,13 +3651,6 @@
 
 The default is @option{-fzero-initialized-in-bss}.
 
-@item -fbounds-check
-@opindex fbounds-check
-For front-ends that support it, generate additional code to check that
-indices used to access arrays are within the declared range.  This is
-currently only supported by the Java and Fortran 77 front-ends, where
-this option defaults to true and false respectively.
-
 @end table
 
 The following options control specific optimizations.  The @option{-O2}
@@ -3880,28 +3862,6 @@
 sense when scheduling before register allocation, i.e.@: with
 @option{-fschedule-insns} or at @option{-O2} or higher.
 
-@item -ffunction-sections
-@itemx -fdata-sections
-@opindex ffunction-sections
-@opindex fdata-sections
-Place each function or data item into its own section in the output
-file if the target supports arbitrary sections.  The name of the
-function or the name of the data item determines the section's name
-in the output file.
-
-Use these options on systems where the linker can perform optimizations
-to improve locality of reference in the instruction space.  HPPA
-processors running HP-UX and SPARC processors running Solaris 2 have
-linkers with such optimizations.  Other systems using the ELF object format
-as well as AIX may have these optimizations in the future.
-
-Only use these options when there are significant benefits from doing
-so.  When you specify these options, the assembler and linker will
-create larger object and executable files and will also be slower.
-You will not be able to use @code{gprof} on all systems if you
-specify this option and you may have problems with debugging if
-you specify both this option and @option{-g}.
-
 @item -fcaller-saves
 @opindex fcaller-saves
 Enable values to be allocated in registers that will be clobbered by
@@ -3914,33 +3874,6 @@
 
 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
 
-@item -ftracer
-@opindex ftracer
-Perform tail duplication to enlarge superblock size. This transformation
-simplifies the control flow of the function allowing other optimizations to do
-better job.
-
-@item -funroll-loops
-@opindex funroll-loops
-Unroll loops whose number of iterations can be determined at compile
-time or upon entry to the loop.  @option{-funroll-loops} implies both
-@option{-fstrength-reduce} and @option{-frerun-cse-after-loop}.  This
-option makes code larger, and may or may not make it run faster.
-
-@item -funroll-all-loops
-@opindex funroll-all-loops
-Unroll all loops, even if their number of iterations is uncertain when
-the loop is entered.  This usually makes programs run more slowly.
-@option{-funroll-all-loops} implies the same options as
-@option{-funroll-loops},
-
-@item -fprefetch-loop-arrays
-@opindex fprefetch-loop-arrays
-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
@@ -3980,27 +3913,6 @@
 @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}
-(@pxref{Debugging Options,, Options for Debugging Your Program or
-@command{gcc}}), you can compile it a second time using
-@option{-fbranch-probabilities}, to improve optimizations based on
-the number of times each branch was taken.  When the program
-compiled with @option{-fprofile-arcs} exits it saves arc execution
-counts to a file called @file{@var{sourcename}.da} for each source
-file  The information in this data file is very dependent on the
-structure of the generated code, so you must use the same source code
-and the same optimization options for both compilations.
-
-With @option{-fbranch-probabilities}, GCC puts a @samp{REG_EXEC_COUNT}
-note on the first instruction of each basic block, and a
-@samp{REG_BR_PROB} note on each @samp{JUMP_INSN} and @samp{CALL_INSN}.
-These can be used to improve optimization.  Currently, they are only
-used in one place: in @file{reorg.c}, instead of guessing which path a
-branch is mostly to take, the @samp{REG_BR_PROB} values are used to
-exactly determine which path is taken more often.
-
 @item -fno-guess-branch-probability
 @opindex fno-guess-branch-probability
 Do not guess branch probabilities using a randomized model.
@@ -4147,23 +4059,6 @@
 
 Enabled at levels @option{-O2}, @option{-O3}.
 
-@item -fssa
-@opindex fssa
-Perform optimizations in static single assignment form.  Each function's
-flow graph is translated into SSA form, optimizations are performed, and
-the flow graph is translated back from SSA form.  Users should not
-specify this option, since it is not yet ready for production use.
-
-@item -fssa-ccp
-@opindex fssa-ccp
-Perform Sparse Conditional Constant Propagation in SSA form.  Requires
-@option{-fssa}.  Like @option{-fssa}, this is an experimental feature.
-
-@item -fssa-dce
-@opindex fssa-dce
-Perform aggressive dead-code elimination in SSA form.  Requires @option{-fssa}.
-Like @option{-fssa}, this is an experimental feature.
-
 @item -frename-registers
 @opindex frename-registers
 Attempt to avoid false dependencies in scheduled code by making use
@@ -4292,6 +4187,110 @@
 Treat floating point constant as single precision constant instead of
 implicitly converting it to double precision constant.
 
+
+@end table
+
+The following options control optimizations that may improve
+performance, but are not enabled by any @option{-O} options.  This
+section includes experimental options that may produce broken code.
+
+@table @gcctabopt
+@item -fbranch-probabilities
+@opindex fbranch-probabilities
+After running a program compiled with @option{-fprofile-arcs}
+(@pxref{Debugging Options,, Options for Debugging Your Program or
+@command{gcc}}), you can compile it a second time using
+@option{-fbranch-probabilities}, to improve optimizations based on
+the number of times each branch was taken.  When the program
+compiled with @option{-fprofile-arcs} exits it saves arc execution
+counts to a file called @file{@var{sourcename}.da} for each source
+file  The information in this data file is very dependent on the
+structure of the generated code, so you must use the same source code
+and the same optimization options for both compilations.
+
+With @option{-fbranch-probabilities}, GCC puts a @samp{REG_EXEC_COUNT}
+note on the first instruction of each basic block, and a
+@samp{REG_BR_PROB} note on each @samp{JUMP_INSN} and @samp{CALL_INSN}.
+These can be used to improve optimization.  Currently, they are only
+used in one place: in @file{reorg.c}, instead of guessing which path a
+branch is mostly to take, the @samp{REG_BR_PROB} values are used to
+exactly determine which path is taken more often.
+
+@item -fnew-ra
+@opindex fnew-ra
+Use a graph coloring register allocator.  Currently this option is meant
+for testing, so we are interested to hear about miscompilations with
+@option{-fnew-ra}.
+
+@item -ftracer
+@opindex ftracer
+Perform tail duplication to enlarge superblock size. This transformation
+simplifies the control flow of the function allowing other optimizations to do
+better job.
+
+@item -funroll-loops
+@opindex funroll-loops
+Unroll loops whose number of iterations can be determined at compile
+time or upon entry to the loop.  @option{-funroll-loops} implies both
+@option{-fstrength-reduce} and @option{-frerun-cse-after-loop}.  This
+option makes code larger, and may or may not make it run faster.
+
+@item -funroll-all-loops
+@opindex funroll-all-loops
+Unroll all loops, even if their number of iterations is uncertain when
+the loop is entered.  This usually makes programs run more slowly.
+@option{-funroll-all-loops} implies the same options as
+@option{-funroll-loops},
+
+@item -fprefetch-loop-arrays
+@opindex fprefetch-loop-arrays
+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 -ffunction-sections
+@itemx -fdata-sections
+@opindex ffunction-sections
+@opindex fdata-sections
+Place each function or data item into its own section in the output
+file if the target supports arbitrary sections.  The name of the
+function or the name of the data item determines the section's name
+in the output file.
+
+Use these options on systems where the linker can perform optimizations
+to improve locality of reference in the instruction space.  HPPA
+processors running HP-UX and SPARC processors running Solaris 2 have
+linkers with such optimizations.  Other systems using the ELF object format
+as well as AIX may have these optimizations in the future.
+
+Only use these options when there are significant benefits from doing
+so.  When you specify these options, the assembler and linker will
+create larger object and executable files and will also be slower.
+You will not be able to use @code{gprof} on all systems if you
+specify this option and you may have problems with debugging if
+you specify both this option and @option{-g}.
+
+@item -fssa
+@opindex fssa
+Perform optimizations in static single assignment form.  Each function's
+flow graph is translated into SSA form, optimizations are performed, and
+the flow graph is translated back from SSA form.  Users should not
+specify this option, since it is not yet ready for production use.
+
+@item -fssa-ccp
+@opindex fssa-ccp
+Perform Sparse Conditional Constant Propagation in SSA form.  Requires
+@option{-fssa}.  Like @option{-fssa}, this is an experimental feature.
+
+@item -fssa-dce
+@opindex fssa-dce
+Perform aggressive dead-code elimination in SSA form.  Requires @option{-fssa}.
+Like @option{-fssa}, this is an experimental feature.
+
+
+
+
 @item --param @var{name}=@var{value}
 @opindex param
 In some places, GCC uses various constants to control the amount of
@@ -10659,6 +10658,18 @@
 it.
 
 @table @gcctabopt
+@item -fbounds-check
+@opindex fbounds-check
+For front-ends that support it, generate additional code to check that
+indices used to access arrays are within the declared range.  This is
+currently only supported by the Java and Fortran 77 front-ends, where
+this option defaults to true and false respectively.
+
+@item -ftrapv
+@opindex ftrapv
+This option generates traps for signed overflow on addition, subtraction,
+multiplication operations.
+
 @item -fexceptions
 @opindex fexceptions
 Enable exception handling.  Generates extra code needed to propagate