PNaCl documentation: clarify vector alignment, and update navigation

native_client_sdk/doc_generated/reference/pnacl-c-cpp-language-support.html

 {{+bindTo:partials.standard_nacl_article}}
 
 <section id="pnacl-c-c-language-support">
 <h1 id="pnacl-c-c-language-support">PNaCl C/C++ Language Support</h1>
 <div class="contents local" id="contents" style="display: none">
 <ul class="small-gap">
 <li><p class="first"><a class="reference internal" href="#source-language-support" id="id3">Source language support</a></p>
 <ul class="small-gap">
 <li><a class="reference internal" href="#versions" id="id4">Versions</a></li>
 <li><a class="reference internal" href="#preprocessor-definitions" id="id5">Preprocessor definitions</a></li>
@@ skipping 177 matching lines @@
 <p>NaCl supports a fairly wide subset of inline assembly through GCC&#8217;s
 inline assembly syntax, with the restriction that the sandboxing model
 for the target architecture has to be respected.</p>
 </section><section id="portable-simd-vectors">
 <span id="id2"></span><h2 id="portable-simd-vectors"><span id="id2"></span>Portable SIMD Vectors</h2>
 <p>SIMD vectors aren&#8217;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.</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>
 and <a class="reference external" href="http://gcc.gnu.org/onlinedocs/gcc/Vector-Extensions.html">GCC vectors</a> since these
 are well supported by different hardware platforms and don&#8217;t require any
 new compiler intrinsics.</p>
 <p>Vector types can be used through the <code>vector_size</code> attribute:</p>
 <pre class="prettyprint">
 #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 = a + b;  /* c = {6,8,10,12} */
 d = b &gt;&gt; a; /* d = {2,1,0,0} */
 </pre>
 <p>Vector comparisons are represented as a bitmask as wide as the compared
 elements of all <code>0</code> or all <code>1</code>:</p>
 <pre class="prettyprint">
 typedef int v4s __attribute__((vector_size(16)));
 v4s snip(v4s in) {
   v4s limit = {32,64,128,256};
   v4s mask = in &gt; limit;
   v4s ret = in &amp; mask;
   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>
 <thead valign="bottom">
 <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>
 </colgroup>
 <tbody valign="top">
 <tr class="row-odd"><td>unary <code>+</code>, <code>-</code></td>
 </tr>
 <tr class="row-even"><td><code>++</code>, <code>--</code></td>
 </tr>
 <tr class="row-odd"><td><code>+</code>, <code>-</code>, <code>*</code>, <code>/</code>, <code>%</code></td>
@@ skipping 152 matching lines @@
 <p>Neither PNaCl nor NaCl currently support asynchronous interruption
 or suspension of threads.</p>
 </li>
 </ul>
 <p>If PNaCl were to support either of these, the interaction of
 <code>volatile</code> and atomics with same-thread signal handling would need
 to be carefully detailed.</p>
 </section></section></section>
 
 {{/partials.standard_nacl_article}}