[PATCH] optimization docs part 5

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

This patch groups together optimization flags that are not enabled at any -
O level.
Flags that are closely related to ones enabled at -O levels I left alone,
since they made
sense to leave there.

I've grouped together -ftrapv, -fnew-ra, -ffunction-sections, -fdata-
sections, -ftracer, -funroll-loops,
-funroll-all-loops, -fprefetch-loop-arrays, -fssa, -fssa-dce, and -fssa-
ccp.

2002-08-30 Jerry Quinn <jlquinn@us.ibm.com>
      * gcc/gcc/doc/invoke.texi (Optimization Options): Group together
optional and
      experimental optimizations.

--- gcc/gcc/doc/invoke.texi.safe           2002-08-25 01:37:00.000000000
-0400
+++ gcc/gcc/doc/invoke.texi          2002-08-25 01:39:33.000000000 -0400
@@ -3335,11 +3335,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
@@ -3413,12 +3408,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-function-cse
 @opindex fno-function-cse
 Do not put function addresses in registers; make each instruction that
@@ -3630,28 +3619,6 @@

 Enabled at levels @option{-O2}, @option{-O3}, @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 -fcaller-saves
 @opindex fcaller-saves
 Enable values to be allocated in registers that will be clobbered by
@@ -3667,33 +3634,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
@@ -3900,23 +3840,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
@@ -4046,6 +3969,93 @@
 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 -ftrapv
+@opindex ftrapv
+This option generates traps for signed overflow on addition, subtraction,
+multiplication operations.
+
+@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 -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 -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