PNaCl SIMD documentation: improve documentation on casts and __builtin_convertvector.

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 185 matching lines @@
 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;
+typedef int v4s __attribute__((vector_size(16)));
+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;
 </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;
+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>
 <table border="1" class="docutils">
 <colgroup>
 </colgroup>
 <thead valign="bottom">
 <tr class="row-odd"><th class="head">Type</th>
@@ skipping 50 matching lines @@
 <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>
-</ul>
+<p>C-style casts can be used to convert one vector type to another without
+modifying the underlying bits. <code>__builtin_convertvector</code> can be used
+to convert from one type to another, truncating when converting from

[nfullagar1, 2014/04/29 16:50:50]

...__builtin_convertvector can be used to convert from one type to another
provided both types have the same number of elements and truncating when...

[JF, 2014/04/29 16:55:38]

Done.

+floating-point to integer.</p>
+<pre class="prettyprint">
+typedef unsigned v4u __attribute__((vector_size(16)));
+typedef float v4f __attribute__((vector_size(16)));
+v4u a = {0x3f19999a,0x40000000,0x40490fdb,0x66ff0c30};
+v4f b = (v4f) a; /* b = {0.6,2,3.14159,6.02214e+23}  */
+v4u c = __builtin_convertvector(b, v4u); /* c = {0,2,3,0} */
+</pre>
 <p>It is also possible to use array-style indexing into vectors to extract
 individual elements using <code>[]</code>.</p>
+<pre class="prettyprint">
+typedef unsigned v4u __attribute__((vector_size(16)));
+template&lt;typename T&gt;
+void print(const T v) {
+  for (size_t i = 0; i != sizeof(v) / sizeof(v[0]); ++i)
+    std::cout &lt;&lt; v[i] &lt;&lt; ' ';
+  std::cout &lt;&lt; std::endl;
+}
+</pre>
 <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">
@@ skipping 65 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}}