PNaCl documentation: add SIMD vectors.

PNaCl documentation: add SIMD vectors.

R= dschuff@chromium.org, nfullagar@chromium.org
BUG= https://code.google.com/p/nativeclient/issues/detail?id=2205
TEST= none
NOTRY=true
(documentation only change)

Committed: https://src.chromium.org/viewvc/chrome?view=rev&revision=265948

[Derek Schuff, 2014-04-24 16:06:19]

https://codereview.chromium.org/250433002/diff/1/native_client_sdk/doc_genera...
File native_client_sdk/doc_generated/_static/pygments.css (right):

https://codereview.chromium.org/250433002/diff/1/native_client_sdk/doc_genera...
native_client_sdk/doc_generated/_static/pygments.css:16: .highlight .go { color:
#333333 } /* Generic.Output */
must...resist...urge...to...bikeshed...

https://codereview.chromium.org/250433002/diff/1/native_client_sdk/src/doc/na...
File native_client_sdk/src/doc/nacl-and-pnacl.rst (right):

https://codereview.chromium.org/250433002/diff/1/native_client_sdk/src/doc/na...
native_client_sdk/src/doc/nacl-and-pnacl.rst:113: offer high-performance
equivalents.
"high-performance portable equivalents"?

https://codereview.chromium.org/250433002/diff/1/native_client_sdk/src/doc/re...
File native_client_sdk/src/doc/reference/pnacl-c-cpp-language-support.rst
(right):

https://codereview.chromium.org/250433002/diff/1/native_client_sdk/src/doc/re...
native_client_sdk/src/doc/reference/pnacl-c-cpp-language-support.rst:221: / `GCC
vectors
maybe "LLVM vectors and GCC vectors" rather than just /

https://codereview.chromium.org/250433002/diff/1/native_client_sdk/src/doc/re...
native_client_sdk/src/doc/reference/pnacl-c-cpp-language-support.rst:266: 64-bit
integers and ``double`` will be supported in a future release, as
maybe just write "64-bit integer and double-precision floating-point types"
rather than mixing an english description with a C data type.

https://codereview.chromium.org/250433002/diff/1/native_client_sdk/src/doc/re...
File native_client_sdk/src/doc/reference/pnacl-undefined-behavior.rst (right):

https://codereview.chromium.org/250433002/diff/1/native_client_sdk/src/doc/re...
native_client_sdk/src/doc/reference/pnacl-undefined-behavior.rst:184: such their
behavior isn't specified at all in C/C++, it is usually left
maybe "SIMD vector types aren't included in the C/C++ standard and as such their
behavior isn't specified at all in C/C++; it is usually left up to the target
architecture to specify behavior"

https://codereview.chromium.org/250433002/diff/1/native_client_sdk/src/doc/sd...
File native_client_sdk/src/doc/sdk/release-notes.rst (right):

https://codereview.chromium.org/250433002/diff/1/native_client_sdk/src/doc/sd...
native_client_sdk/src/doc/sdk/release-notes.rst:13:
<http://clang.llvm.org/docs/LanguageExtensions.html#vectors-and-extended-vecto...
again, probably an "and" would be more clear than just "/"

[JF, 2014-04-24 16:16:29]

https://codereview.chromium.org/250433002/diff/1/native_client_sdk/src/doc/na...
File native_client_sdk/src/doc/nacl-and-pnacl.rst (right):

https://codereview.chromium.org/250433002/diff/1/native_client_sdk/src/doc/na...
native_client_sdk/src/doc/nacl-and-pnacl.rst:113: offer high-performance
equivalents.
On 2014/04/24 16:06:20, Derek Schuff wrote:
> "high-performance portable equivalents"? 

Done.

https://codereview.chromium.org/250433002/diff/1/native_client_sdk/src/doc/re...
File native_client_sdk/src/doc/reference/pnacl-c-cpp-language-support.rst
(right):

https://codereview.chromium.org/250433002/diff/1/native_client_sdk/src/doc/re...
native_client_sdk/src/doc/reference/pnacl-c-cpp-language-support.rst:221: / `GCC
vectors
On 2014/04/24 16:06:20, Derek Schuff wrote:
> maybe "LLVM vectors and GCC vectors" rather than just /

Done.

https://codereview.chromium.org/250433002/diff/1/native_client_sdk/src/doc/re...
native_client_sdk/src/doc/reference/pnacl-c-cpp-language-support.rst:266: 64-bit
integers and ``double`` will be supported in a future release, as
On 2014/04/24 16:06:20, Derek Schuff wrote:
> maybe just write "64-bit integer and double-precision floating-point types"
> rather than mixing an english description with a C data type.

Done.

https://codereview.chromium.org/250433002/diff/1/native_client_sdk/src/doc/re...
File native_client_sdk/src/doc/reference/pnacl-undefined-behavior.rst (right):

https://codereview.chromium.org/250433002/diff/1/native_client_sdk/src/doc/re...
native_client_sdk/src/doc/reference/pnacl-undefined-behavior.rst:184: such their
behavior isn't specified at all in C/C++, it is usually left
On 2014/04/24 16:06:20, Derek Schuff wrote:
> maybe "SIMD vector types aren't included in the C/C++ standard and as such
their
> behavior isn't specified at all in C/C++; it is usually left up to the target
> architecture to specify behavior"

Done. I went for "part of the C/C++ standards".

https://codereview.chromium.org/250433002/diff/1/native_client_sdk/src/doc/sd...
File native_client_sdk/src/doc/sdk/release-notes.rst (right):

https://codereview.chromium.org/250433002/diff/1/native_client_sdk/src/doc/sd...
native_client_sdk/src/doc/sdk/release-notes.rst:13:
<http://clang.llvm.org/docs/LanguageExtensions.html#vectors-and-extended-vecto...
On 2014/04/24 16:06:20, Derek Schuff wrote:
> again, probably an "and" would be more clear than just "/"

Done.

[Derek Schuff, 2014-04-24 16:50:17]

lgtm

[JF, 2014-04-24 16:59:40]

The CQ bit was checked by jfb@chromium.org

[commit-bot: I haz the power, 2014-04-24 17:00:55]

CQ is trying da patch. Follow status at
https://chromium-status.appspot.com/cq/jfb@chromium.org/250433002/20001

[commit-bot: I haz the power, 2014-04-24 17:07:49]

Change committed as 265948

[nfullagar1, 2014-04-24 23:25:32]

https://codereview.chromium.org/250433002/diff/20001/native_client_sdk/doc_ge...
File native_client_sdk/doc_generated/reference/pnacl-c-cpp-language-support.html
(right):

https://codereview.chromium.org/250433002/diff/20001/native_client_sdk/doc_ge...
native_client_sdk/doc_generated/reference/pnacl-c-cpp-language-support.html:296:
<li>Conversion to/from floating-point and signed/unsigned integer.</li>
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.

[JF, 2014-04-28 16:43:22]

On 2014/04/24 23:25:32, nfullagar1 wrote:
>
https://codereview.chromium.org/250433002/diff/20001/native_client_sdk/doc_ge...
> File
native_client_sdk/doc_generated/reference/pnacl-c-cpp-language-support.html
> (right):
> 
>
https://codereview.chromium.org/250433002/diff/20001/native_client_sdk/doc_ge...
>
native_client_sdk/doc_generated/reference/pnacl-c-cpp-language-support.html:296:
> <li>Conversion to/from floating-point and signed/unsigned integer.</li>
> 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.


Improved here:
  https://codereview.chromium.org/255813009

We do currently support truncation/zero/sign extension but AFAIK they can't be
expressed from C: we can do so to/from bool vectors that have the same number of
elements. I've removed this from the docs for now since it's not very useful to
document something that can't be used!