Document bug in the x86 NCG w.r.t. -fexcess-precision (#7069)

2 files changed, 38 insertions, 0 deletions

diff --git a/docs/users_guide/bugs.xml b/docs/users_guide/bugs.xml
index 49d6a8dca6..ca0f65f981 100644
--- a/docs/users_guide/bugs.xml
+++ b/docs/users_guide/bugs.xml
@@ -523,6 +523,36 @@ checking for duplicates.  The reason for this is efficiency, pure and simple.
 	  GHCi.</para>
       </listitem>
 
+
+      <listitem>
+        <para>On 32-bit x86 platforms when using the native code
+        generator, the
+        <option>-fexcess-precision</option><indexterm><primary><option>-fexcess-precision</option></primary></indexterm> option
+        is always on.  This means that floating-point calculations are
+        non-deterministic, because depending on how the program is
+        compiled (optimisation settings, for example), certain
+        calculations might be done at 80-bit precision instead of the
+        intended 32-bit or 64-bit precision.  Floating-point results
+        may differ when optimisation is turned on.  In the worst case,
+        referential transparency is violated, because for example
+        <literal>let x = E1 in E2</literal> can evaluate to a
+        different value than <literal>E2[E1/x]</literal>.</para>
+
+        <para>
+          One workaround is to use the
+          <option>-msse2</option><indexterm><primary><option>-msse2</option></primary></indexterm>
+          option (see <xref linkend="options-platform" />, which
+          generates code to use the SSE2 instruction set instead of
+          the x87 instruction set.  SSE2 code uses the correct
+          precision for all floating-point operations, and so gives
+          deterministic results.  However, note that this only works
+          with processors that support SSE2 (Intel Pentium 4 or AMD
+          Athlon 64 and later), which is why the option is not enabled
+          by default.  The libraries that come with GHC are probably
+          built without this option, unless you built GHC yourself.
+        </para>
+      </listitem>
+
     </itemizedlist>
   </sect2>
 
diff --git a/docs/users_guide/using.xml b/docs/users_guide/using.xml
index 265bf85cf0..684b182b9d 100644
--- a/docs/users_guide/using.xml
+++ b/docs/users_guide/using.xml
@@ -2266,6 +2266,14 @@ last (x : xs) = last' x xs
             precision/range of
             <literal>Float</literal>/<literal>Double</literal> values
             and should not use this option for their compilation.</para>
+
+            <para>
+              Note that the 32-bit x86 native code generator only
+              supports excess-precision mode, so neither
+              <option>-fexcess-precision</option> nor
+              <option>-fno-excess-precision</option> has any effect.
+              This is a known bug, see <xref linkend="bugs-ghc" />.
+            </para>
           </listitem>
         </varlistentry>