 |
Index for
Section 4 |
|
 |
Alphabetical
listing for B |
|
 |
Bottom of
page |
|
builtins(4)
NAME
builtins.h - Header file declaring functions that are unconditionally
intrinsic.
SYNOPSIS
#include <builtins.h>
DESCRIPTION
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 higher-level
interface for some common operations that are complex to implement well in
assembly language. See the /usr/include/c_asm.h 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/include/machine
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/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_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/store-conditional 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 load-locked/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 load-locked/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 Interlocked
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 single-instruction functions that are more
naturally implemented using the asm facility. The referenced header files
contain more specific information.
FILES
/usr/include/machine/builtins.h
RELATED INFORMATION
Functions: asm, fasm, dasm
cc (1)
Programmer's Guide
Files: /usr/include/c_asm.h
|
Index for
Section 4 |
|
|
Alphabetical
listing for B |
|
 |
Top of
page |
|