2 * Copyright (c) 2000 Apple Computer, Inc. All rights reserved.
4 * @APPLE_LICENSE_HEADER_START@
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.
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
20 * @APPLE_LICENSE_HEADER_END@
23 * Copyright (c) 1999 Apple Computer, Inc. All rights reserved.
29 #ifndef _OS_OSATOMIC_H
30 #define _OS_OSATOMIC_H
32 #include <libkern/OSBase.h>
34 #if defined(__cplusplus)
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 @param oldValue The value to compare at address.
42 @param newValue The value to write to address if oldValue compares true.
43 @param address The 4-byte aligned address of the data to update atomically.
44 @result true if newValue was written to the address. */
46 extern Boolean
OSCompareAndSwap( UInt32 oldValue
, UInt32 newValue
, UInt32
* address
);
48 /*! @function OSAddAtomic
49 @abstract 32-bit add operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
50 @discussion The OSAddAtomic function adds the specified amount to the value at the specified address and returns the result.
51 @param amount The amount to add.
52 @param address The 4-byte aligned address of the value to update atomically.
53 @result The result of the addition. */
55 extern SInt32
OSAddAtomic(SInt32 amount
, SInt32
* address
);
57 /*! @function OSAddAtomic16
58 @abstract 16-bit add operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
59 @discussion The OSAddAtomic16 function adds the specified amount to the value at the specified address and returns the result.
60 @param amount The amount to add.
61 @param address The 2-byte aligned address of the value to update atomically.
62 @result The result of the addition. */
64 extern SInt16
OSAddAtomic16(SInt32 amount
, SInt16
* address
);
66 /*! @function OSAddAtomic8
67 @abstract 8-bit add operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
68 @discussion The OSAddAtomic8 function adds the specified amount to the value at the specified address and returns the result.
69 @param amount The amount to add.
70 @param address The address of the value to update atomically.
71 @result The result of the addition. */
73 extern SInt8
OSAddAtomic8(SInt32 amount
, SInt8
* address
);
75 /*! @function OSIncrementAtomic
76 @abstract 32-bit increment operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
77 @discussion The OSIncrementAtomic function increments the value at the specified address by one and returns the value as it was before the change.
78 @param address The 4-byte aligned address of the value to update atomically.
79 @result The value before the increment. */
81 extern SInt32
OSIncrementAtomic(SInt32
* address
);
83 /*! @function OSIncrementAtomic16
84 @abstract 16-bit increment operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
85 @discussion The OSIncrementAtomic16 function increments the value at the specified address by one and returns the value as it was before the change.
86 @param address The 2-byte aligned address of the value to update atomically.
87 @result The value before the increment. */
89 extern SInt16
OSIncrementAtomic16(SInt16
* address
);
91 /*! @function OSIncrementAtomic8
92 @abstract 8-bit increment operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
93 @discussion The OSIncrementAtomic8 function increments the value at the specified address by one and returns the value as it was before the change.
94 @param address The address of the value to update atomically.
95 @result The value before the increment. */
97 extern SInt8
OSIncrementAtomic8(SInt8
* address
);
99 /*! @function OSDecrementAtomic
100 @abstract 32-bit decrement operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
101 @discussion The OSDecrementAtomic function decrements the value at the specified address by one and returns the value as it was before the change.
102 @param address The 4-byte aligned address of the value to update atomically.
103 @result The value before the decrement. */
105 extern SInt32
OSDecrementAtomic(SInt32
* address
);
107 /*! @function OSDecrementAtomic16
108 @abstract 16-bit decrement operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
109 @discussion The OSDecrementAtomic16 function decrements the value at the specified address by one and returns the value as it was before the change.
110 @param address The 2-byte aligned address of the value to update atomically.
111 @result The value before the decrement. */
113 extern SInt16
OSDecrementAtomic16(SInt16
* address
);
115 /*! @function OSDecrementAtomic8
116 @abstract 8-bit decrement operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
117 @discussion The OSDecrementAtomic8 function decrements the value at the specified address by one and returns the value as it was before the change.
118 @param address The address of the value to update atomically.
119 @result The value before the decrement. */
121 extern SInt8
OSDecrementAtomic8(SInt8
* address
);
123 /*! @function OSBitAndAtomic
124 @abstract 32-bit logical and operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
125 @discussion The OSBitAndAtomic function logically ands the bits of the specified mask into the value at the specified address and returns the result.
126 @param mask The mask to logically and with the value.
127 @param address The 4-byte aligned address of the value to update atomically.
128 @result The result of the logical and. */
130 extern UInt32
OSBitAndAtomic(UInt32 mask
, UInt32
* address
);
132 /*! @function OSBitAndAtomic16
133 @abstract 16-bit logical and operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
134 @discussion The OSBitAndAtomic16 function logically ands the bits of the specified mask into the value at the specified address and returns the result.
135 @param mask The mask to logically and with the value.
136 @param address The 2-byte aligned address of the value to update atomically.
137 @result The result of the logical and. */
139 extern UInt16
OSBitAndAtomic16(UInt32 mask
, UInt16
* address
);
141 /*! @function OSBitAndAtomic8
142 @abstract 8-bit logical and operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
143 @discussion The OSBitAndAtomic8 function logically ands the bits of the specified mask into the value at the specified address and returns the result.
144 @param mask The mask to logically and with the value.
145 @param address The address of the value to update atomically.
146 @result The result of the logical and. */
148 extern UInt8
OSBitAndAtomic8(UInt32 mask
, UInt8
* address
);
150 /*! @function OSBitOrAtomic
151 @abstract 32-bit logical or operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
152 @discussion The OSBitOrAtomic function logically ors the bits of the specified mask into the value at the specified address and returns the result.
153 @param mask The mask to logically or with the value.
154 @param address The 4-byte aligned address of the value to update atomically.
155 @result The result of the logical or. */
157 extern UInt32
OSBitOrAtomic(UInt32 mask
, UInt32
* address
);
159 /*! @function OSBitOrAtomic16
160 @abstract 16-bit logical or operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
161 @discussion The OSBitOrAtomic16 function logically ors the bits of the specified mask into the value at the specified address and returns the result.
162 @param mask The mask to logically or with the value.
163 @param address The 2-byte aligned address of the value to update atomically.
164 @result The result of the logical or. */
166 extern UInt16
OSBitOrAtomic16(UInt32 mask
, UInt16
* address
);
168 /*! @function OSBitOrAtomic8
169 @abstract 8-bit logical or operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
170 @discussion The OSBitOrAtomic8 function logically ors the bits of the specified mask into the value at the specified address and returns the result.
171 @param mask The mask to logically or with the value.
172 @param address The address of the value to update atomically.
173 @result The result of the logical or. */
175 extern UInt8
OSBitOrAtomic8(UInt32 mask
, UInt8
* address
);
177 /*! @function OSBitXorAtomic
178 @abstract 32-bit logical xor operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
179 @discussion The OSBitXorAtomic function logically xors the bits of the specified mask into the value at the specified address and returns the result.
180 @param mask The mask to logically or with the value.
181 @param address The 4-byte aligned address of the value to update atomically.
182 @result The result of the logical xor. */
184 extern UInt32
OSBitXorAtomic(UInt32 mask
, UInt32
* address
);
186 /*! @function OSBitXorAtomic16
187 @abstract 16-bit logical xor operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
188 @discussion The OSBitXorAtomic16 function logically xors the bits of the specified mask into the value at the specified address and returns the result.
189 @param mask The mask to logically or with the value.
190 @param address The 2-byte aligned address of the value to update atomically.
191 @result The result of the logical xor. */
193 extern UInt16
OSBitXorAtomic16(UInt32 mask
, UInt16
* address
);
195 /*! @function OSBitXorAtomic8
196 @abstract 8-bit logical xor operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
197 @discussion The OSBitXorAtomic8 function logically xors the bits of the specified mask into the value at the specified address and returns the result.
198 @param mask The mask to logically or with the value.
199 @param address The address of the value to update atomically.
200 @result The result of the logical xor. */
202 extern UInt8
OSBitXorAtomic8(UInt32 mask
, UInt8
* address
);
204 /*! @function OSTestAndSet
205 @abstract Bit test and set operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
206 @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.
207 @param bit The bit number in the range 0 through 7.
208 @param address The address of the byte to update atomically.
209 @result true if the bit was already set, false otherwise. */
211 extern Boolean
OSTestAndSet(UInt32 bit
, UInt8
* startAddress
);
213 /*! @function OSTestAndClear
214 @abstract Bit test and clear operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
215 @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.
216 @param bit The bit number in the range 0 through 7.
217 @param address The address of the byte to update atomically.
218 @result true if the bit was already clear, false otherwise. */
220 extern Boolean
OSTestAndClear(UInt32 bit
, UInt8
* startAddress
);
222 /*! @function OSEnqueueAtomic
223 @abstract Singly linked list head insertion, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
224 @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.
225 @param listHead The address of a head pointer for the list .
226 @param element The list element to insert at the head of the list.
227 @param elementNextFieldOffset The byte offset into the element where a pointer to the next element in the list is stored. */
229 extern void OSEnqueueAtomic(void ** listHead
, void * element
,
230 SInt32 elementNextFieldOffset
);
232 /*! @function OSDequeueAtomic
233 @abstract Singly linked list element head removal, performed atomically with respect to all devices that participate in the coherency architecture of the platform.
234 @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.
235 @param listHead The address of a head pointer for the list .
236 @param elementNextFieldOffset The byte offset into the element where a pointer to the next element in the list is stored.
237 @result A removed element, or zero if the list is empty. */
239 extern void * OSDequeueAtomic(void ** listHead
,
240 SInt32 elementNextFieldOffset
);
242 /*! @function OSSynchronizeIO
243 @abstract The OSSynchronizeIO routine ensures orderly load and store operations to noncached memory mapped I/O devices.
244 @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. */
246 static __inline__
void OSSynchronizeIO(void)
253 #if defined(__cplusplus)
257 #endif /* ! _OS_OSATOMIC_H */