| United States |
|
|
|
| Previous | Contents | Index |
This appendix describes built-in functions available when you compile on Compaq Tru64 UNIX systems. These functions allow you to access hardware and machine instructions directly.
Be sure to include the </machine/builtins.h> header file in your source program to access these built-in functions. Definitions for return types int64 and uint64 are contained in the header file ints.h.
Compaq C++ supports the following translation macros for built-in functions:
_BBCCI(position, address) _BBSSI(position, address) |
Privileged Architecture Library Code Instructions
The following Privileged Architecture Library Code (PALcode) instructions are available as built-in functions:
__PAL_GENTR __PAL_HALT __PAL_BPT __PAL_BUGCHK __PAL_DRAINA |
This function is provided for program debugging. It switches the processor to kernel mode and pushes registers R2 to R7, the updated PC, and PS onto the kernel stack. It then dispatches to the address in the breakpoint vector, which is stored in a control block.
This function has the following format:
|
void __PAL_BPT (void); |
This function is provided for error reporting. It switches the processor to kernel mode and pushes registers R2 to R7, the updated PC, and PS onto the kernel stack. It then dispatches to the address in the bugcheck vector, which is stored in a control block.
This function has the following format:
|
void __PAL_BUGCHK (unsigned long); |
This function stalls instruction issuing until all prior instructions are guaranteed to complete without incurring aborts.
This function has the following format:
|
void __PAL_DRAINA (void); |
This function is used for reporting run-time software conditions.
This function has the following format:
|
void __PAL_GENTRAP (uint64 encoded_software_trap); |
encoded_software_trap
The particular software condition that has occurred.
This function halts the processor when executed by a process running in kernel mode. This is a privileged function.
This function has the following format:
|
void __PAL_HALT (void); |
The __ABS built-in is functionally equivalent to its counterpart, abs, in the standard header file <stdlib.h>.
Its format is also the same:
|
#include <stdlib.h> int __ABS (int x); |
This built-in function does, however, offer performance improvements because there is less call overhead associated with its use.
If you include <stdlib.h>, the built-in function is automatically used for all occurrences of abs. To disable the built-in function, use #undef abs.
Add Aligned Word Interlocked ( __ADAWI)
The __ADAWI function adds its source operand to the destination. This function is interlocked against similar operations by other processors or devices in the system.
This function has the following format:
|
int __ADAWI (short src, short *dest); |
src
The value to be added to the destination.dest
A pointer to the destination. The destination must be aligned on a word boundary. (You can achieve alignment using the _align storage-class modifier.)
The __ADAWI function returns a simulated VAX processor status longword (PSL).
Add Atomic Longword ( __ADD_ATOMIC_LONG)
The __ADD_ATOMIC_LONG function adds the specified expression to the longword data segment pointed to by the address parameter within a load-locked/store-conditional code sequence.
This function has the following format:
|
int __ADD_ATOMIC_LONG int fnc(volatile void *, int, ...); |
address
The address of the data segment.expression
An integer expression....
An optional retry count of type int. If specified, the retry count indicates the number of times the operation is attempted. If the operation cannot be performed successfully in the specified number of retries, a value of 0 is returned.
A value of 1 is returned upon successful completion.
Add Atomic Quadword ( __ADD_ATOMIC_QUAD)
The __ADD_ATOMIC_QUAD function adds the specified expression to the quadword data segment pointed to by the address parameter within a load-locked/store-conditional code sequence.
This function has the following format:
|
int __ADD_ATOMIC_QUAD (void *address, int expression, ...); |
address
The address of the data segment.expression
An integer expression....
An optional retry count of type int. If specified, the retry count indicates the number of times the operation is attempted. If the operation cannot be performed successfully in the specified number of retries, a value of 0 is returned.
A value of 1 is returned upon successful completion.
AND Atomic Longword ( __AND_ATOMIC_LONG)
The __AND_ATOMIC_LONG function performs a logical AND of the specified expression with the longword data segment pointed to by the address parameter within a load-locked/store-conditional code sequence.
This function has the following format:
|
int __AND_ATOMIC_LONG (void *address, int expression, ...); |
address
The address of the data segment.expression
An integer expression....
An optional retry count of type int. If specified, the retry count indicates the number of times the operation is attempted. If the operation cannot be performed successfully in the specified number of retries, a value of 0 is returned.
A value of 1 is returned upon successful completion.
AND Atomic Quadword ( __AND_ATOMIC_QUAD)
The __AND_ATOMIC_QUAD function performs a logical AND of the specified expression with the aligned quadword pointed to by the address parameter within a load-locked/store-conditional code sequence.
This function has the following format:
|
int __AND_ATOMIC_QUAD (void *address, int expression, ...); |
address
The address of the aligned quadword.expression
An integer expression....
An optional retry count of type int . If specified, the retry count indicates the number of times the operation is attempted (which will be at least once, even if the count argument is 0). If the operation cannot be performed successfully in the specified number of retries, a value of 0 is returned.
A value of 1 is returned upon successful completion.
Atomic Add Longword (__ATOMIC_ADD_LONG)
The __ATOMIC_ADD_LONG function adds the specified expression to the aligned longword pointed to by the address parameter within a load-locked/store-conditional code sequence and returns the value of the longword before the addition was performed.
This function has one of the following formats:
|
int __ATOMIC_ADD_LONG (volatile void *address, int expression); int __ATOMIC_ADD_LONG_RETRY (volatile void *address, int expression, int retry, int *status); |
address
The longword-aligned address of the data segment.expression
An integer expression.retry
A retry count of type int that indicates the number of times the operation is attempted (which is at least once, even if the retry argument is 0). If the operation cannot be performed successfully in the specified number of retries, the function returns without updating the longword.status
A pointer to an integer that is set to 0 if the operation did not succeed within the specified number of retries, and set to 1 if the operation succeeded.
Atomic Add Quadword (__ATOMIC_ADD_QUAD)
The __ATOMIC_ADD_QUAD function adds the specified expression to the aligned quadword pointed to by the address parameter within a load-locked/store-conditional code sequence and returns the value of the quadword before the addition was performed.
This function has one of the following formats:
|
int __ATOMIC_ADD_QUAD (volatile void *address, int expression); int __ATOMIC_ADD_QUAD_RETRY (volatile void *address, int expression, int retry, int *status); |
address
The quadword-aligned address of the data segment.expression
An integer expression.retry
A retry count of type int that indicates the number of times the operation is attempted (which is at least once, even if the retry argument is 0). If the operation cannot be performed successfully in the specified number of retries, the function returns without updating the quadword.status
A pointer to an integer that is set to 0 if the operation did not succeed within the specified number of retries, and set to 1 if the operation succeeded.
Atomic AND Longword (__ATOMIC_AND_LONG)
The __ATOMIC_AND_LONG function performs a logical AND of the specified expression with the aligned longword pointed to by the address parameter within a load-locked/store-conditional code sequence and returns the value of the longword before the operation was performed.
This function has one of the following formats:
|
int __ATOMIC_AND_LONG (volatile void *address, int expression); int __ATOMIC_AND_LONG_RETRY (volatile void *address, int expression, int retry, int *status); |
address
The longword-aligned address of the data segment.expression
An integer expression.retry
A retry count of type int that indicates the number of times the operation is attempted (which is at least once, even if the retry argument is 0). If the operation cannot be performed successfully in the specified number of retries, the function returns without updating the longword.status
A pointer to an integer that is set to 0 if the operation did not succeed within the specified number of retries, and set to 1 if the operation succeeded.
Atomic AND Quadword (__ATOMIC_AND_QUAD)
The __ATOMIC_AND_QUAD function performs a logical AND of the specified expression with the aligned quadword pointed to by the address parameter within a load-locked/store-conditional code sequence and returns the value of the quadword before the operation was performed.
This function has one of the following formats:
|
int __ATOMIC_AND_QUAD (volatile void *address, int expression); int __ATOMIC_AND_QUAD_RETRY (volatile void *address, int expression, int retry, int *status); |
address
The quadword-aligned address of the data segment.expression
An integer expression.retry
A retry count of type int that indicates the number of times the operation is attempted (which is at least once, even if the retry argument is 0). If the operation cannot be performed successfully in the specified number of retries, the function returns without updating the quadword.status
A pointer to an integer that is set to 0 if the operation did not succeed within the specified number of retries, and set to 1 if the operation succeeded.
Atomic OR Longword (__ATOMIC_OR_LONG)
The __ATOMIC_OR_LONG function performs a logical OR of the specified expression with the aligned longword pointed to by the address parameter within a load-locked/store-conditional code sequence and returns the value of the longword before the operation was performed.
This function has one of the following formats:
|
int __ATOMIC_OR_LONG (volatile void *address, int expression); int __ATOMIC_OR_LONG_RETRY (volatile void *address, int expression, int retry, int *status); |
address
The longword-aligned address of the data segment.expression
An integer expression.retry
A retry count of type int that indicates the number of times the operation is attempted (which is at least once, even if the retry argument is 0). If the operation cannot be performed successfully in the specified number of retries, the function returns without updating the longword.status
A pointer to an integer that is set to 0 if the operation did not succeed within the specified number of retries, and set to 1 if the operation succeeded.
Atomic OR Quadword (__ATOMIC_OR_QUAD)
The __ATOMIC_OR_QUAD function performs a logical OR of the specified expression with the aligned quadword pointed to by the address parameter within a load-locked/store-conditional code sequence and returns the value of the quadword before the operation was performed.
This function has one of the following formats:
|
int __ATOMIC_OR_QUAD (volatile void *address, int expression); int __ATOMIC_OR_QUAD_RETRY (volatile void *address, int expression, int retry, int *status); |
address
The quadword-aligned address of the data segment.expression
An integer expression.retry
A retry count of type int that indicates the number of times the operation is attempted (which is at least once, even if the retry argument is 0). If the operation cannot be performed successfully in the specified number of retries, the function returns without updating the quadword.status
A pointer to an integer that is set to 0 if the operation did not succeed within the specified number of retries, and set to 1 if the operation succeeded.
Atomic Increment Longword (__ATOMIC_INCREMENT_LONG)
The __ATOMIC_INCREMENT_LONG function increments by 1 the aligned longword pointed to by the address parameter within a load-locked/store-conditional code sequence and returns the value of the longword before the operation was performed.
This function has the following format:
|
int __ATOMIC_INCREMENT_LONG (volatile void *address); |
address
The longword-aligned address of the data segment.
Atomic Increment Quadword (__ATOMIC_INCREMENT_QUAD)
The __ATOMIC_INCREMENT_QUAD function increments by 1 the aligned quadword pointed to by the address parameter within a load-locked/store-conditional code sequence and returns the value of the quadword before the operation was performed.
This function has the following format:
|
int __ATOMIC_INCREMENT_QUAD (volatile void *address); |
address
The quadword-aligned address of the data segment.
Atomic Decrement Longword (__ATOMIC_DECREMENT_LONG)
The __ATOMIC_DECREMENT_LONG function decrements by 1 the aligned longword pointed to by the address parameter within a load-locked/store-conditional code sequence and returns the value of the longword before the operation was performed.
This function has the following format:
|
int __ATOMIC_DECREMENT_LONG (volatile void *address); |
address
The longword-aligned address of the data segment.
Atomic Decrement Quadword (__ATOMIC_DECREMENT_QUAD)
The __ATOMIC_DECREMENT_QUAD function decrements by 1 the aligned quadword pointed to by the address parameter within a load-locked/store-conditional code sequence and returns the value of the quadword before the operation was performed.
This function has the following format:
|
int __ATOMIC_DECREMENT_QUAD (volatile void *address); |
address
The quadword-aligned address of the data segment.
Atomic Exchange Longword (__ATOMIC_EXCH_LONG)
The __ATOMIC_EXCH_LONG function stores the value of the specified expression into the aligned longword pointed to by the address parameter within a load-locked/store-conditional code sequence and returns the value of the longword before the operation was performed.
This function has one of the following formats:
|
int __ATOMIC_EXCH_LONG (volatile void *address, int expression); int __ATOMIC_EXCH_LONG_RETRY (volatile void *address, int expression, int retry, int *status); |
address
The longword-aligned address of the data segment.expression
An integer expression.retry
A retry count of type int that indicates the number of times the operation is attempted (which is at least once, even if the retry argument is 0). If the operation cannot be performed successfully in the specified number of retries, the function returns without updating the longword.status
A pointer to an integer that is set to 0 if the operation did not succeed within the specified number of retries, and set to 1 if the operation succeeded.
Atomic Exchange Quadword (__ATOMIC_EXCH_QUAD)
The __ATOMIC_EXCH_QUAD function stores the value of the specified expression into the aligned quadword pointed to by the address parameter within a load-locked/store-conditional code sequence and returns the value of the quadword before the operation was performed.
This function has one of the following formats:
|
int __ATOMIC_EXCH_QUAD (volatile void *address, int expression); int __ATOMIC_EXCH_QUAD_RETRY (volatile void *address, int expression, int retry, int *status); |
address
The quadword-aligned address of the data segment.expression
An integer expression.retry
A retry count of type int that indicates the number of times the operation is attempted (which is at least once, even if the retry argument is 0). If the operation cannot be performed successfully in the specified number of retries, the function returns without updating the quadword.status
A pointer to an integer that is set to 0 if the operation did not succeed within the specified number of retries, and set to 1 if the operation succeeded.
Allocate Bytes from Stack ( __ALLOCA)
The __ALLOCA function allocates n bytes from the stack.
This function has the following format:
|
void *__ALLOCA (unsigned int n); |
n
The number of bytes to be allocated.
A pointer to the allocated memory is returned.
Single-Precision, Floating-Point Arithmetic Built-in Functions
The following built-in functions provide single-precision, floating-point chopped arithmetic:
| __ADDF_C | __ADDS_C | __SUBF_C | __SUBS_C |
| __MULF_C | __MULS_C | __DIVF_C | __DIVS_C |
They have the following format:
|
float __op{F,S}_C (float operand1, float operand2); |
Where op is one of ADD, SUB, MUL, DIV, and {F,S} represents VAX or IEEE floating-point arithmetic.
The result of the arithmetic operation is returned.
Double-Precision, Floating-Point Arithmetic Built-in Functions
The following built-in functions provide double-precision, floating-point chopped arithmetic:
| __ADDG_C | __ADDT_C | __SUBG_C | __SUBT_C |
| __MULG_C | __MULT_C | __DIVG_C | __DIVT_C |
They have the following format:
|
double __op{G,T}_C (double operand1, double operand2); |
Where op is one of ADD, SUB, MUL, DIV, and {G,T} represents VAX or IEEE floating-point arithmetic.
The result of the arithmetic operation is returned.
Built-in functions are provided to copy selected portions of single- and double-precision, floating-point numbers.
These built-in functions have the following format:
|
float __CPYSF (float operand1, float operand2); double __CPYS (double operand1, double operand2); float __CPYSNF (float operand1, float operand2); double __CPYSN (double operand1, double operand2); float __CPYSEF (float operand1, float operand2); double __CPYSE (double operand1, double operand2); |
The copy sign built-in functions (__CPYSF and __CPYS) fetch the sign bit in operand1, concatenate it with the exponent and fraction bits from operand2, and return the result.
The copy sign negate built-in functions (__CPYSNF and __CPYSN) fetch the sign bit in operand1, complement it, concatenate it with the exponent and fraction bits from operand2, and return the result.
The copy sign exponent built-in functions (__CPYSEF and __CPYSE) fetch the sign and exponent bits from operand1, concatenate them with the fraction bits from operand2, and return the result.
Compare Store Longword ( __CMP_STORE_LONG)
The __CMP_STORE_LONG function has the following format:
|
int __CMP_STORE_LONG (void *source, int old_value, int new_value, void *dest); |
This function compares the value pointed to by source with the longword old_value. If they are equal, the longword new_value is stored into the value pointed to by dest.
The function returns 0 if the two values are unequal, and returns 1 if the two values are equal.
Compare Store Quadword ( __CMP_STORE_QUAD)
The __CMP_STORE_QUAD function has the following format:
|
int __CMP_STORE_QUAD (void *source, int64 old_value, int64 new_value, void *dest); |
This function compares the value pointed to by source with the quadword old_value. If they are equal, the quadword new_value is stored into the value pointed to by dest.
The function returns 0 if the two values are unequal, and returns 1 if the two values are equal.
The __COS built-in function is functionally equivalent to its counterpart, cos, in the standard header file <math.h>.
Its format is also the same:
|
#include <math.h> double __COS (double x); |
x
A radian value.
This built-in function does, however, offer performance improvements because there is less call overhead associated with its use.
If you include <math.h>, the built-in function is automatically used for all occurrences of cos. To disable the built-in function, use #undef cos.
Convert G_Floating to F_Floating Chopped ( __CVTGF_C)
The __CVTGF_C function converts a double-precision, VAX G_floating-point number to a single-precision, VAX F_floating-point number. This conversion chops to single-precision; then the 8-bit exponent range is checked for overflow or underflow.
This function has the following format:
|
float __CVTGF_C (double operand); |
operand
A double-precision, VAX floating-point number.
Convert G-Floating to Quadword ( __CVTGQ)
The __CVTGQ function rounds a double-precision, VAX floating-point number to a 64-bit integer value and returns the result.
This function has the following format:
|
int64 __CVTGQ (double operand); |
operand
A double-precision, VAX floating-point number.
Convert IEEE T_Floating to IEEE S_Floating Chopped ( __CVTTS_C)
The __CVTTS_C function converts a double-precision, IEEE T_floating-point number to a single-precision, IEEE S_floating-point number. This conversion chops to single-precision; then the 8-bit exponent range is checked for overflow or underflow.
This function has the following format:
|
float __CVTTS_C (double operand); |
operand
A double-precision, IEEE floating-point number.
Convert IEEE T-Floating to Quadword ( __CVTTQ)
The __CVTTQ function rounds a double-precision, IEEE-floating-point number to a 64-bit integer value and returns the result.
This function has the following format:
|
int64 __CVTTQ (double operand); |
operand
A double-precision, IEEE T-floating-point number.
Floating-Point Absolute Value ( __FABS)
The __FABS built-in function is functionally equivalent to its counterpart, fabs, in the standard header file <math.h>.
Its format is also the same:
|
#include <math.h> double __FABS (double x); |
x
A floating-point number.
This built-in function does, however, offer performance improvements because there is no call overhead associated with its use.
If you include <math.h>, the built-in function is automatically used for all occurrences of fab. To disable the built-in function, use #undef fab.
Longword Absolute Value ( __LABS)
The __LABS built-in function is functionally equivalent to its counterpart, labs, in the standard header file <stdlib.h>.
Its format is also the same:
|
#include <stdlib.h> long int __LABS (long int x); |
x
An integer.
This built-in function does, however, offer performance improvements because there is less call overhead associated with its use.
If you include <stdlib.h>, the built-in function is automatically used for all occurrences of labs. To disable the built-in function, use #undef labs.
The __MB function directs the compiler to generate a memory barrier instruction.
This function has the following format:
|
void __MB (void); |
Memory Copy and Set Functions ( __MEMCPY, __MEMMOVE, __MEMSET)
The __MEMCPY, __MEMMOVE, and __MEMSET built-in functions are functionally equivalent to their counterparts in the standard header file <string.h>.
Their format is also the same:
|
#include <string.h> void *__MEMCPY (void *s1, const void *s2, size_t size); void *__MEMMOVE (void *s1, const void *s2, size_t size); void *__MEMSET (void *s, int value, size_t size); |
These built-in functions do, however, offer performance improvements because there is less call overhead associated with their use.
If you include <string.h>, the built-in functions are automatically used for all occurrences of memcpy, memmove, and memset. To disable the built-in functions, use #undef memcpy, #undef memmove, and #undef memset.
Read Process Cycle Counter ( __RPCC)
The __RPCC function reads the current process cycle counter.
This function has the following format:
|
int64 __RPCC (void); |
The __SIN built-in function is functionally equivalent to its counterpart in the standard header file <math.h>.
Its format is also the same:
|
#include <math.h> double __SIN (double x); |
x
A radian value.
This built-in function does, however, offer performance improvements because there is less call overhead associated with its use.
If you include <math.h>, the built-in function is used automatically for all occurrences of sin. To disable the built-in function, use #undef sin.
Test for Bit Clear then Clear Bit Interlocked ( __TESTBITCCI)
The __TESTBITCCI function performs the following operations in interlocked fashion:
This function has the following format:
|
int __TESTBITCCI (void *address, int position, ...); |
address
The base address of the field.position
The position within the field of the bit that you want cleared....
An optional retry count of type int. If specified, the retry count indicates the number of times the operation is attempted. If the operation cannot be performed successfully in the specified number of retries, a value of 0 is returned.
Test for Bit Set then Set Bit Interlocked ( __TESTBITSSI)
The __TESTBITSSI function performs the following operations in interlocked fashion:
This function has the following format:
|
int __TESTBITSSI (void *address, int position, ...); |
address
The base address of the field.position
The position within the field of the bit that you want set....
An optional retry count of type int. If specified, the retry count indicates the number of times the operation is attempted. If the operation cannot be performed successfully in the specified number of retries, a value of 0 is returned.
Trap Barrier Instruction ( __TRAPB)
The __TRAPB function allows software to guarantee that, in a pipeline implementation, all previous arithmetic instructions will be completed without incurring any arithmetic traps before any instructions after the TRAPB instruction are issued.
This function has the following format:
|
void __TRAPB (void); |
Unsigned Quadword Multiply High ( __UMULH)
The __UMULH function performs a quadword multiply high instruction.
This function has the following format:
|
uint64 __UMULH (uint64 operand1, uint64 operand2); |
operand1
A 64-bit unsigned integer.operand2
A 64-bit unsigned integer.
The two operands are multiplied as unsigned integers to produce a 128-bit result. The high order 64-bits are returned. Note that uint64 is a typedef for the Compaq Tru64 UNIX data type unsigned __int64.
Other Builtins
int64 _popcnt(unsigned long);
Returns the number of "1" bits in the argument (0 to 64). For example, _popcnt(12) returns 2.int64 _poppar(unsigned long);
Returns "1" if the number of "1" bits in the argument is odd; otherwise, returns "0". otherwise. For example: _poppar(12) returns 0.int64 _leadz(unsigned long);
Returns the number of leading zeroes (starting at the most significant bit position) in the argument. For example, _leadz(1) returns 63. Note that _leadz(0) returns 64.int64 _trailz(unsigned long);
Returns the number of trailing zeroes (counting after the least significant set bit to the least significant bit position) in the argument: For example, _trailz(2) returns 1. Note that _trailz(0) returns 64.
| Previous | Next | Contents | Index |
|
