libkern/libkern/OSAtomic.h

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