PNaCl documentation: add undefined behavior

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

 ============================
 PNaCl C/C++ Language Support
 ============================
 
 .. contents::
    :local:
    :backlinks: none
    :depth: 3
 
 Source language support
@@ skipping 31 matching lines @@
 The memory model offered by PNaCl relies on the same coding guidelines
 as the C11/C++11 one: concurrent accesses must always occur through
 atomic primitives (offered by `atomic intrinsics
 <PNaClLangRef.html#atomicintrinsics>`_), and these accesses must always
 occur with the same size for the same memory location. Visibility of
 stores is provided on a happens-before basis that relates memory
 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
 ``1``, signifying that all types are sometimes lock-free. The
 ``is_lock_free`` methods and ``atomic_is_lock_free`` will return the
 current platform's implementation at translation time. These macros,
 methods and functions are in the C11 header ``<stdatomic.h>`` and the
 C++11 header ``<atomic>``.
 
 The PNaCl toolchain supports concurrent memory accesses through legacy
@@ skipping 118 matching lines @@
 ``asm("":::"memory")``, which gets transformed to a sequentially
 consistent memory barrier (equivalent to ``__sync_synchronize()``). In
 PNaCl this barrier is only guaranteed to order ``volatile`` and atomic
 memory accesses, though in practice the implementation attempts to also
 prevent reordering of memory accesses to objects which may escape.
 
 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
 =================
 
 SIMD
 ----
 
 PNaCl currently doesn't support SIMD. We plan to add SIMD support in the
 very near future.
 
 NaCl supports SIMD.
@@ skipping 36 matching lines @@
 ``volatile`` and atomics with same-thread signal handling would need
 to be carefully detailed.
 
 Computed ``goto``
 -----------------
 
 PNaCl currently doesn't support computed ``goto``, a non-standard
 extension to C used by some interpreters.
 
 NaCl supports computed ``goto``.