Appendix B. Built-in Functions

The compiler provides you with a selection of built-in functions to help you write more efficient programs. This section summarizes the various built-in functions available to you.

You can also find additional built-in functions described at Built-in Functions Used for Parallel Processing.


Name Prototype Description
__alignx void __alignx(int alignment, const void *address); Informs the compiler that the specified address is aligned at a known compile-time offset. Alignment must be a positive constant integer with a value greater than zero and of a power of two.
__bcopy void __bcopy(char *, char *, int); Block copy
__bzero void __bzero(void *, size_t); Block zero
__check_lock_mp unsigned int __check_lock_mp (const int* addr, int old_value, int new_value); Check Lock on MultiProcessor systems.

Conditionally updates a single word variable atomically. addr specifies the address of the single word variable. old_value specifies the old value to be checked against the value of the single word variable. new_value specifies the new value to be conditionally assigned to the single word variable. The word variable must be aligned on a full word boundary.

Return values:

  1. A return value of false indicates that the single word variable was equal to the old value and has been set to the new value.
  2. A return value of true indicates that the single word variable was not equal to the old value and has been left unchanged.
__check_lockd_mp unsigned int __check_lockd_mp (const long long int* addr, long long int old_value, long long int new_value); Check Lock Doubleword on MultiProcessor systems.

Conditionally updates a double word variable atomically. addr specifies the address of the double word variable. old_value specifies the old value to be checked against the value of the double word variable. new_value specifies the new value to be conditionally assigned to the double word variable. The double word variable must be aligned on a double word boundary.

Return values:

  1. A return value of false indicates that the double word variable was equal to the old value and has been set to the new value.
  2. A return value of true indicates that the double word variable was not equal to the old value and has been left unchanged.
__check_lock_up unsigned int __check_lock_up (const int* addr, int old_value, int new_value); Check Lock on UniProcessor systems.

Conditionally updates a single word variable atomically. addr specifies the address of the single word variable. old_value specifies the old value to be checked against the value of the single word variable. new_value specifies the new value to be conditionally assigned to the single word variable. The word variable must be aligned on a full word boundary.

Return values:

  • A return value of false indicates that the single word variable was equal to the old value, and has been set to the new value.
  • A return value of true indicates that the single word variable was not equal to the old value and has been left unchanged.
__check_lockd_up unsigned int __check_lockd_up (const long long int* addr, long long int old_value, int long long new_value); Check Lock Doubleword on UniProcessor systems.

Conditionally updates a double word variable atomically. addr specifies the address of the double word variable. old_value specifies the old value to be checked against the value of the double word variable. new_value specifies the new value to be conditionally assigned to the double word variable. The double word variable must be aligned on a double word boundary.

Return values:

  • A return value of false indicates that the double word variable was equal to the old value, and has been set to the new value.
  • A return value of true indicates that the double word variable was not equal to the old value and has been left unchanged.
__clear_lock_mp void __clear_lock_mp (const int* addr, int value); Clear Lock on MultiProcessor systems.

Atomic store of the value into the single word variable at the address addr. The word variable must be aligned on a full word boundary.

__clear_lockd_mp void __clear_lockd_mp (const long long int* addr, long long int value); Clear Lock Doubleword on MultiProcessor systems.

Atomic store of the value into the double word variable at the address addr. The double word variable must be aligned on a double word boundary.

__clear_lock_up void __clear_lock_up (const int* addr, int value); Clear Lock on UniProcessor systems.

Atomic store of the value into the single word variable at the address addr. The word variable must be aligned on a full word boundary.

__clear_lockd_up void __clear_lockd_up (const long long int* addr, long long int value); Clear Lock Doubleword on UniProcessor systems.

Atomic store of the value into the double word variable at the address addr. The double word variable must be aligned on a double word boundary.

__cntlz4 unsigned int __cntlz4(unsigned int); Count Leading Zeros, 4-Byte Integer
__cntlz8 unsigned int __cntlz8(unsigned long long); Count Leading Zeros, 8-Byte Integer
__cnttz4 unsigned int __cnttz4(unsigned int); Count Trailing Zeros, 4-Byte Integer
__cnttz8 unsigned int __cnttz8(unsigned long long); Count Trailing Zeros, 8-Byte Integer
__dcbt( ) void __dcbt (void *); Data Cache Block Touch.

Loads the block of memory containing the specified address into the data cache.

__dcbz( ) void __dcbz (void *); Data Cache Block set to Zero.

Sets the specified address in the data cache to zero (0).

__eieio void __eieio(void); Extra name for the existing __iospace_eieio built-in.

Compiler will recognize __eieio built-in. Everything except for the name is exactly same as for __iospace_eieio. __eieio is consistent with the corresponding PowerPC instruction name.

__exp double __exp(double); Returns the exponential value
__fabs double __fabs(double); Returns the absolute value
__fabss float __fabss(float); Returns the short floating point absolute value
__fcfid double __fcfid (double); Floating Convert From Integer Doubleword.

The 64bit signed fixedpoint operand is converted to a double-precision floating-point.

__fctid double __fctid (double); Floating Convert to Integer Doubleword.

The floating-point operand is converted into 64-bit signed fixed-point integer, using the rounding mode specified by FPSCRRN (Floating-Point Rounding Control field in the Floating-Point Status and Control Register).

__fctidz double __fctidz (double); Floating Convert to Integer Doubleword with Rounding towards Zero.

The floating-point operand is converted into 64-bit signed fixed-point integer, using the rounding mode Round toward Zero.

__fctiw double __fctiw (double); Floating Convert To Integer Word.

The floating-point operand is converted to a 32-bit signed fixed-point integer, using the rounding mode specified by FPSCRRN (Floating-Point Rounding Control field in the Floating-Point Status and Control Register).

__fctiwz double __fctiwz (double); Floating Convert To Integer Word with Rounding towards Zero.

The floating-point operand is converted to a 32-bit signed fixed-point integer, using the rounding mode Round toward Zero.

__fmadd double __fmadd(double, double, double); Floating point multiply-add
__fmadds float __fmadds(float, float, float); Floating point multiply-add short
__fmsub double __fmsub(double, double, double); Floating point multiply-subtract
__fmsubs float __fmsubs(float, float, float); Floating point multiply-subtract
__fnabs double __fnabs(double); Floating point negative absolute
__fnabss float __fnabss(float); Floating point negative absolute
__fnmadd double __fnmadd(double, double, double); Floating point negative multiply-add
__fnmadds float __fnmadds (float, float, float); Floating point negative multiply-add
__fnmsub double __fnmsub(double, double, double); Floating point negative multiply-subtract
__fnmsubs float __fnmsubs (float, float, float); __fnmsubs (a, x, y) = [- (a * x - y)]
__fre double fre (double); Floating point reciprocal
__fre (x) = [(estimate of) 1.0/x] (POWER5 processors only)
__fres float __fres (float); Floating point reciprocal
__fres (x) = [(estimate of) 1.0/x]
__frsqrte double __frsqrte (double); Floating point reciprocal square root
__frsqrte (x) = [(estimate of) 1.0/sqrt(x)]
__frsqrtes float __frsqrtes (float); Floating point reciprocal square root
__frsqrtes (x) = [(estimate of) 1.0/sqrt(x)] (POWER5 processors only)
__fsel double __fsel (double, double, double); Floating point select
if (a >= 0.0) then __fsel (a, x, y) = x;
else __fsel (a, x, y) = y
__fsels float __fsels (float, float, float); Floating point select
if (a >= 0.0) then __fsels (a, x, y) = x;
else __fsels (a, x, y) = y
__fsqrt double __fsqrt (double); Floating point square root
__fsqrt (x) = square root of x
__fsqrts float __fsqrts (float); Floating point square root
__fsqrts (x) = square root of x
__iospace_eieio void __iospace_eieio(void); Generates an EIEIO instruction
__iospace_lwsync (equivalent to: void __iospace_lwsync(void);) Generates a lwsync instruction
__iospace_sync (equivalent to: void __iospace_sync(void);) Generates a sync instruction
__isync void __isync(void); Waits for all previous instructions to complete and then discards any prefetched instructions, causing subsequent instructions to be fetched (or refetched) and executed in the context established by previous instructions.
__load2r unsigned short __load2r(unsigned short*); Load halfword byte reversed
__load4r unsigned int __load4r(unsigned int*); Load word byte reversed
__lwsync (Compiler will recognize __lwsync built-in.) Extra name for the existing __iospace_lwsync built-in.

Compiler will recognize __lwsync built-in. Everything except for the name is exactly same as for __iospace_lwsync. __lwsync is consistent with the corresponding PowerPC instruction name. This function is supported only by the PowerPC 970 processor.

Value must be known at compile time.

__mfdcr unsigned __mfdcr(const int); Returns value of device control register. Valid only for PowerPC 440.
__mtdcr void __mtdcr(const int, unsigned long); Set value of device control register with unsigned long value. Value must be known at compile time. Valid only for PowerPC 440.
__mfspr unsigned __mfspr(const int); Returns value of special purpose register. Value of "const int" must be known at compile time.
__mtspr void __mtspr(const int, unsigned long); Set value of special purpose register with unsigned long value. Values must be known at compile time.
__mtfsb0 void __mtfsb0(unsigned int bt); Move to FPSCR Bit 0.

Bit bt of the FPSCR is set to 0. bt must be a constant and 0<=bt<=31.

__mtfsb1 void __mtfsb1(unsigned int bt); Move to FPSCR Bit 1.

Bit bt of the FPSCR is set to 1. bt must be a constant and 0<=bt<=31.

__mtfsf void __mtfsf(unsigned int flm, unsigned int frb); Move to FPSCR Fields.

The contents of frb are placed into the FPSCR under control of the field mask specified by flm. The field mask flm identifies the 4bit fields of the FPSCR affected. flm must be a constant 8-bit mask.

__mtfsfi void __mtfsfi(unsigned int bf, unsigned int u); Move to FPSCR Field Immediate.

The value of the u is placed into FPSCR field specified by bf. bf and u must be constants, with 0<=bf<=7 and 0<=u<=15.

__mulhd long long int __mulhd(long long int ra, long long int rb); Multiply High Doubleword Signed.

Returns the highorder 64 bits of the 128bit product of the operands ra and rb.

__mulhdu unsigned long long int __mulhdu(unsigned long long int ra, unsigned long long int rb); Multiply High Doubleword Unsigned.

Returns the highorder 64 bits of the 128bit product of the operands ra and rb.

__mulhw int __mulhw(int ra, int rb); Multiply High Word Signed.

Returns the highorder 32 bits of the 64bit product of the operands ra and rb.

__mulhwu unsigned int __mulhwu(unsigned int ra, unsigned int rb); Multiply High Word Unsigned.

Returns the highorder 32 bits of the 64bit product of the operands ra and rb.

__parthds int __parthds(void); Returns the value of the parthds run-time option.

If the parthds option is not explicitly set by the user, the function returns the default value set by the run-time library. If the -qsmp compiler option was not specified during program compilation, this function returns 1 regardless of run-time options selected.

__popcnt4 int __popcnt4(unsigned int); Returns the number of bits set for a 32-bit integer
__popcnt8 int __popcnt8(unsigned long long); Returns the number of bits set for a 64-bit integer
__poppar4 int __poppar4(unsigned int); Returns 1 if there is an odd number of bits set in a 32-bit integer. Returns 0 otherwise.
__poppar8 int __poppar8(unsigned long long); Returns 1 if there is an odd number of bits set in a 64-bit integer. Returns 0 otherwise.
__pow double __pow(double, double);
__prefetch_by_load void __prefetch_by_load(const void*); Touch a memory location via explicit load
__prefetch_by_stream void __prefetch_by_stream(const int, const void*); Touch a memory location via explicit stream
__protected_stream_count void __protected_stream_count(unsigned int unit_cnt, unsigned int ID); Sets unit_cnt number of cache lines for the limited length protected stream with identifier ID. Unit_cnt must be an integer with value of 0 to 1023. Stream ID must have integer value 0 to 15.

(POWER5 processors only)

__protected_stream_go void __protected_stream_go(); Starts prefetching all limited-length protected streams.

(POWER5 processors only)

__protected_stream_set void __protected_stream_set(unsigned int direction, const void* addr, unsigned int ID); Establishes a limited length protected stream using identifier ID, which begins with the cache line at addr and then depending on the value of direction, fetches from either incremental (forward) or decremental (backward) memory addresses. The stream is protected from being replaced by any hardware detected streams.

Direction must have value of 1 (forward) or 3 (backward). Stream ID must have integer value 0 to 15.

(POWER5 processors only)

__protected_unlimited_stream_set_go void __protected_unlimited_stream_set_go (unsigned int direction, const void* addr, unsigned int ID); Establishes an unlimited length protected stream using identifier ID, which begins with the cache line at addr and then depending on the value of direction, fetches from either incremental (forward) or decremental (backward) memory addresses. The stream is protected from being replaced by any hardware detected streams.

Direction must have value of 1 (forward) or 3 (backward). Stream ID must have integer value 0 to 15.

(PowerPC 970 and POWER5 processors only)

__protected_stream_stop void __protected_stream_stop(unsigned int ID); Stops prefetching the protected steam with identifier ID.

(POWER5 processors only)

__protected_stream_stop_all void __protected_stream_stop_all(); Stops prefetching all protected steams.

(POWER5 processors only)

__rdlam unsigned long long __rdlam(unsigned long long rs, unsigned int shift, unsigned long long mask); Rotate Double Left and AND with Mask.

The contents of rs are rotated left shift bits. The rotated data is ANDed with the mask and returned as a result. mask must be a constant and represent a contiguous bit field.

__readflm double __readflm(); Read floating point status/control register
__rldimi unsigned long long __rldimi(unsigned long long rs, unsigned long long is, unsigned int shift, unsigned long long mask); Rotate Left Doubleword Immediate then Mask Insert.

Rotates rs left shift bits then inserts rs into is under bit mask mask. Shift must be a constant and 0<=shift<=63. mask must be a constant and represent a contiguous bit field.

__rlwimi unsigned int __rlwimi(unsigned int rs, unsigned int is, unsigned int shift, unsigned int mask); Rotate Left Word Immidiate then Mask Insert.

Rotates rs left shift bits then inserts rs into is under bit mask mask. Shift must be a constant and 0<=shift<=31. mask must be a constant and represent a contiguous bit field.

__rlwnm unsigned int __rlwnm(unsigned int rs, unsigned int shift, unsigned int mask); Rotate Left Word then AND with Mask.

Rotates rs left shift bits, then ANDs rs with bit mask mask. mask must be a constant and represent a contiguous bit field.

__rotatel4 unsigned int __rotatel4(unsigned int rs, unsigned int shift); Rotate Left Word.

Rotates rs left shift bits.

__setflm double __setflm(double); Set Floating Point Status/Control Register
__setrnd double __setrnd(int); Set Rounding Mode
__stfiw void __stfiw( const int* addr, double value); Store Floating-Point as Integer Word.

The contents of the loworder 32 bits of value are stored, without conversion, into the word in storage addressed by addr.

__store2r void __store2r(unsigned short, unsigned short *); Store 2-byte register
__store4r void __store4r(unsigned int, unsigned int *); Store 4-byte register
__swdiv_nochk double __swdiv_nochk(double, double); Floating-point division of double types; no range checking. This function can provide better performance than the normal divide operator or the __swdiv built-in function in situations where division is performed repeatedly in a loop and when arguments are within the permitted ranges.

Argument restrictions: numerators equal to infinity are not allowed; denominators equal to infinity, zero, or denormalized are not allowed; the quotient of numerator and denominator may not be equal to positive or negative infinity.

With -qstrict in effect, the result is identical bitwise to IEEE division. For correct operation in this scenario, the arguments must satisfy the following additional restrictions. Numerators must have an absolute value greater than 2 ^ (-970) and less than infinity. Denominators must have an absolute value greater than 2 ^ (-1022) and less than 2 ^ 1021. The quotient of numerator and denominator must have an absolute value greater than 2 ^ (-1021) and less than 2 ^ 1023.

__swdiv double __swdiv(double, double); Floating-point division of double types. No argument restrictions.
__swdivs_nochk float __swdivs_nochk(float, float); Floating-point division of float types; no range checking. Argument restrictions: numerators equal to infinity are not allowed; denominators equal to infinity, zero, or denormalized are not allowed; the quotient of numerator and denominator may not be equal to positive or negative infinity.
__swdivs float __swdivs(float, float); Floating-point division of double types. No argument restrictions.
__sync void __sync(void); Extra name for the existing __iospace_sync built-in.

Compiler will recognize __sync built-in. Everything except for the name is exactly same as for __iospace_sync. __sync is consistent with the corresponding PowerPC instruction name.

__tdw void __tdw(long long a, long long b, unsigned int TO); Trap Doubleword.

Operand a is compared with operand b. This comparison results in five conditions which are ANDed with a 5-bit constant TO containing a value of 0 to 31 inclusive.

If the result is not 0 the system trap handler is invoked. Each bit positon, if set, indicates one or more of the following possible conditions:

0 (high-order bit)
a Less Than b, using signed comparison.

1
a Greater Than b, using signed comparison.

2
a Equal b

3
a Less Than b, using unsigned comparison.

4 (low order bit)
a Greater Than b, using unsigned comparison.
__trap void __trap(int); Trap
__trapd void __trapd (longlong); Trap if the parameter is not zero.
__tw void __tw(int a, int b, unsigned int TO); Trap Word.

Operand a is compared with operand b. This comparison results in five conditions which are ANDed with a 5-bit constant TO containing a value of 0 to 31 inclusive.

If the result is not 0 the system trap handler is invoked. Each bit positon, if set, indicates one or more of the following possible conditions:

0 (high-order bit)
a Less Than b, using signed comparison.

1
a Greater Than b, using signed comparison.

2
a Equal b

3
a Less Than b, using unsigned comparison.

4 (low order bit)
a Greater Than b, using unsigned comparison.
__usrthds int __usrthds(void); Returns the value of the usrthds run-time option.

If the usrthds option is not explicitly set by the user, or the -qsmp compiler option was not specified during program compilation, this function returns 0 regardless of run-time options selected.

IBM Copyright 2003