PNaCl documentation: add SIMD vectors.

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="id2">Source language support</a></p>
+<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="id3">Versions</a></li>
-<li><a class="reference internal" href="#preprocessor-definitions" id="id4">Preprocessor definitions</a></li>
+<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>
 </ul>
 </li>
-<li><p class="first"><a class="reference internal" href="#memory-model-and-atomics" id="id5">Memory Model and Atomics</a></p>
+<li><p class="first"><a class="reference internal" href="#memory-model-and-atomics" id="id6">Memory Model and Atomics</a></p>
 <ul class="small-gap">
-<li><a class="reference internal" href="#memory-model-for-concurrent-operations" id="id6">Memory Model for Concurrent Operations</a></li>
-<li><a class="reference internal" href="#atomic-memory-ordering-constraints" id="id7">Atomic Memory Ordering Constraints</a></li>
-<li><a class="reference internal" href="#volatile-memory-accesses" id="id8">Volatile Memory Accesses</a></li>
+<li><a class="reference internal" href="#memory-model-for-concurrent-operations" id="id7">Memory Model for Concurrent Operations</a></li>
+<li><a class="reference internal" href="#atomic-memory-ordering-constraints" id="id8">Atomic Memory Ordering Constraints</a></li>
+<li><a class="reference internal" href="#volatile-memory-accesses" id="id9">Volatile Memory Accesses</a></li>
 </ul>
 </li>
-<li><a class="reference internal" href="#threading" id="id9">Threading</a></li>
-<li><a class="reference internal" href="#setjmp-and-longjmp" id="id10"><code>setjmp</code> and <code>longjmp</code></a></li>
-<li><a class="reference internal" href="#c-exception-handling" id="id11">C++ Exception Handling</a></li>
-<li><a class="reference internal" href="#inline-assembly" id="id12">Inline Assembly</a></li>
-<li><a class="reference internal" href="#undefined-behavior" id="id13">Undefined Behavior</a></li>
-<li><a class="reference internal" href="#floating-point" id="id14">Floating-Point</a></li>
-<li><a class="reference internal" href="#computed-goto" id="id15">Computed <code>goto</code></a></li>
-<li><p class="first"><a class="reference internal" href="#future-directions" id="id16">Future Directions</a></p>
+<li><a class="reference internal" href="#threading" id="id10">Threading</a></li>
+<li><a class="reference internal" href="#setjmp-and-longjmp" id="id11"><code>setjmp</code> and <code>longjmp</code></a></li>
+<li><a class="reference internal" href="#c-exception-handling" id="id12">C++ Exception Handling</a></li>
+<li><a class="reference internal" href="#inline-assembly" id="id13">Inline Assembly</a></li>
+<li><p class="first"><a class="reference internal" href="#portable-simd-vectors" id="id14">Portable SIMD Vectors</a></p>
 <ul class="small-gap">
-<li><a class="reference internal" href="#simd" id="id17">SIMD</a></li>
-<li><a class="reference internal" href="#inter-process-communication" id="id18">Inter-Process Communication</a></li>
-<li><a class="reference internal" href="#posix-style-signal-handling" id="id19">POSIX-style Signal Handling</a></li>
+<li><a class="reference internal" href="#hand-coding-vector-extensions" id="id15">Hand-Coding Vector Extensions</a></li>
+<li><a class="reference internal" href="#auto-vectorization" id="id16">Auto-Vectorization</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#undefined-behavior" id="id17">Undefined Behavior</a></li>
+<li><a class="reference internal" href="#floating-point" id="id18">Floating-Point</a></li>
+<li><a class="reference internal" href="#computed-goto" id="id19">Computed <code>goto</code></a></li>
+<li><p class="first"><a class="reference internal" href="#future-directions" id="id20">Future Directions</a></p>
+<ul class="small-gap">
+<li><a class="reference internal" href="#inter-process-communication" id="id21">Inter-Process Communication</a></li>
+<li><a class="reference internal" href="#posix-style-signal-handling" id="id22">POSIX-style Signal Handling</a></li>
 </ul>
 </li>
 </ul>
 
 </div><section id="source-language-support">
 <h2 id="source-language-support">Source language support</h2>
 <p>The currently supported languages are C and C++. The PNaCl toolchain is
 based on recent Clang, which fully supports C++11 and most of C11. A
 detailed status of the language support is available <a class="reference external" href="http://clang.llvm.org/cxx_status.html">here</a>.</p>
 <p>For information on using languages other than C/C++, see the <a class="reference internal" href="/native-client/faq.html#other-languages"><em>FAQ
@@ skipping 131 matching lines @@
 <p>Inline assembly isn&#8217;t supported by PNaCl because it isn&#8217;t portable. The
 one current exception is the common compiler barrier idiom
 <code>asm(&quot;&quot;:::&quot;memory&quot;)</code>, which gets transformed to a sequentially
 consistent memory barrier (equivalent to <code>__sync_synchronize()</code>). In
 PNaCl this barrier is only guaranteed to order <code>volatile</code> and atomic
 memory accesses, though in practice the implementation attempts to also
 prevent reordering of memory accesses to objects which may escape.</p>
 <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="undefined-behavior">
+</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 36
+of Chrome, and more features are expected to be added in subsequent
+releases.</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">
+typedef int v4si __attribute__((vector_size(16)));
+v4si a = {1,2,3,4};
+v4si b = {5,6,7,8};
+v4si c, d, e;
+c = b + 1;  /* c = b + {1,1,1,1}; */
+d = 2 * b;  /* d = {2,2,2,2} * b; */
+e = c + d;
+</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 v4si __attribute__((vector_size(16)));
+v4si snip(v2si in) {
+  v4si limit = {32,64,128,256};
+  vs4i mask = in &gt; limit;
+  vs4i 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>
+<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>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code>uint8_t</code></td>
+<td>16</td>
+<td>128</td>
+</tr>
+<tr class="row-odd"><td><code>int8_t</code></td>
+<td>16</td>
+<td>128</td>
+</tr>
+<tr class="row-even"><td><code>uint16_t</code></td>
+<td>8</td>
+<td>128</td>
+</tr>
+<tr class="row-odd"><td><code>int16_t</code></td>
+<td>8</td>
+<td>128</td>
+</tr>
+<tr class="row-even"><td><code>uint32_t</code></td>
+<td>4</td>
+<td>128</td>
+</tr>
+<tr class="row-odd"><td><code>int32_t</code></td>
+<td>4</td>
+<td>128</td>
+</tr>
+<tr class="row-even"><td><code>float</code></td>
+<td>4</td>
+<td>128</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>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>
+</tr>
+<tr class="row-even"><td><code>&amp;</code>, <code>|</code>, <code>^</code>, <code>~</code></td>
+</tr>
+<tr class="row-odd"><td><code>&gt;&gt;</code>, <code>&lt;&lt;</code></td>
+</tr>
+<tr class="row-even"><td><code>!</code>, <code>&amp;&amp;</code>, <code>||</code></td>
+</tr>
+<tr class="row-odd"><td><code>==</code>, <code>!=</code>, <code>&gt;</code>, <code>&lt;</code>, <code>&gt;=</code>, <code>&lt;=</code></td>
+</tr>
+<tr class="row-even"><td><code>=</code></td>
+</tr>
+</tbody>
+</table>
+<p>Furthermore, C-style casts can be used for:</p>
+<ul class="small-gap">
+<li>Truncation.</li>
+<li>Zero- and sign-extension.</li>
+<li>Conversion to/from floating-point and signed/unsigned integer.</li>

[nfullagar1, 2014/04/24 23:25:33]

A few comments that should be addressed in a follow up CL -
  C-style casts on vectors do no conversion, they only change the type while
keeping the bits the same.  It follows C-style casts on vectors do not zero
extend or sign extend.

Use __builtin_convertvector() to convert between float and integer vectors. 
__builtin_convertvector() will truncate when converting float to int.

When support for vector sizes other than 128bit come online, then
__builtin_convertvector() can also be used to zero or sign extend between
different sized fixed point formats, providing the src and dest types have the
same number of elements.

+</ul>
+<p>It is also possible to use array-style indexing into vectors to extract
+individual elements using <code>[]</code>.</p>
+<p>Vector shuffles are currently unsupported but will be added soon.</p>
+</section><section id="auto-vectorization">
+<h3 id="auto-vectorization">Auto-Vectorization</h3>
+<p>Auto-vectorization is currently not enabled for Portable Native Client,
+but will be in a future release.</p>
+</section></section><section id="undefined-behavior">
 <h2 id="undefined-behavior">Undefined Behavior</h2>
 <p>The C and C++ languages expose some undefined behavior which is
 discussed in <a class="reference internal" href="/native-client/reference/pnacl-undefined-behavior.html#undefined-behavior"><em>PNaCl Undefined Behavior</em></a>.</p>
 </section><section id="floating-point">
 <h2 id="floating-point">Floating-Point</h2>
 <p>PNaCl exposes 32-bit and 64-bit floating point operations which are
 mostly IEEE-754 compliant. There are a few caveats:</p>
 <ul class="small-gap">
 <li>Some <a class="reference internal" href="/native-client/reference/pnacl-undefined-behavior.html#undefined-behavior-fp"><em>floating-point behavior is currently left as undefined</em></a>.</li>
 <li>The default rounding mode is round-to-nearest and other rounding modes
@@ skipping 25 matching lines @@
 <p>PNaCl supports computed <code>goto</code>, a non-standard GCC extension to C used
 by some interpreters, by lowering them to <code>switch</code> statements. The
 resulting use of <code>switch</code> might not be as fast as the original
 indirect branches. If you are compiling a program that has a
 compile-time option for using computed <code>goto</code>, it&#8217;s possible that the
 program will run faster with the option turned off (e.g., if the program
 does extra work to take advantage of computed <code>goto</code>).</p>
 <p>NaCl supports computed <code>goto</code> without any transformation.</p>
 </section><section id="future-directions">
 <h2 id="future-directions">Future Directions</h2>
-<section id="simd">
-<h3 id="simd">SIMD</h3>
-<p>PNaCl currently doesn&#8217;t support SIMD. We plan to add SIMD support in the
-very near future.</p>
-<p>NaCl supports SIMD.</p>
-</section><section id="inter-process-communication">
+<section id="inter-process-communication">
 <h3 id="inter-process-communication">Inter-Process Communication</h3>
 <p>Inter-process communication through shared memory is currently not
 supported by PNaCl/NaCl. When implemented, it may be limited to
 operations which are lock-free on the current platform (<code>is_lock_free</code>
 methods). It will rely on the address-free properly discussed in <a class="reference internal" href="#memory-model-for-concurrent-operations">Memory
 Model for Concurrent Operations</a>.</p>
 </section><section id="posix-style-signal-handling">
 <h3 id="posix-style-signal-handling">POSIX-style Signal Handling</h3>
 <p>POSIX-style signal handling really consists of two different features:</p>
 <ul class="small-gap">
@@ skipping 13 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}}