DEC C
User's Guide for OpenVMS Systems

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 */

6.2.1.68 __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); /* User Stack Pointer */ 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 */

6.2.1.69 __PAL_PROBER

This function checks the read 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 one or 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 one or 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);

6.2.1.72 __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 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_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 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_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 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_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 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

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

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

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

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

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 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 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 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 __RPCC function reads the current process cycle counter.

This function has the following format:

uint64 __RPCC (void);

6.2.1.88 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.89 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.90 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 one of 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.