libkern/libkern/OSAtomic.h

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