builtins.h - Header file declaring functions that are
unconditionally intrinsic.
#include <builtins.h>
A builtin is a function whose name is specially recognized
by the compiler and is similar to declaring the function
to be intrinsic. Intrinsic functions are functions for
which the C compiler generates optimized code in certain
situations possibly avoiding a function call. While
intrinsic functions can have their special treatment
enabled or disabled by pragmas, builtin functions are
always treated specially and always have names in the
reserved namespace.
Builtin functions allow you to directly access hardware
and machine instructions to perform operations that are
cumbersome, slow, or impossible to implement in the C language.
While the user of inline assembly code can provide
similar capabilities, builtin functions provide a higherlevel
interface for some common operations that are complex
to implement well in assembly language. See the file
for further information on asm in-line assembly language
generator functions.
These functions are very efficient because they are built
into the DEC C (-newc) compiler. This means that a call to
one of these functions does not result in a reference to a
function in the run-time library or to a function in your
program. Instead, the compiler generates the machine
instructions necessary to carry out the function directly
at the call site.
Be sure to include the <builtins.h> header file in your
source program to access these built-in functions and add
a line similar to the following to the cc command line
(the file is not located in the default header file directory
(/usr/include)). -I /usr/includemachine
Note that by convention, the suffixes _LONG and _QUAD designate,
respectively, 32-bit longword and 64-bit quadword
operations (as defined by the Alpha architecture). In
particular, the _LONG suffix designating a 32-bit longword,
should not be confused with the C language type
long, which is 64-bits on Tru64 UNIX.
The following describes the DEC C (-newc) built-in functions
available on Tru64 UNIX. Note that the return value
is always the old value of the location before the operation
is performed. The retry variants provide successful
status through the status pointer. The only exceptions
are the __LOCK_LONG_RETRY and __ACQUIRE_SEM_LONG_RETRY
functions. Atomic Add Longword
The __ATOMIC_ADD_LONG function adds the specified
expression to the aligned longword pointed to by
the address parameter within a load-locked/storeconditional
code sequence and returns the value of
the longword before the addition was performed.
This function has one of the following formats:
int __ATOMIC_ADD_LONG (
volatile void *__address,
int __expression);
int __ATOMIC_ADD_LONG_RETRY (
volatile void *__address,
int __expression,
int __retry,
int *__status); address
The longword-aligned address ofthe data segment.
expression
An integer expression. retry
A count of type int. The retry count indicates the
number of times the operation is attempted (which
will be at least once even if the count argument is
0). If the operation cannot be performed successfully
in the specified number of retries, the function
returns without updating the longword. status
A pointer to an integer that is set to 0 if the
operation did not succeed within the specified number
of retries, and set to 1 if the operation succeeded.
Atomic Add Quadword
The __ATOMIC_ADD_QUAD function adds the specified
expression to the aligned quadword pointed to by
the address parameter within a load-locked/storeconditional
code sequence and returns the value of
the quadword before the operation was performed.
This function has one of the following formats:
long __ATOMIC_ADD_QUAD (
volatile void *__address,
long __expression);
long __ATOMIC_ADD_QUAD_RETRY (
volatile void *__address,
long __expression,
int __retry,
int *__status); address
The quadword-aligned address of the data segment.
expression
An expression of type long. retry
A count of type int. The retry count indicates the
number of times the operation is attempted (which
will be at least once even if the count argument is
0). If the operation cannot be performed successfully
in the specified number of retries, the function
returns without updating the longword. status
A pointer to an integer that is set to 0 if the
operation did not succeed with in the specified
number of retries, and set to 1 if the operation
succeeded. Atomic AND Longword
The __ATOMIC_AND_LONG function performs a logical
AND of the specified expression with the aligned
longword pointed to by the address parameter within
a load-locked/store-conditional code sequence and
returns the value of the longword before the addition
was performed.
This function has one of the following formats:
int __ATOMIC_AND_LONG (
volatile void *__address,
int __expression);
int __ATOMIC_AND_LONG_RETRY (
volatile void *__address,
int __expression,
int __retry,
int *__status); address
The longword-aligned address of the data segment.
expression
An integer expression. retry
A count of type int. The retry count indicates the
number of times the operation is attempted (which
will be at least once even if the count argument is
0). If the operation cannot be performed successfully
in the specified number of retries, the function
returns without updating the longword. status
A pointer to an integer that is set to 0 if the
operation did not succeed with in the specified
number of retries, and set to 1 if the operation
succeeded. Atomic AND Quadword
The __ATOMIC_AND_QUAD function performs a logical
AND of the specified expression with the aligned
quadword pointed to by the address parameter within
a load-locked/store-conditional code sequence and
returns the value of the longword before the addition
was performed.
This function has one of the following formats:
long __ATOMIC_AND_QUAD (
volatile void *__address,
long __expression);
long __ATOMIC_AND_QUAD_RETRY (
volatile void *__address,
long __expression,
int __retry,
int *__status); address
The quadword-aligned address of the data segment.
expression
An expression of type long. retry
A count of type int. The retry count indicates the
number of times the operation is attempted (which
will be at least once even if the count argument is
0). If the operation cannot be performed successfully
in the specified number of retries, the function
returns without updating the longword. status
A pointer to an integer that is set to 0 if the
operation did not succeed with in the specified
number of retries, and set to 1 if the operation
succeeded. Atomic OR Longword
The __ATOMIC_OR_LONG function performs a logical OR
of the specified expression with the aligned longword
pointed to by the address parameter within a
load-locked/store-conditional code sequence and
returns the value of the longword before the addition
was performed.
This function has one of the following formats:
int __ATOMIC_OR_LONG (
volatile void *__address,
int __expression);
int __ATOMIC_OR_LONG_RETRY (
volatile void *__address,
int __expression,
int __retry,
int *__status); address
The longword-aligned address of the data segment.
expression
An integer expression. retry
A count of type int. The retry count indicates the
number of times the operation is attempted (which
will be at least once even if the count argument is
0). If the operation cannot be performed successfully
in the specified number of retries, the function
returns without updating the longword. status
A pointer to an integer that is set to 0 if the
operation did not succeed with in the specified
number of retries, and set to 1 if the operation
succeeded. Atomic OR Quadword
The __ATOMIC_OR_QUAD function performs a logical OR
of the specified expression with the aligned quadword
pointed to by the address parameter within a
load-locked/store-conditional code sequence and
returns the value of the longword before the addition
was performed.
This function has one of the following formats:
long __ATOMIC_OR_QUAD (
volatile void *__address,
long __expression);
long __ATOMIC_OR_QUAD_RETRY (
volatile void *__address,
long __expression,
int __retry,
int *__status);
address
The quadword-aligned address of the data segment.
expression
An expression of type long. retry
A count of type int. The retry count indicates the
number of times the operation is attempted (which
will be at least once even if the count argument is
0). If the operation cannot be performed successfully
in the specified number of retries, the function
returns without updating the longword. status
A pointer to an integer that is set to 0 if the
operation did not succeed with in the specified
number of retries, and set to 1 if the operation
succeeded. Atomic Increment Longword
The __ATOMIC_INCREMENT_LONG function increments by
1 the aligned longword pointed to by the address
parameter within a load-locked/store-conditional
code sequence and returns the value of the longword
before the addition was performed.
This function has the following format:
int __ATOMIC_INCREMENT_LONG (
volatile void *__address); address
The longword-aligned address of the data segment.
Atomic Increment Quadword
The __ATOMIC_INCREMENT_QUAD function increments by
1 the aligned quadword pointed to by the address
parameter within a load-locked/store-conditional
code sequence and returns the value of the longword
before the addition was performed.
This function has the following format:
long __ATOMIC_INCREMENT_QUAD (
volatile void *__address); address
The quadword-aligned address of the data segment.
Atomic Decrement Longword
The __ATOMIC_DECREMENT_LONG function decrements by
1 the aligned longword pointed to by the address
parameter within a load-locked/store-conditional
code sequence and returns the value of the longword
before the addition was performed.
This function has the following format:
int __ATOMIC_DECREMENT_LONG (
volatile void *__address); address
The longword-aligned address of the data segment.
Atomic Decrement Quadword
The __ATOMIC_DECREMENT_QUAD function decrements by
1 the aligned quadword pointed to by the address
parameter within a load-locked/store-conditional
code sequence and returns the value of the longword
before the addition was performed.
This function has the following format:
long __ATOMIC_DECREMENT_QUAD (
volatile void *__address); address
The quadword-aligned address of the data segment.
Atomic Exchange Longword
The __ATOMIC_EXCH_LONG function stores the value of
the specified expression into the aligned longword
specified by the address parameter within a loadlocked/store-conditional
code sequence, and returns
the value of the longword before the store was performed.
This function has one of the following formats:
int __ATOMIC_EXCH_LONG (
volatile void *__address,
int __expression);
int __ATOMIC_EXCH_LONG_RETRY (
volatile void *__address,
int __expression,
int __retry,
int *__status); address
The longword-aligned address of the data segment.
expression
An integer expression. retry
A count of type int. The retry count indicates the
number of times the operation is attempted (which
will be at least once even if the count argument is
0). If the operation cannot be performed successfully
in the specified number of retries, the function
returns without updating the longword. status
A pointer to an integer that is set to 0 if the
operation did not succeed with in the specified
number of retries, and set to 1 if the operation
succeeded. Atomic Exchange Quadword
The __ATOMIC_EXCH_QUAD function stores the value of
the specified expression into the aligned quadword
specified by the address parameter within a loadlocked/store-conditional
code sequence, and returns
the value of the quadword before the store was performed.
This function has one of the following formats:
long __ATOMIC_EXCH_QUAD (
volatile void *__address,
long __expression);
long __ATOMIC_EXCH_QUAD_RETRY (
volatile void *__address,
long __expression,
int __retry,
int *__status); address
The quadword-aligned address of the data segment.
expression
An expression of type long. retry
A count of type int. The retry count indicates the
number of times the operation is attempted (which
will be at least once even if the count argument is
0). If the operation cannot be performed
successfully in the specified number of retries,
the function returns without updating the longword.
status
A pointer to an integer that is set to 0 if the
operation did not succeed with in the specified
number of retries, and set to 1 if the operation
succeeded. Test for Bit Clear Then Clear Bit
Interlocked
The __INTERLOCKED_TESTBITCC_QUAD function performs
the following functions in interlocked fashion:
Returns the complement of the specified bit before
being cleared 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.
position
The position within the field of the bit that you
want cleared, in the range of 0 to 63. retry
A count of type int. The retry count indicates the
number of times the operation is attempted (which
will be at least once even if the count argument is
0). If the operation cannot be performed successfully
in the specified number of retries, the function
returns without updating the longword. status
A pointer to an integer that is set to 0 if the
operation did not succeed with in the specified
number of retries, and set to 1 if the operation
succeeded. Test for Bit Set Then Set Bit Inter-
locked
The __INTERLOCKED_TESTBITSS_QUAD function performs
the following operations in interlocked fashion:
Returns the value of the specified bit before being
set Sets the bit
This function has one of the following formats:
int __INTERLOCKED_TESTBITSS_QUAD (
volatile void *__address,
int __bit_position);
int __INTERLOCKED_TESTBITSS_QUAD_RETRY (
volatile void *__address,
int __bit_position,
int __retry,
int *__status); address
The quadword-aligned base address of the bit field.
position
The position within the field of the bit that you
want set, in the range of 0 to 63. retry
A count of type int. The retry count indicates the
number of times the operation is attempted (which
will be at least once even if the count argument is
0). If the operation cannot be performed successfully
in the specified number of retries, the function
returns without updating the longword. status
A pointer to an integer that is set to 0 if the
operation did not succeed with in the specified
number of retries, and set to 1 if the operation
succeeded. Lock and Unlock Longword
The __LOCK_LONG and __UNLOCK_LONG functions provide
a binary spinlock capability based on the low-order
bit of a longword.
The __LOCK_LONG function executes in a loop waiting
for the bit to be cleared and then sets it within a
load-locked/store-conditional sequence; it then
issues a memory barrier. The __UNLOCK_LONG function
issues a memory barrier and then zeroes the
longword.
The __LOCK_LONG_RETRY function returns 1 if the
lock was acquired within the specified number of
returns and 0 if the lock was not acquired.
This function has one of the following formats:
void __LOCK_LONG (
volatile void *__address);
int __LOCK_LONG_RETRY (
volatile void *__address,
int __retry);
The __UNLOCK_LONG function has the following format:
void __UNLOCK_LONG (
volatile void *__address); address
The quadword-aligned address of the longword used
for the lock. retry
A count of type int. The retry count indicates the
number of times the operation is attempted (which
will be at least once even if the count argument is
0). If the operation cannot be performed successfully
in the specified number of retries, the function
returns without updating the longword.
Acquire and Release Longword Semaphore
The __ACQUIRE_SEM_LONG and__RELEASE_SEM_LONG functions
provide a counted semaphore capability where
the positive value of a longword is interpreted as
the number of resources are available. The
__ACQUIRE_SEM_LONG function loops until the longword
has a positive value and then decrements it
within a load-locked/store-conditional sequence; it
then issues a memory barrier. The
__RELEASE_SEM_LONG function issues a memory barrier
and then does an _ATOMIC_INCREMENT_LONG on the
longword. The __ACQUIRE_SEM_LONG_RETRY function
returns 1 if the resource count was successfully
decremented within the specified number of retries,
and 0 otherwise. Acquire Semaphore Longword
The __ACQUIRE_SEM_LONG function has one of the following
formats:
void __ACQUIRE_SEM_LONG (
volatile void *__address);
int __ACQUIRE_SEM_LONG_RETRY (
volatile void *__address,
int __retry); address
The longword-aligned address of the resource count.
retry
A count of type int. The retry count indicates the
number of times the operation is attempted (which
will be at least once even if the count argument is
0). If the operation cannot be performed successfully
in the specified number of retries, the function
returns without updating the longword.
Release Semaphore Longword
The __RELEASE_SEM_LONG function has the following
format:
void __RELEASE_SEM_LONG (
volatile void *__address); address
The longword-aligned address of the resource count.
Compare and Store Longword
The __CMP_STORE_LONG function has the following
format:
int __CMP_STORE_LONG (
volatile void *__source,
int __old_value,
int __new_value,
volatile void *__dest);
This function performs a conditional atomic compare
and update operation involving one or two longwords
in the same lock region. The value pointed to by
source is compared with the longword old_value. If
they are equal, the longword new_value is conditionally
stored into the longword pointed to by
dest.
The store will not complete if the compare yields
unequal values or if there is an intervening store
to the lock region involved. To be in the same
lock region, source and dest must point to aligned
longwords in the same naturally aligned 16-byte
region.
The function returns 0 if the store does not complete,
and returns 1 if the store does complete.
Compare and Store Quadword
The __CMP_STORE_QUAD function has the following
format:
int __CMP_STORE_QUAD (
volatile void *__source,
long __old_value,
long __new_value,
volatile void *__dest);
This function performs a conditional atomic compare
and update operation involving one or two quadwords
in the same lock region. The value pointed to by
source is compared with the quadword old_value. If
they are equal, the quadword new_value is conditionally
stored into the quadword pointed to by
dest.
The store will not complete if the compare yields
unequal values or if there is an intervening store
to the lock region involved. To be in the same
lock region, source and dest must point to aligned
quadwords in the same naturally aligned 16-byte
region.
The function returns 0 if the store does not complete,
and returns 1 if the store does complete.
Add Aligned Word Interlocked
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 and is provided to emulate the VAX
instructions of that name. This function returns
the value of bits 0:3 of a VAX Program Status Longword.
The __ADAWI function has the following format:
int __ADAWI (
short __src,
volatile 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.
Because of their prior availability on the OpenVMS Alpha
platform, there are a number of additional builtins that
are recognized by DEC C and declared in the builtins.h
file. These builtins should not generally be used in new
code. These include a number of atomic/interlocked operations
that issue memory barriers before and after the
load-locked/store-conditional sequence, and some singleinstruction
functions that are more naturally implemented
using the asm facility. The referenced header files contain
more specific information.
/usr/include/machine/builtins.h
Functions: asm, fasm, dasm
cc (1)
Programmer's Guide
Files: /usr/include/c_asm.h delim off
builtins(4)
[ Back ] |
