Concurrency support for PNaCl ABI

docs/PNaClLangRef.rst

 ==============================
 PNaCl Bitcode Reference Manual
 ==============================
 
 .. contents::
    :local:
    :depth: 3
 
 Introduction
 ============
@@ skipping 88 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>`_
 
-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
 ---------------
 
 `LLVM LangRef: Fast-Math Flags <LangRef.html#fastmath>`_
 
 Fast-math mode is not currently supported by the PNaCl bitcode.
 
 Type System
 ===========
@@ skipping 129 matching lines @@
 
 .. code-block:: llvm
 
     %buf = alloca i8, i32 8, align 4
 
 * ``load``, ``store``
 
   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``
 * ``fptrunc``
 * ``fpext``
 * ``fptoui``
 * ``fptosi``
 * ``uitofp``
 * ``sitofp``
 
@@ skipping 18 matching lines @@
 * ``select``
 * ``call``
 
 Intrinsic Functions
 ===================
 
 `LLVM LangRef: Intrinsic Functions <LangRef.html#intrinsics>`_
 
 The only intrinsics supported by PNaCl bitcode are the following.
 
-TODO(jfb): atomics
-
 * ``llvm.memcpy``
 * ``llvm.memmove``
 * ``llvm.memset``
 * ``llvm.bswap``
 
   The llvm.bswap intrinsic is only supported with the following argument types:
   i16, i32, i64.
 
 * ``llvm.ctlz``
 * ``llvm.cttz``
 * ``llvm.ctpop``
 
   The llvm.ctlz, llvm.cttz, and llvm.ctpop intrinsics only support
   i32 and i64 argument types (the types supported by C-style GCC builtins).
 
 * ``llvm.trap``
 * ``llvm.nacl.read.tp``
 
   TODO: describe
 
 * ``llvm.nacl.longjmp``
 
   TODO: describe
 
 * ``llvm.nacl.setjmp``
 
   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.