This appendix describes built-in functions available when you compile on OpenVMS Alpha systems. These functions allow you to directly access hardware and machine instructions.

Be sure to include the <builtins.h> header file in your source program to access these built-in functions.

DEC C++ for OpenVMS Alpha systems does not support the built-in functions available with DEC C++ for OpenVMS VAX systems. However, the <builtins.h> header file contains macro definitions that translate some VAX C built-in functions to the equivalent DEC C++ for OpenVMS Alpha built-in functions. Consequently, the following VAX C built-in functions are effectively supported:

_BBCCI(position, address) _BBSSI(position, address) _INSQHI(new_entry, head) _INSQTI(new_entry, head) _INSQUE(new_entry, predecessor) _REMQHI(head, removed_entry) _REMQTI(head, removed_entry) _REMQUE(entry, removed_entry) _PROBER(mode, length, address) _PROBEW(mode, length, address)

B.1 Privileged Architecture Library Code Instructions

The following Privileged Architecture Library Code (PALcode) instructions are available as built-in functions:

__PAL_GENTRAP __PAL_INSQHIL __PAL_REMQHIL __PAL_MTPR_ASTEN __PAL_MFPR_ASTEN __PAL_HALT __PAL_INSQTIL __PAL_REMQTIL __PAL_MTPR_ASTSR __PAL_MFPR_ASTSR __PAL_PROBER __PAL_INSQUEL __PAL_REMQUEL __PAL_MTPR_DATFX __PAL_MFPR_ESP __PAL_PROBEW __PAL_INSQHIQ __PAL_REMQHIQ __PAL_MTPR_ESP __PAL_MFPR_FEN __PAL_CHME __PAL_INSQTIQ __PAL_REMQTIQ __PAL_MTPR_FEN __PAL_MFPR_IPL __PAL_CHMK __PAL_INSQUEQ __PAL_REMQUEQ __PAL_MTPR_IPIR __PAL_MFPR_MCES __PAL_CHMS __PAL_INSQUEL_D __PAL_REMQUEL_D __PAL_MTPR_IPL __PAL_MFPR_PCBB __PAL_CHMU __PAL_INSQUEQ_D __PAL_REMQUEQ_D __PAL_MTPR_MCES __PAL_MFPR_PRBR __PAL_LDQP __PAL_INSQHILR __PAL_REMQHILR __PAL_MTPR_PRBR __PAL_MFPR_PTBR __PAL_STQP __PAL_INSQTILR __PAL_REMQTILR __PAL_MTPR_SCBB __PAL_MFPR_SCBB __PAL_BPT __PAL_INSQHIQR __PAL_REMQHIQR __PAL_MTPR_SIRR __PAL_MFPR_SISR __PAL_BUGCHK __PAL_INSQTIQR __PAL_REMQTIQR __PAL_MTPR_SSP __PAL_MFPR_SSP __PAL_CFLUSH __PAL_MTPR_TBIA __PAL_MFPR_TBCHK __PAL_DRAINA __PAL_MTPR_TBIAP __PAL_MFPR_USP __PAL_RD_PS __PAL_MTPR_TBIS __PAL_MFPR_VPTB __PAL_SWPCTX __PAL_MTPR_TBISD __PAL_MFPR_WHAMI __PAL_SWASTEN __PAL_MTPR_TBISI __PAL_WR_PS_SW __PAL_MTPR_USP __PAL_MTPR_VPTB

The following sections describe these PALcodes.

B.1.1 __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);

B.1.2 __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 (void);

B.1.3 __PAL_CFLUSH

This function flushes at least the entire physical page specified by the page frame number value from any data caches associated with the current processor. After a CFLUSH is done, the first subsequent load on the same processor to an arbitrary address in the target page is fetched from physical memory.

This function has the following format:

void __PAL_CFLUSH (int value);

value

A page frame number.

This function allows a process to change its mode to Executive in a controlled manner. The change in mode also results in a change of stack pointers: the old pointer is saved and the new pointer is loaded. Registers R2 to R7, PS, and PC are pushed onto the selected stack. The saved PC addresses the instruction following the CHME instruction.

This function has the following format:

void __PAL_CHME (void);

B.1.5 __PAL_CHMK

This function allows a process to change its mode to kernel in a controlled manner. The change in mode also results in a change of stack pointers: the old pointer is saved and the new pointer is loaded. Registers R2 to R7, PS, and PC are pushed onto the kernel stack. The saved PC addresses the instruction following the CHMK instruction.

This function has the following format:

void __PAL_CHMK (void);

B.1.6 __PAL_CHMS

This function allows a process to change its mode to Supervisor in a controlled manner. The change in mode also results in a change of stack pointers: the old pointer is saved and the new pointer is loaded. Registers R2 to R7, PS, and PC are pushed onto the selected stack. The saved PC addresses the instruction following the CHMS instruction.

This function has the following format:

void __PAL_CHMS (void);

B.1.7 __PAL_CHMU

This function allows a process to call a routine using the change mode mechanism. Registers R2 to R7, PS, and PC are pushed onto the current stack. The saved PC addresses the instruction following the CHMU instruction.

This function has the following format:

void __PAL_CHMU (void);

B.1.8 __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);

B.1.9 __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.

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

B.1.11 __PAL_INSQHIL

This function inserts an entry at the front of a longword queue in an indivisible manner. This operation is interlocked against similar operations by other preprocessors or devices in the system. This function must have write access to header and queue entries. The pointers to head and new_entry must not be equal.

This function has the following format:

int __PAL_INSQHIL (void *head, void *new_entry); /* At head, interlocked */

head

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

new_entry

A pointer to the new entry to be inserted. The entry must be aligned on a longword boundary.

There are three possible return values:

• --1 if the entry was not inserted because the secondary interlock failed
• 0 if the entry was inserted but it was not the only entry in the list
• 1 if the entry was inserted and it was the only entry in the list

This function inserts an entry into the front of a longword queue in an indivisible manner. This operation is interlocked against similar operations by other preprocessors or devices in the system. This function must have write access to the header and queue entries. The pointers to head and new_entry must not be equal. All parts of the queue must be memory resident.

This function has the following format:

int __PAL_INSQHILR (void *head, void *new_entry); /* At head, interlocked resident */

head

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

new_entry

A pointer to the new entry to be inserted. The entry must be aligned on a quadword boundary.

There are three possible return values:

• --1 if the entry was not inserted because the secondary interlock failed
• 0 if the entry was inserted but it was not the only entry in the list
• 1 if the entry was inserted and it was the only entry in the list

This function inserts an entry at the front of a quadword queue in an indivisible manner. This operation is interlocked against similar operations by other preprocessors or devices in the system. This function must have write access to header and queue entries. The pointers to head and new_entry must not be equal.

This function has the following format:

int __PAL_INSQHIQ (void *head, void *new_entry); /* At head, interlocked */

head

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

new_entry

A pointer to the new entry to be inserted. The entry must be aligned on an octaword boundary.

There are three possible return values:

• --1 if the entry was not inserted because the secondary interlock failed
• 0 if the entry was inserted but it was not the only entry in the list
• 1 if the entry was inserted and it was the only entry in the list

This function inserts an entry into the front of a quadword queue in an indivisible manner. This operation is interlocked against similar operations by other preprocessors or devices in the system. This function must have write access to the header and queue entries. The pointers to head and new_entry must not be equal. All parts of the queue must be memory resident.

This function has the following format:

int __PAL_INSQHIQR (void *head, void *new_entry); /* At head, interlocked resident */

head

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

new_entry

A pointer to the new entry to be inserted. The entry must be aligned on an octaword boundary.

There are three possible return values:

• --1 if the entry was not inserted because the secondary interlock failed
• 0 if the entry was inserted but it was not the only entry in the list
• 1 if the entry was inserted and it was the only entry in the list

This function inserts an entry at the end of a longword queue in an indivisible manner. This operation is interlocked against similar operations by other preprocessors or devices in the system. This function must have write access to header and queue entries. The pointers to head and new_entry must not be equal.

This function has the following format:

int __PAL_INSQTIL (void *head, void *new_entry); /* At tail, interlocked */

head

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

new_entry

A pointer to the new entry to be inserted. The entry must be aligned on a quadword boundary.

There are three possible return values:

• --1 if the entry was not inserted because the secondary interlock failed
• 0 if the entry was inserted but it was not the only entry in the list
• 1 if the entry was inserted and it was the only entry in the list

This function inserts an entry at the end of a longword queue in an indivisible manner. This operation is interlocked against similar operations by other preprocessors or devices in the system. This function must have write access to the header and queue entries. The pointers to head and new_entry must not be equal. All parts of the queue must be memory resident.

This function has the following format:

int __PAL_INSQTILR (void *head, void *new_entry); /* At tail, interlocked resident */

head

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

new_entry

A pointer to the new entry to be inserted. The entry must be aligned on a quadword boundary.

There are three possible return values:

• --1 if the entry was not inserted because the secondary interlock failed
• 0 if the entry was inserted but it was not the only entry in the list
• 1 if the entry was inserted and it was the only entry in the list

This function inserts an entry at the end of a quadword queue in an indivisible manner. This operation is interlocked against similar operations by other preprocessors or devices in the system. This function must have write access to header and queue entries. The pointers to head and new_entry must not be equal.

This function has the following format:

int __PAL_INSQTIQ (void *head, void *new_entry); /* At tail, interlocked */

head

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

new_entry

A pointer to the new entry to be inserted. The entry must be aligned on an octaword boundary.

There are three possible return values:

• --1 if the entry was not inserted because the secondary interlock failed
• 0 if the entry was inserted but it was not the only entry in the list
• 1 if the entry was inserted and it was the only entry in the list

This function inserts an entry at the end of a quadword queue in an indivisible manner. This operation is interlocked against similar operations by other preprocessors or devices in the system. This function must have write access to the header and queue entries. The pointers to head and new_entry must not be equal. All parts of the queue must be memory resident.

This function has the following format:

int __PAL_INSQTIQR (void *head, void *new_entry); /* At tail, interlocked resident */

head

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

new_entry

A pointer to the new entry to be inserted. The entry must be aligned on an octaword boundary.

There are three possible return values:

• --1 if the entry was not inserted because the secondary interlock failed
• 0 if the entry was inserted but it was not the only entry in the list
• 1 if the entry was inserted and it was the only entry in the list

This function inserts a new entry after an existing entry into a longword queue. This function must have write access to header and queue entries.

This function has the following format:

int __PAL_INSQUEL (void *predecessor, void *new_entry);

predecessor

A pointer to an existing entry in the queue.

new_entry

A pointer to the new entry to be inserted.

There are two possible return values:

• 0 if the entry was not the only entry in the queue
• 1 if the entry was the only entry in the queue

This function inserts a new entry after an existing entry into a longword queue deferred. This function must have write access to header and queue entries.

This function has the following format:

int __PAL_INSQUEL_D (void **predecessor, void *new_entry); /* Deferred */

predecessor

A pointer to a pointer to the predecessor entry.

new_entry

A pointer to the new entry to be inserted.

There are two possible return values:

• 0 if the entry was not the only entry in the queue
• 1 if the entry was the only entry in the queue

This function inserts a new entry after an existing entry into a quadword queue. This function must have write access to header and queue entries.

This function has the following format:

int __PAL_INSQUEQ (void *predecessor, void *new_entry);

predecessor

A pointer to an existing entry in the queue.

new_entry

A pointer to the new entry to be inserted.

There are two possible return values:

• 0 if the entry was not the only entry in the queue
• 1 if the entry was the only entry in the queue

This function inserts a new entry after an existing entry into a quadword queue deferred. This function must have write access to header and queue entries.

This function has the following format:

int __PAL_INSQUEQ_D (void **predecessor, void *new_entry); /* Deferred */

predecessor

A pointer to a pointer to the predecessor entry.

new_entry

A pointer to the new entry to be inserted.

There are two possible return values:

• 0 if the entry was not the only entry in the queue
• 1 if the entry was the only entry in the queue

This function returns the quadword-aligned memory object specified by address.

This function has the following format:

uint64 __PAL_LDQP (void *address);

address

A pointer to the quadword-aligned memory object to be returned.

If the object pointed to by address is not quadword-aligned, the result is unpredictable.

B.1.24 __PAL_MFPR_XXXX

These privileged functions return the contents of a particular processor register. The XXXX indicates the processor register to be read.

These functions have the following format:

unsigned int __PAL_MFPR_ASTEN (void); /* AST Enable */ unsigned int __PAL_MFPR_ASTSR (void); /* AST Summary Register */ void *__PAL_MFPR_ESP (void); /* Executive Stack Pointer */ int __PAL_MFPR_FEN (void); /* Floating-Point Enable */ int __PAL_MFPR_IPL (void); /* Interrupt Priority Level */ int __PAL_MFPR_MCES (void); /* Machine Check Error Summary */ void *__PAL_MFPR_PCBB (void); /* Privileged Context Block Base */ int64 __PAL_MFPR_PRBR (void); /* Processor Base Register */ int __PAL_MFPR_PTBR (void); /* Page Table Base Register */ void *__PAL_MFPR_SCBB (void); /* System Control Block Base */ unsigned int __PAL_MFPR_SISR (void); /* Software Interrupt Summary Register */ void *__PAL_MFPR_SSP (void); /* Supervisor Stack Pointer */ int64 __PAL_MFPR_TBCHK (void *address); /* Translation Buffer Check */ void *__PAL_MFPR_USP (void); /* User Stack Pointer */ void *__PAL_MFPR_VPTB (void); /* Virtual Page Table */ int64 __PAL_MFPR_WHAMI (void); /* Who Am I */

B.1.25 __PAL_MTPR_XXXX

These privileged functions load a value into one of the special processor registers. The XXXX indicates the processor register to be loaded.

These functions have the following format:

void __PAL_MTPR_ASTEN (unsigned int mask); /* AST Enable */ void __PAL_MTPR_ASTSR (unsigned int mask); /* AST Summary Register */ void __PAL_MTPR_DATFX (int value); /* Data Alignment Trap Fixup */ void __PAL_MTPR_ESP (void *address); /* Executive Stack Pointer */ void __PAL_MTPR_FEN (int value); /* Floating-Point Enable */ void __PAL_MTPR_IPIR (int64 number); /* Interprocessor Interrupt Request */ int __PAL_MTPR_IPL (int value); /* Interrupt Priority Level */ void __PAL_MTPR_MCES (int value); /* Machine Check Error Summary */ void __PAL_MTPR_PRBR (int64 value); /* Processor Base Register */ void __PAL_MTPR_SCBB (void *address); /* System Control Block Base */ void __PAL_MTPR_SIRR (int level); /* Software Interrupt Request Register */ void __PAL_MTPR_SSP (int *address); /* Supervisor Stack Pointer */ void __PAL_MTPR_TBIA (void); /* Translation Buffer Invalidate All*/ void __PAL_MTPR_TBIAP (void); /* Translation Buffer Invalidate All Process */ void __PAL_MTPR_TBIS (void *address); /* Translation Buffer Invalidate Single */ void __PAL_MTPR_TBISD (void *address); /* Translation Buffer Invalidate Single Data */ void __PAL_MTPR_TBISI (void *address); /* Translation Buffer Invalidate Single Instruction */ void __PAL_MTPR_USP (void *address); /* User Stack Pointer */ void __PAL_MTPR_VPTB (void *address); /* Virtual Page Table */

B.1.26 __PAL_PROBER

This function checks the write accessibility of the first and last byte of the given address and length pair.

This function has the following format:

int __PAL_PROBER (const void *base_address, int length, char mode);

base_address

The pointer to the memory segment to be tested for read access.

length

The length of the memory segment, in bytes.

mode

The processor mode used for checking access.

There are two possible return values:

• 0 if both bytes are not accessible
• 1 if both bytes are accessible

This function checks the write accessibility of the first and last byte of the given address and length pair.

This function has the following format:

int __PAL_PROBEW (const void *base_address, int length, char mode);

base_address

The pointer to the memory segment to be tested for write access.

length

The length of the memory segment, in bytes.

mode

The processor mode used for checking access.

There are two possible return values:

• 0 if both bytes are not accessible
• 1 if both bytes are accessible

This function returns the Processor Status (PS).

This function has the following format:

uint64 __PAL_RD_PS (void);

B.1.29 __PAL_REMQHIL

This function removes the first entry from a longword queue in an indivisible manner. This operation is interlocked against similar operations by other preprocessors 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_REMQHIL (void *head, void **removed_entry); /* At head, 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

This function removes the first entry from a longword queue in an indivisible manner. This operation is interlocked against similar operations by other preprocessors 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_REMQHILR (void *head, void **removed_entry); /* At head, 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

This function removes the first entry from a quadword queue in an indivisible manner. This operation is interlocked against similar operations by other preprocessors 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_REMQHIQ (void *head, void **removed_entry); /* At head, 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

This function removes the first entry from a quadword queue in an indivisible manner. This operation is interlocked against similar operations by other preprocessors 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

This function removes the last entry from a longword queue in an indivisible manner. This operation is interlocked against similar operations by other preprocessors 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

This function removes the last entry from a longword queue in an indivisible manner. This operation is interlocked against similar operations by other preprocessors 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

This function removes the last entry from a quadword queue in an indivisible manner. This operation is interlocked against similar operations by other preprocessors 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

This function removes the last entry from a quadword queue in an indivisible manner. This operation is interlocked against similar operations by other preprocessors 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

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

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

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

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

This function writes the quadword value to the memory location pointed to by address.

This function has the following format:

void __PAL_STQP (void *address, uint64 value);

address

Memory location to be written to.

value

Quadword value to be stored.

If the location pointed to by address is not quadword-aligned, the result is unpredictable.

B.1.42 __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.

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.

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

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 .

B.3 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).

B.4 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 (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.

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

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

B.7 AND Atomic Quadword ( __AND_ATOMIC_QUAD)

The __AND_ATOMIC_QUAD function performs a logical AND of the specified expression with 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 __AND_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.

B.8 OR Atomic Longword ( __OR_ATOMIC_LONG)

The __OR_ATOMIC_LONG function performs a logical OR 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 __OR_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.

B.9 OR Atomic Quadword ( __OR_ATOMIC_QUAD)

The __OR_ATOMIC_QUAD function performs a logical OR of the specified expression with 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 __OR_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.

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

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

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

B.13 Copy Sign Built-in Functions

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.

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

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

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

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

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.

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.

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.

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 .

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

B.23 Memory Barrier ( __MB)

The __MB function directs the compiler to generate a memory barrier instruction.

This function has the following format:

void __MB (void);

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

B.25 Read Process Cycle Counter ( __RPCC)

The __RPCC function reads the current process cycle counter.

This function has the following format:

int64 __RPCC (void);

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

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

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.

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

B.30 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 OpenVMS Alpha data type unsigned __int64 .