PNaCl documentation: clarify vector alignment, and update navigation

R= binji@chromium.org
TEST=none
BUG=none
NOTRY=true
(documentation only change)

Review URL: https://codereview.chromium.org/419803005

git-svn-id: svn://svn.chromium.org/chrome/trunk/src@285923 0039d316-1c4b-4281-b951-d872f2087c98

3 files changed, 61 insertions, 22 deletions

diff --git a/chrome/common/extensions/docs/templates/json/chrome_sidenav.json b/chrome/common/extensions/docs/templates/json/chrome_sidenav.json
index 312affa..f143482 100644
--- a/chrome/common/extensions/docs/templates/json/chrome_sidenav.json
+++ b/chrome/common/extensions/docs/templates/json/chrome_sidenav.json
@@ -861,6 +861,10 @@
                 "href": "/native-client/reference/pnacl-bitcode-abi"
               },
               {
+                "title": "PNaCl Undefined Behavior",
+                "href": "/native-client/reference/pnacl-undefined-behavior"
+              },
+              {
                 "title": "PNaCl C/C++ Language Support",
                 "href": "/native-client/reference/pnacl-c-cpp-language-support"
               },
@@ -871,6 +875,10 @@
                     {
                       "title": "ARM 32-bit Sandbox",
                       "href": "/native-client/reference/sandbox_internals/arm-32-bit-sandbox"
+                    },
+                    {
+                      "title": "x86-64 Sandbox",
+                      "href": "/native-client/reference/sandbox_internals/x86-64-sandbox"
                     }
                 ]
               }
diff --git a/native_client_sdk/doc_generated/reference/pnacl-c-cpp-language-support.html b/native_client_sdk/doc_generated/reference/pnacl-c-cpp-language-support.html
index 7ee087e..d5b2973 100644
--- a/native_client_sdk/doc_generated/reference/pnacl-c-cpp-language-support.html
+++ b/native_client_sdk/doc_generated/reference/pnacl-c-cpp-language-support.html
@@ -195,9 +195,10 @@ 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.</p>
-<p>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.</p>
+<p>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 <a class="reference internal" href="/native-client/sdk/release-notes.html#sdk-release-notes"><em>Release Notes</em></a> for more
+details.</p>
 <section id="hand-coding-vector-extensions">
 <h3 id="hand-coding-vector-extensions">Hand-Coding Vector Extensions</h3>
 <p>The initial vector support in Portable Native Client adds <a class="reference external" href="http://clang.llvm.org/docs/LanguageExtensions.html#vectors-and-extended-vectors">LLVM vectors</a>
@@ -225,8 +226,10 @@ v4s snip(v4s in) {
   return ret;
 }
 </pre>
-<p>Vector datatypes are currently expected to be 128-bit wide with one of
-the following element types:</p>
+<p>Vector datatypes are currently expected to be 128-bit wide with one of the
+following element types, and they&#8217;re expected to be aligned to the underlying
+element&#8217;s bit width (loads and store will otherwise be broken up into scalar
+accesses to prevent faults):</p>
 <table border="1" class="docutils">
 <colgroup>
 </colgroup>
@@ -234,41 +237,56 @@ the following element types:</p>
 <tr class="row-odd"><th class="head">Type</th>
 <th class="head">Num Elements</th>
 <th class="head">Vector Bit Width</th>
+<th class="head">Expected Bit Alignment</th>
 </tr>
 </thead>
 <tbody valign="top">
 <tr class="row-even"><td><code>uint8_t</code></td>
 <td>16</td>
 <td>128</td>
+<td>8</td>
 </tr>
 <tr class="row-odd"><td><code>int8_t</code></td>
 <td>16</td>
 <td>128</td>
+<td>8</td>
 </tr>
 <tr class="row-even"><td><code>uint16_t</code></td>
 <td>8</td>
 <td>128</td>
+<td>16</td>
 </tr>
 <tr class="row-odd"><td><code>int16_t</code></td>
 <td>8</td>
 <td>128</td>
+<td>16</td>
 </tr>
 <tr class="row-even"><td><code>uint32_t</code></td>
 <td>4</td>
 <td>128</td>
+<td>32</td>
 </tr>
 <tr class="row-odd"><td><code>int32_t</code></td>
 <td>4</td>
 <td>128</td>
+<td>32</td>
 </tr>
 <tr class="row-even"><td><code>float</code></td>
 <td>4</td>
 <td>128</td>
+<td>32</td>
 </tr>
 </tbody>
 </table>
 <p>64-bit integers and double-precision floating point will be supported in
 a future release, as will 256-bit and 512-bit vectors.</p>
+<p>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:</p>
+<pre class="prettyprint">
+typedef int v4s_element   __attribute__((vector_size(16), aligned(4)));
+typedef int v4s_unaligned __attribute__((vector_size(16), aligned(1)));
+</pre>
 <p>The following operators are supported on vectors:</p>
 <table border="1" class="docutils">
 <colgroup>
diff --git a/native_client_sdk/src/doc/reference/pnacl-c-cpp-language-support.rst b/native_client_sdk/src/doc/reference/pnacl-c-cpp-language-support.rst
index af1ff31..6fb8751 100644
--- a/native_client_sdk/src/doc/reference/pnacl-c-cpp-language-support.rst
+++ b/native_client_sdk/src/doc/reference/pnacl-c-cpp-language-support.rst
@@ -215,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 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
 -----------------------------
@@ -254,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:
 
 +----------------------------------------------+