Content-type: text/html Man page of builtins

builtins

Section: Devices and Network Interfaces (4)
Index Return to Main Contents
 

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

The following describes the DEC C (-newc) built-in functions available on Digital 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 delim off


 

Index

NAME
SYNOPSIS
DESCRIPTION
FILES
RELATED INFORMATION

This document was created by man2html, using the manual pages.
Time: 02:40:11 GMT, October 02, 2010