Rework PNaCl memory ordering

docs/PNaClLangRef.rst

 ==============================
 PNaCl Bitcode Reference Manual
 ==============================
 
 .. contents::
    :local:
    :depth: 3
 
 Introduction
 ============
@@ skipping 125 matching lines @@
 
 `LLVM LangRef: Module-Level Inline Assembly <LangRef.html#moduleasm>`_
 
 PNaCl bitcode does not support inline assembly.
 
 Volatile Memory Accesses
 ------------------------
 
 `LLVM LangRef: Volatile Memory Accesses <LangRef.html#volatile>`_
 
-PNaCl bitcode does not support volatile memory accesses. The ``volatile``
-attribute on loads and stores is not supported. See the
+PNaCl bitcode does not support volatile memory accesses. The
+``volatile`` attribute on loads and stores is not supported. See the
 `PNaCl Developer's Guide <PNaClDeveloperGuide.html>`_ for more details.
 
 Memory Model for Concurrent Operations
 --------------------------------------
 
-`LLVM LangRef: Memory Model for Concurrent Operations <LangRef.html#memmodel>`_
+`LLVM LangRef: Memory Model for Concurrent Operations
+<LangRef.html#memmodel>`_
 
-See the `PNaCl Developer's Guide <PNaClDeveloperGuide.html>`_ for more details.
+See the `PNaCl Developer's Guide <PNaClDeveloperGuide.html>`_ for more
+details.
 
 Atomic Memory Ordering Constraints
 ----------------------------------
 
 `LLVM LangRef: Atomic Memory Ordering Constraints <LangRef.html#ordering>`_
 
-PNaCl bitcode currently supports sequential consistency only, through its
-`atomic intrinsics`_. See the
-`PNaCl Developer's Guide <PNaClDeveloperGuide.html>`_ for more details.
+PNaCl bitcode currently supports sequential consistency only, through
+its `atomic intrinsics`_. See the `PNaCl Developer's Guide
+<PNaClDeveloperGuide.html>`_ for more details. It supports the usually

[eliben, 2013/08/05 18:35:54]

Parse error on: "the usually C11/C++11 sequential consistency"

[JF, 2013/08/05 20:37:48]

Done.

+C11/C++11 sequential consistency, as well as a stronger form of
+sequential consistency which attempts to act as a barrier for non-atomic
+and non-``volatile`` accesses.
 
 Fast-Math Flags
 ---------------
 
 `LLVM LangRef: Fast-Math Flags <LangRef.html#fastmath>`_
 
 Fast-math mode is not currently supported by the PNaCl bitcode.
 
 Type System
 ===========
@@ skipping 228 matching lines @@
 
   See :ref:`Setjmp and Longjmp <setjmplongjmp>`.
 
 .. _atomic intrinsics:
 
 * ``llvm.nacl.atomic.store``
 * ``llvm.nacl.atomic.load``
 * ``llvm.nacl.atomic.rmw``
 * ``llvm.nacl.atomic.cmpxchg``
 * ``llvm.nacl.atomic.fence``
+* ``llvm.nacl.atomic.is.lock.free``
 
   See :ref:`atomic intrinsics <atomicintrinsics>`.
 
 .. _threadpointerintrinsics:
 
 Thread pointer related intrinsics
 ---------------------------------
 
 .. code-block:: llvm
 
     declare i8* @llvm.nacl.read.tp()
 
 Returns the thread pointer, which can be set by the embedding sandbox's runtime.
 
 .. _setjmplongjmp:
 
 Setjmp and Longjmp
 ------------------
 
 .. code-block:: llvm
 
     declare void @llvm.nacl.longjmp(i8* %jmpbuf, i32)
     declare i32 @llvm.nacl.setjmp(i8* %jmpbuf)
 
-These intrinsics implement the semantics of C11 ``setjmp`` and ``longjmp``. The
-``jmpbuf`` pointer must be 64-bit aligned and point to at least 1024 bytes of
-allocated memory.
+These intrinsics implement the semantics of C11 ``setjmp`` and

[eliben, 2013/08/05 18:35:54]

What are these reformatting changes doing here?

[JF, 2013/08/05 20:37:48]

Enthusiastic select-and-auto-format got a bit further than I intended.

+``longjmp``. The ``jmpbuf`` pointer must be 64-bit aligned and point to
+at least 1024 bytes of allocated memory.
 
 .. _atomicintrinsics:
 
 Atomic intrinsics
 -----------------
 
 .. code-block:: llvm
 
     declare iN @llvm.nacl.atomic.load.<size>(
             iN* <source>, i32 <memory_order>)
     declare void @llvm.nacl.atomic.store.<size>(
             iN <operand>, iN* <destination>, i32 <memory_order>)
     declare iN @llvm.nacl.atomic.rmw.<size>(
             i32 <computation>, iN* <object>, iN <operand>, i32 <memory_order>)
     declare iN @llvm.nacl.atomic.cmpxchg.<size>(
             iN* <object>, iN <expected>, iN <desired>,
             i32 <memory_order_success>, i32 <memory_order_failure>)
     declare void @llvm.nacl.atomic.fence(i32 <memory_order>)
 
-Each of these intrinsics is overloaded on the ``iN`` argument, which
-is reflected through ``<size>`` in the overload's name. Integral types
-of 8, 16, 32 and 64-bit width are supported for these arguments.
+Each of these intrinsics is overloaded on the ``iN`` argument, which is
+reflected through ``<size>`` in the overload's name. Integral types of
+8, 16, 32 and 64-bit width are supported for these arguments.
 
 The ``@llvm.nacl.atomic.rmw`` intrinsic implements the following
 read-modify-write operations, from the general and arithmetic sections
 of the C11/C++11 standards:
 
  - ``add``
  - ``sub``
  - ``or``
  - ``and``
  - ``xor``
  - ``exchange``
 
 For all of these read-modify-write operations, the returned value is
-that at ``object`` before the computation. The ``computation``
-argument must be a compile-time constant.
+that at ``object`` before the computation. The ``computation`` argument
+must be a compile-time constant.
 
 All atomic intrinsics also support C11/C++11 memory orderings, which
 must be compile-time constants. Those are detailed in `Atomic Memory
 Ordering Constraints`_.
 
 Integer values for these computations and memory orderings are defined
 in ``"llvm/IR/NaClAtomicIntrinsics.h"``.
 
 .. note::
 
     These intrinsics allow PNaCl to support C11/C++11 style atomic
     operations as well as some legacy GCC-style ``__sync_*`` builtins
-    while remaining stable as the LLVM codebase changes. The user
-    isn't expected to use these intrinsics directly.
+    while remaining stable as the LLVM codebase changes. The user isn't
+    expected to use these intrinsics directly.
 
 .. code-block:: llvm
 
   declare i1 @llvm.nacl.atomic.is.lock.free(i32 <byte_size>, i8* <address>)
 
   The ``llvm.nacl.atomic.is.lock.free`` intrinsic is designed to
   determine at translation time whether atomic operations of a certain
   ``byte_size`` (a compile-time constant), at a particular ``address``,
   are lock-free or not. This reflects the C11 ``atomic_is_lock_free``
   function from header ``<stdatomic.h>`` and the C++11 ``is_lock_free``
   member function in header ``<atomic>``. It can be used through the
   ``__nacl_atomic_is_lock_free`` builtin.