NaCl documentation: update vector documentation

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 209 matching lines @@
 <http://clang.llvm.org/docs/LanguageExtensions.html#vectors-and-extended-vectors>`_
 and `GCC vectors
 <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 v4s __attribute__((vector_size(16)));
+  #define VECTOR_BYTES 16
+  typedef int v4s __attribute__((vector_size(VECTOR_BYTES)));
   v4s a = {1,2,3,4};
   v4s b = {5,6,7,8};
   v4s 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``:
 
@@ skipping 65 matching lines @@
 .. naclcode::
 
   typedef unsigned v4u __attribute__((vector_size(16)));
   template<typename T>
   void print(const T v) {
     for (size_t i = 0; i != sizeof(v) / sizeof(v[0]); ++i)
       std::cout << v[i] << ' ';
     std::cout << std::endl;
   }
 
-Vector shuffles are currently unsupported but will be added soon.
+Vector shuffles (often called permutation or swizzle) operations are
+supported through ``__builtin_shufflevector``. The builtin has two
+vector arguments of the same element type, followed by a list of
+constant integers that specify the elements indices of the first two
+vectors that should be extracted and returned in a new vector. These
+element indices are numbered sequentially starting with the first
+vector, continuing into the second vector. Thus, if ``vec1`` is a
+4-element vector, index ``5`` would refer to the second element of
+``vec2``. An index of ``-1`` can be used to indicate that the
+corresponding element in the returned vector is a don’t care and can be
+optimized by the backend.
+
+The result of ``__builtin_shufflevector`` is a vector with the same
+element type as ``vec1`` / ``vec2`` but that has an element count equal
+to the number of indices specified.
+
+.. naclcode::
+
+  // identity operation - return 4-element vector v1.
+  __builtin_shufflevector(v1, v1, 0, 1, 2, 3)
+
+  // "Splat" element 0 of V1 into a 4-element result.
+  __builtin_shufflevector(V1, V1, 0, 0, 0, 0)
+
+  // Reverse 4-element vector V1.
+  __builtin_shufflevector(V1, V1, 3, 2, 1, 0)
+
+  // Concatenate every other element of 4-element vectors V1 and V2.
+  __builtin_shufflevector(V1, V2, 0, 2, 4, 6)
+
+  // Concatenate every other element of 8-element vectors V1 and V2.
+  __builtin_shufflevector(V1, V2, 0, 2, 4, 6, 8, 10, 12, 14)
+
+  // Shuffle v1 with some elements being undefined
+  __builtin_shufflevector(v1, v1, 3, -1, 1, -1)
 
 Auto-Vectorization
 ------------------
 
 Auto-vectorization is currently not enabled for Portable Native Client,
 but will be in a future release.
 
 Undefined Behavior
 ==================
 
@@ skipping 76 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.