Upstream version 9.38.198.0

[platform/framework/web/crosswalk.git] / src / native_client_sdk / src / doc / reference / pnacl-c-cpp-language-support.rst

diff --git a/src/native_client_sdk/src/doc/reference/pnacl-c-cpp-language-support.rst b/src/native_client_sdk/src/doc/reference/pnacl-c-cpp-language-support.rst
index 3bece15..6fb8751 100644 (file)
--- a/src/native_client_sdk/src/doc/reference/pnacl-c-cpp-language-support.rst
+++ b/src/native_client_sdk/src/doc/reference/pnacl-c-cpp-language-support.rst
@@ -170,6 +170,8 @@ in `Memory Model and Atomics`_.
 PNaCl and NaCl support ``setjmp`` and ``longjmp`` without any
 restrictions beyond C's.
 
+.. _exception_handling:
+
 C++ Exception Handling
 ======================
 
@@ -194,6 +196,10 @@ 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.
 
+PNaCl supports :ref:`Portable SIMD Vectors <portable_simd_vectors>`,
+which are traditionally expressed through target-specific intrinsics or
+inline assembly.
+
 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.
@@ -209,9 +215,10 @@ 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.
+SIMD vector support was added to Portable Native Client for version 37 of Chrome
+and more features, including performance enhancements, have been added in
+subsequent releases, see the :ref:`Release Notes <sdk-release-notes>` for more
+details.
 
 Hand-Coding Vector Extensions
 -----------------------------
@@ -232,9 +239,8 @@ Vector types can be used through the ``vector_size`` attribute:
   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;
+  c = a + b;  /* c = {6,8,10,12} */
+  d = b >> a; /* d = {2,1,0,0} */
 
 Vector comparisons are represented as a bitmask as wide as the compared
 elements of all ``0`` or all ``1``:
@@ -249,24 +255,36 @@ elements of all ``0`` or all ``1``:
     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
-============  ============  ================
+Vector datatypes are currently expected to be 128-bit wide with one of the
+following element types, and they're expected to be aligned to the underlying
+element's bit width (loads and store will otherwise be broken up into scalar
+accesses to prevent faults):
+
+============  ============  ================ ======================
+Type          Num Elements  Vector Bit Width Expected Bit Alignment
+============  ============  ================ ======================
+``uint8_t``   16            128              8
+``int8_t``    16            128              8
+``uint16_t``  8             128              16
+``int16_t``   8             128              16
+``uint32_t``  4             128              32
+``int32_t``   4             128              32
+``float``     4             128              32
+============  ============  ================ ======================
 
 64-bit integers and double-precision floating point will be supported in
 a future release, as will 256-bit and 512-bit vectors.
 
+Vector element bit width alignment can be stated explicitly (this is assumed by
+PNaCl, but not necessarily by other compilers), and smaller alignments can also
+be specified:
+
+.. naclcode::
+
+  typedef int v4s_element   __attribute__((vector_size(16), aligned(4)));
+  typedef int v4s_unaligned __attribute__((vector_size(16), aligned(1)));
+
+
 The following operators are supported on vectors:
 
 +----------------------------------------------+
@@ -335,21 +353,32 @@ to the number of indices specified.
   // 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)
+  // "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)
+  // 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 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)
+  // 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)
 
+One common use of ``__builtin_shufflevector`` is to perform
+vector-scalar operations:
+
+.. naclcode::
+
+  typedef int v4s __attribute__((vector_size(16)));
+  v4s shift_right_by(v4s shift_me, int shift_amount) {
+    v4s tmp = {shift_amount};
+    return shift_me >> __builtin_shuffle_vector(tmp, tmp, 0, 0, 0, 0);
+  }
+
 Auto-Vectorization
 ------------------