[PATCH] optimization docs part 4

[Jerome L Quinn]

This patch groups the floating point flags together.  Currently they are
spread out in
several places.  It seemed more intuitive to me to have them all in one
place.

2002-08-30 Jerry Quinn <jlquinn@us.ibm.com>
      * gcc/gcc/doc/invoke.texi (Optimization Options): Group floating
point flags together.

--- gcc/gcc/doc/invoke.texi.safe           2002-08-25 01:28:13.000000000
-0400
+++ gcc/gcc/doc/invoke.texi          2002-08-25 01:35:37.000000000 -0400
@@ -3275,21 +3275,6 @@
 adding it.

 @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
@@ -3445,89 +3430,6 @@

 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
@@ -4015,11 +3917,6 @@
 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
@@ -4038,6 +3935,117 @@

 Enabled 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.
+
 @item --param @var{name}=@var{value}
 @opindex param
 In some places, GCC uses various constants to control the amount of