xnu-4570.1.46.tar.gz

[apple/xnu.git] / libkern / libkern / OSAtomic.h

diff --git a/libkern/libkern/OSAtomic.h b/libkern/libkern/OSAtomic.h
index 98b5388b412d844f7b1f18f52cfef404d195f230..76b945443ba43c53d1d2f5bddb451e6133d4cedb 100644 (file)
--- a/libkern/libkern/OSAtomic.h
+++ b/libkern/libkern/OSAtomic.h
@@ -1,17 +1,21 @@
 /*
 /*

- * Copyright (c) 2000 Apple Computer, Inc. All rights reserved.
+ * Copyright (c) 2007-2012 Apple Inc. All rights reserved.
+ * Copyright (c) 2000-2006 Apple Computer, Inc. All rights reserved.
+ *
+ * @APPLE_OSREFERENCE_LICENSE_HEADER_START@

  *
  *

- * @APPLE_LICENSE_HEADER_START@
- * 
- * Copyright (c) 1999-2003 Apple Computer, Inc.  All Rights Reserved.
- * 

  * This file contains Original Code and/or Modifications of Original Code
  * as defined in and that are subject to the Apple Public Source License
  * Version 2.0 (the 'License'). You may not use this file except in
  * This file contains Original Code and/or Modifications of Original Code
  * as defined in and that are subject to the Apple Public Source License
  * Version 2.0 (the 'License'). You may not use this file except in

- * compliance with the License. Please obtain a copy of the License at
- * http://www.opensource.apple.com/apsl/ and read it before using this
- * file.
- * 
+ * compliance with the License. The rights granted to you under the License
+ * may not be used to create, or enable the creation or redistribution of,
+ * unlawful or unlicensed copies of an Apple operating system, or to
+ * circumvent, violate, or enable the circumvention or violation of, any
+ * terms of an Apple operating system software license agreement.
+ *
+ * Please obtain a copy of the License at
+ * http://www.opensource.apple.com/apsl/ and read it before using this file.
+ *

  * The Original Code and all software distributed under the License are
  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  * The Original Code and all software distributed under the License are
  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,


@@ -19,8 +23,8 @@
  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  * Please see the License for the specific language governing rights and
  * limitations under the License.
  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  * Please see the License for the specific language governing rights and
  * limitations under the License.

- * 
- * @APPLE_LICENSE_HEADER_END@
+ *
+ * @APPLE_OSREFERENCE_LICENSE_HEADER_END@

  */
 /*
  * Copyright (c) 1999 Apple Computer, Inc.  All rights reserved.
  */
 /*
  * Copyright (c) 1999 Apple Computer, Inc.  All rights reserved.


@@ -38,266 +42,663 @@
 extern "C" {
 #endif
 
 extern "C" {
 #endif
 

-/*! @function OSCompareAndSwap
-    @abstract Compare and swap operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
-    @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.
-    @param oldValue The value to compare at address.
-    @param newValue The value to write to address if oldValue compares true.
-    @param address The 4-byte aligned address of the data to update atomically.
-    @result true if newValue was written to the address. */
-
-extern Boolean OSCompareAndSwap( UInt32 oldValue, UInt32 newValue, UInt32 * address );
-
-/*! @function OSAddAtomic
-    @abstract 32-bit add operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
-    @discussion The OSAddAtomic function adds the specified amount to the value at the specified address and returns the result.
-
-    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.
-    @param amount The amount to add.
-    @param address The 4-byte aligned address of the value to update atomically.
-    @result The value before the addition */
-
-extern SInt32  OSAddAtomic(SInt32 amount, SInt32 * address);
-
-/*! @function OSAddAtomic16
-    @abstract 16-bit add operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
-    @discussion The OSAddAtomic16 function adds the specified amount to the value at the specified address and returns the result.
-
-    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.
-    @param amount The amount to add.
-    @param address The 2-byte aligned address of the value to update atomically.
-    @result The value before the addition */
-
-extern SInt16  OSAddAtomic16(SInt32 amount, SInt16 * address);
-
-/*! @function OSAddAtomic8
-    @abstract 8-bit add operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
-    @discussion The OSAddAtomic8 function adds the specified amount to the value at the specified address and returns the result.
-
-    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.
-    @param amount The amount to add.
-    @param address The address of the value to update atomically.
-    @result The value before the addition */
-
-extern SInt8   OSAddAtomic8(SInt32 amount, SInt8 * address);
-
-/*! @function OSIncrementAtomic
-    @abstract 32-bit increment operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
-    @discussion The OSIncrementAtomic function increments the value at the specified address by one and returns the value as it was before the change.
-
-    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.
-    @param address The 4-byte aligned address of the value to update atomically.
-    @result The value before the increment. */
-
-extern SInt32  OSIncrementAtomic(SInt32 * address);
-
-/*! @function OSIncrementAtomic16
-    @abstract 16-bit increment operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
-    @discussion The OSIncrementAtomic16 function increments the value at the specified address by one and returns the value as it was before the change.
-
-    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.
-    @param address The 2-byte aligned address of the value to update atomically.
-    @result The value before the increment. */
-
-extern SInt16  OSIncrementAtomic16(SInt16 * address);
-
-/*! @function OSIncrementAtomic8
-    @abstract 8-bit increment operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
-    @discussion The OSIncrementAtomic8 function increments the value at the specified address by one and returns the value as it was before the change.
-
-    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.
-    @param address The address of the value to update atomically.
-    @result The value before the increment. */
-
-extern SInt8   OSIncrementAtomic8(SInt8 * address);
-
-/*! @function OSDecrementAtomic
-    @abstract 32-bit decrement operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
-    @discussion The OSDecrementAtomic function decrements the value at the specified address by one and returns the value as it was before the change.
-
-    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.
-    @param address The 4-byte aligned address of the value to update atomically.
-    @result The value before the decrement. */
-
-extern SInt32  OSDecrementAtomic(SInt32 * address);
-
-/*! @function OSDecrementAtomic16
-    @abstract 16-bit decrement operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
-    @discussion The OSDecrementAtomic16 function decrements the value at the specified address by one and returns the value as it was before the change.
-
-    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.
-    @param address The 2-byte aligned address of the value to update atomically.
-    @result The value before the decrement. */
-
-extern SInt16  OSDecrementAtomic16(SInt16 * address);
-
-/*! @function OSDecrementAtomic8
-    @abstract 8-bit decrement operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
-    @discussion The OSDecrementAtomic8 function decrements the value at the specified address by one and returns the value as it was before the change.
-
-    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.
-    @param address The address of the value to update atomically.
-    @result The value before the decrement. */
-
-extern SInt8   OSDecrementAtomic8(SInt8 * address);
-
-/*! @function OSBitAndAtomic
-    @abstract 32-bit logical and operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
-    @discussion The OSBitAndAtomic function logically ands the bits of the specified mask into the value at the specified address and returns the result.
-
-    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.
-    @param mask The mask to logically and with the value.
-    @param address The 4-byte aligned address of the value to update atomically.
-    @result The value before the bitwise operation */
-
-extern UInt32  OSBitAndAtomic(UInt32 mask, UInt32 * address);
-
-/*! @function OSBitAndAtomic16
-    @abstract 16-bit logical and operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
-    @discussion The OSBitAndAtomic16 function logically ands the bits of the specified mask into the value at the specified address and returns the result.
-
-    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.
-    @param mask The mask to logically and with the value.
-    @param address The 2-byte aligned address of the value to update atomically.
-    @result The value before the bitwise operation. */
-
-extern UInt16  OSBitAndAtomic16(UInt32 mask, UInt16 * address);
-
-/*! @function OSBitAndAtomic8
-    @abstract 8-bit logical and operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
-    @discussion The OSBitAndAtomic8 function logically ands the bits of the specified mask into the value at the specified address and returns the result.
-
-    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.
-    @param mask The mask to logically and with the value.
-    @param address The address of the value to update atomically.
-    @result The value before the bitwise operation. */
-
-extern UInt8   OSBitAndAtomic8(UInt32 mask, UInt8 * address);
-
-/*! @function OSBitOrAtomic
-    @abstract 32-bit logical or operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
-    @discussion The OSBitOrAtomic function logically ors the bits of the specified mask into the value at the specified address and returns the result.
-
-    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.
-    @param mask The mask to logically or with the value.
-    @param address The 4-byte aligned address of the value to update atomically.
-    @result The value before the bitwise operation. */
-
-extern UInt32  OSBitOrAtomic(UInt32 mask, UInt32 * address);
-
-/*! @function OSBitOrAtomic16
-    @abstract 16-bit logical or operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
-    @discussion The OSBitOrAtomic16 function logically ors the bits of the specified mask into the value at the specified address and returns the result.
+#ifdef XNU_KERNEL_PRIVATE
+/*
+ * The macro SAFE_CAST_PTR() casts one type of pointer to another type, making sure
+ * the data the pointer is referencing is the same size. If it is not, it will cause
+ * a division by zero compiler warning. This is to work around "SInt32" being defined
+ * as "long" on ILP32 and as "int" on LP64, which would require an explicit cast to
+ * "SInt32*" when for instance passing an "int*" to OSAddAtomic() - which masks size
+ * mismatches.
+ * -- var is used, but sizeof does not evaluate the
+ *    argument, i.e. we're safe against "++" etc. in var --
+ */
+#define __SAFE_CAST_PTR(type, var) (((type)(var))+(0/(sizeof(*var) == sizeof(*(type)0) ? 1 : 0)))
+#else
+#define __SAFE_CAST_PTR(type, var) ((type)(var))
+#endif

 
 

-    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.
-    @param mask The mask to logically or with the value.
-    @param address The 2-byte aligned address of the value to update atomically.
-    @result The value before the bitwise operation. */
+/*!
+ * @header
+ *
+ * @abstract
+ * This header declares the OSAtomic group of functions for atomic
+ * reading and updating of values.
+ */
+ 
+/*!
+ * @function OSCompareAndSwap64
+ *
+ * @abstract
+ * 64-bit compare and swap operation.
+ *
+ * @discussion
+ * See OSCompareAndSwap.
+ */
+extern Boolean OSCompareAndSwap64(
+    UInt64            oldValue,
+    UInt64            newValue,
+    volatile UInt64 * address);
+#define OSCompareAndSwap64(a, b, c) \
+       (OSCompareAndSwap64(a, b, __SAFE_CAST_PTR(volatile UInt64*,c)))
+
+/*!
+ * @function OSAddAtomic64
+ *
+ * @abstract
+ * 64-bit atomic add operation.
+ *
+ * @discussion
+ * See OSAddAtomic.
+ */
+extern SInt64 OSAddAtomic64(
+    SInt64            theAmount,
+    volatile SInt64 * address);
+#define OSAddAtomic64(a, b) \
+       (OSAddAtomic64(a, __SAFE_CAST_PTR(volatile SInt64*,b)))
+
+/*!
+ * @function OSIncrementAtomic64
+ *
+ * @abstract
+ * 64-bit increment.
+ *
+ * @discussion
+ * See OSIncrementAtomic.
+*/
+inline static SInt64 OSIncrementAtomic64(volatile SInt64 * address)
+{
+    return OSAddAtomic64(1LL, address);
+}

 
 

-extern UInt16  OSBitOrAtomic16(UInt32 mask, UInt16 * address);
+/*!
+ * @function OSDecrementAtomic64
+ *
+ * @abstract
+ * 64-bit decrement.
+ *
+ * @discussion
+ * See OSDecrementAtomic.
+*/
+inline static SInt64 OSDecrementAtomic64(volatile SInt64 * address)
+{
+    return OSAddAtomic64(-1LL, address);
+}

 
 

-/*! @function OSBitOrAtomic8
-    @abstract 8-bit logical or operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
+#if XNU_KERNEL_PRIVATE
+/* Not to be included in headerdoc.
+ *
+ * @function OSAddAtomicLong
+ *
+ * @abstract
+ * 32/64-bit atomic add operation, depending on sizeof(long).
+ *
+ * @discussion
+ * See OSAddAtomic.
+ */
+extern long OSAddAtomicLong(
+    long            theAmount,
+    volatile long * address);
+#define OSAddAtomicLong(a, b) \
+       (OSAddAtomicLong(a, __SAFE_CAST_PTR(volatile long*,b)))

 
 

-    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.
-    @discussion The OSBitOrAtomic8 function logically ors the bits of the specified mask into the value at the specified address and returns the result.
-    @param mask The mask to logically or with the value.
-    @param address The address of the value to update atomically.
-    @result The value before the bitwise operation. */
+/* Not to be included in headerdoc.
+ *
+ * @function OSIncrementAtomicLong
+ *
+ * @abstract
+ * 32/64-bit increment, depending on sizeof(long)
+ *
+ * @discussion
+ * See OSIncrementAtomic.
+*/
+inline static long OSIncrementAtomicLong(volatile long * address)
+{
+    return OSAddAtomicLong(1L, address);
+}

 
 

-extern UInt8   OSBitOrAtomic8(UInt32 mask, UInt8 * address);
+/* Not to be included in headerdoc.
+ *
+ * @function OSDecrementAtomicLong
+ *
+ * @abstract
+ * 32/64-bit decrement, depending on sizeof(long)
+ *@discussion See OSDecrementAtomic.
+ */
+inline static long OSDecrementAtomicLong(volatile long * address)
+{
+    return OSAddAtomicLong(-1L, address);
+}
+#endif /* XNU_KERNEL_PRIVATE */

 
 

-/*! @function OSBitXorAtomic
-    @abstract 32-bit logical xor operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
+#if XNU_KERNEL_PRIVATE
+/*!
+ * @function OSCompareAndSwap8
+ *
+ * @abstract
+ * Compare and swap operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
+ *
+ * @discussion
+ * The OSCompareAndSwap8 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. Additionally, this function incorporates a memory barrier on systems with weakly-ordered memory architectures.
+ *
+ * @param oldValue The value to compare at address.
+ * @param newValue The value to write to address if oldValue compares true.
+ * @param address The byte aligned address of the data to update atomically.
+ * @result true if newValue was written to the address.
+ */
+extern Boolean OSCompareAndSwap8(
+    UInt8            oldValue,
+    UInt8            newValue,
+    volatile UInt8 * address);
+#define OSCompareAndSwap8(a, b, c) \
+       (OSCompareAndSwap8(a, b, __SAFE_CAST_PTR(volatile UInt8*,c)))
+
+/*!
+ * @function OSCompareAndSwap16
+ *
+ * @abstract
+ * Compare and swap operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
+ *
+ * @discussion
+ * The OSCompareAndSwap16 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. Additionally, this function incorporates a memory barrier on systems with weakly-ordered memory architectures.
+ *
+ * @param oldValue The value to compare at address.
+ * @param newValue The value to write to address if oldValue compares true.
+ * @param address The 2-byte aligned address of the data to update atomically.
+ * @result true if newValue was written to the address.
+ */
+extern Boolean OSCompareAndSwap16(
+    UInt16            oldValue,
+    UInt16            newValue,
+    volatile UInt16 * address);
+#define OSCompareAndSwap16(a, b, c) \
+       (OSCompareAndSwap16(a, b, __SAFE_CAST_PTR(volatile UInt16*,c)))

 
 

-    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.
-    @discussion The OSBitXorAtomic function logically xors the bits of the specified mask into the value at the specified address and returns the result.
-    @param mask The mask to logically or with the value.
-    @param address The 4-byte aligned address of the value to update atomically.
-    @result The value before the bitwise operation. */
+#endif /* XNU_KERNEL_PRIVATE */

 
 

-extern UInt32  OSBitXorAtomic(UInt32 mask, UInt32 * address);
+/*!
+ * @function OSCompareAndSwap
+ *
+ * @abstract
+ * Compare and swap operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
+ *
+ * @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. Additionally, this function incorporates a memory barrier on systems with weakly-ordered memory architectures.
+ *
+ * @param oldValue The value to compare at address.
+ * @param newValue The value to write to address if oldValue compares true.
+ * @param address The 4-byte aligned address of the data to update atomically.
+ * @result true if newValue was written to the address.
+ */
+extern Boolean OSCompareAndSwap(
+    UInt32            oldValue,
+    UInt32            newValue,
+    volatile UInt32 * address);
+#define OSCompareAndSwap(a, b, c) \
+       (OSCompareAndSwap(a, b, __SAFE_CAST_PTR(volatile UInt32*,c)))
+
+/*!
+ * @function OSCompareAndSwapPtr
+ *
+ * @abstract
+ * Compare and swap operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
+ *
+ * @discussion
+ * The OSCompareAndSwapPtr function compares the pointer-sized 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. OSCompareAndSwapPtr 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. Additionally, this function incorporates a memory barrier on systems with weakly-ordered memory architectures.
+ * @param oldValue The pointer value to compare at address.
+ * @param newValue The pointer value to write to address if oldValue compares true.
+ * @param address The pointer-size aligned address of the data to update atomically.
+ * @result true if newValue was written to the address.
+ */
+extern Boolean OSCompareAndSwapPtr(
+    void            * oldValue,
+    void            * newValue,
+    void * volatile * address);
+#define OSCompareAndSwapPtr(a, b, c) \
+       (OSCompareAndSwapPtr(a, b, __SAFE_CAST_PTR(void * volatile *,c)))
+
+/*!
+ * @function OSAddAtomic
+ *
+ * @abstract
+ * 32-bit add operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
+ *
+ * @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. Previous incarnations of this function incorporated a memory barrier on systems with weakly-ordered memory architectures, but current versions contain no barriers.
+ * @param amount The amount to add.
+ * @param address The 4-byte aligned address of the value to update atomically.
+ * @result The value before the addition
+ */
+extern SInt32 OSAddAtomic(
+    SInt32            amount,
+    volatile SInt32 * address);
+#define OSAddAtomic(a, b) \
+       (OSAddAtomic(a, __SAFE_CAST_PTR(volatile SInt32*,b)))
+
+/*!
+ * @function OSAddAtomic16
+ *
+ * @abstract
+ * 16-bit add operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
+ *
+ * @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. Previous incarnations of this function incorporated a memory barrier on systems with weakly-ordered memory architectures, but current versions contain no barriers.
+ * @param address The 2-byte aligned address of the value to update atomically.
+ * @result The value before the addition
+ */
+extern SInt16 OSAddAtomic16(
+    SInt32            amount,
+    volatile SInt16 * address);

 
 

-/*! @function OSBitXorAtomic16
-    @abstract 16-bit logical xor operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
-    @discussion The OSBitXorAtomic16 function logically xors the bits of the specified mask into the value at the specified address and returns the result.
+/*!
+ * @function OSAddAtomic8
+ *
+ * @abstract
+ * 8-bit add operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
+ *
+ * @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. Previous incarnations of this function incorporated a memory barrier on systems with weakly-ordered memory architectures, but current versions contain no barriers.
+ * @param amount The amount to add.
+ * @param address The address of the value to update atomically.
+ * @result The value before the addition.
+ */
+extern SInt8 OSAddAtomic8(
+    SInt32           amount,
+    volatile SInt8 * address);

 
 

-    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.
-    @param mask The mask to logically or with the value.
-    @param address The 2-byte aligned address of the value to update atomically.
-    @result The value before the bitwise operation. */
+/*!
+ * @function OSIncrementAtomic
+ *
+ * @abstract
+ * 32-bit increment operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
+ *
+ * @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.
+ * @param address The 4-byte aligned address of the value to update atomically.
+ * @result The value before the increment.
+ */
+extern SInt32 OSIncrementAtomic(volatile SInt32 * address);
+#define OSIncrementAtomic(a) \
+       (OSIncrementAtomic(__SAFE_CAST_PTR(volatile SInt32*,a)))

 
 

-extern UInt16  OSBitXorAtomic16(UInt32 mask, UInt16 * address);
+/*!
+ * @function OSIncrementAtomic16
+ *
+ * @abstract
+ * 16-bit increment operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
+ *
+ * @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. Previous incarnations of this function incorporated a memory barrier on systems with weakly-ordered memory architectures, but current versions contain no barriers.
+ * @param address The 2-byte aligned address of the value to update atomically.
+ * @result The value before the increment.
+ */
+extern SInt16 OSIncrementAtomic16(volatile SInt16 * address);

 
 

-/*! @function OSBitXorAtomic8
-    @abstract 8-bit logical xor operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
+/*!
+ * @function OSIncrementAtomic8
+ *
+ * @abstract
+ * 8-bit increment operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
+ *
+ * @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. Previous incarnations of this function incorporated a memory barrier on systems with weakly-ordered memory architectures, but current versions contain no barriers.
+ * @param address The address of the value to update atomically.
+ * @result The value before the increment.
+ */
+extern SInt8 OSIncrementAtomic8(volatile SInt8 * address);

 
 

-    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.
-    @discussion The OSBitXorAtomic8 function logically xors the bits of the specified mask into the value at the specified address and returns the result.
-    @param mask The mask to logically or with the value.
-    @param address The address of the value to update atomically.
-    @result The value before the bitwise operation. */
+/*!
+ * @function OSDecrementAtomic
+ *
+ * @abstract
+ * 32-bit decrement operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
+ *
+ * @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. Previous incarnations of this function incorporated a memory barrier on systems with weakly-ordered memory architectures, but current versions contain no barriers.
+ * @param address The 4-byte aligned address of the value to update atomically.
+ * @result The value before the decrement.
+ */
+extern SInt32 OSDecrementAtomic(volatile SInt32 * address);
+#define OSDecrementAtomic(a) \
+       (OSDecrementAtomic(__SAFE_CAST_PTR(volatile SInt32*,a)))

 
 

-extern UInt8   OSBitXorAtomic8(UInt32 mask, UInt8 * address);
+/*!
+ * @function OSDecrementAtomic16
+ *
+ * @abstract
+ * 16-bit decrement operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
+ *
+ * @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. Previous incarnations of this function incorporated a memory barrier on systems with weakly-ordered memory architectures, but current versions contain no barriers.
+ * @param address The 2-byte aligned address of the value to update atomically.
+ * @result The value before the decrement.
+ */
+extern SInt16 OSDecrementAtomic16(volatile SInt16 * address);

 
 

-/*! @function OSTestAndSet
-    @abstract Bit test and set operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
+/*!
+ * @function OSDecrementAtomic8
+ *
+ * @abstract
+ * 8-bit decrement operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
+ *
+ * @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. Previous incarnations of this function incorporated a memory barrier on systems with weakly-ordered memory architectures, but current versions contain no barriers.
+ * @param address The address of the value to update atomically.
+ * @result The value before the decrement.
+ */
+extern SInt8 OSDecrementAtomic8(volatile SInt8 * address);

 
 

-    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.
-    @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.
-    @param bit The bit number in the range 0 through 7.
-    @param address The address of the byte to update atomically.
-    @result true if the bit was already set, false otherwise. */
+/*!
+ * @function OSBitAndAtomic
+ *
+ * @abstract
+ * 32-bit logical and operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
+ *
+ * @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. Previous incarnations of this function incorporated a memory barrier on systems with weakly-ordered memory architectures, but current versions contain no barriers..
+ * @param mask The mask to logically and with the value.
+ * @param address The 4-byte aligned address of the value to update atomically.
+ * @result The value before the bitwise operation
+ */
+extern UInt32 OSBitAndAtomic(
+    UInt32            mask,
+    volatile UInt32 * address);
+#define OSBitAndAtomic(a, b) \
+       (OSBitAndAtomic(a, __SAFE_CAST_PTR(volatile UInt32*,b)))
+
+/*!
+ * @function OSBitAndAtomic16
+ *
+ * @abstract
+ * 16-bit logical and operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
+ *
+ * @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.
+ * @param mask The mask to logically and with the value.
+ * @param address The 2-byte aligned address of the value to update atomically.
+ * @result The value before the bitwise operation.
+ */
+extern UInt16 OSBitAndAtomic16(
+    UInt32            mask,
+    volatile UInt16 * address);

 
 

-extern Boolean OSTestAndSet(UInt32 bit, UInt8 * startAddress);
+/*!
+ * @function OSBitAndAtomic8
+ *
+ * @abstract
+ * 8-bit logical and operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
+ *
+ * @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.
+ * @param mask The mask to logically and with the value.
+ * @param address The address of the value to update atomically.
+ * @result The value before the bitwise operation.
+ */
+extern UInt8 OSBitAndAtomic8(
+    UInt32           mask,
+    volatile UInt8 * address);

 
 

-/*! @function OSTestAndClear
-    @abstract Bit test and clear operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
-    @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.
+/*!
+ * @function OSBitOrAtomic
+ *
+ * @abstract
+ * 32-bit logical or operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
+ *
+ * @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.
+ * @param mask The mask to logically or with the value.
+ * @param address The 4-byte aligned address of the value to update atomically.
+ * @result The value before the bitwise operation.
+ */
+extern UInt32 OSBitOrAtomic(
+    UInt32            mask,
+    volatile UInt32 * address);
+#define OSBitOrAtomic(a, b) \
+       (OSBitOrAtomic(a, __SAFE_CAST_PTR(volatile UInt32*,b)))
+
+/*!
+ * @function OSBitOrAtomic16
+ *
+ * @abstract
+ * 16-bit logical or operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
+ *
+ * @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.
+ * @param mask The mask to logically or with the value.
+ * @param address The 2-byte aligned address of the value to update atomically.
+ * @result The value before the bitwise operation.
+ */
+extern UInt16 OSBitOrAtomic16(
+    UInt32            mask,
+    volatile UInt16 * address);

 
 

-    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.
-    @param bit The bit number in the range 0 through 7.
-    @param address The address of the byte to update atomically.
-    @result true if the bit was already clear, false otherwise. */
+/*!
+ * @function OSBitOrAtomic8
+ *
+ * @abstract
+ * 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.
+ *
+ * @discussion
+ * The OSBitOrAtomic8 function logically ors the bits of the specified mask into the value at the specified address and returns the original value.
+ * @param mask The mask to logically or with the value.
+ * @param address The address of the value to update atomically.
+ * @result The value before the bitwise operation.
+ */
+extern UInt8 OSBitOrAtomic8(
+    UInt32           mask,
+    volatile UInt8 * address);

 
 

-extern Boolean OSTestAndClear(UInt32 bit, UInt8 * startAddress);
+/*!
+ * @function OSBitXorAtomic
+ *
+ * @abstract
+ * 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.
+ *
+ * @discussion
+ * The OSBitXorAtomic function logically xors the bits of the specified mask into the value at the specified address and returns the original value.
+ * @param mask The mask to logically or with the value.
+ * @param address The 4-byte aligned address of the value to update atomically.
+ * @result The value before the bitwise operation.
+ */
+extern UInt32 OSBitXorAtomic(
+    UInt32            mask,
+    volatile UInt32 * address);
+#define OSBitXorAtomic(a, b) \
+       (OSBitXorAtomic(a, __SAFE_CAST_PTR(volatile UInt32*,b)))
+
+/*!
+ * @function OSBitXorAtomic16
+ *
+ * @abstract
+ * 16-bit logical xor operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
+ *
+ * @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.
+ * @param mask The mask to logically or with the value.
+ * @param address The 2-byte aligned address of the value to update atomically.
+ * @result The value before the bitwise operation.
+ */
+extern UInt16 OSBitXorAtomic16(
+    UInt32            mask,
+    volatile UInt16 * address);

 
 

-/*! @function OSEnqueueAtomic
-    @abstract Singly linked list head insertion, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
-    @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.
+/*!
+ * @function OSBitXorAtomic8
+ *
+ * @abstract
+ * 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.
+ *
+ * @discussion
+ * The OSBitXorAtomic8 function logically xors the bits of the specified mask into the value at the specified address and returns the original value.
+ * @param mask The mask to logically or with the value.
+ * @param address The address of the value to update atomically.
+ * @result The value before the bitwise operation.
+ */
+extern UInt8 OSBitXorAtomic8(
+    UInt32           mask,
+    volatile UInt8 * address);

 
 

-    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.
-    @param listHead The address of a head pointer for the list .
-    @param element The list element to insert at the head of the list.
-    @param elementNextFieldOffset The byte offset into the element where a pointer to the next element in the list is stored. */
+/*!
+ * @function OSTestAndSet
+ *
+ * @abstract
+ * 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.
+ *
+ * @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.
+ * @param bit The bit number in the range 0 through 7. Bit 0 is the most significant.
+ * @param startAddress The address of the byte to update atomically.
+ * @result true if the bit was already set, false otherwise.
+ */
+extern Boolean OSTestAndSet(
+    UInt32           bit,
+    volatile UInt8 * startAddress);

 
 

-extern void    OSEnqueueAtomic(void ** listHead, void * element,
-                               SInt32 elementNextFieldOffset);
+/*!
+ * @function OSTestAndClear
+ *
+ * @abstract
+ * Bit test and clear operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
+ *
+ * @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.
+ * @param bit The bit number in the range 0 through 7. Bit 0 is the most significant.
+ * @param startAddress The address of the byte to update atomically.
+ * @result true if the bit was already clear, false otherwise.
+ */
+extern Boolean OSTestAndClear(
+    UInt32           bit,
+    volatile UInt8 * startAddress);

 
 

-/*! @function OSDequeueAtomic
-    @abstract Singly linked list element head removal, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
-    @discussion 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.
+/*!
+ * @defined OS_SPINLOCK_INIT
+ *
+ * @abstract
+ * The default value for an OSSpinLock.
+ *
+ * @discussion
+ * The convention is that unlocked is zero, locked is nonzero.
+ */
+#define        OS_SPINLOCK_INIT 0

 
 

-    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.
-    @param listHead The address of a head pointer for the list .
-    @param 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. */
+/*! 
+ * @typedef OSSpinLock
+ *
+ * @abstract
+ * Data type for a spinlock.
+ *
+ * @discussion
+ * You should always initialize a spinlock to OS_SPINLOCK_INIT before using it.
+ */
+typedef SInt32 OSSpinLock;

 
 

-extern void *  OSDequeueAtomic(void ** listHead,
-                               SInt32 elementNextFieldOffset);
+#ifdef PRIVATE
+/*!
+ * @function OSSpinLockTry
+ *
+ * @abstract
+ * Locks a spinlock if it would not block.
+ *
+ * @discussion
+ * Multiprocessor locks used within the shared memory area between the kernel and event system.  These must work in both user and kernel mode.
+ *
+ * @result
+ * Returns false if the lock was already held by another thread, true if it took the lock successfully. 
+ */
+extern Boolean OSSpinLockTry(volatile OSSpinLock * lock);

 
 

-/*! @function OSSynchronizeIO
-    @abstract The OSSynchronizeIO routine ensures orderly load and store operations to noncached memory mapped I/O devices.
-    @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. */
+/*!
+ * @function OSSpinLockUnlock
+ *
+ * @abstract
+ * Unlocks a spinlock.
+ *
+ * @discussion
+ * Unlocks a spinlock.
+ */
+extern void OSSpinLockUnlock(volatile OSSpinLock * lock);
+#endif /* PRIVATE */

 
 

+/*!
+ * @function OSSynchronizeIO
+ *
+ * @abstract
+ * The OSSynchronizeIO routine ensures orderly load and store operations to noncached memory mapped I/O devices.
+ *
+ * @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.
+ */
+#if defined(__arm__) || defined(__arm64__)
+extern void OSSynchronizeIO(void);
+#else

 static __inline__ void OSSynchronizeIO(void)
 {
 static __inline__ void OSSynchronizeIO(void)
 {

-#if defined(__ppc__)
-        __asm__ ("eieio");
+}

 #endif
 #endif

+
+#if    defined(KERNEL_PRIVATE)
+
+#if    defined(__arm__) || defined(__arm64__)
+static inline void OSMemoryBarrier(void) {
+       __asm__ volatile("dmb ish" ::: "memory");

 }
 }

+#elif defined(__i386__) || defined(__x86_64__)
+#if    defined(XNU_KERNEL_PRIVATE)
+static inline void OSMemoryBarrier(void) {
+       __asm__ volatile("mfence" ::: "memory");
+}
+#endif /* XNU_KERNEL_PRIVATE */
+#endif
+
+#endif /* KERNEL_PRIVATE */

 
 #if defined(__cplusplus)
 }
 
 #if defined(__cplusplus)
 }