Clarify FP exception documentation and messages

From-SVN: r173944

gcc/fortran/ChangeLog

@@ -1,4 +1,12 @@
-2011-06-19  Tobias Burnus  <burnus@net-b.de>
+2011-05-20  Janne Blomqvist  <jb@gcc.gnu.org>
+
+        * gfortran.texi (set_fpe): Update documentation.
+        * invoke.texi (-ffpe-trap): Likewise.
+        * libgfortran.h (GFC_FPE_PRECISION): Rename to GFC_FPE_INEXACT.
+        * options.c (gfc_handle_fpe_trap_option): Handle inexact and make
+        precision an alias for it.
+
+2011-05-19  Tobias Burnus  <burnus@net-b.de>
 
 	PR fortran/18918
 	* trans-types.c (gfc_get_element_type): Handle scalar coarrays.

gcc/fortran/gfortran.texi

@@ -2718,16 +2718,15 @@ int main (int argc, char *argv[])
 
 
 @node _gfortran_set_fpe
-@subsection @code{_gfortran_set_fpe} --- Set when a Floating Point Exception should be raised
+@subsection @code{_gfortran_set_fpe} --- Enable floating point exception traps
 @fnindex _gfortran_set_fpe
 @cindex libgfortran initialization, set_fpe
 
 @table @asis
 @item @emph{Description}:
-@code{_gfortran_set_fpe} sets the IEEE exceptions for which a
+@code{_gfortran_set_fpe} enables floating point exception traps for
-Floating Point Exception (FPE) should be raised.  On most systems,
+the specified exceptions.  On most systems, this will result in a
-this will result in a SIGFPE signal being sent and the program
+SIGFPE signal being sent and the program being aborted.
-being interrupted.
 
 @item @emph{Syntax}:
 @code{void _gfortran_set_fpe (int val)}
@@ -2738,7 +2737,7 @@ being interrupted.
 (bitwise or-ed) zero (0, default) no trapping,
 @code{GFC_FPE_INVALID} (1), @code{GFC_FPE_DENORMAL} (2),
 @code{GFC_FPE_ZERO} (4), @code{GFC_FPE_OVERFLOW} (8),
-@code{GFC_FPE_UNDERFLOW} (16), and @code{GFC_FPE_PRECISION} (32).
+@code{GFC_FPE_UNDERFLOW} (16), and @code{GFC_FPE_INEXACT} (32).
 @end multitable
 
 @item @emph{Example}:

gcc/fortran/invoke.texi

@@ -919,21 +919,31 @@ GNU Fortran compiler itself.  This option is deprecated; use
 
 @item -ffpe-trap=@var{list}
 @opindex @code{ffpe-trap=}@var{list}
-Specify a list of IEEE exceptions when a Floating Point Exception
+Specify a list of floating point exception traps to enable.  On most
-(FPE) should be raised.  On most systems, this will result in a SIGFPE
+systems, if a floating point exception occurs and the trap for that
-signal being sent and the program being interrupted, producing a core
+exception is enabled, a SIGFPE signal will be sent and the program
-file useful for debugging.  @var{list} is a (possibly empty) comma-separated
+being aborted, producing a core file useful for debugging.  @var{list}
-list of the following IEEE exceptions: @samp{invalid} (invalid floating
+is a (possibly empty) comma-separated list of the following
-point operation, such as @code{SQRT(-1.0)}), @samp{zero} (division by
+exceptions: @samp{invalid} (invalid floating point operation, such as
-zero), @samp{overflow} (overflow in a floating point operation),
+@code{SQRT(-1.0)}), @samp{zero} (division by zero), @samp{overflow}
-@samp{underflow} (underflow in a floating point operation),
+(overflow in a floating point operation), @samp{underflow} (underflow
-@samp{precision} (loss of precision during operation) and @samp{denormal}
+in a floating point operation), @samp{inexact} (loss of precision
-(operation produced a denormal value).
+during operation), and @samp{denormal} (operation performed on a
+denormal value).  The first five exceptions correspond to the five
+IEEE 754 exceptions, whereas the last one (@samp{denormal}) is not
+part of the IEEE 754 standard but is available on some common
+architectures such as x86.
 
-Some of the routines in the Fortran runtime library, like
+The first three exceptions (@samp{invalid}, @samp{zero}, and
-@samp{CPU_TIME}, are likely to trigger floating point exceptions when
+@samp{overflow}) often indicate serious errors, and unless the program
-@code{ffpe-trap=precision} is used. For this reason, the use of 
+has provisions for dealing with these exceptions, enabling traps for
-@code{ffpe-trap=precision} is not recommended.
+these three exceptions is probably a good idea.
+
+Many, if not most, floating point operations incur loss of precision
+due to rounding, and hence the @code{ffpe-trap=inexact} is likely to
+be uninteresting in practice.
+
+By default no exception traps are enabled.
 
 @item -fno-backtrace
 @opindex @code{fno-backtrace}

gcc/fortran/libgfortran.h

@@ -42,7 +42,7 @@ along with GCC; see the file COPYING3.  If not see
 #define GFC_FPE_ZERO       (1<<2)
 #define GFC_FPE_OVERFLOW   (1<<3)
 #define GFC_FPE_UNDERFLOW  (1<<4)
-#define GFC_FPE_PRECISION  (1<<5)
+#define GFC_FPE_INEXACT    (1<<5)
 
 
 /* Bitmasks for the various runtime checks that can be enabled.  */

gcc/fortran/options.c

@@ -492,12 +492,14 @@ static void
 gfc_handle_fpe_trap_option (const char *arg)
 {
   int result, pos = 0, n;
+  /* precision is a backwards compatibility alias for inexact.  */
   static const char * const exception[] = { "invalid", "denormal", "zero",
 					    "overflow", "underflow",
-					    "precision", NULL };
+					    "inexact", "precision", NULL };
   static const int opt_exception[] = { GFC_FPE_INVALID, GFC_FPE_DENORMAL,
 				       GFC_FPE_ZERO, GFC_FPE_OVERFLOW,
-				       GFC_FPE_UNDERFLOW, GFC_FPE_PRECISION,
+				       GFC_FPE_UNDERFLOW, GFC_FPE_INEXACT,
+				       GFC_FPE_INEXACT,
 				       0 };
  
   while (*arg)

libgfortran/ChangeLog

@@ -1,3 +1,14 @@
+2011-05-20  Janne Blomqvist  <jb@gcc.gnu.org>
+
+        * config/fpu-387.h (set_fpu): Use renamed inexact macro.
+        * config/fpu-aix.h (set_fpu): Clarify error messages, use renamed
+        inexact macro, set TRP_INEXACT for inexact exception instead of
+        TRP_UNDERFLOW.
+        * config/fpu-generic.h (set_fpu): Clarify error messages, use
+        renamed inexact macro.
+        * config/fpu-glibc.h (set_fpu): Likewise.
+        * config/fpu-sysv.h (set_fpu): Likewise.
+
 2011-05-14  Tobias Burnus  <burnus@net-b.de>
 
 	* runtime/stop.c (error_stop_string, error_stop_numeric):

libgfortran/config/fpu-387.h

@@ -110,7 +110,7 @@ void set_fpu (void)
   if (options.fpe & GFC_FPE_ZERO) cw &= ~_FPU_MASK_ZM;
   if (options.fpe & GFC_FPE_OVERFLOW) cw &= ~_FPU_MASK_OM;
   if (options.fpe & GFC_FPE_UNDERFLOW) cw &= ~_FPU_MASK_UM;
-  if (options.fpe & GFC_FPE_PRECISION) cw &= ~_FPU_MASK_PM;
+  if (options.fpe & GFC_FPE_INEXACT) cw &= ~_FPU_MASK_PM;
 
   asm volatile ("fldcw %0" : : "m" (cw));
 
@@ -129,7 +129,7 @@ void set_fpu (void)
       if (options.fpe & GFC_FPE_ZERO) cw_sse &= ~(_FPU_MASK_ZM << 7);
       if (options.fpe & GFC_FPE_OVERFLOW) cw_sse &= ~(_FPU_MASK_OM << 7);
       if (options.fpe & GFC_FPE_UNDERFLOW) cw_sse &= ~(_FPU_MASK_UM << 7);
-      if (options.fpe & GFC_FPE_PRECISION) cw_sse &= ~(_FPU_MASK_PM << 7);
+      if (options.fpe & GFC_FPE_INEXACT) cw_sse &= ~(_FPU_MASK_PM << 7);
 
       asm volatile ("ldmxcsr %0" : : "m" (cw_sse));
     }

libgfortran/config/fpu-aix.h

@@ -43,7 +43,7 @@ set_fpu (void)
 #endif
 
   if (options.fpe & GFC_FPE_DENORMAL)
-    estr_write ("Fortran runtime warning: IEEE 'denormal number' "
+    estr_write ("Fortran runtime warning: Floating point 'denormal operand' "
 	        "exception not supported.\n");
 
   if (options.fpe & GFC_FPE_ZERO)
@@ -70,11 +70,11 @@ set_fpu (void)
 	        "exception not supported.\n");
 #endif
 
-  if (options.fpe & GFC_FPE_PRECISION)
+  if (options.fpe & GFC_FPE_INEXACT)
-#ifdef TRP_UNDERFLOW
+#ifdef TRP_INEXACT
-    mode |= TRP_UNDERFLOW;
+    mode |= TRP_INEXACT;
 #else
-    estr_write ("Fortran runtime warning: IEEE 'loss of precision' "
+    estr_write ("Fortran runtime warning: IEEE 'inexact' "
 	        "exception not supported.\n");
 #endif
 

libgfortran/config/fpu-generic.h

@@ -35,7 +35,7 @@ set_fpu (void)
     estr_write ("Fortran runtime warning: IEEE 'invalid operation' "
 	        "exception not supported.\n");
   if (options.fpe & GFC_FPE_DENORMAL)
-    estr_write ("Fortran runtime warning: IEEE 'denormal number' "
+    estr_write ("Fortran runtime warning: Floating point 'denormal operand' "
 	        "exception not supported.\n");
   if (options.fpe & GFC_FPE_ZERO)
     estr_write ("Fortran runtime warning: IEEE 'division by zero' "
@@ -46,7 +46,7 @@ set_fpu (void)
   if (options.fpe & GFC_FPE_UNDERFLOW)
     estr_write ("Fortran runtime warning: IEEE 'underflow' "
 	        "exception not supported.\n");
-  if (options.fpe & GFC_FPE_PRECISION)
+  if (options.fpe & GFC_FPE_INEXACT)
-    estr_write ("Fortran runtime warning: IEEE 'loss of precision' "
+    estr_write ("Fortran runtime warning: IEEE 'inexact' "
 	        "exception not supported.\n");
 }

libgfortran/config/fpu-glibc.h

@@ -49,7 +49,7 @@ void set_fpu (void)
 #ifdef FE_DENORMAL
     feenableexcept (FE_DENORMAL);
 #else
-    estr_write ("Fortran runtime warning: IEEE 'denormal number' "
+    estr_write ("Fortran runtime warning: Floating point 'denormal operand' "
 	        "exception not supported.\n");
 #endif
 
@@ -77,11 +77,11 @@ void set_fpu (void)
 	        "exception not supported.\n");
 #endif
 
-  if (options.fpe & GFC_FPE_PRECISION)
+  if (options.fpe & GFC_FPE_INEXACT)
 #ifdef FE_INEXACT
     feenableexcept (FE_INEXACT);
 #else
-    estr_write ("Fortran runtime warning: IEEE 'loss of precision' "
+    estr_write ("Fortran runtime warning: IEEE 'inexact' "
 	        "exception not supported.\n");
 #endif
 }

libgfortran/config/fpu-sysv.h

@@ -42,7 +42,7 @@ set_fpu (void)
 #ifdef FP_X_DNML
     cw |= FP_X_DNML;
 #else
-    estr_write ("Fortran runtime warning: IEEE 'denormal number' "
+    estr_write ("Fortran runtime warning: Floating point 'denormal operand' "
 	        "exception not supported.\n");
 #endif
 
@@ -70,11 +70,11 @@ set_fpu (void)
 	        "exception not supported.\n");
 #endif
 
-  if (options.fpe & GFC_FPE_PRECISION)
+  if (options.fpe & GFC_FPE_INEXACT)
 #ifdef FP_X_IMP
     cw |= FP_X_IMP;
 #else
-    estr_write ("Fortran runtime warning: IEEE 'loss of precision' "
+    estr_write ("Fortran runtime warning: IEEE 'inexact' "
 	        "exception not supported.\n");
 #endif