]> git.saurik.com Git - apple/xnu.git/blob - libkern/libkern/OSAtomic.h
cb03381566c4d8035fccf2956aac12daa4780fcf
[apple/xnu.git] / libkern / libkern / OSAtomic.h
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 @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. */
45
46 extern Boolean OSCompareAndSwap( UInt32 oldValue, UInt32 newValue, UInt32 * address );
47
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. */
54
55 extern SInt32 OSAddAtomic(SInt32 amount, SInt32 * address);
56
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. */
63
64 extern SInt16 OSAddAtomic16(SInt32 amount, SInt16 * address);
65
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. */
72
73 extern SInt8 OSAddAtomic8(SInt32 amount, SInt8 * address);
74
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. */
80
81 extern SInt32 OSIncrementAtomic(SInt32 * address);
82
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. */
88
89 extern SInt16 OSIncrementAtomic16(SInt16 * address);
90
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. */
96
97 extern SInt8 OSIncrementAtomic8(SInt8 * address);
98
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. */
104
105 extern SInt32 OSDecrementAtomic(SInt32 * address);
106
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. */
112
113 extern SInt16 OSDecrementAtomic16(SInt16 * address);
114
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. */
120
121 extern SInt8 OSDecrementAtomic8(SInt8 * address);
122
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. */
129
130 extern UInt32 OSBitAndAtomic(UInt32 mask, UInt32 * address);
131
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. */
138
139 extern UInt16 OSBitAndAtomic16(UInt32 mask, UInt16 * address);
140
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. */
147
148 extern UInt8 OSBitAndAtomic8(UInt32 mask, UInt8 * address);
149
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. */
156
157 extern UInt32 OSBitOrAtomic(UInt32 mask, UInt32 * address);
158
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. */
165
166 extern UInt16 OSBitOrAtomic16(UInt32 mask, UInt16 * address);
167
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. */
174
175 extern UInt8 OSBitOrAtomic8(UInt32 mask, UInt8 * address);
176
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. */
183
184 extern UInt32 OSBitXorAtomic(UInt32 mask, UInt32 * address);
185
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. */
192
193 extern UInt16 OSBitXorAtomic16(UInt32 mask, UInt16 * address);
194
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. */
201
202 extern UInt8 OSBitXorAtomic8(UInt32 mask, UInt8 * address);
203
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. */
210
211 extern Boolean OSTestAndSet(UInt32 bit, UInt8 * startAddress);
212
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. */
219
220 extern Boolean OSTestAndClear(UInt32 bit, UInt8 * startAddress);
221
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. */
228
229 extern void OSEnqueueAtomic(void ** listHead, void * element,
230 SInt32 elementNextFieldOffset);
231
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. */
238
239 extern void * OSDequeueAtomic(void ** listHead,
240 SInt32 elementNextFieldOffset);
241
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. */
245
246 static __inline__ void OSSynchronizeIO(void)
247 {
248 #if defined(__ppc__)
249 __asm__ ("eieio");
250 #endif
251 }
252
253 #if defined(__cplusplus)
254 }
255 #endif
256
257 #endif /* ! _OS_OSATOMIC_H */