ADC Home > Reference Library > Reference > Darwin > Kernel Framework Reference

 

OSAtomic.h

Includes:
<libkern/OSBase.h>

Overview

This header contains a collection of atomic functions that guarantee atomicity only with main system memory.


Functions

OSAddAtomic

32-bit add operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.

OSAddAtomic16

16-bit add operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.

OSAddAtomic64

64-bit atomic add operation.

OSAddAtomic8

8-bit add operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.

OSBitAndAtomic

32-bit logical and operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.

OSBitAndAtomic16

16-bit logical and operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.

OSBitAndAtomic8

8-bit logical and operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.

OSBitOrAtomic

32-bit logical or operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.

OSBitOrAtomic16

16-bit logical or operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.

OSBitOrAtomic8

8-bit logical or operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.

This function guarantees atomicity only with main system memory. It is specifically unsuitable for use on noncacheable memory such as that in devices; this function cannot guarantee atomicity, for example, on memory mapped from a PCI device.

OSBitXorAtomic

32-bit logical xor operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.

This function guarantees atomicity only with main system memory. It is specifically unsuitable for use on noncacheable memory such as that in devices; this function cannot guarantee atomicity, for example, on memory mapped from a PCI device.

OSBitXorAtomic16

16-bit logical xor operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.

OSBitXorAtomic8

8-bit logical xor operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.

This function guarantees atomicity only with main system memory. It is specifically unsuitable for use on noncacheable memory such as that in devices; this function cannot guarantee atomicity, for example, on memory mapped from a PCI device.

OSCompareAndSwap

Compare and swap operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.

OSCompareAndSwap64

64-bit compare and swap operation.

OSDecrementAtomic

32-bit decrement operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.

OSDecrementAtomic16

16-bit decrement operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.

OSDecrementAtomic64

64-bit decrement.

OSDecrementAtomic8

8-bit decrement operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.

OSDequeueAtomic

Singly linked list element head removal, performed atomically with respect to all devices that participate in the coherency architecture of the platform.

OSEnqueueAtomic

Singly linked list head insertion, performed atomically with respect to all devices that participate in the coherency architecture of the platform.

OSIncrementAtomic

32-bit increment operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.

OSIncrementAtomic16

16-bit increment operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.

OSIncrementAtomic64

64-bit increment.

OSIncrementAtomic8

8-bit increment operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.

OSSynchronizeIO

Ensures orderly load and store operations to noncached memory mapped I/O devices.

OSTestAndClear

Bit test and clear operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.

OSTestAndSet

Bit test and set operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.

This function guarantees atomicity only with main system memory. It is specifically unsuitable for use on noncacheable memory such as that in devices; this function cannot guarantee atomicity, for example, on memory mapped from a PCI device.

OSAddAtomic

32-bit add operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform. 

extern SInt32 OSAddAtomic(
    SInt32 amount,
    volatile SInt32 *address);
Parameters
amount

The amount to add.

address

The 4-byte aligned address of the value to update atomically.

Return Value

The value before the addition

Discussion

The OSAddAtomic function adds the specified amount to the value at the specified address and returns the original value.

This function guarantees atomicity only with main system memory. It is specifically unsuitable for use on noncacheable memory such as that in devices; this function cannot guarantee atomicity, for example, on memory mapped from a PCI device.

OSAddAtomic16

16-bit add operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform. 

extern SInt16 OSAddAtomic16(
    SInt32 amount,
    volatile SInt16 *address);
Parameters
amount

The amount to add.

address

The 2-byte aligned address of the value to update atomically.

Return Value

The value before the addition

Discussion

The OSAddAtomic16 function adds the specified amount to the value at the specified address and returns the original value.

This function guarantees atomicity only with main system memory. It is specifically unsuitable for use on noncacheable memory such as that in devices; this function cannot guarantee atomicity, for example, on memory mapped from a PCI device.

OSAddAtomic64

64-bit atomic add operation. 

extern SInt64 OSAddAtomic64(
    SInt64 theAmount,
    volatile SInt64 *address);
Discussion

See OSAddAtomic.

OSAddAtomic8

8-bit add operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform. 

extern SInt8 OSAddAtomic8(
    SInt32 amount,
    volatile SInt8 *address);
Parameters
amount

The amount to add.

address

The address of the value to update atomically.

Return Value

The value before the addition

Discussion

The OSAddAtomic8 function adds the specified amount to the value at the specified address and returns the original value.

This function guarantees atomicity only with main system memory. It is specifically unsuitable for use on noncacheable memory such as that in devices; this function cannot guarantee atomicity, for example, on memory mapped from a PCI device.

OSBitAndAtomic

32-bit logical and operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform. 

extern UInt32 OSBitAndAtomic(
    UInt32 mask,
    volatile UInt32 *address);
Parameters
mask

The mask to logically and with the value.

address

The 4-byte aligned address of the value to update atomically.

Return Value

The value before the bitwise operation

Discussion

The OSBitAndAtomic function logically ands the bits of the specified mask into the value at the specified address and returns the original value.

This function guarantees atomicity only with main system memory. It is specifically unsuitable for use on noncacheable memory such as that in devices; this function cannot guarantee atomicity, for example, on memory mapped from a PCI device.

OSBitAndAtomic16

16-bit logical and operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform. 

extern UInt16 OSBitAndAtomic16(
    UInt32 mask,
    volatile UInt16 *address);
Parameters
mask

The mask to logically and with the value.

address

The 2-byte aligned address of the value to update atomically.

Return Value

The value before the bitwise operation.

Discussion

The OSBitAndAtomic16 function logically ands the bits of the specified mask into the value at the specified address and returns the original value.

This function guarantees atomicity only with main system memory. It is specifically unsuitable for use on noncacheable memory such as that in devices; this function cannot guarantee atomicity, for example, on memory mapped from a PCI device.

OSBitAndAtomic8

8-bit logical and operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform. 

extern UInt8 OSBitAndAtomic8(
    UInt32 mask,
    volatile UInt8 *address);
Parameters
mask

The mask to logically and with the value.

address

The address of the value to update atomically.

Return Value

The value before the bitwise operation.

Discussion

The OSBitAndAtomic8 function logically ands the bits of the specified mask into the value at the specified address and returns the original value.

This function guarantees atomicity only with main system memory. It is specifically unsuitable for use on noncacheable memory such as that in devices; this function cannot guarantee atomicity, for example, on memory mapped from a PCI device.

OSBitOrAtomic

32-bit logical or operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform. 

extern UInt32 OSBitOrAtomic(
    UInt32 mask,
    volatile UInt32 *address);
Parameters
mask

The mask to logically or with the value.

address

The 4-byte aligned address of the value to update atomically.

Return Value

The value before the bitwise operation.

Discussion

The OSBitOrAtomic function logically ors the bits of the specified mask into the value at the specified address and returns the original value.

This function guarantees atomicity only with main system memory. It is specifically unsuitable for use on noncacheable memory such as that in devices; this function cannot guarantee atomicity, for example, on memory mapped from a PCI device.

OSBitOrAtomic16

16-bit logical or operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform. 

extern UInt16 OSBitOrAtomic16(
    UInt32 mask,
    volatile UInt16 *address);
Parameters
mask

The mask to logically or with the value.

address

The 2-byte aligned address of the value to update atomically.

Return Value

The value before the bitwise operation.

Discussion

The OSBitOrAtomic16 function logically ors the bits of the specified mask into the value at the specified address and returns the original value.

This function guarantees atomicity only with main system memory. It is specifically unsuitable for use on noncacheable memory such as that in devices; this function cannot guarantee atomicity, for example, on memory mapped from a PCI device.

OSBitOrAtomic8

8-bit logical or operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.

This function guarantees atomicity only with main system memory. It is specifically unsuitable for use on noncacheable memory such as that in devices; this function cannot guarantee atomicity, for example, on memory mapped from a PCI device. 

extern UInt8 OSBitOrAtomic8(
    UInt32 mask,
    volatile UInt8 *address);
Parameters
mask

The mask to logically or with the value.

address

The address of the value to update atomically.

Return Value

The value before the bitwise operation.

Discussion

The OSBitOrAtomic8 function logically ors the bits of the specified mask into the value at the specified address and returns the original value.

OSBitXorAtomic

32-bit logical xor operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.

This function guarantees atomicity only with main system memory. It is specifically unsuitable for use on noncacheable memory such as that in devices; this function cannot guarantee atomicity, for example, on memory mapped from a PCI device. 

extern UInt32 OSBitXorAtomic(
    UInt32 mask,
    volatile UInt32 *address);
Parameters
mask

The mask to logically or with the value.

address

The 4-byte aligned address of the value to update atomically.

Return Value

The value before the bitwise operation.

Discussion

The OSBitXorAtomic function logically xors the bits of the specified mask into the value at the specified address and returns the original value.

OSBitXorAtomic16

16-bit logical xor operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform. 

extern UInt16 OSBitXorAtomic16(
    UInt32 mask,
    volatile UInt16 *address);
Parameters
mask

The mask to logically or with the value.

address

The 2-byte aligned address of the value to update atomically.

Return Value

The value before the bitwise operation.

Discussion

The OSBitXorAtomic16 function logically xors the bits of the specified mask into the value at the specified address and returns the original value.

This function guarantees atomicity only with main system memory. It is specifically unsuitable for use on noncacheable memory such as that in devices; this function cannot guarantee atomicity, for example, on memory mapped from a PCI device.

OSBitXorAtomic8

8-bit logical xor operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.

This function guarantees atomicity only with main system memory. It is specifically unsuitable for use on noncacheable memory such as that in devices; this function cannot guarantee atomicity, for example, on memory mapped from a PCI device. 

extern UInt8 OSBitXorAtomic8(
    UInt32 mask,
    volatile UInt8 *address);
Parameters
mask

The mask to logically or with the value.

address

The address of the value to update atomically.

Return Value

The value before the bitwise operation.

Discussion

The OSBitXorAtomic8 function logically xors the bits of the specified mask into the value at the specified address and returns the original value.

OSCompareAndSwap

Compare and swap operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform. 

extern Boolean OSCompareAndSwap(
    UInt32 oldValue,
    UInt32 newValue, 
    volatile UInt32 *address);
Parameters
oldValue

The value to compare at address.

newValue

The value to write to address if oldValue compares true.

address

The 4-byte aligned address of the data to update atomically.

Return Value

true if newValue was written to the address.

Discussion

The OSCompareAndSwap function compares the value at the specified address with oldVal. The value of newValue is written to the address only if oldValue and the value at the address are equal. OSCompareAndSwap returns true if newValue is written to the address; otherwise, it returns false.

This function guarantees atomicity only with main system memory. It is specifically unsuitable for use on noncacheable memory such as that in devices; this function cannot guarantee atomicity, for example, on memory mapped from a PCI device.

OSCompareAndSwap64

64-bit compare and swap operation. 

extern Boolean OSCompareAndSwap64(
    UInt64 oldValue,
    UInt64 newValue, 
    volatile UInt64 *address);
Discussion

See OSCompareAndSwap.

OSDecrementAtomic

32-bit decrement operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform. 

extern SInt32 OSDecrementAtomic(
    volatile SInt32 *address);
Parameters
address

The 4-byte aligned address of the value to update atomically.

Return Value

The value before the decrement.

Discussion

The OSDecrementAtomic function decrements the value at the specified address by one and returns the original value.

This function guarantees atomicity only with main system memory. It is specifically unsuitable for use on noncacheable memory such as that in devices; this function cannot guarantee atomicity, for example, on memory mapped from a PCI device.

OSDecrementAtomic16

16-bit decrement operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform. 

extern SInt16 OSDecrementAtomic16(
    volatile SInt16 *address);
Parameters
address

The 2-byte aligned address of the value to update atomically.

Return Value

The value before the decrement.

Discussion

The OSDecrementAtomic16 function decrements the value at the specified address by one and returns the original value.

This function guarantees atomicity only with main system memory. It is specifically unsuitable for use on noncacheable memory such as that in devices; this function cannot guarantee atomicity, for example, on memory mapped from a PCI device.

OSDecrementAtomic64

64-bit decrement. 

inline static SInt64 OSDecrementAtomic64(
    volatile SInt64 *address)
Discussion

See OSDecrementAtomic.

OSDecrementAtomic8

8-bit decrement operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform. 

extern SInt8 OSDecrementAtomic8(
    volatile SInt8 *address);
Parameters
address

The address of the value to update atomically.

Return Value

The value before the decrement.

Discussion

The OSDecrementAtomic8 function decrements the value at the specified address by one and returns the original value.

This function guarantees atomicity only with main system memory. It is specifically unsuitable for use on noncacheable memory such as that in devices; this function cannot guarantee atomicity, for example, on memory mapped from a PCI device.

OSDequeueAtomic

Singly linked list element head removal, performed atomically with respect to all devices that participate in the coherency architecture of the platform. 

extern void * OSDequeueAtomic(
    void *volatile * listHead, 
    SInt32 elementNextFieldOffset);
Parameters
listHead

The address of a head pointer for the list .

elementNextFieldOffset

The byte offset into the element where a pointer to the next element in the list is stored.

Return Value

A removed element, or zero if the list is empty.

Discussion

The OSDequeueAtomic function removes an element from the head of a singly linked list, which is specified with the address of a head pointer, listHead. The element structure has a next field whose offset is specified.

This function guarantees atomicity only with main system memory. It is specifically unsuitable for use on noncacheable memory such as that in devices; this function cannot guarantee atomicity, for example, on memory mapped from a PCI device.

OSEnqueueAtomic

Singly linked list head insertion, performed atomically with respect to all devices that participate in the coherency architecture of the platform. 

extern void OSEnqueueAtomic(
    void *volatile * listHead,
    void *element, 
    SInt32 elementNextFieldOffset);
Parameters
listHead

The address of a head pointer for the list .

element

The list element to insert at the head of the list.

elementNextFieldOffset

The byte offset into the element where a pointer to the next element in the list is stored.

Discussion

The OSEnqueueAtomic function places an element at the head of a single linked list, which is specified with the address of a head pointer, listHead. The element structure has a next field whose offset is specified.

This function guarantees atomicity only with main system memory. It is specifically unsuitable for use on noncacheable memory such as that in devices; this function cannot guarantee atomicity, for example, on memory mapped from a PCI device.

OSIncrementAtomic

32-bit increment operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform. 

extern SInt32 OSIncrementAtomic(
    volatile SInt32 *address);
Parameters
address

The 4-byte aligned address of the value to update atomically.

Return Value

The value before the increment.

Discussion

The OSIncrementAtomic function increments the value at the specified address by one and returns the original value.

This function guarantees atomicity only with main system memory. It is specifically unsuitable for use on noncacheable memory such as that in devices; this function cannot guarantee atomicity, for example, on memory mapped from a PCI device.

OSIncrementAtomic16

16-bit increment operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform. 

extern SInt16 OSIncrementAtomic16(
    volatile SInt16 *address);
Parameters
address

The 2-byte aligned address of the value to update atomically.

Return Value

The value before the increment.

Discussion

The OSIncrementAtomic16 function increments the value at the specified address by one and returns the original value.

This function guarantees atomicity only with main system memory. It is specifically unsuitable for use on noncacheable memory such as that in devices; this function cannot guarantee atomicity, for example, on memory mapped from a PCI device.

OSIncrementAtomic64

64-bit increment. 

inline static SInt64 OSIncrementAtomic64(
    volatile SInt64 *address)
Discussion

See OSIncrementAtomic.

OSIncrementAtomic8

8-bit increment operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform. 

extern SInt8 OSIncrementAtomic8(
    volatile SInt8 *address);
Parameters
address

The address of the value to update atomically.

Return Value

The value before the increment.

Discussion

The OSIncrementAtomic8 function increments the value at the specified address by one and returns the original value.

This function guarantees atomicity only with main system memory. It is specifically unsuitable for use on noncacheable memory such as that in devices; this function cannot guarantee atomicity, for example, on memory mapped from a PCI device.

OSSynchronizeIO

Ensures orderly load and store operations to noncached memory mapped I/O devices. 

#if defined(__arm__) && defined(__thumb__) 
extern void OSSynchronizeIO(
    void);  
#else 
static __inline__ void OSSynchronizeIO(
    void) __asm__ ("eieio")__asm__ volatile("mcr p15, 0, %0, c7, c10, 4" : : "r" (temp))
#endif
Discussion

The OSSynchronizeIO routine ensures orderly load and store operations to noncached memory mapped I/O devices. It executes the eieio instruction on PowerPC processors.

OSTestAndClear

Bit test and clear operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform. 

extern Boolean OSTestAndClear(
    UInt32 bit,
    volatile UInt8 *startAddress);
Parameters
bit

The bit number in the range 0 through 7.

address

The address of the byte to update atomically.

Return Value

true if the bit was already clear, false otherwise.

Discussion

The OSTestAndClear function clears a single bit in a byte at a specified address. It returns true if the bit was already clear, false otherwise.

This function guarantees atomicity only with main system memory. It is specifically unsuitable for use on noncacheable memory such as that in devices; this function cannot guarantee atomicity, for example, on memory mapped from a PCI device.

OSTestAndSet

Bit test and set operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.

This function guarantees atomicity only with main system memory. It is specifically unsuitable for use on noncacheable memory such as that in devices; this function cannot guarantee atomicity, for example, on memory mapped from a PCI device. 

extern Boolean OSTestAndSet(
    UInt32 bit,
    volatile UInt8 *startAddress);
Parameters
bit

The bit number in the range 0 through 7.

address

The address of the byte to update atomically.

Return Value

true if the bit was already set, false otherwise.

Discussion

The OSTestAndSet function sets a single bit in a byte at a specified address. It returns true if the bit was already set, false otherwise.


Did this document help you?
Yes: Tell us what works for you.
It’s good, but: Report typos, inaccuracies, and so forth.
It wasn’t helpful: Tell us what would have helped.

 

Last Updated: 2008-12-19