HP C++ User Documentation

HP C++Using HP C++ for Tru64 UNIX and Linux
Alpha

Appendix BBuilt-In Functions

This appendix describes built-in functions available when you compile
on HP Tru64 UNIX and Linux Alpha 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
.

Translation Macros

Compaq C++ supports the following translation macros for built-in
functions:

Like builtin-functions, ASMs are implemented with a function-call
syntax. But unlike built-in functions, to use ASMs you must include the
<c_asm.h>
header file containing prototypes for the three types of ASMs, and the
#pragma intrinsic
preprocessor directive.

An instruction_operand is generally recognized as an assembly language
instruction separated by whitespace from a sequence of comma-separated
operands.

You can code multiple instruction sequences into one literal string,
separating them by semicolons.

Because adjacent string literals are concatenated into a single string,
successive instructions can be written as separate strings, one per
line (as is normally done in assembly language) as long as each
instruction is terminated by a semicolon (as shown in the examples).

There are semantic and syntax rules associated with ASMs: The first
argument to an ASM call is interpreted as the instructions to be
assembled in the metalanguage, and must be fully understood by the
compiler at compile time. Therefore, it must be a literal string (or a
macro expanding to a literal string) and must not be a run-time value
containing a string. Therefore, the following are not allowed:
indirections, table lookups, structure dereferences, and so on. The
remaining arguments are loaded into the argument registers like normal
function arguments, except that the second argument to the ASM
call is treated as the first argument for purposes of the
calling standard. For example, in the following test, the six
arguments are loaded into arg registers a0 through a5, and the result
of each subexpression is stored in the value return register v0. Since
v0 is the calling standard's return value register (R0 for an integer
function), the result of the final MULQ is the value returned by the
"call":

The following example does not work. There is no value loaded into
the floating-point return register. Furthermore, it results in a
compile-time warning stating that r2 is used before it is set, because
the arguments are loaded into the arg registers and not into r2:

z = fasm("mulq %r2, %a1 %r5", x=10, y=5);

The correct way of doing this is to specify an argument register
number in place of r2. A correct version of the above would be:

Note that the memory location used for the transfer from integer to
floating-point register is made available to the asm code by passing as
an argument the address of a variable allocated in the C code for that
purpose.

A return register must be specified in the metalanguage for the
result to appear in the expected place.

For intructions that do not take any argument and do not have a
return type, leave out the arguments. For example:

asm("MB");

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

__PAL_BPT

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);

__PAL_BUGCHK

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);

__PAL_DRAINA

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);

__PAL_GENTRAP

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.

__PAL_HALT

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);

Absolute Value ( __ABS)

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 __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 bit-wise or arithmetic 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 bit-wise or arithmetic 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.

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.

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 bit-wise or arithmetic 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.

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 bit-wise or arithmetic 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.

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 bit-wise or arithmetic 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.

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 bit-wise or arithmetic 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.

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.

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.

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.

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.

Cosine ( __COS)

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
.

Memory Barrier ( __MB)

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>
.

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);

Sine ( __SIN)

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 <stdlib.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:

Returns the complement of the specified bit before being cleared

Clears the bit

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:

Returns the value of the specified bit before being set

Sets the bit

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 HP Tru64 UNIX and Linux Alpha 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.