PNaCl documentation: add undefined behavior

native_client_sdk/src/doc/reference/pnacl-c-cpp-language-support.rst

Index: native_client_sdk/src/doc/reference/pnacl-c-cpp-language-support.rst
diff --git a/native_client_sdk/src/doc/reference/pnacl-c-cpp-language-support.rst b/native_client_sdk/src/doc/reference/pnacl-c-cpp-language-support.rst
index d63a9439c0c0f7505ba51599a17319b510132991..d61d445ddbdefa35eacb7ec7480a740341148e07 100644
--- a/native_client_sdk/src/doc/reference/pnacl-c-cpp-language-support.rst
+++ b/native_client_sdk/src/doc/reference/pnacl-c-cpp-language-support.rst
@@ -49,7 +49,8 @@ locations to each other as the C11/C++11 standards do.
 
 Non-atomic memory accesses may be reordered, separated, elided or fused
 according to C and C++'s memory model before the pexe is created as well
-as after its creation.
+as after its creation. Accessing atomic memory location through
+non-atomic primitives is `Undefined Behavior <undefined_behavior>`.
 
 As in C11/C++11 some atomic accesses may be implemented with locks on
 certain platforms. The ``ATOMIC_*_LOCK_FREE`` macros will always be
@@ -188,6 +189,41 @@ NaCl supports a fairly wide subset of inline assembly through GCC's
 inline assembly syntax, with the restriction that the sandboxing model
 for the target architecture has to be respected.
 
+Undefined Behavior
+==================
+
+The C and C++ languages expose some undefined behavior which is
+discussed in `PNaCl Undefined Behavior <undefined_behavior>`.
+
+Float-Point
+===========
+
+PNaCl exposes 32-bit and 64-bit floating point operations which are
+mostly IEEE-754 compliant. There are a few caveats:
+
+* Some :ref:`floating-point behavior is currently left as undefined
+  <undefined_behavior_fp>`.
+* Different rounding modes are currently not usable, which isn't
+  IEEE-754 compliant. PNaCl could support switching modes (the 4 modes
+  exposed by C99 ``FLT_ROUNDS`` macros).
+* Signaling ``NaN`` never fault.
+* Fast-math optimizations are currently supported before *pexe* creation
+  time. A *pexe* loses all fast-math information when it is
+  created. Fast-math translation could be enabled at a later date,
+  potentially at a perf-function granularity. This wouldn't affect
+  already-existing *pexe*; it would be an opt-in feature.
+
+  * Fused-multiply-add have higher precision and often execute faster;
+    PNaCl currently disallows them in the *pexe* because they aren't
+    supported on all platforms and can't realistically be
+    emulated. PNaCl could (but currently doesn't) only generate them in
+    the backend if fast-math were specified and the hardware supports
+    the operation.
+  * Transcendentals aren't exposed by PNaCl's ABI; they are part of the
+    math library that is included in the *pexe*. PNaCl could, but
+    currently doesn't, use hardware support if fast-math were provided
+    in the *pexe*.
+
 Future Directions
 =================