1 /******************************************************************************
2  *
3  *   Copyright © International Business Machines  Corp., 2009
4  *
5  *   This program is free software;  you can redistribute it and/or modify
6  *   it under the terms of the GNU General Public License as published by
7  *   the Free Software Foundation; either version 2 of the License, or
8  *   (at your option) any later version.
9  *
10  * DESCRIPTION
11  *      Glibc independent futex library for testing kernel functionality.
12  *
13  * AUTHOR
14  *      Darren Hart <dvhart@linux.intel.com>
15  *
16  * HISTORY
17  *      2009-Nov-6: Initial version by Darren Hart <dvhart@linux.intel.com>
18  *
19  *****************************************************************************/
20 
21 #ifndef _FUTEXTEST_H
22 #define _FUTEXTEST_H
23 
24 #include <unistd.h>
25 #include <sys/syscall.h>
26 #include <sys/types.h>
27 #include <linux/futex.h>
28 
29 typedef volatile u_int32_t futex_t;
30 #define FUTEX_INITIALIZER 0
31 
32 /* Define the newer op codes if the system header file is not up to date. */
33 #ifndef FUTEX_WAIT_BITSET
34 #define FUTEX_WAIT_BITSET		9
35 #endif
36 #ifndef FUTEX_WAKE_BITSET
37 #define FUTEX_WAKE_BITSET		10
38 #endif
39 #ifndef FUTEX_WAIT_REQUEUE_PI
40 #define FUTEX_WAIT_REQUEUE_PI		11
41 #endif
42 #ifndef FUTEX_CMP_REQUEUE_PI
43 #define FUTEX_CMP_REQUEUE_PI		12
44 #endif
45 #ifndef FUTEX_WAIT_REQUEUE_PI_PRIVATE
46 #define FUTEX_WAIT_REQUEUE_PI_PRIVATE	(FUTEX_WAIT_REQUEUE_PI | \
47 					 FUTEX_PRIVATE_FLAG)
48 #endif
49 #ifndef FUTEX_REQUEUE_PI_PRIVATE
50 #define FUTEX_CMP_REQUEUE_PI_PRIVATE	(FUTEX_CMP_REQUEUE_PI | \
51 					 FUTEX_PRIVATE_FLAG)
52 #endif
53 
54 /**
55  * futex() - SYS_futex syscall wrapper
56  * @uaddr:	address of first futex
57  * @op:		futex op code
58  * @val:	typically expected value of uaddr, but varies by op
59  * @timeout:	typically an absolute struct timespec (except where noted
60  *              otherwise). Overloaded by some ops
61  * @uaddr2:	address of second futex for some ops\
62  * @val3:	varies by op
63  * @opflags:	flags to be bitwise OR'd with op, such as FUTEX_PRIVATE_FLAG
64  *
65  * futex() is used by all the following futex op wrappers. It can also be
66  * used for misuse and abuse testing. Generally, the specific op wrappers
67  * should be used instead. It is a macro instead of an static inline function as
68  * some of the types over overloaded (timeout is used for nr_requeue for
69  * example).
70  *
71  * These argument descriptions are the defaults for all
72  * like-named arguments in the following wrappers except where noted below.
73  */
74 #define futex(uaddr, op, val, timeout, uaddr2, val3, opflags) \
75 	syscall(SYS_futex, uaddr, op | opflags, val, timeout, uaddr2, val3)
76 
77 /**
78  * futex_wait() - block on uaddr with optional timeout
79  * @timeout:	relative timeout
80  */
81 static inline int
82 futex_wait(futex_t *uaddr, futex_t val, struct timespec *timeout, int opflags)
83 {
84 	return futex(uaddr, FUTEX_WAIT, val, timeout, NULL, 0, opflags);
85 }
86 
87 /**
88  * futex_wake() - wake one or more tasks blocked on uaddr
89  * @nr_wake:	wake up to this many tasks
90  */
91 static inline int
92 futex_wake(futex_t *uaddr, int nr_wake, int opflags)
93 {
94 	return futex(uaddr, FUTEX_WAKE, nr_wake, NULL, NULL, 0, opflags);
95 }
96 
97 /**
98  * futex_wait_bitset() - block on uaddr with bitset
99  * @bitset:	bitset to be used with futex_wake_bitset
100  */
101 static inline int
102 futex_wait_bitset(futex_t *uaddr, futex_t val, struct timespec *timeout,
103 		  u_int32_t bitset, int opflags)
104 {
105 	return futex(uaddr, FUTEX_WAIT_BITSET, val, timeout, NULL, bitset,
106 		     opflags);
107 }
108 
109 /**
110  * futex_wake_bitset() - wake one or more tasks blocked on uaddr with bitset
111  * @bitset:	bitset to compare with that used in futex_wait_bitset
112  */
113 static inline int
114 futex_wake_bitset(futex_t *uaddr, int nr_wake, u_int32_t bitset, int opflags)
115 {
116 	return futex(uaddr, FUTEX_WAKE_BITSET, nr_wake, NULL, NULL, bitset,
117 		     opflags);
118 }
119 
120 /**
121  * futex_lock_pi() - block on uaddr as a PI mutex
122  * @detect:	whether (1) or not (0) to perform deadlock detection
123  */
124 static inline int
125 futex_lock_pi(futex_t *uaddr, struct timespec *timeout, int detect,
126 	      int opflags)
127 {
128 	return futex(uaddr, FUTEX_LOCK_PI, detect, timeout, NULL, 0, opflags);
129 }
130 
131 /**
132  * futex_unlock_pi() - release uaddr as a PI mutex, waking the top waiter
133  */
134 static inline int
135 futex_unlock_pi(futex_t *uaddr, int opflags)
136 {
137 	return futex(uaddr, FUTEX_UNLOCK_PI, 0, NULL, NULL, 0, opflags);
138 }
139 
140 /**
141  * futex_wake_op() - FIXME: COME UP WITH A GOOD ONE LINE DESCRIPTION
142  */
143 static inline int
144 futex_wake_op(futex_t *uaddr, futex_t *uaddr2, int nr_wake, int nr_wake2,
145 	      int wake_op, int opflags)
146 {
147 	return futex(uaddr, FUTEX_WAKE_OP, nr_wake, nr_wake2, uaddr2, wake_op,
148 		     opflags);
149 }
150 
151 /**
152  * futex_requeue() - requeue without expected value comparison, deprecated
153  * @nr_wake:	wake up to this many tasks
154  * @nr_requeue:	requeue up to this many tasks
155  *
156  * Due to its inherently racy implementation, futex_requeue() is deprecated in
157  * favor of futex_cmp_requeue().
158  */
159 static inline int
160 futex_requeue(futex_t *uaddr, futex_t *uaddr2, int nr_wake, int nr_requeue,
161 	      int opflags)
162 {
163 	return futex(uaddr, FUTEX_REQUEUE, nr_wake, nr_requeue, uaddr2, 0,
164 		     opflags);
165 }
166 
167 /**
168  * futex_cmp_requeue() - requeue tasks from uaddr to uaddr2
169  * @nr_wake:	wake up to this many tasks
170  * @nr_requeue:	requeue up to this many tasks
171  */
172 static inline int
173 futex_cmp_requeue(futex_t *uaddr, futex_t val, futex_t *uaddr2, int nr_wake,
174 		  int nr_requeue, int opflags)
175 {
176 	return futex(uaddr, FUTEX_CMP_REQUEUE, nr_wake, nr_requeue, uaddr2,
177 		     val, opflags);
178 }
179 
180 /**
181  * futex_wait_requeue_pi() - block on uaddr and prepare to requeue to uaddr2
182  * @uaddr:	non-PI futex source
183  * @uaddr2:	PI futex target
184  *
185  * This is the first half of the requeue_pi mechanism. It shall always be
186  * paired with futex_cmp_requeue_pi().
187  */
188 static inline int
189 futex_wait_requeue_pi(futex_t *uaddr, futex_t val, futex_t *uaddr2,
190 		      struct timespec *timeout, int opflags)
191 {
192 	return futex(uaddr, FUTEX_WAIT_REQUEUE_PI, val, timeout, uaddr2, 0,
193 		     opflags);
194 }
195 
196 /**
197  * futex_cmp_requeue_pi() - requeue tasks from uaddr to uaddr2 (PI aware)
198  * @uaddr:	non-PI futex source
199  * @uaddr2:	PI futex target
200  * @nr_wake:	wake up to this many tasks
201  * @nr_requeue:	requeue up to this many tasks
202  */
203 static inline int
204 futex_cmp_requeue_pi(futex_t *uaddr, futex_t val, futex_t *uaddr2, int nr_wake,
205 		     int nr_requeue, int opflags)
206 {
207 	return futex(uaddr, FUTEX_CMP_REQUEUE_PI, nr_wake, nr_requeue, uaddr2,
208 		     val, opflags);
209 }
210 
211 /**
212  * futex_cmpxchg() - atomic compare and exchange
213  * @uaddr:	The address of the futex to be modified
214  * @oldval:	The expected value of the futex
215  * @newval:	The new value to try and assign the futex
216  *
217  * Implement cmpxchg using gcc atomic builtins.
218  * http://gcc.gnu.org/onlinedocs/gcc-4.1.0/gcc/Atomic-Builtins.html
219  *
220  * Return the old futex value.
221  */
222 static inline u_int32_t
223 futex_cmpxchg(futex_t *uaddr, u_int32_t oldval, u_int32_t newval)
224 {
225 	return __sync_val_compare_and_swap(uaddr, oldval, newval);
226 }
227 
228 /**
229  * futex_dec() - atomic decrement of the futex value
230  * @uaddr:	The address of the futex to be modified
231  *
232  * Return the new futex value.
233  */
234 static inline u_int32_t
235 futex_dec(futex_t *uaddr)
236 {
237 	return __sync_sub_and_fetch(uaddr, 1);
238 }
239 
240 /**
241  * futex_inc() - atomic increment of the futex value
242  * @uaddr:	the address of the futex to be modified
243  *
244  * Return the new futex value.
245  */
246 static inline u_int32_t
247 futex_inc(futex_t *uaddr)
248 {
249 	return __sync_add_and_fetch(uaddr, 1);
250 }
251 
252 /**
253  * futex_set() - atomic decrement of the futex value
254  * @uaddr:	the address of the futex to be modified
255  * @newval:	New value for the atomic_t
256  *
257  * Return the new futex value.
258  */
259 static inline u_int32_t
260 futex_set(futex_t *uaddr, u_int32_t newval)
261 {
262 	*uaddr = newval;
263 	return newval;
264 }
265 
266 #endif
267