OSAtomic.h

Functions

OSAddAtomic

Abstract: 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, SInt32 * address);

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

Parameters

Name Description

amount The amount to add.

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

Name	Description
`amount`	The amount to add.
`address`	The 4-byte aligned address of the value to update atomically.

Result: The result of the addition.

OSAddAtomic16

Abstract: 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, SInt16 * address);

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

Parameters

Name Description

amount The amount to add.

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

Name	Description
`amount`	The amount to add.
`address`	The 4-byte aligned address of the value to update atomically.

Result: The result of the addition.

OSAddAtomic8

Abstract: 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, SInt8 * address);

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

Parameters

Name Description

amount The amount to add.

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

Name	Description
`amount`	The amount to add.
`address`	The 4-byte aligned address of the value to update atomically.

Result: The result of the addition.

OSBitAndAtomic

Abstract: 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, UInt32 * address);

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

Parameters

Name Description

mask The mask to logically and with the value.

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

Name	Description
`mask`	The mask to logically and with the value.
`address`	The 4-byte aligned address of the value to update atomically.

Result: The result of the logical and.

OSBitAndAtomic16

Abstract: 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, UInt16 * address);

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

Parameters

Name Description

mask The mask to logically and with the value.

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

Name	Description
`mask`	The mask to logically and with the value.
`address`	The 4-byte aligned address of the value to update atomically.

Result: The result of the logical and.

OSBitAndAtomic8

Abstract: 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, UInt8 * address);

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

Parameters

Name Description

mask The mask to logically and with the value.

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

Name	Description
`mask`	The mask to logically and with the value.
`address`	The 4-byte aligned address of the value to update atomically.

Result: The result of the logical and.

OSBitOrAtomic

Abstract: 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, UInt32 * address);

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

Parameters

Name Description

mask The mask to logically or with the value.

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

Name	Description
`mask`	The mask to logically or with the value.
`address`	The 4-byte aligned address of the value to update atomically.

Result: The result of the logical or.

OSBitOrAtomic16

Abstract: 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, UInt16 * address);

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

Parameters

Name Description

mask The mask to logically or with the value.

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

Name	Description
`mask`	The mask to logically or with the value.
`address`	The 4-byte aligned address of the value to update atomically.

Result: The result of the logical or.

OSBitOrAtomic8

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

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

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

Parameters

Name Description

mask The mask to logically or with the value.

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

Name	Description
`mask`	The mask to logically or with the value.
`address`	The 4-byte aligned address of the value to update atomically.

Result: The result of the logical or.

OSBitXorAtomic

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

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

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

Parameters

Name Description

mask The mask to logically or with the value.

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

Name	Description
`mask`	The mask to logically or with the value.
`address`	The 4-byte aligned address of the value to update atomically.

Result: The result of the logical xor.

OSBitXorAtomic16

Abstract: 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, UInt16 * address);

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

Parameters

Name Description

mask The mask to logically or with the value.

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

Name	Description
`mask`	The mask to logically or with the value.
`address`	The 4-byte aligned address of the value to update atomically.

Result: The result of the logical xor.

OSBitXorAtomic8

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

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

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

Parameters

Name Description

mask The mask to logically or with the value.

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

Name	Description
`mask`	The mask to logically or with the value.
`address`	The 4-byte aligned address of the value to update atomically.

Result: The result of the logical xor.

OSCompareAndSwap

Abstract: 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, UInt32 * address );

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. A false return value does not imply that oldValue and the value at the specified address are not equal; it only implies that OSCompareAndSwap did not write newValue to the address.

Parameters

Name Description

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.

Name	Description
`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.

Result: true if newValue was written to the address.

OSDecrementAtomic

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

extern SInt32 OSDecrementAtomic(SInt32 * address);

The OSDecrementAtomic function decrements the value at the specified address by one and returns the value as it was before the change.

Parameters

Name Description

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

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

Result: The value before the decrement.

OSDecrementAtomic16

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

extern SInt16 OSDecrementAtomic16(SInt16 * address);

The OSDecrementAtomic16 function decrements the value at the specified address by one and returns the value as it was before the change.

Parameters

Name Description

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

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

Result: The value before the decrement.

OSDecrementAtomic8

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

extern SInt8 OSDecrementAtomic8(SInt8 * address);

The OSDecrementAtomic8 function decrements the value at the specified address by one and returns the value as it was before the change.

Parameters

Name Description

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

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

Result: The value before the decrement.

OSDequeueAtomic

Abstract: 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 ** listHead,
 SInt32 elementNextFieldOffset);

The OSDequeueAtomic function removes an element from 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.

Parameters

Name Description

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.

Name	Description
`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.

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

OSEnqueueAtomic

Abstract: 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 ** listHead, void * element,
 SInt32 elementNextFieldOffset);

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.

Parameters

Name Description

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.

Name	Description
`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.

OSIncrementAtomic

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

extern SInt32 OSIncrementAtomic(SInt32 * address);

The OSIncrementAtomic function increments the value at the specified address by one and returns the value as it was before the change.

Parameters

Name Description

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

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

Result: The value before the increment.

OSIncrementAtomic16

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

extern SInt16 OSIncrementAtomic16(SInt16 * address);

The OSIncrementAtomic16 function increments the value at the specified address by one and returns the value as it was before the change.

Parameters

Name Description

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

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

Result: The value before the increment.

OSIncrementAtomic8

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

extern SInt8 OSIncrementAtomic8(SInt8 * address);

The OSIncrementAtomic8 function increments the value at the specified address by one and returns the value as it was before the change.

Parameters

Name Description

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

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

Result: The value before the increment.

OSSynchronizeIO

Abstract: The OSSynchronizeIO routine ensures orderly load and store operations to noncached memory mapped I/O devices.

static __inline__ void OSSynchronizeIO(void)
{
#if defined(__ppc__)
 __asm__ ("eieio");

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

Abstract: 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, UInt8 * startAddress);

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.

Parameters

Name Description

bit The bit number in the range 0 through 7.

address The address of the byte to update atomically.

Name	Description
`bit`	The bit number in the range 0 through 7.
`address`	The address of the byte to update atomically.

Result: true if the bit was already clear, false otherwise.

OSTestAndSet

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

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

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.

Parameters

Name Description

bit The bit number in the range 0 through 7.

address The address of the byte to update atomically.

Name	Description
`bit`	The bit number in the range 0 through 7.
`address`	The address of the byte to update atomically.

Result: true if the bit was already set, false otherwise.