path: root/devdocs/gcc~13/powerpc-altivec_002fvsx-built-in-functions.html

<div class="subsection-level-extent" id="PowerPC-AltiVec_002fVSX-Built-in-Functions"> <div class="nav-panel"> <p> Next: <a href="powerpc-hardware-transactional-memory-built-in-functions" accesskey="n" rel="next">PowerPC Hardware Transactional Memory Built-in Functions</a>, Previous: <a href="basic-powerpc-built-in-functions" accesskey="p" rel="prev">Basic PowerPC Built-in Functions</a>, Up: <a href="target-builtins" accesskey="u" rel="up">Built-in Functions Specific to Particular Target Machines</a> [<a href="index#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="indices" title="Index" rel="index">Index</a>]</p> </div>  <h1 class="subsection" id="PowerPC-AltiVec_002fVSX-Built-in-Functions-1"><span>6.60.23 PowerPC AltiVec/VSX Built-in Functions<a class="copiable-link" href="#PowerPC-AltiVec_002fVSX-Built-in-Functions-1"> ¶</a></span></h1> <p>GCC provides an interface for the PowerPC family of processors to access the AltiVec operations described in Motorola’s AltiVec Programming Interface Manual. The interface is made available by including <code class="code">&lt;altivec.h&gt;</code> and using <samp class="option">-maltivec</samp> and <samp class="option">-mabi=altivec</samp>. The interface supports the following vector types. </p> <div class="example smallexample"> <pre class="example-preformatted" data-language="cpp">vector unsigned char
vector signed char
vector bool char

vector unsigned short
vector signed short
vector bool short
vector pixel

vector unsigned int
vector signed int
vector bool int
vector float</pre>
</div> <p>GCC’s implementation of the high-level language interface available from C and C++ code differs from Motorola’s documentation in several ways. </p> <ul class="itemize mark-bullet"> <li>A vector constant is a list of constant expressions within curly braces. </li>
<li>A vector initializer requires no cast if the vector constant is of the same type as the variable it is initializing. </li>
<li>If <code class="code">signed</code> or <code class="code">unsigned</code> is omitted, the signedness of the vector type is the default signedness of the base type. The default varies depending on the operating system, so a portable program should always specify the signedness. </li>
<li>Compiling with <samp class="option">-maltivec</samp> adds keywords <code class="code">__vector</code>, <code class="code">vector</code>, <code class="code">__pixel</code>, <code class="code">pixel</code>, <code class="code">__bool</code> and <code class="code">bool</code>. When compiling ISO C, the context-sensitive substitution of the keywords <code class="code">vector</code>, <code class="code">pixel</code> and <code class="code">bool</code> is disabled. To use them, you must include <code class="code">&lt;altivec.h&gt;</code> instead. </li>
<li>GCC allows using a <code class="code">typedef</code> name as the type specifier for a vector type, but only under the following circumstances: <ul class="itemize mark-bullet"> <li>When using <code class="code">__vector</code> instead of <code class="code">vector</code>; for example, <div class="example smallexample"> <pre class="example-preformatted" data-language="cpp">typedef signed short int16;
__vector int16 data;</pre>
</div> </li>
<li>When using <code class="code">vector</code> in keyword-and-predefine mode; for example, <div class="example smallexample"> <pre class="example-preformatted" data-language="cpp">typedef signed short int16;
vector int16 data;</pre>
</div> <p>Note that keyword-and-predefine mode is enabled by disabling GNU extensions (e.g., by using <code class="code">-std=c11</code>) and including <code class="code">&lt;altivec.h&gt;</code>. </p>
</li>
</ul> </li>
<li>For C, overloaded functions are implemented with macros so the following does not work: <div class="example smallexample"> <pre class="example-preformatted" data-language="cpp">vec_add ((vector signed int){1, 2, 3, 4}, foo);</pre>
</div> <p>Since <code class="code">vec_add</code> is a macro, the vector constant in the example is treated as four separate arguments. Wrap the entire argument in parentheses for this to work. </p>
</li>
</ul> <p><em class="emph">Note:</em> Only the <code class="code">&lt;altivec.h&gt;</code> interface is supported. Internally, GCC uses built-in functions to achieve the functionality in the aforementioned header file, but they are not supported and are subject to change without notice. </p> <p>GCC complies with the Power Vector Intrinsic Programming Reference (PVIPR), which may be found at <a class="uref" href="https://openpowerfoundation.org/?resource_lib=power-vector-intrinsic-programming-reference">https://openpowerfoundation.org/?resource_lib=power-vector-intrinsic-programming-reference</a>. Chapter 4 of this document fully documents the vector API interfaces that must be provided by compliant compilers. Programmers should preferentially use the interfaces described therein. However, historically GCC has provided additional interfaces for access to vector instructions. These are briefly described below. Where the PVIPR provides a portable interface, other functions in GCC that provide the same capabilities should be considered deprecated. </p> <p>The PVIPR documents the following overloaded functions: </p> <table class="multitable"> <tbody>
<tr>
<td width="33%"><code class="code">vec_abs</code></td>
<td width="33%"><code class="code">vec_absd</code></td>
<td width="33%"><code class="code">vec_abss</code></td>
</tr> <tr>
<td width="33%"><code class="code">vec_add</code></td>
<td width="33%"><code class="code">vec_addc</code></td>
<td width="33%"><code class="code">vec_adde</code></td>
</tr> <tr>
<td width="33%"><code class="code">vec_addec</code></td>
<td width="33%"><code class="code">vec_adds</code></td>
<td width="33%"><code class="code">vec_all_eq</code></td>
</tr> <tr>
<td width="33%"><code class="code">vec_all_ge</code></td>
<td width="33%"><code class="code">vec_all_gt</code></td>
<td width="33%"><code class="code">vec_all_in</code></td>
</tr> <tr>
<td width="33%"><code class="code">vec_all_le</code></td>
<td width="33%"><code class="code">vec_all_lt</code></td>
<td width="33%"><code class="code">vec_all_nan</code></td>
</tr> <tr>
<td width="33%"><code class="code">vec_all_ne</code></td>
<td width="33%"><code class="code">vec_all_nge</code></td>
<td width="33%"><code class="code">vec_all_ngt</code></td>
</tr> <tr>
<td width="33%"><code class="code">vec_all_nle</code></td>
<td width="33%"><code class="code">vec_all_nlt</code></td>
<td width="33%"><code class="code">vec_all_numeric</code></td>
</tr> <tr>
<td width="33%"><code class="code">vec_and</code></td>
<td width="33%"><code class="code">vec_andc</code></td>
<td width="33%"><code class="code">vec_any_eq</code></td>
</tr> <tr>
<td width="33%"><code class="code">vec_any_ge</code></td>
<td width="33%"><code class="code">vec_any_gt</code></td>
<td width="33%"><code class="code">vec_any_le</code></td>
</tr> <tr>
<td width="33%"><code class="code">vec_any_lt</code></td>
<td width="33%"><code class="code">vec_any_nan</code></td>
<td width="33%"><code class="code">vec_any_ne</code></td>
</tr> <tr>
<td width="33%"><code class="code">vec_any_nge</code></td>
<td width="33%"><code class="code">vec_any_ngt</code></td>
<td width="33%"><code class="code">vec_any_nle</code></td>
</tr> <tr>
<td width="33%"><code class="code">vec_any_nlt</code></td>
<td width="33%"><code class="code">vec_any_numeric</code></td>
<td width="33%"><code class="code">vec_any_out</code></td>
</tr> <tr>
<td width="33%"><code class="code">vec_avg</code></td>
<td width="33%"><code class="code">vec_bperm</code></td>
<td width="33%"><code class="code">vec_ceil</code></td>
</tr> <tr>
<td width="33%"><code class="code">vec_cipher_be</code></td>
<td width="33%"><code class="code">vec_cipherlast_be</code></td>
<td width="33%"><code class="code">vec_cmpb</code></td>
</tr> <tr>
<td width="33%"><code class="code">vec_cmpeq</code></td>
<td width="33%"><code class="code">vec_cmpge</code></td>
<td width="33%"><code class="code">vec_cmpgt</code></td>
</tr> <tr>
<td width="33%"><code class="code">vec_cmple</code></td>
<td width="33%"><code class="code">vec_cmplt</code></td>
<td width="33%"><code class="code">vec_cmpne</code></td>
</tr> <tr>
<td width="33%"><code class="code">vec_cmpnez</code></td>
<td width="33%"><code class="code">vec_cntlz</code></td>
<td width="33%"><code class="code">vec_cntlz_lsbb</code></td>
</tr> <tr>
<td width="33%"><code class="code">vec_cnttz</code></td>
<td width="33%"><code class="code">vec_cnttz_lsbb</code></td>
<td width="33%"><code class="code">vec_cpsgn</code></td>
</tr> <tr>
<td width="33%"><code class="code">vec_ctf</code></td>
<td width="33%"><code class="code">vec_cts</code></td>
<td width="33%"><code class="code">vec_ctu</code></td>
</tr> <tr>
<td width="33%"><code class="code">vec_div</code></td>
<td width="33%"><code class="code">vec_double</code></td>
<td width="33%"><code class="code">vec_doublee</code></td>
</tr> <tr>
<td width="33%"><code class="code">vec_doubleh</code></td>
<td width="33%"><code class="code">vec_doublel</code></td>
<td width="33%"><code class="code">vec_doubleo</code></td>
</tr> <tr>
<td width="33%"><code class="code">vec_eqv</code></td>
<td width="33%"><code class="code">vec_expte</code></td>
<td width="33%"><code class="code">vec_extract</code></td>
</tr> <tr>
<td width="33%"><code class="code">vec_extract_exp</code></td>
<td width="33%"><code class="code">vec_extract_fp32_from_shorth</code></td>
<td width="33%"><code class="code">vec_extract_fp32_from_shortl</code></td>
</tr> <tr>
<td width="33%"><code class="code">vec_extract_sig</code></td>
<td width="33%"><code class="code">vec_extract_4b</code></td>
<td width="33%"><code class="code">vec_first_match_index</code></td>
</tr> <tr>
<td width="33%"><code class="code">vec_first_match_or_eos_index</code></td>
<td width="33%"><code class="code">vec_first_mismatch_index</code></td>
<td width="33%"><code class="code">vec_first_mismatch_or_eos_index</code></td>
</tr> <tr>
<td width="33%"><code class="code">vec_float</code></td>
<td width="33%"><code class="code">vec_float2</code></td>
<td width="33%"><code class="code">vec_floate</code></td>
</tr> <tr>
<td width="33%"><code class="code">vec_floato</code></td>
<td width="33%"><code class="code">vec_floor</code></td>
<td width="33%"><code class="code">vec_gb</code></td>
</tr> <tr>
<td width="33%"><code class="code">vec_insert</code></td>
<td width="33%"><code class="code">vec_insert_exp</code></td>
<td width="33%"><code class="code">vec_insert4b</code></td>
</tr> <tr>
<td width="33%"><code class="code">vec_ld</code></td>
<td width="33%"><code class="code">vec_lde</code></td>
<td width="33%"><code class="code">vec_ldl</code></td>
</tr> <tr>
<td width="33%"><code class="code">vec_loge</code></td>
<td width="33%"><code class="code">vec_madd</code></td>
<td width="33%"><code class="code">vec_madds</code></td>
</tr> <tr>
<td width="33%"><code class="code">vec_max</code></td>
<td width="33%"><code class="code">vec_mergee</code></td>
<td width="33%"><code class="code">vec_mergeh</code></td>
</tr> <tr>
<td width="33%"><code class="code">vec_mergel</code></td>
<td width="33%"><code class="code">vec_mergeo</code></td>
<td width="33%"><code class="code">vec_mfvscr</code></td>
</tr> <tr>
<td width="33%"><code class="code">vec_min</code></td>
<td width="33%"><code class="code">vec_mradds</code></td>
<td width="33%"><code class="code">vec_msub</code></td>
</tr> <tr>
<td width="33%"><code class="code">vec_msum</code></td>
<td width="33%"><code class="code">vec_msums</code></td>
<td width="33%"><code class="code">vec_mtvscr</code></td>
</tr> <tr>
<td width="33%"><code class="code">vec_mul</code></td>
<td width="33%"><code class="code">vec_mule</code></td>
<td width="33%"><code class="code">vec_mulo</code></td>
</tr> <tr>
<td width="33%"><code class="code">vec_nabs</code></td>
<td width="33%"><code class="code">vec_nand</code></td>
<td width="33%"><code class="code">vec_ncipher_be</code></td>
</tr> <tr>
<td width="33%"><code class="code">vec_ncipherlast_be</code></td>
<td width="33%"><code class="code">vec_nearbyint</code></td>
<td width="33%"><code class="code">vec_neg</code></td>
</tr> <tr>
<td width="33%"><code class="code">vec_nmadd</code></td>
<td width="33%"><code class="code">vec_nmsub</code></td>
<td width="33%"><code class="code">vec_nor</code></td>
</tr> <tr>
<td width="33%"><code class="code">vec_or</code></td>
<td width="33%"><code class="code">vec_orc</code></td>
<td width="33%"><code class="code">vec_pack</code></td>
</tr> <tr>
<td width="33%"><code class="code">vec_pack_to_short_fp32</code></td>
<td width="33%"><code class="code">vec_packpx</code></td>
<td width="33%"><code class="code">vec_packs</code></td>
</tr> <tr>
<td width="33%"><code class="code">vec_packsu</code></td>
<td width="33%"><code class="code">vec_parity_lsbb</code></td>
<td width="33%"><code class="code">vec_perm</code></td>
</tr> <tr>
<td width="33%"><code class="code">vec_permxor</code></td>
<td width="33%"><code class="code">vec_pmsum_be</code></td>
<td width="33%"><code class="code">vec_popcnt</code></td>
</tr> <tr>
<td width="33%"><code class="code">vec_re</code></td>
<td width="33%"><code class="code">vec_recipdiv</code></td>
<td width="33%"><code class="code">vec_revb</code></td>
</tr> <tr>
<td width="33%"><code class="code">vec_reve</code></td>
<td width="33%"><code class="code">vec_rint</code></td>
<td width="33%"><code class="code">vec_rl</code></td>
</tr> <tr>
<td width="33%"><code class="code">vec_rlmi</code></td>
<td width="33%"><code class="code">vec_rlnm</code></td>
<td width="33%"><code class="code">vec_round</code></td>
</tr> <tr>
<td width="33%"><code class="code">vec_rsqrt</code></td>
<td width="33%"><code class="code">vec_rsqrte</code></td>
<td width="33%"><code class="code">vec_sbox_be</code></td>
</tr> <tr>
<td width="33%"><code class="code">vec_sel</code></td>
<td width="33%"><code class="code">vec_shasigma_be</code></td>
<td width="33%"><code class="code">vec_signed</code></td>
</tr> <tr>
<td width="33%"><code class="code">vec_signed2</code></td>
<td width="33%"><code class="code">vec_signede</code></td>
<td width="33%"><code class="code">vec_signedo</code></td>
</tr> <tr>
<td width="33%"><code class="code">vec_sl</code></td>
<td width="33%"><code class="code">vec_sld</code></td>
<td width="33%"><code class="code">vec_sldw</code></td>
</tr> <tr>
<td width="33%"><code class="code">vec_sll</code></td>
<td width="33%"><code class="code">vec_slo</code></td>
<td width="33%"><code class="code">vec_slv</code></td>
</tr> <tr>
<td width="33%"><code class="code">vec_splat</code></td>
<td width="33%"><code class="code">vec_splat_s8</code></td>
<td width="33%"><code class="code">vec_splat_s16</code></td>
</tr> <tr>
<td width="33%"><code class="code">vec_splat_s32</code></td>
<td width="33%"><code class="code">vec_splat_u8</code></td>
<td width="33%"><code class="code">vec_splat_u16</code></td>
</tr> <tr>
<td width="33%"><code class="code">vec_splat_u32</code></td>
<td width="33%"><code class="code">vec_splats</code></td>
<td width="33%"><code class="code">vec_sqrt</code></td>
</tr> <tr>
<td width="33%"><code class="code">vec_sr</code></td>
<td width="33%"><code class="code">vec_sra</code></td>
<td width="33%"><code class="code">vec_srl</code></td>
</tr> <tr>
<td width="33%"><code class="code">vec_sro</code></td>
<td width="33%"><code class="code">vec_srv</code></td>
<td width="33%"><code class="code">vec_st</code></td>
</tr> <tr>
<td width="33%"><code class="code">vec_ste</code></td>
<td width="33%"><code class="code">vec_stl</code></td>
<td width="33%"><code class="code">vec_sub</code></td>
</tr> <tr>
<td width="33%"><code class="code">vec_subc</code></td>
<td width="33%"><code class="code">vec_sube</code></td>
<td width="33%"><code class="code">vec_subec</code></td>
</tr> <tr>
<td width="33%"><code class="code">vec_subs</code></td>
<td width="33%"><code class="code">vec_sum2s</code></td>
<td width="33%"><code class="code">vec_sum4s</code></td>
</tr> <tr>
<td width="33%"><code class="code">vec_sums</code></td>
<td width="33%"><code class="code">vec_test_data_class</code></td>
<td width="33%"><code class="code">vec_trunc</code></td>
</tr> <tr>
<td width="33%"><code class="code">vec_unpackh</code></td>
<td width="33%"><code class="code">vec_unpackl</code></td>
<td width="33%"><code class="code">vec_unsigned</code></td>
</tr> <tr>
<td width="33%"><code class="code">vec_unsigned2</code></td>
<td width="33%"><code class="code">vec_unsignede</code></td>
<td width="33%"><code class="code">vec_unsignedo</code></td>
</tr> <tr>
<td width="33%"><code class="code">vec_xl</code></td>
<td width="33%"><code class="code">vec_xl_be</code></td>
<td width="33%"><code class="code">vec_xl_len</code></td>
</tr> <tr>
<td width="33%"><code class="code">vec_xl_len_r</code></td>
<td width="33%"><code class="code">vec_xor</code></td>
<td width="33%"><code class="code">vec_xst</code></td>
</tr> <tr>
<td width="33%"><code class="code">vec_xst_be</code></td>
<td width="33%"><code class="code">vec_xst_len</code></td>
<td width="33%"><code class="code">vec_xst_len_r</code></td>
</tr> </tbody> </table> <ul class="mini-toc"> <li><a href="powerpc-altivec-built-in-functions-on-isa-2_002e05" accesskey="1">PowerPC AltiVec Built-in Functions on ISA 2.05</a></li> <li><a href="powerpc-altivec-built-in-functions-available-on-isa-2_002e06" accesskey="2">PowerPC AltiVec Built-in Functions Available on ISA 2.06</a></li> <li><a href="powerpc-altivec-built-in-functions-available-on-isa-2_002e07" accesskey="3">PowerPC AltiVec Built-in Functions Available on ISA 2.07</a></li> <li><a href="powerpc-altivec-built-in-functions-available-on-isa-3_002e0" accesskey="4">PowerPC AltiVec Built-in Functions Available on ISA 3.0</a></li> <li><a href="powerpc-altivec-built-in-functions-available-on-isa-3_002e1" accesskey="5">PowerPC AltiVec Built-in Functions Available on ISA 3.1</a></li> </ul> </div>  <div class="nav-panel"> <p> Next: <a href="powerpc-hardware-transactional-memory-built-in-functions">PowerPC Hardware Transactional Memory Built-in Functions</a>, Previous: <a href="basic-powerpc-built-in-functions">Basic PowerPC Built-in Functions</a>, Up: <a href="target-builtins">Built-in Functions Specific to Particular Target Machines</a> [<a href="index#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="indices" title="Index" rel="index">Index</a>]</p> </div><div class="_attribution">
  <p class="_attribution-p">
    &copy; Free Software Foundation<br>Licensed under the GNU Free Documentation License, Version 1.3.<br>
    <a href="https://gcc.gnu.org/onlinedocs/gcc-13.1.0/gcc/PowerPC-AltiVec_002fVSX-Built-in-Functions.html" class="_attribution-link">https://gcc.gnu.org/onlinedocs/gcc-13.1.0/gcc/PowerPC-AltiVec_002fVSX-Built-in-Functions.html</a>
  </p>
</div>