6.60.23.5 PowerPC AltiVec Built-in Functions Available on ISA 3.1

The following additional built-in functions are also available for the PowerPC family of processors, starting with ISA 3.1 (-mcpu=power10):

vector unsigned long long int
vec_cfuge (vector unsigned long long int, vector unsigned long long int)

Perform a vector centrifuge operation, as if implemented by the vcfuged instruction.

vector unsigned long long int
vec_cntlzm (vector unsigned long long int, vector unsigned long long int)

Perform a vector count leading zeros under bit mask operation, as if implemented by the vclzdm instruction.

vector unsigned long long int
vec_cnttzm (vector unsigned long long int, vector unsigned long long int)

Perform a vector count trailing zeros under bit mask operation, as if implemented by the vctzdm instruction.

vector signed char
vec_clrl (vector signed char a, unsigned int n)
vector unsigned char
vec_clrl (vector unsigned char a, unsigned int n)

Clear the left-most (16 - n) bytes of vector argument a, as if implemented by the vclrlb instruction on a big-endian target and by the vclrrb instruction on a little-endian target. A value of n that is greater than 16 is treated as if it equaled 16.

vector signed char
vec_clrr (vector signed char a, unsigned int n)
vector unsigned char
vec_clrr (vector unsigned char a, unsigned int n)

Clear the right-most (16 - n) bytes of vector argument a, as if implemented by the vclrrb instruction on a big-endian target and by the vclrlb instruction on a little-endian target. A value of n that is greater than 16 is treated as if it equaled 16.

vector unsigned long long int
vec_gnb (vector unsigned __int128, const unsigned char)

Perform a 128-bit vector gather operation, as if implemented by the vgnb instruction. The second argument must be a literal integer value between 2 and 7 inclusive.

Vector Extract

vector unsigned long long int
vec_extractl (vector unsigned char, vector unsigned char, unsigned int)
vector unsigned long long int
vec_extractl (vector unsigned short, vector unsigned short, unsigned int)
vector unsigned long long int
vec_extractl (vector unsigned int, vector unsigned int, unsigned int)
vector unsigned long long int
vec_extractl (vector unsigned long long, vector unsigned long long, unsigned int)

Extract an element from two concatenated vectors starting at the given byte index in natural-endian order, and place it zero-extended in doubleword 1 of the result according to natural element order. If the byte index is out of range for the data type, the intrinsic will be rejected. For little-endian, this output will match the placement by the hardware instruction, i.e., dword[0] in RTL notation. For big-endian, an additional instruction is needed to move it from the "left" doubleword to the "right" one. For little-endian, semantics matching the vextdubvrx, vextduhvrx, vextduwvrx instruction will be generated, while for big-endian, semantics matching the vextdubvlx, vextduhvlx, vextduwvlx instructions will be generated. Note that some fairly anomalous results can be generated if the byte index is not aligned on an element boundary for the element being extracted. This is a limitation of the bi-endian vector programming model is consistent with the limitation on vec_perm.

vector unsigned long long int
vec_extracth (vector unsigned char, vector unsigned char, unsigned int)
vector unsigned long long int
vec_extracth (vector unsigned short, vector unsigned short,
unsigned int)
vector unsigned long long int
vec_extracth (vector unsigned int, vector unsigned int, unsigned int)
vector unsigned long long int
vec_extracth (vector unsigned long long, vector unsigned long long,
unsigned int)

Extract an element from two concatenated vectors starting at the given byte index. The index is based on big endian order for a little endian system. Similarly, the index is based on little endian order for a big endian system. The extraced elements are zero-extended and put in doubleword 1 according to natural element order. If the byte index is out of range for the data type, the intrinsic will be rejected. For little-endian, this output will match the placement by the hardware instruction (vextdubvrx, vextduhvrx, vextduwvrx, vextddvrx) i.e., dword[0] in RTL notation. For big-endian, an additional instruction is needed to move it from the "left" doubleword to the "right" one. For little-endian, semantics matching the vextdubvlx, vextduhvlx, vextduwvlx instructions will be generated, while for big-endian, semantics matching the vextdubvrx, vextduhvrx, vextduwvrx instructions will be generated. Note that some fairly anomalous results can be generated if the byte index is not aligned on the element boundary for the element being extracted. This is a limitation of the bi-endian vector programming model consistent with the limitation on vec_perm.

vector unsigned long long int
vec_pdep (vector unsigned long long int, vector unsigned long long int)

Perform a vector parallel bits deposit operation, as if implemented by the vpdepd instruction.

Vector Insert

vector unsigned char
vec_insertl (unsigned char, vector unsigned char, unsigned int);
vector unsigned short
vec_insertl (unsigned short, vector unsigned short, unsigned int);
vector unsigned int
vec_insertl (unsigned int, vector unsigned int, unsigned int);
vector unsigned long long
vec_insertl (unsigned long long, vector unsigned long long,
unsigned int);
vector unsigned char
vec_insertl (vector unsigned char, vector unsigned char, unsigned int;
vector unsigned short
vec_insertl (vector unsigned short, vector unsigned short,
unsigned int);
vector unsigned int
vec_insertl (vector unsigned int, vector unsigned int, unsigned int);

Let src be the first argument, when the first argument is a scalar, or the rightmost element of the left doubleword of the first argument, when the first argument is a vector. Insert the source into the destination at the position given by the third argument, using natural element order in the second argument. The rest of the second argument is unchanged. If the byte index is greater than 14 for halfwords, greater than 12 for words, or greater than 8 for doublewords the result is undefined. For little-endian, the generated code will be semantically equivalent to vins[bhwd]rx instructions. Similarly for big-endian it will be semantically equivalent to vins[bhwd]lx. Note that some fairly anomalous results can be generated if the byte index is not aligned on an element boundary for the type of element being inserted.

vector unsigned char
vec_inserth (unsigned char, vector unsigned char, unsigned int);
vector unsigned short
vec_inserth (unsigned short, vector unsigned short, unsigned int);
vector unsigned int
vec_inserth (unsigned int, vector unsigned int, unsigned int);
vector unsigned long long
vec_inserth (unsigned long long, vector unsigned long long,
unsigned int);
vector unsigned char
vec_inserth (vector unsigned char, vector unsigned char, unsigned int);
vector unsigned short
vec_inserth (vector unsigned short, vector unsigned short,
unsigned int);
vector unsigned int
vec_inserth (vector unsigned int, vector unsigned int, unsigned int);

Let src be the first argument, when the first argument is a scalar, or the rightmost element of the first argument, when the first argument is a vector. Insert src into the second argument at the position identified by the third argument, using opposite element order in the second argument, and leaving the rest of the second argument unchanged. If the byte index is greater than 14 for halfwords, 12 for words, or 8 for doublewords, the intrinsic will be rejected. Note that the underlying hardware instruction uses the same register for the second argument and the result. For little-endian, the code generation will be semantically equivalent to vins[bhwd]lx, while for big-endian it will be semantically equivalent to vins[bhwd]rx. Note that some fairly anomalous results can be generated if the byte index is not aligned on an element boundary for the sort of element being inserted.

Vector Replace Element

vector signed int vec_replace_elt (vector signed int, signed int,
const int);
vector unsigned int vec_replace_elt (vector unsigned int,
unsigned int, const int);
vector float vec_replace_elt (vector float, float, const int);
vector signed long long vec_replace_elt (vector signed long long,
signed long long, const int);
vector unsigned long long vec_replace_elt (vector unsigned long long,
unsigned long long, const int);
vector double rec_replace_elt (vector double, double, const int);

The third argument (constrained to [0,3]) identifies the natural-endian element number of the first argument that will be replaced by the second argument to produce the result. The other elements of the first argument will remain unchanged in the result.

If it’s desirable to insert a word at an unaligned position, use vec_replace_unaligned instead.

Vector Replace Unaligned

vector unsigned char vec_replace_unaligned (vector unsigned char,
signed int, const int);
vector unsigned char vec_replace_unaligned (vector unsigned char,
unsigned int, const int);
vector unsigned char vec_replace_unaligned (vector unsigned char,
float, const int);
vector unsigned char vec_replace_unaligned (vector unsigned char,
signed long long, const int);
vector unsigned char vec_replace_unaligned (vector unsigned char,
unsigned long long, const int);
vector unsigned char vec_replace_unaligned (vector unsigned char,
double, const int);

The second argument replaces a portion of the first argument to produce the result, with the rest of the first argument unchanged in the result. The third argument identifies the byte index (using left-to-right, or big-endian order) where the high-order byte of the second argument will be placed, with the remaining bytes of the second argument placed naturally "to the right" of the high-order byte.

The programmer is responsible for understanding the endianness issues involved with the first argument and the result.

Vector Shift Left Double Bit Immediate

vector signed char vec_sldb (vector signed char, vector signed char,
const unsigned int);
vector unsigned char vec_sldb (vector unsigned char,
vector unsigned char, const unsigned int);
vector signed short vec_sldb (vector signed short, vector signed short,
const unsigned int);
vector unsigned short vec_sldb (vector unsigned short,
vector unsigned short, const unsigned int);
vector signed int vec_sldb (vector signed int, vector signed int,
const unsigned int);
vector unsigned int vec_sldb (vector unsigned int, vector unsigned int,
const unsigned int);
vector signed long long vec_sldb (vector signed long long,
vector signed long long, const unsigned int);
vector unsigned long long vec_sldb (vector unsigned long long,
vector unsigned long long, const unsigned int);

Shift the combined input vectors left by the amount specified by the low-order three bits of the third argument, and return the leftmost remaining 128 bits. Code using this instruction must be endian-aware.

Vector Shift Right Double Bit Immediate

vector signed char vec_srdb (vector signed char, vector signed char,
const unsigned int);
vector unsigned char vec_srdb (vector unsigned char, vector unsigned char,
const unsigned int);
vector signed short vec_srdb (vector signed short, vector signed short,
const unsigned int);
vector unsigned short vec_srdb (vector unsigned short, vector unsigned short,
const unsigned int);
vector signed int vec_srdb (vector signed int, vector signed int,
const unsigned int);
vector unsigned int vec_srdb (vector unsigned int, vector unsigned int,
const unsigned int);
vector signed long long vec_srdb (vector signed long long,
vector signed long long, const unsigned int);
vector unsigned long long vec_srdb (vector unsigned long long,
vector unsigned long long, const unsigned int);

Shift the combined input vectors right by the amount specified by the low-order three bits of the third argument, and return the remaining 128 bits. Code using this built-in must be endian-aware.

Vector Splat

vector signed int vec_splati (const signed int);
vector float vec_splati (const float);

Splat a 32-bit immediate into a vector of words.

vector double vec_splatid (const float);

Convert a single precision floating-point value to double-precision and splat the result to a vector of double-precision floats.

vector signed int vec_splati_ins (vector signed int,
const unsigned int, const signed int);
vector unsigned int vec_splati_ins (vector unsigned int,
const unsigned int, const unsigned int);
vector float vec_splati_ins (vector float, const unsigned int,
const float);

Argument 2 must be either 0 or 1. Splat the value of argument 3 into the word identified by argument 2 of each doubleword of argument 1 and return the result. The other words of argument 1 are unchanged.

Vector Blend Variable

vector signed char vec_blendv (vector signed char, vector signed char,
vector unsigned char);
vector unsigned char vec_blendv (vector unsigned char,
vector unsigned char, vector unsigned char);
vector signed short vec_blendv (vector signed short,
vector signed short, vector unsigned short);
vector unsigned short vec_blendv (vector unsigned short,
vector unsigned short, vector unsigned short);
vector signed int vec_blendv (vector signed int, vector signed int,
vector unsigned int);
vector unsigned int vec_blendv (vector unsigned int,
vector unsigned int, vector unsigned int);
vector signed long long vec_blendv (vector signed long long,
vector signed long long, vector unsigned long long);
vector unsigned long long vec_blendv (vector unsigned long long,
vector unsigned long long, vector unsigned long long);
vector float vec_blendv (vector float, vector float,
vector unsigned int);
vector double vec_blendv (vector double, vector double,
vector unsigned long long);

Blend the first and second argument vectors according to the sign bits of the corresponding elements of the third argument vector. This is similar to the vsel and xxsel instructions but for bigger elements.

Vector Permute Extended

vector signed char vec_permx (vector signed char, vector signed char,
vector unsigned char, const int);
vector unsigned char vec_permx (vector unsigned char,
vector unsigned char, vector unsigned char, const int);
vector signed short vec_permx (vector signed short,
vector signed short, vector unsigned char, const int);
vector unsigned short vec_permx (vector unsigned short,
vector unsigned short, vector unsigned char, const int);
vector signed int vec_permx (vector signed int, vector signed int,
vector unsigned char, const int);
vector unsigned int vec_permx (vector unsigned int,
vector unsigned int, vector unsigned char, const int);
vector signed long long vec_permx (vector signed long long,
vector signed long long, vector unsigned char, const int);
vector unsigned long long vec_permx (vector unsigned long long,
vector unsigned long long, vector unsigned char, const int);
vector float (vector float, vector float, vector unsigned char,
const int);
vector double (vector double, vector double, vector unsigned char,
const int);

Perform a partial permute of the first two arguments, which form a 32-byte section of an emulated vector up to 256 bytes wide, using the partial permute control vector in the third argument. The fourth argument (constrained to values of 0-7) identifies which 32-byte section of the emulated vector is contained in the first two arguments.

vector unsigned long long int
vec_pext (vector unsigned long long int, vector unsigned long long int)

Perform a vector parallel bit extract operation, as if implemented by the vpextd instruction.

vector unsigned char vec_stril (vector unsigned char)
vector signed char vec_stril (vector signed char)
vector unsigned short vec_stril (vector unsigned short)
vector signed short vec_stril (vector signed short)

Isolate the left-most non-zero elements of the incoming vector argument, replacing all elements to the right of the left-most zero element found within the argument with zero. The typical implementation uses the vstribl or vstrihl instruction on big-endian targets and uses the vstribr or vstrihr instruction on little-endian targets.

int vec_stril_p (vector unsigned char)
int vec_stril_p (vector signed char)
int short vec_stril_p (vector unsigned short)
int vec_stril_p (vector signed short)

Return a non-zero value if and only if the argument contains a zero element. The typical implementation uses the vstribl. or vstrihl. instruction on big-endian targets and uses the vstribr. or vstrihr. instruction on little-endian targets. Choose this built-in to check for presence of zero element if the same argument is also passed to vec_stril.

vector unsigned char vec_strir (vector unsigned char)
vector signed char vec_strir (vector signed char)
vector unsigned short vec_strir (vector unsigned short)
vector signed short vec_strir (vector signed short)

Isolate the right-most non-zero elements of the incoming vector argument, replacing all elements to the left of the right-most zero element found within the argument with zero. The typical implementation uses the vstribr or vstrihr instruction on big-endian targets and uses the vstribl or vstrihl instruction on little-endian targets.

int vec_strir_p (vector unsigned char)
int vec_strir_p (vector signed char)
int short vec_strir_p (vector unsigned short)
int vec_strir_p (vector signed short)

Return a non-zero value if and only if the argument contains a zero element. The typical implementation uses the vstribr. or vstrihr. instruction on big-endian targets and uses the vstribl. or vstrihl. instruction on little-endian targets. Choose this built-in to check for presence of zero element if the same argument is also passed to vec_strir.

vector unsigned char
vec_ternarylogic (vector unsigned char, vector unsigned char,
vector unsigned char, const unsigned int)
vector unsigned short
vec_ternarylogic (vector unsigned short, vector unsigned short,
vector unsigned short, const unsigned int)
vector unsigned int
vec_ternarylogic (vector unsigned int, vector unsigned int,
vector unsigned int, const unsigned int)
vector unsigned long long int
vec_ternarylogic (vector unsigned long long int, vector unsigned long long int,
vector unsigned long long int, const unsigned int)
vector unsigned __int128
vec_ternarylogic (vector unsigned __int128, vector unsigned __int128,
vector unsigned __int128, const unsigned int)

Perform a 128-bit vector evaluate operation, as if implemented by the xxeval instruction. The fourth argument must be a literal integer value between 0 and 255 inclusive.

vector unsigned char vec_genpcvm (vector unsigned char, const int)
vector unsigned short vec_genpcvm (vector unsigned short, const int)
vector unsigned int vec_genpcvm (vector unsigned int, const int)
vector unsigned int vec_genpcvm (vector unsigned long long int,
const int)

Vector Integer Multiply/Divide/Modulo

vector signed int
vec_mulh (vector signed int a, vector signed int b)
vector unsigned int
vec_mulh (vector unsigned int a, vector unsigned int b)

For each integer value i from 0 to 3, do the following. The integer value in word element i of a is multiplied by the integer value in word element i of b. The high-order 32 bits of the 64-bit product are placed into word element i of the vector returned.

vector signed long long
vec_mulh (vector signed long long a, vector signed long long b)
vector unsigned long long
vec_mulh (vector unsigned long long a, vector unsigned long long b)

For each integer value i from 0 to 1, do the following. The integer value in doubleword element i of a is multiplied by the integer value in doubleword element i of b. The high-order 64 bits of the 128-bit product are placed into doubleword element i of the vector returned.

vector unsigned long long
vec_mul (vector unsigned long long a, vector unsigned long long b)
vector signed long long
vec_mul (vector signed long long a, vector signed long long b)

For each integer value i from 0 to 1, do the following. The integer value in doubleword element i of a is multiplied by the integer value in doubleword element i of b. The low-order 64 bits of the 128-bit product are placed into doubleword element i of the vector returned.

vector signed int
vec_div (vector signed int a, vector signed int b)
vector unsigned int
vec_div (vector unsigned int a, vector unsigned int b)

For each integer value i from 0 to 3, do the following. The integer in word element i of a is divided by the integer in word element i of b. The unique integer quotient is placed into the word element i of the vector returned. If an attempt is made to perform any of the divisions <anything> ÷ 0 then the quotient is undefined.

vector signed long long
vec_div (vector signed long long a, vector signed long long b)
vector unsigned long long
vec_div (vector unsigned long long a, vector unsigned long long b)

For each integer value i from 0 to 1, do the following. The integer in doubleword element i of a is divided by the integer in doubleword element i of b. The unique integer quotient is placed into the doubleword element i of the vector returned. If an attempt is made to perform any of the divisions 0x8000_0000_0000_0000 ÷ -1 or <anything> ÷ 0 then the quotient is undefined.

vector signed int
vec_dive (vector signed int a, vector signed int b)
vector unsigned int
vec_dive (vector unsigned int a, vector unsigned int b)

For each integer value i from 0 to 3, do the following. The integer in word element i of a is shifted left by 32 bits, then divided by the integer in word element i of b. The unique integer quotient is placed into the word element i of the vector returned. If the quotient cannot be represented in 32 bits, or if an attempt is made to perform any of the divisions <anything> ÷ 0 then the quotient is undefined.

vector signed long long
vec_dive (vector signed long long a, vector signed long long b)
vector unsigned long long
vec_dive (vector unsigned long long a, vector unsigned long long b)

For each integer value i from 0 to 1, do the following. The integer in doubleword element i of a is shifted left by 64 bits, then divided by the integer in doubleword element i of b. The unique integer quotient is placed into the doubleword element i of the vector returned. If the quotient cannot be represented in 64 bits, or if an attempt is made to perform <anything> ÷ 0 then the quotient is undefined.

vector signed int
vec_mod (vector signed int a, vector signed int b)
vector unsigned int
vec_mod (vector unsigned int a, vector unsigned int b)

For each integer value i from 0 to 3, do the following. The integer in word element i of a is divided by the integer in word element i of b. The unique integer remainder is placed into the word element i of the vector returned. If an attempt is made to perform any of the divisions 0x8000_0000 ÷ -1 or <anything> ÷ 0 then the remainder is undefined.

vector signed long long
vec_mod (vector signed long long a, vector signed long long b)
vector unsigned long long
vec_mod (vector unsigned long long a, vector unsigned long long b)

For each integer value i from 0 to 1, do the following. The integer in doubleword element i of a is divided by the integer in doubleword element i of b. The unique integer remainder is placed into the doubleword element i of the vector returned. If an attempt is made to perform <anything> ÷ 0 then the remainder is undefined.

Generate PCV from specified Mask size, as if implemented by the xxgenpcvbm, xxgenpcvhm, xxgenpcvwm instructions, where immediate value is either 0, 1, 2 or 3.

Previous: , Up: PowerPC AltiVec/VSX Built-in Functions [Contents][Index]

© Free Software Foundation
Licensed under the GNU Free Documentation License, Version 1.3.
https://gcc.gnu.org/onlinedocs/gcc-11.1.0/gcc/PowerPC-AltiVec-Built_002din-Functions-Available-on-ISA-3_002e1.html