libkern/libkern/OSAtomic.h

   1 /*
   2  * Copyright (c) 2000 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
   5  *
   6  * This file contains Original Code and/or Modifications of Original Code
   7  * as defined in and that are subject to the Apple Public Source License
   8  * Version 2.0 (the 'License'). You may not use this file except in
   9  * compliance with the License. The rights granted to you under the License
  10  * may not be used to create, or enable the creation or redistribution of,
  11  * unlawful or unlicensed copies of an Apple operating system, or to
  12  * circumvent, violate, or enable the circumvention or violation of, any
  13  * terms of an Apple operating system software license agreement.
  14  *
  15  * Please obtain a copy of the License at
  16  * http://www.opensource.apple.com/apsl/ and read it before using this file.
  17  *
  18  * The Original Code and all software distributed under the License are
  19  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  20  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  21  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  22  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  23  * Please see the License for the specific language governing rights and
  24  * limitations under the License.
  25  *
  26  * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
  27  */
  28 /*
  29  * Copyright (c) 1999 Apple Computer, Inc.  All rights reserved.
  30  *
  31  * HISTORY
  32  *
  33  */
  34
  35 #ifndef _OS_OSATOMIC_H
  36 #define _OS_OSATOMIC_H
  37
  38 #include <libkern/OSBase.h>
  39
  40 #if defined(__cplusplus)
  41 extern "C" {
  42 #endif
  43
  44 /*! @function OSCompareAndSwap
  45     @abstract Compare and swap operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
  46     @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.
  47
  48     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.
  49     @param oldValue The value to compare at address.
  50     @param newValue The value to write to address if oldValue compares true.
  51     @param address The 4-byte aligned address of the data to update atomically.
  52     @result true if newValue was written to the address. */
  53
  54 extern Boolean OSCompareAndSwap( UInt32 oldValue, UInt32 newValue, UInt32 * address );
  55
  56 /*! @function OSAddAtomic
  57     @abstract 32-bit add operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
  58     @discussion The OSAddAtomic function adds the specified amount to the value at the specified address and returns the original value.
  59
  60     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.
  61     @param amount The amount to add.
  62     @param address The 4-byte aligned address of the value to update atomically.
  63     @result The value before the addition */
  64
  65 extern SInt32   OSAddAtomic(SInt32 amount, SInt32 * address);
  66
  67 /*! @function OSAddAtomic16
  68     @abstract 16-bit add operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
  69     @discussion The OSAddAtomic16 function adds the specified amount to the value at the specified address and returns the original value.
  70
  71     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.
  72     @param amount The amount to add.
  73     @param address The 2-byte aligned address of the value to update atomically.
  74     @result The value before the addition */
  75
  76 extern SInt16   OSAddAtomic16(SInt32 amount, SInt16 * address);
  77
  78 /*! @function OSAddAtomic8
  79     @abstract 8-bit add operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
  80     @discussion The OSAddAtomic8 function adds the specified amount to the value at the specified address and returns the original value.
  81
  82     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.
  83     @param amount The amount to add.
  84     @param address The address of the value to update atomically.
  85     @result The value before the addition */
  86
  87 extern SInt8    OSAddAtomic8(SInt32 amount, SInt8 * address);
  88
  89 /*! @function OSIncrementAtomic
  90     @abstract 32-bit increment operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
  91     @discussion The OSIncrementAtomic function increments the value at the specified address by one and returns the original value.
  92
  93     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.
  94     @param address The 4-byte aligned address of the value to update atomically.
  95     @result The value before the increment. */
  96
  97 extern SInt32   OSIncrementAtomic(SInt32 * address);
  98
  99 /*! @function OSIncrementAtomic16
 100     @abstract 16-bit increment operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
 101     @discussion The OSIncrementAtomic16 function increments the value at the specified address by one and returns the original value.
 102
 103     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.
 104     @param address The 2-byte aligned address of the value to update atomically.
 105     @result The value before the increment. */
 106
 107 extern SInt16   OSIncrementAtomic16(SInt16 * address);
 108
 109 /*! @function OSIncrementAtomic8
 110     @abstract 8-bit increment operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
 111     @discussion The OSIncrementAtomic8 function increments the value at the specified address by one and returns the original value.
 112
 113     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.
 114     @param address The address of the value to update atomically.
 115     @result The value before the increment. */
 116
 117 extern SInt8    OSIncrementAtomic8(SInt8 * address);
 118
 119 /*! @function OSDecrementAtomic
 120     @abstract 32-bit decrement operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
 121     @discussion The OSDecrementAtomic function decrements the value at the specified address by one and returns the original value.
 122
 123     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.
 124     @param address The 4-byte aligned address of the value to update atomically.
 125     @result The value before the decrement. */
 126
 127 extern SInt32   OSDecrementAtomic(SInt32 * address);
 128
 129 /*! @function OSDecrementAtomic16
 130     @abstract 16-bit decrement operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
 131     @discussion The OSDecrementAtomic16 function decrements the value at the specified address by one and returns the original value.
 132
 133     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.
 134     @param address The 2-byte aligned address of the value to update atomically.
 135     @result The value before the decrement. */
 136
 137 extern SInt16   OSDecrementAtomic16(SInt16 * address);
 138
 139 /*! @function OSDecrementAtomic8
 140     @abstract 8-bit decrement operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
 141     @discussion The OSDecrementAtomic8 function decrements the value at the specified address by one and returns the original value.
 142
 143     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.
 144     @param address The address of the value to update atomically.
 145     @result The value before the decrement. */
 146
 147 extern SInt8    OSDecrementAtomic8(SInt8 * address);
 148
 149 /*! @function OSBitAndAtomic
 150     @abstract 32-bit logical and operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
 151     @discussion The OSBitAndAtomic function logically ands the bits of the specified mask into the value at the specified address and returns the original value.
 152
 153     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.
 154     @param mask The mask to logically and with the value.
 155     @param address The 4-byte aligned address of the value to update atomically.
 156     @result The value before the bitwise operation */
 157
 158 extern UInt32   OSBitAndAtomic(UInt32 mask, UInt32 * address);
 159
 160 /*! @function OSBitAndAtomic16
 161     @abstract 16-bit logical and operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
 162     @discussion The OSBitAndAtomic16 function logically ands the bits of the specified mask into the value at the specified address and returns the original value.
 163
 164     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.
 165     @param mask The mask to logically and with the value.
 166     @param address The 2-byte aligned address of the value to update atomically.
 167     @result The value before the bitwise operation. */
 168
 169 extern UInt16   OSBitAndAtomic16(UInt32 mask, UInt16 * address);
 170
 171 /*! @function OSBitAndAtomic8
 172     @abstract 8-bit logical and operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
 173     @discussion The OSBitAndAtomic8 function logically ands the bits of the specified mask into the value at the specified address and returns the original value.
 174
 175     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.
 176     @param mask The mask to logically and with the value.
 177     @param address The address of the value to update atomically.
 178     @result The value before the bitwise operation. */
 179
 180 extern UInt8    OSBitAndAtomic8(UInt32 mask, UInt8 * address);
 181
 182 /*! @function OSBitOrAtomic
 183     @abstract 32-bit logical or operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
 184     @discussion The OSBitOrAtomic function logically ors the bits of the specified mask into the value at the specified address and returns the original value.
 185
 186     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.
 187     @param mask The mask to logically or with the value.
 188     @param address The 4-byte aligned address of the value to update atomically.
 189     @result The value before the bitwise operation. */
 190
 191 extern UInt32   OSBitOrAtomic(UInt32 mask, UInt32 * address);
 192
 193 /*! @function OSBitOrAtomic16
 194     @abstract 16-bit logical or operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
 195     @discussion The OSBitOrAtomic16 function logically ors the bits of the specified mask into the value at the specified address and returns the original value.
 196
 197     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.
 198     @param mask The mask to logically or with the value.
 199     @param address The 2-byte aligned address of the value to update atomically.
 200     @result The value before the bitwise operation. */
 201
 202 extern UInt16   OSBitOrAtomic16(UInt32 mask, UInt16 * address);
 203
 204 /*! @function OSBitOrAtomic8
 205     @abstract 8-bit logical or operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
 206
 207     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.
 208     @discussion The OSBitOrAtomic8 function logically ors the bits of the specified mask into the value at the specified address and returns the original value.
 209     @param mask The mask to logically or with the value.
 210     @param address The address of the value to update atomically.
 211     @result The value before the bitwise operation. */
 212
 213 extern UInt8    OSBitOrAtomic8(UInt32 mask, UInt8 * address);
 214
 215 /*! @function OSBitXorAtomic
 216     @abstract 32-bit logical xor operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
 217
 218     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.
 219     @discussion The OSBitXorAtomic function logically xors the bits of the specified mask into the value at the specified address and returns the original value.
 220     @param mask The mask to logically or with the value.
 221     @param address The 4-byte aligned address of the value to update atomically.
 222     @result The value before the bitwise operation. */
 223
 224 extern UInt32   OSBitXorAtomic(UInt32 mask, UInt32 * address);
 225
 226 /*! @function OSBitXorAtomic16
 227     @abstract 16-bit logical xor operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
 228     @discussion The OSBitXorAtomic16 function logically xors the bits of the specified mask into the value at the specified address and returns the original value.
 229
 230     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.
 231     @param mask The mask to logically or with the value.
 232     @param address The 2-byte aligned address of the value to update atomically.
 233     @result The value before the bitwise operation. */
 234
 235 extern UInt16   OSBitXorAtomic16(UInt32 mask, UInt16 * address);
 236
 237 /*! @function OSBitXorAtomic8
 238     @abstract 8-bit logical xor operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
 239
 240     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.
 241     @discussion The OSBitXorAtomic8 function logically xors the bits of the specified mask into the value at the specified address and returns the original value.
 242     @param mask The mask to logically or with the value.
 243     @param address The address of the value to update atomically.
 244     @result The value before the bitwise operation. */
 245
 246 extern UInt8    OSBitXorAtomic8(UInt32 mask, UInt8 * address);
 247
 248 /*! @function OSTestAndSet
 249     @abstract Bit test and set operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
 250
 251     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.
 252     @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.
 253     @param bit The bit number in the range 0 through 7.
 254     @param address The address of the byte to update atomically.
 255     @result true if the bit was already set, false otherwise. */
 256
 257 extern Boolean  OSTestAndSet(UInt32 bit, UInt8 * startAddress);
 258
 259 /*! @function OSTestAndClear
 260     @abstract Bit test and clear operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
 261     @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.
 262
 263     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.
 264     @param bit The bit number in the range 0 through 7.
 265     @param address The address of the byte to update atomically.
 266     @result true if the bit was already clear, false otherwise. */
 267
 268 extern Boolean  OSTestAndClear(UInt32 bit, UInt8 * startAddress);
 269
 270 #ifdef __ppc__
 271 /*! @function OSEnqueueAtomic
 272     @abstract Singly linked list head insertion, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
 273     @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.
 274
 275     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.
 276     @param listHead The address of a head pointer for the list .
 277     @param element The list element to insert at the head of the list.
 278     @param elementNextFieldOffset The byte offset into the element where a pointer to the next element in the list is stored. */
 279
 280 extern void     OSEnqueueAtomic(void ** listHead, void * element,
 281                                 SInt32 elementNextFieldOffset);
 282
 283 /*! @function OSDequeueAtomic
 284     @abstract Singly linked list element head removal, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
 285     @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.
 286
 287     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.
 288     @param listHead The address of a head pointer for the list .
 289     @param elementNextFieldOffset The byte offset into the element where a pointer to the next element in the list is stored.
 290     @result A removed element, or zero if the list is empty. */
 291
 292 extern void *   OSDequeueAtomic(void ** listHead,
 293                                 SInt32 elementNextFieldOffset);
 294 #endif /* __ppc__ */
 295
 296 /*! @function OSSynchronizeIO
 297     @abstract The OSSynchronizeIO routine ensures orderly load and store operations to noncached memory mapped I/O devices.
 298     @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. */
 299
 300 static __inline__ void OSSynchronizeIO(void)
 301 {
 302 #if defined(__ppc__)
 303         __asm__ ("eieio");
 304 #endif
 305 }
 306
 307 #if defined(__cplusplus)
 308 }
 309 #endif
 310
 311 #endif /* ! _OS_OSATOMIC_H */