PNaCl documentation: add undefined behavior

native_client_sdk/doc_generated/reference/pnacl-c-cpp-language-support.html

 {{+bindTo:partials.standard_nacl_article}}
 
 <section id="pnacl-c-c-language-support">
 <h1 id="pnacl-c-c-language-support">PNaCl C/C++ Language Support</h1>
 <div class="contents local" id="contents" style="display: none">
 <ul class="small-gap">
 <li><p class="first"><a class="reference internal" href="#source-language-support" id="id2">Source language support</a></p>
 <ul class="small-gap">
 <li><a class="reference internal" href="#preprocessor-definitions" id="id3">Preprocessor definitions</a></li>
 </ul>
 </li>
 <li><p class="first"><a class="reference internal" href="#memory-model-and-atomics" id="id4">Memory Model and Atomics</a></p>
 <ul class="small-gap">
 <li><a class="reference internal" href="#memory-model-for-concurrent-operations" id="id5">Memory Model for Concurrent Operations</a></li>
 <li><a class="reference internal" href="#atomic-memory-ordering-constraints" id="id6">Atomic Memory Ordering Constraints</a></li>
 <li><a class="reference internal" href="#volatile-memory-accesses" id="id7">Volatile Memory Accesses</a></li>
 </ul>
 </li>
 <li><a class="reference internal" href="#threading" id="id8">Threading</a></li>
 <li><a class="reference internal" href="#setjmp-and-longjmp" id="id9"><code>setjmp</code> and <code>longjmp</code></a></li>
 <li><a class="reference internal" href="#c-exception-handling" id="id10">C++ Exception Handling</a></li>
 <li><a class="reference internal" href="#inline-assembly" id="id11">Inline Assembly</a></li>
-<li><p class="first"><a class="reference internal" href="#future-directions" id="id12">Future Directions</a></p>
+<li><a class="reference internal" href="#undefined-behavior" id="id12">Undefined Behavior</a></li>
+<li><a class="reference internal" href="#float-point" id="id13">Float-Point</a></li>
+<li><p class="first"><a class="reference internal" href="#future-directions" id="id14">Future Directions</a></p>
 <ul class="small-gap">
-<li><a class="reference internal" href="#simd" id="id13">SIMD</a></li>
-<li><a class="reference internal" href="#inter-process-communication" id="id14">Inter-Process Communication</a></li>
-<li><a class="reference internal" href="#posix-style-signal-handling" id="id15">POSIX-style Signal Handling</a></li>
-<li><a class="reference internal" href="#computed-goto" id="id16">Computed <code>goto</code></a></li>
+<li><a class="reference internal" href="#simd" id="id15">SIMD</a></li>
+<li><a class="reference internal" href="#inter-process-communication" id="id16">Inter-Process Communication</a></li>
+<li><a class="reference internal" href="#posix-style-signal-handling" id="id17">POSIX-style Signal Handling</a></li>
+<li><a class="reference internal" href="#computed-goto" id="id18">Computed <code>goto</code></a></li>
 </ul>
 </li>
 </ul>
 
 </div><section id="source-language-support">
 <h2 id="source-language-support">Source language support</h2>
 <p>The currently supported languages are C and C++. The PNaCl toolchain is
 based on Clang 3.3, which fully supports C++11 and most of C11. A
 detailed status of the language support is available <a class="reference external" href="http://clang.llvm.org/cxx_status.html">here</a>.</p>
 <p>For information on using languages other than C/C++, see the <a class="reference internal" href="/native-client/faq.html#other-languages"><em>FAQ
@@ skipping 13 matching lines @@
 <section id="memory-model-for-concurrent-operations">
 <h3 id="memory-model-for-concurrent-operations">Memory Model for Concurrent Operations</h3>
 <p>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 <a class="reference external" href="PNaClLangRef.html#atomicintrinsics">atomic intrinsics</a>), 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.</p>
 <p>Non-atomic memory accesses may be reordered, separated, elided or fused
 according to C and C++&#8217;s memory model before the pexe is created as well
-as after its creation.</p>
+as after its creation. Accessing atomic memory location through
+non-atomic primitives is <cite>Undefined Behavior &lt;undefined_behavior&gt;</cite>.</p>
 <p>As in C11/C++11 some atomic accesses may be implemented with locks on
 certain platforms. The <code>ATOMIC_*_LOCK_FREE</code> macros will always be
 <code>1</code>, signifying that all types are sometimes lock-free. The
 <code>is_lock_free</code> methods and <code>atomic_is_lock_free</code> will return the
 current platform&#8217;s implementation at translation time. These macros,
 methods and functions are in the C11 header <code>&lt;stdatomic.h&gt;</code> and the
 C++11 header <code>&lt;atomic&gt;</code>.</p>
 <p>The PNaCl toolchain supports concurrent memory accesses through legacy
 GCC-style <code>__sync_*</code> builtins, as well as through C11/C++11 atomic
 primitives and the underlying <a class="reference external" href="http://gcc.gnu.org/wiki/Atomic/GCCMM">GCCMM</a> <code>__atomic_*</code>
@@ skipping 88 matching lines @@
 <p>Inline assembly isn&#8217;t supported by PNaCl because it isn&#8217;t portable. The
 one current exception is the common compiler barrier idiom
 <code>asm(&quot;&quot;:::&quot;memory&quot;)</code>, which gets transformed to a sequentially
 consistent memory barrier (equivalent to <code>__sync_synchronize()</code>). In
 PNaCl this barrier is only guaranteed to order <code>volatile</code> and atomic
 memory accesses, though in practice the implementation attempts to also
 prevent reordering of memory accesses to objects which may escape.</p>
 <p>NaCl supports a fairly wide subset of inline assembly through GCC&#8217;s
 inline assembly syntax, with the restriction that the sandboxing model
 for the target architecture has to be respected.</p>
+</section><section id="undefined-behavior">
+<h2 id="undefined-behavior">Undefined Behavior</h2>
+<p>The C and C++ languages expose some undefined behavior which is
+discussed in <cite>PNaCl Undefined Behavior &lt;undefined_behavior&gt;</cite>.</p>
+</section><section id="float-point">
+<h2 id="float-point">Float-Point</h2>
+<p>PNaCl exposes 32-bit and 64-bit floating point operations which are
+mostly IEEE-754 compliant. There are a few caveats:</p>
+<ul class="small-gap">
+<li>Some <a class="reference internal" href="/native-client/reference/pnacl-undefined-behavior.html#undefined-behavior-fp"><em>floating-point behavior is currently left as undefined</em></a>.</li>
+<li>Different rounding modes are currently not usable, which isn&#8217;t
+IEEE-754 compliant. PNaCl could support switching modes (the 4 modes
+exposed by C99 <code>FLT_ROUNDS</code> macros).</li>
+<li>Signaling <code>NaN</code> never fault.</li>
+<li><p class="first">Fast-math optimizations are currently supported before <em>pexe</em> creation
+time. A <em>pexe</em> 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&#8217;t affect
+already-existing <em>pexe</em>; it would be an opt-in feature.</p>
+<ul class="small-gap">
+<li>Fused-multiply-add have higher precision and often execute faster;
+PNaCl currently disallows them in the <em>pexe</em> because they aren&#8217;t
+supported on all platforms and can&#8217;t realistically be
+emulated. PNaCl could (but currently doesn&#8217;t) only generate them in
+the backend if fast-math were specified and the hardware supports
+the operation.</li>
+<li>Transcendentals aren&#8217;t exposed by PNaCl&#8217;s ABI; they are part of the
+math library that is included in the <em>pexe</em>. PNaCl could, but
+currently doesn&#8217;t, use hardware support if fast-math were provided
+in the <em>pexe</em>.</li>
+</ul>
+</li>
+</ul>
 </section><section id="future-directions">
 <h2 id="future-directions">Future Directions</h2>
 <section id="simd">
 <h3 id="simd">SIMD</h3>
 <p>PNaCl currently doesn&#8217;t support SIMD. We plan to add SIMD support in the
 very near future.</p>
 <p>NaCl supports SIMD.</p>
 </section><section id="inter-process-communication">
 <h3 id="inter-process-communication">Inter-Process Communication</h3>
 <p>Inter-process communication through shared memory is currently not
@@ skipping 26 matching lines @@
 <code>volatile</code> and atomics with same-thread signal handling would need
 to be carefully detailed.</p>
 </section><section id="computed-goto">
 <h3 id="computed-goto">Computed <code>goto</code></h3>
 <p>PNaCl currently doesn&#8217;t support computed <code>goto</code>, a non-standard
 extension to C used by some interpreters.</p>
 <p>NaCl supports computed <code>goto</code>.</p>
 </section></section></section>
 
 {{/partials.standard_nacl_article}}