Concurrency support for PNaCl ABI

docs/PNaClLangRef.rst

Index: docs/PNaClLangRef.rst
diff --git a/docs/PNaClLangRef.rst b/docs/PNaClLangRef.rst
index b1d39a7187806fc36a4dc8a54d38feb6441eb48d..f04ee1dacebb8aec8b03277bda0b873a5296fe13 100644
--- a/docs/PNaClLangRef.rst
+++ b/docs/PNaClLangRef.rst
@@ -106,21 +106,76 @@ Volatile Memory Accesses
 
 `LLVM LangRef: Volatile Memory Accesses <LangRef.html#volatile>`_
 
-TODO: are we going to promote volatile to atomic?
+We recommend that C11/C++11 atomics be used instead of ``volatile``.
+
+The C and C++ standards mandate that ``volatile`` accesses execute in
+program order (but are not fences, so other memory operations can
+reorder around them), are not necessarily atomic, and can’t be elided or
+fused.
+
+The PNaCl toolchain applies regular LLVM optimizations along these
+guidelines, and the PNaCl then toolchain freezes ``volatile`` accesses
+into atomic accesses with sequential consistency memory ordering. This
+eases the support of legacy (i.e. non-C11/C++11) code, and combined with
+builtin fences these programs can do meaningful cross-thread
+communication without changing code.
+
+Relaxed ordering could be used instead, but for the first release it is
+more conservative to apply sequential consistency. Future releases may
+change what happens at compile-time, but already-release pexes will

[Derek Schuff, 2013/06/26 17:03:29]

release->released

[JF, 2013/06/26 23:41:12]

Done.

+continue using sequential consistency.
+
+The PNaCl toolchain also tries to guarantee natural alignment of
+``volatile`` accesses, a requirement for atomicity on some platforms.
 
 Memory Model for Concurrent Operations
 --------------------------------------
 
 `LLVM LangRef: Memory Model for Concurrent Operations <LangRef.html#memmodel>`_
 
-TODO.
+The PNaCl toolchain currently supports concurrent memory accesses
+through legacy GCC-style ``__sync_*`` builtins, as well as through
+C11/C++11 atomic primitives. ``volatile`` memory accesses can also be
+used, though these are discouraged.
+
+Note that PNaCl explicitly supports concurrency through threading, but
+doesn't support interacting with device memory, nor does it attempt to
+support cross-program communication, including through shared
+memory. These concerns are left up to the embedding sandbox's runtime
+(e.g. NaCl's Pepper APIs).
+
+PNaCl also doesn't currently support signal handling, and therefore
+promotes all primitives to cross-thread (instead of single-thread). This
+may change at a later date.
+
+The PNaCl toolchain currently optimizes for memory ordering as LLVM
+normally does, but at pexe creation time it promotes all ``volatile``
+accesses as well as all atomic accesses to be sequentially consistent.
+
+This means that ``volatile`` and atomic memory accesses can only be
+re-ordered before the pexe is created, and will act as fences for all
+memory accesses (even non-atomic and non-``volatile``) after pexe
+creation. Non-atomic and non-``volatile`` memory accesses may be
+reordered (unless a fence intervenes), separate, elided or fused

[Derek Schuff, 2013/06/26 17:03:29]

separate->separated?

[JF, 2013/06/26 23:41:12]

Done.

+according to C and C++'s memory model before the pexe is created as well
+as after its creation.
 
 Atomic Memory Ordering Constraints
 ----------------------------------
 
 `LLVM LangRef: Atomic Memory Ordering Constraints <LangRef.html#ordering>`_
 
-TODO.
+Atomics follow the same ordering constraints as in regular LLVM, but all
+accesses are promoted to sequential consistency (the strongest memory
+ordering) at pexe creation time. We may relax these rules and honor the
+program's memory ordering constraints as more C11/C++11 code allows us
+to understand performance and portability needs.
+
+As in C11/C++11:
+
+ - Atomic accesses must at least be naturally aligned.
+ - Some accesses may not actually be atomic on certain platforms,
+   requiring an implementation that uses a global lock.
 
 Fast-Math Flags
 ---------------
@@ -270,14 +325,6 @@ Only the LLVM instructions listed here are supported by PNaCl bitcode.
   The pointer argument of these instructions must be a *normalized* pointer
   (see :ref:`pointer types <pointertypes>`).
 
-* ``fence``
-* ``cmpxchg``, ``atomicrmw``
-
-  The pointer argument of these instructions must be a *normalized* pointer
-  (see :ref:`pointer types <pointertypes>`).
-
-  TODO(jfb): this may change
-
 * ``trunc``
 * ``zext``
 * ``sext``
@@ -316,8 +363,6 @@ Intrinsic Functions
 
 The only intrinsics supported by PNaCl bitcode are the following.
 
-TODO(jfb): atomics
-
 * ``llvm.memcpy``
 * ``llvm.memmove``
 * ``llvm.memset``
@@ -346,3 +391,40 @@ TODO(jfb): atomics
 
   TODO: describe
 
+* ``llvm.nacl.atomic.8``
+* ``llvm.nacl.atomic.16``
+* ``llvm.nacl.atomic.32``
+* ``llvm.nacl.atomic.64``
+
+  These intrinsics provide support for atomic accesses at 8, 16, 32 and
+  64-bit sizes for primitives required to implement C11/C++11 atomic
+  accesses:
+
+   - load
+   - store
+   - add
+   - sub
+   - or
+   - and
+   - xor
+   - xchg
+   - cmpxchg
+   - fence
+
+  They also support C11/C++11 memory orderings:
+
+   - Relaxed: no operation orders memory.
+   - Consume: a load operation performs a consume operation on the
+     affected memory location (currently unsupported by LLVM).
+   - Acquire: a load operation performs an acquire operation on the
+     affected memory location.
+   - Release: a store operation performs a release operation on the
+     affected memory location.
+   - Acquire-release: load and store operations perform acquire and
+     release operations on the affected memory.
+   - Sequentially consistent: same as acquire-release, but providing a
+     total ordering for all affected locations.
+
+  Note that PNaCl currently strengthens all memory ordering
+  specifications to sequential consistency, the strongest form of memory
+  ordering.