HP C
User's Guide for OpenVMS Systems

6.2.2.36 Conditional Atomic Compare and Exchange Quadword (__CMP_SWAP_QUAD)

The __CMP_SWAP_QUAD function performs a conditional atomic compare and exchange operation on a quadword. The quadword pointed to by source is read and compared with the quadword old_value. If they are equal, the quadword new_value is written into the quadword pointed to by source. The read and write is performed atomically, with no intervening access to the same memory region.

The function returns 1 if the write occurs, and 0 otherwise.

This function has the following format:

int __CMP_SWAP_QUAD (volatile void *source, int old_value, int new_value);

source

The quadword value to be compared with old_value.

old_value

The quadword value source is compared with.

new_value

The quadword value written to source if source and old_value are equal.

6.2.2.37 Conditional Atomic Compare and Exchange Longword with Acquire Semantics ( __CMP_SWAP_LONG_ACQ)

The __CMP_SWAP_LONG_ACQ function performs a conditional atomic compare and exchange operation with acquire semantics on a longword. The longword pointed to by source is read and compared with the longword old_value. If they are equal, the longword new_value is written into the longword pointed to by source. The read and write is performed atomically, with no intervening access to the same memory region.

Acquire memory ordering guarantees that the memory read/write is made visible before all subsequent data accesses to the same memory location by other processors.

The function returns 1 if the write occurs, and 0 otherwise.

This function has the following format:

int __CMP_SWAP_LONG_ACQ (volatile void *source, int old_value, int new_value);

source

The longword value to be compared with old_value.

old_value

The longword value source is compared with.

new_value

The longword value written into source if source and old_value are equal.

6.2.2.38 Conditional Atomic Compare and Exchange Quadword with Acquire Semantics ( __CMP_SWAP_QUAD_ACQ)

The __CMP_SWAP_QUAD_ACQ function performs a conditional atomic compare and exchange operation with acquire semantics on a quadword. The quadword pointed to by source is read and compared with the quadword old_value. If they are equal, the quadword new_value is written into the quadword pointed to by source. The read and write is performed atomically, with no intervening access to the same memory region.

Acquire memory ordering guarantees that the memory read/write is made visible before all subsequent memory data accesses to the same memory location by other processors.

The function returns 1 if the write occurs, and 0 otherwise.

This function has the following format:

int __CMP_SWAP_QUAD_ACQ (volatile void *source, int old_value, int new_value);

source

The quadword value to be compared with old_value.

old_value

The quadword value source is compared with.

new_value

The quadword value written into source if source and old_value are equal.

6.2.2.39 Conditional Atomic Compare and Exchange Longword with Release Semantics ( __CMP_SWAP_LONG_REL)

The __CMP_SWAP_LONG_REL function performs a conditional atomic compare and exchange operation with release semantics on a longword. The longword pointed to by source is read and compared with the longword old_value. If they are equal, the longword new_value is written into the longword pointed to by source. The read and write is performed atomically, with no intervening access to the same memory region.

Release memory ordering guarantees that the memory read/write is made visible after all previous data memory acceses to the same memory location by other processors.

The function returns 1 if the write occurs, and 0 otherwise.

This function has the following format:

int __CMP_SWAP_LONG_REL (volatile void *source, int old_value, int new_value);

source

The longword value to be compared with old_value.

old_value

The longword value source is compared with.

new_value

The longword value written into source if source and old_value are equal.

6.2.2.40 Conditional Atomic Compare and Exchange Quadword with Release Semantics ( __CMP_SWAP_QUAD_REL)

The __CMP_SWAP_QUAD_REL function performs a conditional atomic compare and exchange operation with release semantics on a quadword. The quadword pointed to by source is read and compared with the quadword old_value. If they are equal, the quadword new_value is written into the quadword pointed to by source. The read and write is performed atomically, with no intervening access to the same memory region.

Release memory ordering guarantees that the memory read/write is made visible after all previous data memory acceses to the same memory location by other processors.

The function returns 1 if the write occurs, and 0 otherwise.

This function has the following format:

int __CMP_SWAP_QUAD_REL (volatile void *source, int old_value, int new_value);

source

The quadword value to be compared with old_value.

old_value

The quadword value source is compared with.

new_value

The quadword value written into source if source and old_value are equal.

6.2.2.41 Return Address ( __RETURN_ADDRESS)

The __RETURN_ADDRESS function produces the address to which the function containing the built-in call will return as a 64-bit integer (on Alpha systems, the value of R26 on entry to the function; on I64 systems, the value of B0 on entry to the function).

This built-in function cannot be used within a function specified to use nonstandard linkage.

This function has the following format:

__int64 __RETURN_ADDRESS (void);

6.2.2.42 Implement Alpha __PAL_GENTRAP and __PAL_BUGCHK Builtins (__break2)

The __break2 function is used to implement the Alpha __PAL_GENTRAP and __PAL_BUGCHK built-in functions on OpenVMS I64 systems.

The __break2 function is equivalent to the __break function with the second parameter passed in general register 17:

R17 = __R17_value; __break (__break_code);

This function has the following format:

void __break2 (__Integer_Constant __break_code, unsigned __int64 __r17_value);

__breakcode

The particular software condition that has occurred.

__r17_value

The value of R17, a volatile general register reserved by the OpenVMS Itanium calling standard for use by compiled code to communicate with specialized compiler support routines that require out-of-band information passing.

6.2.2.43 Flush Register Stack ( __flushrs)

The __flushrs function flushes the register stack.

This function has the following format:

void __flushrs (void);

6.2.2.44 Load Register Stack ( __loadrs)

The __loadrs function loads the register stack.

This function has the following format:

void __loadrs (void);

6.2.2.45 Probe Read-Access Permission ( __prober)

The __prober function determines whether read access to the virtual address specified by __address bits {60:0} and the region register indexed by __address bits {63:61} is permitted at the privilege level given by __mode bits {1:0}. It returns 1 if the access is permitted, and 0 otherwise.

This function can probe only with equal or lower privilege levels. If the specified privilege level is higher (lower number), then the probe is performed with the current privilege level.

This function is the same as the Intel __probe_r function.

This function has the following format:

int __prober (__int64 __address, unsigned int __mode);

__address

Virtual address for which read-access permission is being checked.

__mode

Privilege level for which read-access permission is being checked.

6.2.2.46 Probe Write-Access Permission ( __probew)

The __probew function determines whether write access to the virtual address specified by __address bits {60:0} and the region register indexed by __address bits {63:61}, is permitted at the privilege level given by __mode bits {1:0}. It returns 1 if the access is permitted, and 0 otherwise.

This function can probe only with equal or lower privilege levels. If the specified privilege level is higher (lower number), then the probe is performed with the current privilege level.

This function is the same as the Intel __probe_w function.

This function has the following format:

int __probew (__int64 __address, unsigned int __mode);

__address

Virtual address for which write-access permission is being checked.

__mode

Privilege level for which write-access permission is being checked.

6.2.2.47 Translation Access Key ( __tak)

The __tak function returns the translation access key.

This function has the following format:

unsigned int __tak (__int64 __address);

__address

Virtual address for translation key is being returned.

6.2.2.48 Translate to Physical Address ( __tpa)

The __tpa function translates a virtual address to a physical address.

This function has the following format:

__int64 __tpa(__int64 __address);

__address

Virtual address to be translated.

6.2.3 Built-In Functions for OpenVMS VAX Systems (VAX ONLY)

The following sections describe the HP C built-in functions available on OpenVMS VAX systems.

The HP C built-in functions use enumerated typedefs to define possible return values. We recommend that you use the enumerated types to store and compare return values.

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

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

The _ADAWI function has the following format:

typedef enum { _adawi_sum_neg=--1, _adawi_sum_zero, _adawi_sum_pos} _ADAWI_STATUS; _ADAWI_STATUS _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 or __align storage-class modifier.)

There are three possible return values:

• adawi_sum_neg (--1) if the sum when considered to be a signed number is negative
• adawi_sum_zero (0) if the sum is 0
• adawi_sum_pos (1) if the sum is positive

6.2.3.3 Branch on Bit Clear-Clear Interlocked ( _BBCCI)

The _BBCCI function performs the following functions in interlocked fashion:

• Returns the complement of the bit specified by the two arguments
• Clears the bit specified by the two arguments

The _BBCCI function has the following format:

typedef enum { _bbcci_oldval_1, _bbcci_oldval_0} _BBCCI_STATUS; _BBCCI_STATUS _BBCCI (int __position, void *__address);

__position

The position of the bit within the field.

__address

The base address of the field.

The return value of _bbcci_oldval_1 (0) or _bbcci_oldval_0 (1) is the complement of the value of the specified bit before being cleared.

6.2.3.4 Branch on Bit Set-Set Interlocked ( _BBSSI)

The _BBSSI function performs the following functions in interlocked fashion:

• Returns the status of the bit specified by the two arguments
• Sets the bit specified by the two arguments

The _BBSSI function has the following format:

typedef enum { _bbssi_oldval_0, _bbcci_oldval_1} _BBSSI_STATUS; _BBSSI_STATUS _BBSSI (int __position, void *__address);

__position

The position of the bit within the field.

__address

The base address of the field.

The return value of _bbssi_oldval_0 (0) or _bbssi_oldval_1 (1) is the value of the specified bit before being set.

6.2.3.5 Find First Clear Bit ( _FFC)

The _FFC function finds the position of the first clear bit in a field. The bits are tested for clear status starting at bit 0 and extending to the highest bit in the field.

The _FFC function has the following format:

typedef enum { _ff_bit_not_found, _ff_bit_found} _FF_STATUS; _FF_STATUS _FFC (int __start, char __size, const void *__base, int *__position);

__start

The start position of the field.

__size

The size of the field, in bits. The size must be a value from 0 to 32 bits.

__base

The address of the field.

__position

The address of an integer to receive the position of the clear bit. If no bit is clear, the integer is set to the position of the first bit past the last bit tested.

There are two possible return values:

• _ff_bit_not_found (0) if all bits in the field are set
• _ff_bit_found (1) if a bit with value 0 is found

6.2.3.6 Find First Set Bit ( _FFS)

The _FFS function finds the position of the first set bit in a field. The bits are tested for set status starting at bit 0 and extending to the highest bit in the field.

The _FFS function has the following format:

typedef enum { _ff_bit_not_found, _ff_bit_found} _FF_STATUS; _FF_STATUS _FFS (int __start, char __size, const void *__base, int *__position);

__start

The start position of the field.

__size

The size of the field, in bits. The size must be a value from 0 to 32 bits.

__base

The address of the field.

__position

The address of an integer to receive the position of the set bit. If no bit is set, the integer is set to the position of the first bit past the last bit tested.

There are two possible return values:

• _ff_bit_not_found (0) if all bits in the field are clear
• _ff_bit_found (1) if a bit with value 1 is found

6.2.3.7 Halt ( _HALT)

The _HALT function halts the processor when executed by a process running in kernel mode. This is a privileged function.

The _HALT function has the following format:

void _HALT (void);

6.2.3.8 Insert Entry into Queue at Head Interlocked ( _INSQHI)

The _INSQHI function inserts an entry into the front of a queue in an indivisible manner. This operation is interlocked against similar operations by other processors or devices in the system.

The _INSQHI function has the following format:

typedef enum {_insqi_inserted_many, _insqi_not_inserted, _insqi_inserted_only} _INSQI_STATUS; _INSQI_STATUS _INSQHI (void *__new_entry, void *__head);

__new_entry

A pointer to the new entry to be inserted. The entry must be aligned on a quadword boundary. (You can achieve alignment using the _align or __align storage-class modifier.)

__head

A pointer to the queue header. The header must be aligned on a quadword boundary. (You can achieve alignment using the _align or __align storage-class modifier.)

There are three possible return values:

• _insqi_inserted_many (0) if the entry was inserted, but it was not the only entry in the list
• _insqi_not_inserted (1) if the entry was not inserted because the secondary interlock failed
• _insqi_inserted_only (2) if the entry was inserted and it was the only entry in the list

6.2.3.9 Insert Entry into Queue at Tail Interlocked ( _INSQTI)

The _INSQTI function inserts an entry at the end of a queue in an indivisible manner. This operation is interlocked against similar operations by other processors or devices in the system.

The _INSQTI function has the following format:

typedef enum {_insqi_inserted_many, _insqi_not_inserted, _insqi_inserted_only} _INSQI_STATUS; _INSQI_STATUS _INSQTI (void *__new_entry, void *__head);

__new_entry

A pointer to the new entry to be inserted. The entry must be aligned on a quadword boundary. (You can achieve alignment using the _align or __align storage-class modifier.)

__head

A pointer to the queue header. The header must be aligned on a quadword boundary. (You can achieve alignment using the _align or __align storage-class modifier.)

There are three possible return values:

• _insqi_inserted_many (0) if the entry was inserted, but it was not the only entry in the list
• _insqi_not_inserted (1) if the entry was not inserted because the secondary interlock failed
• _insqi_inserted_only (2) if the entry was inserted and it was the only entry in the list

6.2.3.10 Insert Entry in Queue ( _INSQUE)

The _INSQUE function inserts a new entry into a queue following an existing entry.

The _INSQUE function has the following format:

typedef enum { _insque_inserted_only, _insque_inserted_many} _INSQUE_STATUS; _INSQUE_STATUS _INSQUE (void *__new_entry, void *__predecessor);

__new_entry

A pointer to the new entry to be inserted.

__predecessor

A pointer to an existing entry in the queue.

There are two possible return values:

• _insque_inserted_only (0) if the entry was the only entry in the queue
• _insque_inserted_many (1) if the entry was not the only entry in the queue