PNaCl documentation: add SIMD vectors.

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 180 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.
 
+.. _portable_simd_vectors:
+
+Portable SIMD Vectors
+=====================
+
+SIMD vectors aren't part of the C/C++ standards and are traditionally
+very hardware-specific. Portable Native Client offers a portable version
+of SIMD vector datatypes and operations which map well to modern
+architectures and offer performance which matches or approaches
+hardware-specific uses.
+
+SIMD vector support was added to Portable Native Client for version 36
+of Chrome, and more features are expected to be added in subsequent
+releases.
+
+Hand-Coding Vector Extensions
+-----------------------------
+
+The initial vector support in Portable Native Client adds `LLVM vectors
+<http://clang.llvm.org/docs/LanguageExtensions.html#vectors-and-extended-vectors>`_
+/ `GCC vectors

[Derek Schuff, 2014/04/24 16:06:20]

maybe "LLVM vectors and GCC vectors" rather than just /

[JF, 2014/04/24 16:16:30]

Done.

+<http://gcc.gnu.org/onlinedocs/gcc/Vector-Extensions.html>`_ since these
+are well supported by different hardware platforms and don't require any
+new compiler intrinsics.
+
+Vector types can be used through the ``vector_size`` attribute:
+
+.. naclcode::
+
+  typedef int v4si __attribute__((vector_size(16)));
+  v4si a = {1,2,3,4};
+  v4si b = {5,6,7,8};
+  v4si c, d, e;
+  c = b + 1;  /* c = b + {1,1,1,1}; */
+  d = 2 * b;  /* d = {2,2,2,2} * b; */
+  e = c + d;
+
+Vector comparisons are represented as a bitmask as wide as the compared
+elements of all ``0`` or all ``1``:
+
+.. naclcode::
+
+  typedef int v4si __attribute__((vector_size(16)));
+  v4si snip(v2si in) {
+    v4si limit = {32,64,128,256};
+    vs4i mask = in > limit;
+    vs4i ret = in & mask;
+    return ret;
+  }
+
+Vector datatypes are currently expected to be 128-bit wide with one of
+the following element types:
+
+============  ============  ================
+Type          Num Elements  Vector Bit Width
+============  ============  ================
+``uint8_t``   16            128
+``int8_t``    16            128
+``uint16_t``  8             128
+``int16_t``   8             128
+``uint32_t``  4             128
+``int32_t``   4             128
+``float``     4             128
+============  ============  ================
+
+64-bit integers and ``double`` will be supported in a future release, as

[Derek Schuff, 2014/04/24 16:06:20]

maybe just write "64-bit integer and double-precision floating-point types"
rather than mixing an english description with a C data type.

[JF, 2014/04/24 16:16:30]

Done.

+will 256-bit and 512-bit vectors.
+
+The following operators are supported on vectors:
+
++----------------------------------------------+
+| unary ``+``, ``-``                           |
++----------------------------------------------+
+| ``++``, ``--``                               |
++----------------------------------------------+
+| ``+``, ``-``, ``*``, ``/``, ``%``            |
++----------------------------------------------+
+| ``&``, ``|``, ``^``, ``~``                   |
++----------------------------------------------+
+| ``>>``, ``<<``                               |
++----------------------------------------------+
+| ``!``, ``&&``, ``||``                        |
++----------------------------------------------+
+| ``==``, ``!=``, ``>``, ``<``, ``>=``, ``<=`` |
++----------------------------------------------+
+| ``=``                                        |
++----------------------------------------------+
+
+Furthermore, C-style casts can be used for:
+
+* Truncation.
+* Zero- and sign-extension.
+* Conversion to/from floating-point and signed/unsigned integer.
+
+It is also possible to use array-style indexing into vectors to extract
+individual elements using ``[]``.
+
+Vector shuffles are currently unsupported but will be added soon.
+
+Auto-Vectorization
+------------------
+
+Auto-vectorization is currently not enabled for Portable Native Client,
+but will be in a future release.
+
 Undefined Behavior
 ==================
 
 The C and C++ languages expose some undefined behavior which is
 discussed in :ref:`PNaCl Undefined Behavior <undefined_behavior>`.
 
 Floating-Point
 ==============
 
 PNaCl exposes 32-bit and 64-bit floating point operations which are
@@ skipping 32 matching lines @@
 indirect branches. If you are compiling a program that has a
 compile-time option for using computed ``goto``, it's possible that the
 program will run faster with the option turned off (e.g., if the program
 does extra work to take advantage of computed ``goto``).
 
 NaCl supports computed ``goto`` without any transformation.
 
 Future Directions
 =================
 
-SIMD
-----
-
-PNaCl currently doesn't support SIMD. We plan to add SIMD support in the
-very near future.
-
-NaCl supports SIMD.
-
 Inter-Process Communication
 ---------------------------
 
 Inter-process communication through shared memory is currently not
 supported by PNaCl/NaCl. When implemented, it may be limited to
 operations which are lock-free on the current platform (``is_lock_free``
 methods). It will rely on the address-free properly discussed in `Memory
 Model for Concurrent Operations`_.
 
 POSIX-style Signal Handling
@@ skipping 17 matching lines @@
   A similar feature is **thread suspension**: The ability to
   asynchronously suspend and resume a thread and inspect or modify its
   execution state (such as register state).
 
   Neither PNaCl nor NaCl currently support asynchronous interruption
   or suspension of threads.
 
 If PNaCl were to support either of these, the interaction of
 ``volatile`` and atomics with same-thread signal handling would need
 to be carefully detailed.