libkern/libkern/OSAtomic.h.save

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