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