invoke.texi (Optimization Options): Group together optional and experimental flags.

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

From-SVN: r61897

2 files changed, 234 insertions, 203 deletions

diff --git a/gcc/ChangeLog b/gcc/ChangeLog
index 009fc55f487..c8c64b0d626 100644
--- a/gcc/ChangeLog
+++ b/gcc/ChangeLog
@@ -1,3 +1,10 @@
+2003-01-25  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.
+	(Code Gen Options): Move trapv and bounds-check to here.
+
 2003-01-27  Josef Zlomek  <zlomekj@suse.cz>
 
 	* gcse.c (constprop_register): Check NEXT_INSN (insn) != NULL.
diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi
index 1826df2d2d0..f8a03960d70 100644
--- a/gcc/doc/invoke.texi
+++ b/gcc/doc/invoke.texi
@@ -265,7 +265,6 @@ in the following sections.
 @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
@@ -291,7 +290,7 @@ in the following sections.
 -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}
 
@@ -712,7 +711,8 @@ in the following sections.
 -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
@@ -3527,21 +3527,6 @@ can use the following flags in the rare cases when ``fine-tuning'' of
 optimizations to be performed is desired.
 
 @table @gcctabopt
-@item -ffloat-store
-@opindex ffloat-store
-Do not store floating point variables in registers, and inhibit other
-options that might change whether a floating point value is taken from a
-register or memory.
-
-@cindex floating point precision
-This option prevents undesirable excess precision on machines such as
-the 68000 where the floating registers (of the 68881) keep more
-precision than a @code{double} is supposed to have.  Similarly for the
-x86 architecture.  For most programs, the excess precision does only
-good, but a few programs rely on the precise definition of IEEE floating
-point.  Use @option{-ffloat-store} for such programs, after modifying
-them to store all pertinent intermediate computations into variables.
-
 @item -fno-default-inline
 @opindex fno-default-inline
 Do not make member functions inline by default merely because they are
@@ -3598,11 +3583,6 @@ 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,
-multiplication operations.
-
 @item -fno-inline
 @opindex fno-inline
 Don't pay attention to the @code{inline} keyword.  Normally this option
@@ -3704,89 +3684,6 @@ 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}, @*
-@option{-fno-trapping-math}, @option{-ffinite-math-only} and @*
-@option{-fno-signaling-nans}.
-
-This option causes the preprocessor macro @code{__FAST_MATH__} to be defined.
-
-This option should never be turned on by any @option{-O} option since
-it can result in incorrect output for programs which depend on
-an exact implementation of IEEE or ISO rules/specifications for
-math functions.
-
-@item -fno-math-errno
-@opindex fno-math-errno
-Do not set ERRNO after calling math functions that are executed
-with a single instruction, e.g., sqrt.  A program that relies on
-IEEE exceptions for math error handling may want to use this flag
-for speed while maintaining IEEE arithmetic compatibility.
-
-This option should never be turned on by any @option{-O} option since
-it can result in incorrect output for programs which depend on
-an exact implementation of IEEE or ISO rules/specifications for
-math functions.
-
-The default is @option{-fmath-errno}.
-
-@item -funsafe-math-optimizations
-@opindex funsafe-math-optimizations
-Allow optimizations for floating-point arithmetic that (a) assume
-that arguments and results are valid and (b) may violate IEEE or
-ANSI standards.  When used at link-time, it may include libraries
-or startup files that change the default FPU control word or other
-similar optimizations.
-
-This option should never be turned on by any @option{-O} option since
-it can result in incorrect output for programs which depend on
-an exact implementation of IEEE or ISO rules/specifications for
-math functions.
-
-The default is @option{-fno-unsafe-math-optimizations}.
-
-@item -ffinite-math-only
-@opindex ffinite-math-only
-Allow optimizations for floating-point arithmetic that assume
-that arguments and results are not NaNs or +-Infs.
-
-This option should never be turned on by any @option{-O} option since
-it can result in incorrect output for programs which depend on
-an exact implementation of IEEE or ISO rules/specifications.
-
-The default is @option{-fno-finite-math-only}.
-
-@item -fno-trapping-math
-@opindex fno-trapping-math
-Compile code assuming that floating-point operations cannot generate
-user-visible traps.  These traps include division by zero, overflow,
-underflow, inexact result and invalid operation.  This option implies
-@option{-fno-signaling-nans}.  Setting this option may allow faster
-code if one relies on ``non-stop'' IEEE arithmetic, for example.
-
-This option should never be turned on by any @option{-O} option since
-it can result in incorrect output for programs which depend on
-an exact implementation of IEEE or ISO rules/specifications for
-math functions.
-
-The default is @option{-ftrapping-math}.
-
-@item -fsignaling-nans
-@opindex fsignaling-nans
-Compile code assuming that IEEE signaling NaNs may generate user-visible
-traps during floating-point operations.  Setting this option disables
-optimizations that may change the number of exceptions visible with
-signaling NaNs.  This option implies @option{-ftrapping-math}.
-
-This option causes the preprocessor macro @code{__SUPPORT_SNAN__} to
-be defined.
-
-The default is @option{-fno-signaling-nans}.
-
-This option is experimental and does not currently guarantee to
-disable all GCC optimizations that affect signaling NaN behavior.
-
 @item -fno-zero-initialized-in-bss
 @opindex fno-zero-initialized-in-bss
 If the target supports a BSS section, GCC by default puts variables that
@@ -3800,13 +3697,6 @@ assumptions based on that.
 
 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.
-
 @item -fstrength-reduce
 @opindex fstrength-reduce
 Perform the optimizations of loop strength reduction and
@@ -4003,28 +3893,6 @@ Allow speculative motion of more load instructions.  This only makes
 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 @command{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
@@ -4037,33 +3905,6 @@ those which have no call-preserved registers to use instead.
 
 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
@@ -4103,27 +3944,6 @@ 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}
-(@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.
@@ -4270,6 +4090,218 @@ If @var{n} is not specified, use a machine-dependent default.
 
 Enabled at levels @option{-O2}, @option{-O3}.
 
+@item -frename-registers
+@opindex frename-registers
+Attempt to avoid false dependencies in scheduled code by making use
+of registers left over after register allocation.  This optimization
+will most benefit processors with lots of registers.  It can, however,
+make debugging impossible, since variables will no longer stay in
+a ``home register''.
+
+Enabled at levels @option{-O3}.
+
+@item -fno-cprop-registers
+@opindex fno-cprop-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.
+
+Disabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
+
+@end table
+
+The following options control compiler behavior regarding floating
+point arithmetic.  These options trade off between speed and
+correctness.  All must be specifically enabled.
+
+@table @gcctabopt
+@item -ffloat-store
+@opindex ffloat-store
+Do not store floating point variables in registers, and inhibit other
+options that might change whether a floating point value is taken from a
+register or memory.
+
+@cindex floating point precision
+This option prevents undesirable excess precision on machines such as
+the 68000 where the floating registers (of the 68881) keep more
+precision than a @code{double} is supposed to have.  Similarly for the
+x86 architecture.  For most programs, the excess precision does only
+good, but a few programs rely on the precise definition of IEEE floating
+point.  Use @option{-ffloat-store} for such programs, after modifying
+them to store all pertinent intermediate computations into variables.
+
+@item -ffast-math
+@opindex ffast-math
+Sets @option{-fno-math-errno}, @option{-funsafe-math-optimizations}, @*
+@option{-fno-trapping-math}, @option{-ffinite-math-only} and @*
+@option{-fno-signaling-nans}.
+
+This option causes the preprocessor macro @code{__FAST_MATH__} to be defined.
+
+This option should never be turned on by any @option{-O} option since
+it can result in incorrect output for programs which depend on
+an exact implementation of IEEE or ISO rules/specifications for
+math functions.
+
+@item -fno-math-errno
+@opindex fno-math-errno
+Do not set ERRNO after calling math functions that are executed
+with a single instruction, e.g., sqrt.  A program that relies on
+IEEE exceptions for math error handling may want to use this flag
+for speed while maintaining IEEE arithmetic compatibility.
+
+This option should never be turned on by any @option{-O} option since
+it can result in incorrect output for programs which depend on
+an exact implementation of IEEE or ISO rules/specifications for
+math functions.
+
+The default is @option{-fmath-errno}.
+
+@item -funsafe-math-optimizations
+@opindex funsafe-math-optimizations
+Allow optimizations for floating-point arithmetic that (a) assume
+that arguments and results are valid and (b) may violate IEEE or
+ANSI standards.  When used at link-time, it may include libraries
+or startup files that change the default FPU control word or other
+similar optimizations.
+
+This option should never be turned on by any @option{-O} option since
+it can result in incorrect output for programs which depend on
+an exact implementation of IEEE or ISO rules/specifications for
+math functions.
+
+The default is @option{-fno-unsafe-math-optimizations}.
+
+@item -ffinite-math-only
+@opindex ffinite-math-only
+Allow optimizations for floating-point arithmetic that assume
+that arguments and results are not NaNs or +-Infs.
+
+This option should never be turned on by any @option{-O} option since
+it can result in incorrect output for programs which depend on
+an exact implementation of IEEE or ISO rules/specifications.
+
+The default is @option{-fno-finite-math-only}.
+
+@item -fno-trapping-math
+@opindex fno-trapping-math
+Compile code assuming that floating-point operations cannot generate
+user-visible traps.  These traps include division by zero, overflow,
+underflow, inexact result and invalid operation.  This option implies
+@option{-fno-signaling-nans}.  Setting this option may allow faster
+code if one relies on ``non-stop'' IEEE arithmetic, for example.
+
+This option should never be turned on by any @option{-O} option since
+it can result in incorrect output for programs which depend on
+an exact implementation of IEEE or ISO rules/specifications for
+math functions.
+
+The default is @option{-ftrapping-math}.
+
+@item -fsignaling-nans
+@opindex fsignaling-nans
+Compile code assuming that IEEE signaling NaNs may generate user-visible
+traps during floating-point operations.  Setting this option disables
+optimizations that may change the number of exceptions visible with
+signaling NaNs.  This option implies @option{-ftrapping-math}.
+
+This option causes the preprocessor macro @code{__SUPPORT_SNAN__} to
+be defined.
+
+The default is @option{-fno-signaling-nans}.
+
+This option is experimental and does not currently guarantee to
+disable all GCC optimizations that affect signaling NaN behavior.
+
+@item -fsingle-precision-constant
+@opindex fsingle-precision-constant
+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
@@ -4287,28 +4319,8 @@ Perform Sparse Conditional Constant Propagation in SSA form.  Requires
 Perform aggressive dead-code elimination in SSA form.  Requires @option{-fssa}.
 Like @option{-fssa}, this is an experimental feature.
 
-@item -fsingle-precision-constant
-@opindex fsingle-precision-constant
-Treat floating point constant as single precision constant instead of
-implicitly converting it to double precision constant.
-
-@item -frename-registers
-@opindex frename-registers
-Attempt to avoid false dependencies in scheduled code by making use
-of registers left over after register allocation.  This optimization
-will most benefit processors with lots of registers.  It can, however,
-make debugging impossible, since variables will no longer stay in
-a ``home register''.
-
-Enabled at levels @option{-O3}.
 
-@item -fno-cprop-registers
-@opindex fno-cprop-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.
 
-Disabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
 
 @item --param @var{name}=@var{value}
 @opindex param
@@ -10578,6 +10590,18 @@ can figure out the other form by either removing @samp{no-} or adding
 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