PNaCl documentation: clarify vector alignment, and update navigation

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 197 matching lines @@
 
 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 37
-of Chrome and more features, including performance enhancements, 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
 -----------------------------
 
 The initial vector support in Portable Native Client adds `LLVM vectors
 <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.
@@ skipping 16 matching lines @@
 .. naclcode::
 
   typedef int v4s __attribute__((vector_size(16)));
   v4s snip(v4s in) {
     v4s limit = {32,64,128,256};
     v4s mask = in > limit;
     v4s ret = in & mask;
     return ret;
   }
 
-Vector datatypes are currently expected to be 128-bit wide with one of
-the following element types:
+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
-============  ============  ================
-``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
-============  ============  ================
+============  ============  ================ ======================
+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:
 
 +----------------------------------------------+
 | unary ``+``, ``-``                           |
 +----------------------------------------------+
 | ``++``, ``--``                               |
 +----------------------------------------------+
 | ``+``, ``-``, ``*``, ``/``, ``%``            |
 +----------------------------------------------+
 | ``&``, ``|``, ``^``, ``~``                   |
@@ skipping 169 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.