[clang] [flang] [llvm] [flang][flang-rt] Add -ffpe-trap= to set the initial FP exception halting mode (PR #208828)

[Tarun Prabhu via cfe-commits]

================
@@ -327,6 +326,54 @@ defm real_sum_reassociation
         standard-conforming Fortran semantics.
       }]>;
 
+def ffpe_trap_EQ : Joined<["-"], "ffpe-trap=">, Group<f_Group>,
+  HelpText<"Set the initial floating-point exception halting mode for the main program">,
+  DocBrief<[{The ``-ffpe-trap=[list]`` option sets the initial floating-point
+exception halting mode for the main program unit. This is the halting mode in
+effect when the main program begins execution; the program may subsequently
+change it (for example, with ``IEEE_SET_HALTING_MODE``). ``[list]`` is a
+comma-separated list of the exceptions to halt on: ``invalid``, ``zero``,
+``overflow``, ``underflow``, and ``inexact``, corresponding to the Fortran 2023
+(17.6) ``IEEE_FLAG_TYPE`` values ``IEEE_INVALID``, ``IEEE_DIVIDE_BY_ZERO``,
+``IEEE_OVERFLOW``, ``IEEE_UNDERFLOW``, and ``IEEE_INEXACT``. As a non-standard
+GFortran-compatible extension, ``denormal`` halts on the hardware denormal
+(subnormal) operand exception. An empty list, or the value ``none``, disables
+halting. In the absence of this option, the program runs with traps disabled
+(equivalent to passing ``none``). Multiple occurrences are allowed; only the
+last ``-ffpe-trap=`` takes effect.
+
+Run-time halting relies on glibc's ``feenableexcept`` (exposed as
+``IEEE_SUPPORT_HALTING``). The compile-time warning is a conservative
+approximation from the target triple; the runtime is the definitive authority on
+which exceptions can be trapped.
+
+The table below summarizes the halting behavior for different system
+configurations. In it, ``halts`` = the exception is trapped, ``ignored`` = no
+run-time effect, "Standard" = ``invalid``, ``zero``, ``overflow``,
+``underflow``, ``inexact`` exceptions, and "Others" = any non-x86 architecture
+(AArch64, PowerPC, RISC-V, ...):
+
++--------+-----------+----------+----------+-------------------+
+| Arch   | C library | Standard | denormal | Warning           |
++========+===========+==========+==========+===================+
+| x86    | glibc     | halts    | halts    | none              |
++--------+-----------+----------+----------+-------------------+
+| Others | glibc     | halts    | ignored  | ``denormal`` only |
++--------+-----------+----------+----------+-------------------+
+| x86    | non-glibc | ignored  | ignored  | none (silent)     |
++--------+-----------+----------+----------+-------------------+
+| Others | non-glibc | ignored  | ignored  | always            |
++--------+-----------+----------+----------+-------------------+
+
+Notes:
----------------
tarunprabhu wrote:

More generally, I think this table helps, but we again have Linux as a special case, which gets mentioned in the notes, but nowhere else. This is a pretty complicated matrix. I think it may be better to move this to flang's documentation and just point users at that page from here. That would give us a lot more formatting options to clarify this.

https://github.com/llvm/llvm-project/pull/208828