HP C
User's Guide for OpenVMS Systems

6.2.1.76 __PAL_REMQHIQR

This function removes the first entry from a quadword queue in an indivisible manner. This operation is interlocked against similar operations by other processors or devices in the system. This function must have write access to the header and queue entries. All parts of the queue must be memory resident.

This function has the following format:

int __PAL_REMQHIQR (void *head, void **removed_entry); /* At head, interlocked resident */

head

A pointer to the queue header. The header must be aligned on an octaword boundary.

removed_entry

A pointer to the address of the entry removed from the queue.

There are four possible return values:

• --1 if the entry cannot be removed because the secondary interlock failed
• 0 if the queue was empty
• 1 if the entry was removed and the queue has remaining entries
• 2 if the entry was removed and the queue is now empty

6.2.1.77 __PAL_REMQTIL

This function removes the last entry from a longword queue in an indivisible manner. This operation is interlocked against similar operations by other processors or devices in the system. This function must have write access to the header and queue entries.

This function has the following format:

int __PAL_REMQTIL (void *head, void **removed_entry); /* At tail, interlocked */

head

A pointer to the queue header. The header must be aligned on a quadword boundary.

removed_entry

A pointer to the address of the entry removed from the queue.

There are four possible return values:

• --1 if the entry cannot be removed because the secondary interlock failed
• 0 if the queue was empty
• 1 if the entry was removed and the queue has remaining entries
• 2 if the entry was removed and the queue is now empty

6.2.1.78 __PAL_REMQTILR

This function removes the last entry from a longword queue in an indivisible manner. This operation is interlocked against similar operations by other processors or devices in the system. This function must have write access to the header and queue entries. All parts of the queue must be memory resident.

This function has the following format:

int __PAL_REMQTILR (void *head, void **removed_entry); /* At tail, interlocked resident */

head

A pointer to the queue header. The header must be aligned on a quadword boundary.

removed_entry

A pointer to the address of the entry removed from the queue.

There are four possible return values:

• --1 if the entry cannot be removed because the secondary interlock failed
• 0 if the queue was empty
• 1 if the entry was removed and the queue has remaining entries
• 2 if the entry was removed and the queue is now empty

6.2.1.79 __PAL_REMQTIQ

This function removes the last entry from a quadword queue in an indivisible manner. This operation is interlocked against similar operations by other processors or devices in the system. This function must have write access to the header and queue entries.

This function has the following format:

int __PAL_REMQTIQ (void *head, void **removed_entry); /* At tail, interlocked */

head

A pointer to the queue header. The header must be aligned on an octaword boundary.

removed_entry

A pointer to the address of the entry removed from the queue.

There are four possible return values:

• --1 if the entry cannot be removed because the secondary interlock failed
• 0 if the queue was empty
• 1 if the entry was removed and the queue has remaining entries
• 2 if the entry was removed and the queue is now empty

6.2.1.80 __PAL_REMQTIQR

This function removes the last entry from a quadword queue in an indivisible manner. This operation is interlocked against similar operations by other processors or devices in the system. This function must have write access to the header and queue entries. All parts of the queue must be memory resident.

This function has the following format:

int __PAL_REMQTIQR (void *head, void **removed_entry); /* At tail, interlocked resident */

head

A pointer to the queue header. The header must be aligned on an octaword boundary.

removed_entry

A pointer to the address of the entry removed from the queue.

There are four possible return values:

• --1 if the entry cannot be removed because the secondary interlock failed
• 0 if the queue was empty
• 1 if the entry was removed and the queue has remaining entries
• 2 if the entry was removed and the queue is now empty

6.2.1.81 __PAL_REMQUEL

This function removes an entry from a longword queue. This function must have write access to header and queue entries.

This function has the following format:

int _PAL_REMQUEL (void *entry, void **removed_entry);

entry

A pointer to the queue entry to be removed.

removed_entry

A pointer to the address of the entry removed from the queue.

There are three possible return values:

• --1 if the queue was empty
• 0 if the entry was removed and the queue is now empty
• 1 if the entry was removed and the queue has remaining entries

6.2.1.82 __PAL_REMQUEL_D

This function removes an entry from a longword queue deferred. This function must have write access to header and queue entries.

This function has the following format:

int __PAL_REMQUEL_D (void **entry, void **removed_entry); /* Deferred */

entry

A pointer to a pointer to the queue entry to be removed.

removed_entry

A pointer to the address of the entry removed from the queue.

There are three possible return values:

• --1 if the queue was empty
• 0 if the entry was removed and the queue is now empty
• 1 if the entry was removed and the queue has remaining entries

6.2.1.83 __PAL_REMQUEQ

This function removes an entry from a quadword queue. This function must have write access to header and queue entries.

This function has the following format:

int __PAL_REMQUEQ (void *entry, void **removed_entry);

entry

A pointer to the queue entry to be removed.

removed_entry

A pointer to the address of the entry removed from the queue.

There are three possible return values:

• --1 if the queue was empty
• 0 if the entry was removed and the queue is now empty
• 1 if the entry was removed and the queue has remaining entries

6.2.1.84 __PAL_REMQUEQ_D

This function removes an entry from a quadword queue deferred. This function must have write access to header and queue entries.

This function has the following format:

int __PAL_REMQUEQ_D (void **entry, void **removed_entry); /* Deferred */

entry

A pointer to a pointer to the queue entry to be removed.

removed_entry

A pointer to the address of the entry removed from the queue.

There are three possible return values:

• --1 if the queue was empty
• 0 if the entry was removed and the queue is now empty
• 1 if the entry was removed and the queue has remaining entries

6.2.1.85 __PAL_SWPCTX

This function returns ownership of the data structure that contains the current hardware privileged context (the HWPCB) to the operating system and passes ownership of the new HWPCB to the processor.

This function has the following format:

void __PAL_SWPCTX (void *address);

address

A pointer to the new HWPCB.

6.2.1.86 __PAL_SWASTEN

This function swaps the previous state of the Asynchronous System Trap (AST) enable bit for the new state. The new state is supplied in bit 0 of new_state_mask. The previous state is returned, zero-extended.

A check is made to determine if an AST is pending. If the enabling conditions are present for an AST at the completion of this instruction, the AST occurs before the next instruction.

This function has the following format:

unsigned int __PAL_SWASTEN (int new_state_mask);

new_state_mask

An integer whose 0 bit is the new state of the AST enable bit.

6.2.1.87 __PAL_WR_PS_SW

This function writes the low-order three bits of mask into the Processor Status software field (PS<SW>).

This function has the following format:

void __PAL_WR_PS_SW (int mask);

mask

An integer whose low-order three bits are written into PS<SW>.

6.2.1.88 _popcnt

The _popcnt built-in function returns the number of "1" bits (0 to 64) in its argument. For example, _popcnt(12) returns 2.

This function has the following format:

int64 _popcnt (unsigned int64);

6.2.1.89 _poppar

The _poppar built-in function returns 1 if the number of "1" bits in its argument is odd; otherwise it returns 0. For example, _poppar(12) returns 0.

This function has the following format:

int64 _poppar (unsigned int64);

6.2.1.90 Read Process Cycle Counter ( __RPCC)

The __RPCC function reads the current process cycle counter.

This function has the following format:

uint64 __RPCC (void);

6.2.1.91 Sine ( __SIN)

The __SIN built-in is functionally equivalent to its counterpart, sin , 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 offers performance improvements because there is less call overhead associated with its use.

If you include <math.h> , the built-in is automatically used for all occurrences of sin . To disable the built-in, use #undef sin .

6.2.1.92 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, respectively.

The result of the arithmetic operation is returned.

6.2.1.93 Test for Bit Clear then Clear Bit Interlocked (__INTERLOCKED_TESTBITCC_QUAD)

The __INTERLOCKED_TESTBITCC_QUAD function performs the following functions in interlocked fashion:

1. Returns the complement of the specified bit before being cleared.
2. Clears the bit.

This function has the following formats:

int __INTERLOCKED_TESTBITCC_QUAD (volatile void *address, int bit_position); int __INTERLOCKED_TESTBITCC_QUAD_RETRY (volatile void *address, int bit_position, int retry, int *status);

address

The quadword-aligned base address of the bit field.

bit_position

The position within the field of the bit that you want cleared, in the range of 0 to 63.

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.

6.2.1.94 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 (which will be at least once, even if the count argument is 0).

6.2.1.95 Test for Bit Set Then Set Bit Interlocked (__INTERLOCKED_TESTBITSS_QUAD)

The __INTERLOCKED_TESTBITSS_QUAD function performs the following functions in interlocked fashion:

1. Returns the value of the specified bit before being set.
2. Sets the bit.

This function has the following formats:

int __INTERLOCKED_TESTBITSS_QUAD (volatile void *address, int bit_position); int __INTERLOCKED_TESTBITSS_QUAD_RETRY (volatile void *address, int expression, int retry, int *status);

address

The quadword-aligned base address of the bit field.

bit_position

The position within the field of the bit that you want cleared, in the range of 0 to 63.

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.

6.2.1.96 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 (which will be at least once, even if the count argument is 0).

6.2.1.97 _trailz

The _trailz built-in function returns the number of trailing zeros (counting after the least significant set bit to the least significant bit position) in its argument. For example, _trailz(2) returns 1, and _trailz(0) returns 64.

This function has the following format:

int64 _trailz (unsigned int64);

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

6.2.1.99 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 Alpha data type unsigned __int64 .

6.2.2 Built-In Functions for I64 Systems (I64 ONLY)

The HP C built-in functions available on OpenVMS Alpha systems are also available on I64 systems, with some differences, as described in this section. This section also describes built-in functions that are specific to I64 systems.

6.2.2.1 Builtin Differences on I64 Systems

The <builtins.h> header file contains comments noting which built-in functions are not available or are not the preferred form for I64 systems. The compiler issues diagnostics where using a different built-in function for I64 systems would be preferable.

Here is a summary of these differences on I64 systems:

• There is no support for the asm , fasm , and dasm intrinsics (declared in the <c_asm.h> header file).
• The functionality provided by the special-case treatment of R26 in an Alpha system asm , as in asm("MOV R26,R0") , is provided by a new built-in function for I64 systems:

  __int64 __RETURN_ADDRESS(void);

  
  This built-in function produces the address to which the function containing the built-in call will return (the value of R26 on entry to the function on Alpha systems; the value of B0 on entry to the function on I64 systems). This built-in function cannot be used within a function specified to use nonstandard linkage.

• The only PAL function calls implemented as built-in functions within the compiler are the 24 queue-manipulation builtins. The queue manipulation builtins generate calls to new OpenVMS system services SYS$<name>, where <name> is the name of the builtin with the leading underscores removed.
  Any other OpenVMS PAL calls are supported through macros defined in the <pal_builtins.h> header file included in the <builtins.h> header file. Typically, the macros in <pal_builtins.h> transform an invocation of an Alpha system builtin into a call to a system service that performs the equivalent function on an I64 system. Two notable exceptions are __PAL_GENTRAP and __PAL_BUGCHK, which instead invoke the I64 specific compiler builtin __break2.
• There is no support for the various floating-point built-in functions used by the OpenVMS math library (for example, operations with chopped rounding and conversions).
• For most built-in functions that take a retry count, the compiler issues a warning message, evaluates the count for possible side effects, ignores it, and then invokes the same function without a retry count. This is necessary because the retry behavior allowed by Alpha load-locked/store-conditional sequences does not exist on I64 systems. There are two exceptions to this: __LOCK_LONG_RETRY and __ACQUIRE_SEM_LONG_RETRY; in these cases, the retry behavior involves comparisons of data values, not just load-locked/store-conditional.
• The __CMP_STORE_LONG and __CMP_STORE_QUAD built-in functions produce either a warning or an error, depending on whether or not the compiler can determine if the source and destination addresses are identical. If the addresses are identical, the compiler treats the builtin as the new __CMP_SWAP_ form and issues a warning. Otherwise it is an error.