futex/include/futextest.h

0001 /* SPDX-License-Identifier: GPL-2.0-or-later */
0002 /******************************************************************************
0003  *
0004  *   Copyright © International Business Machines  Corp., 2009
0005  *
0006  * DESCRIPTION
0007  *      Glibc independent futex library for testing kernel functionality.
0008  *
0009  * AUTHOR
0010  *      Darren Hart <dvhart@linux.intel.com>
0011  *
0012  * HISTORY
0013  *      2009-Nov-6: Initial version by Darren Hart <dvhart@linux.intel.com>
0014  *
0015  *****************************************************************************/
0016
0017 #ifndef _FUTEXTEST_H
0018 #define _FUTEXTEST_H
0019
0020 #include <unistd.h>
0021 #include <sys/syscall.h>
0022 #include <sys/types.h>
0023 #include <linux/futex.h>
0024
0025 typedef volatile u_int32_t futex_t;
0026 #define FUTEX_INITIALIZER 0
0027
0028 /* Define the newer op codes if the system header file is not up to date. */
0029 #ifndef FUTEX_WAIT_BITSET
0030 #define FUTEX_WAIT_BITSET       9
0031 #endif
0032 #ifndef FUTEX_WAKE_BITSET
0033 #define FUTEX_WAKE_BITSET       10
0034 #endif
0035 #ifndef FUTEX_WAIT_REQUEUE_PI
0036 #define FUTEX_WAIT_REQUEUE_PI       11
0037 #endif
0038 #ifndef FUTEX_CMP_REQUEUE_PI
0039 #define FUTEX_CMP_REQUEUE_PI        12
0040 #endif
0041 #ifndef FUTEX_WAIT_REQUEUE_PI_PRIVATE
0042 #define FUTEX_WAIT_REQUEUE_PI_PRIVATE   (FUTEX_WAIT_REQUEUE_PI | \
0043                      FUTEX_PRIVATE_FLAG)
0044 #endif
0045 #ifndef FUTEX_REQUEUE_PI_PRIVATE
0046 #define FUTEX_CMP_REQUEUE_PI_PRIVATE    (FUTEX_CMP_REQUEUE_PI | \
0047                      FUTEX_PRIVATE_FLAG)
0048 #endif
0049
0050 /**
0051  * futex() - SYS_futex syscall wrapper
0052  * @uaddr:  address of first futex
0053  * @op:     futex op code
0054  * @val:    typically expected value of uaddr, but varies by op
0055  * @timeout:    typically an absolute struct timespec (except where noted
0056  *              otherwise). Overloaded by some ops
0057  * @uaddr2: address of second futex for some ops\
0058  * @val3:   varies by op
0059  * @opflags:    flags to be bitwise OR'd with op, such as FUTEX_PRIVATE_FLAG
0060  *
0061  * futex() is used by all the following futex op wrappers. It can also be
0062  * used for misuse and abuse testing. Generally, the specific op wrappers
0063  * should be used instead. It is a macro instead of an static inline function as
0064  * some of the types over overloaded (timeout is used for nr_requeue for
0065  * example).
0066  *
0067  * These argument descriptions are the defaults for all
0068  * like-named arguments in the following wrappers except where noted below.
0069  */
0070 #define futex(uaddr, op, val, timeout, uaddr2, val3, opflags) \
0071     syscall(SYS_futex, uaddr, op | opflags, val, timeout, uaddr2, val3)
0072
0073 /**
0074  * futex_wait() - block on uaddr with optional timeout
0075  * @timeout:    relative timeout
0076  */
0077 static inline int
0078 futex_wait(futex_t *uaddr, futex_t val, struct timespec *timeout, int opflags)
0079 {
0080     return futex(uaddr, FUTEX_WAIT, val, timeout, NULL, 0, opflags);
0081 }
0082
0083 /**
0084  * futex_wake() - wake one or more tasks blocked on uaddr
0085  * @nr_wake:    wake up to this many tasks
0086  */
0087 static inline int
0088 futex_wake(futex_t *uaddr, int nr_wake, int opflags)
0089 {
0090     return futex(uaddr, FUTEX_WAKE, nr_wake, NULL, NULL, 0, opflags);
0091 }
0092
0093 /**
0094  * futex_wait_bitset() - block on uaddr with bitset
0095  * @bitset: bitset to be used with futex_wake_bitset
0096  */
0097 static inline int
0098 futex_wait_bitset(futex_t *uaddr, futex_t val, struct timespec *timeout,
0099           u_int32_t bitset, int opflags)
0100 {
0101     return futex(uaddr, FUTEX_WAIT_BITSET, val, timeout, NULL, bitset,
0102              opflags);
0103 }
0104
0105 /**
0106  * futex_wake_bitset() - wake one or more tasks blocked on uaddr with bitset
0107  * @bitset: bitset to compare with that used in futex_wait_bitset
0108  */
0109 static inline int
0110 futex_wake_bitset(futex_t *uaddr, int nr_wake, u_int32_t bitset, int opflags)
0111 {
0112     return futex(uaddr, FUTEX_WAKE_BITSET, nr_wake, NULL, NULL, bitset,
0113              opflags);
0114 }
0115
0116 /**
0117  * futex_lock_pi() - block on uaddr as a PI mutex
0118  * @detect: whether (1) or not (0) to perform deadlock detection
0119  */
0120 static inline int
0121 futex_lock_pi(futex_t *uaddr, struct timespec *timeout, int detect,
0122           int opflags)
0123 {
0124     return futex(uaddr, FUTEX_LOCK_PI, detect, timeout, NULL, 0, opflags);
0125 }
0126
0127 /**
0128  * futex_unlock_pi() - release uaddr as a PI mutex, waking the top waiter
0129  */
0130 static inline int
0131 futex_unlock_pi(futex_t *uaddr, int opflags)
0132 {
0133     return futex(uaddr, FUTEX_UNLOCK_PI, 0, NULL, NULL, 0, opflags);
0134 }
0135
0136 /**
0137  * futex_wake_op() - FIXME: COME UP WITH A GOOD ONE LINE DESCRIPTION
0138  */
0139 static inline int
0140 futex_wake_op(futex_t *uaddr, futex_t *uaddr2, int nr_wake, int nr_wake2,
0141           int wake_op, int opflags)
0142 {
0143     return futex(uaddr, FUTEX_WAKE_OP, nr_wake, nr_wake2, uaddr2, wake_op,
0144              opflags);
0145 }
0146
0147 /**
0148  * futex_requeue() - requeue without expected value comparison, deprecated
0149  * @nr_wake:    wake up to this many tasks
0150  * @nr_requeue: requeue up to this many tasks
0151  *
0152  * Due to its inherently racy implementation, futex_requeue() is deprecated in
0153  * favor of futex_cmp_requeue().
0154  */
0155 static inline int
0156 futex_requeue(futex_t *uaddr, futex_t *uaddr2, int nr_wake, int nr_requeue,
0157           int opflags)
0158 {
0159     return futex(uaddr, FUTEX_REQUEUE, nr_wake, nr_requeue, uaddr2, 0,
0160              opflags);
0161 }
0162
0163 /**
0164  * futex_cmp_requeue() - requeue tasks from uaddr to uaddr2
0165  * @nr_wake:    wake up to this many tasks
0166  * @nr_requeue: requeue up to this many tasks
0167  */
0168 static inline int
0169 futex_cmp_requeue(futex_t *uaddr, futex_t val, futex_t *uaddr2, int nr_wake,
0170           int nr_requeue, int opflags)
0171 {
0172     return futex(uaddr, FUTEX_CMP_REQUEUE, nr_wake, nr_requeue, uaddr2,
0173              val, opflags);
0174 }
0175
0176 /**
0177  * futex_wait_requeue_pi() - block on uaddr and prepare to requeue to uaddr2
0178  * @uaddr:  non-PI futex source
0179  * @uaddr2: PI futex target
0180  *
0181  * This is the first half of the requeue_pi mechanism. It shall always be
0182  * paired with futex_cmp_requeue_pi().
0183  */
0184 static inline int
0185 futex_wait_requeue_pi(futex_t *uaddr, futex_t val, futex_t *uaddr2,
0186               struct timespec *timeout, int opflags)
0187 {
0188     return futex(uaddr, FUTEX_WAIT_REQUEUE_PI, val, timeout, uaddr2, 0,
0189              opflags);
0190 }
0191
0192 /**
0193  * futex_cmp_requeue_pi() - requeue tasks from uaddr to uaddr2 (PI aware)
0194  * @uaddr:  non-PI futex source
0195  * @uaddr2: PI futex target
0196  * @nr_wake:    wake up to this many tasks
0197  * @nr_requeue: requeue up to this many tasks
0198  */
0199 static inline int
0200 futex_cmp_requeue_pi(futex_t *uaddr, futex_t val, futex_t *uaddr2, int nr_wake,
0201              int nr_requeue, int opflags)
0202 {
0203     return futex(uaddr, FUTEX_CMP_REQUEUE_PI, nr_wake, nr_requeue, uaddr2,
0204              val, opflags);
0205 }
0206
0207 /**
0208  * futex_cmpxchg() - atomic compare and exchange
0209  * @uaddr:  The address of the futex to be modified
0210  * @oldval: The expected value of the futex
0211  * @newval: The new value to try and assign the futex
0212  *
0213  * Implement cmpxchg using gcc atomic builtins.
0214  * http://gcc.gnu.org/onlinedocs/gcc-4.1.0/gcc/Atomic-Builtins.html
0215  *
0216  * Return the old futex value.
0217  */
0218 static inline u_int32_t
0219 futex_cmpxchg(futex_t *uaddr, u_int32_t oldval, u_int32_t newval)
0220 {
0221     return __sync_val_compare_and_swap(uaddr, oldval, newval);
0222 }
0223
0224 /**
0225  * futex_dec() - atomic decrement of the futex value
0226  * @uaddr:  The address of the futex to be modified
0227  *
0228  * Return the new futex value.
0229  */
0230 static inline u_int32_t
0231 futex_dec(futex_t *uaddr)
0232 {
0233     return __sync_sub_and_fetch(uaddr, 1);
0234 }
0235
0236 /**
0237  * futex_inc() - atomic increment of the futex value
0238  * @uaddr:  the address of the futex to be modified
0239  *
0240  * Return the new futex value.
0241  */
0242 static inline u_int32_t
0243 futex_inc(futex_t *uaddr)
0244 {
0245     return __sync_add_and_fetch(uaddr, 1);
0246 }
0247
0248 /**
0249  * futex_set() - atomic decrement of the futex value
0250  * @uaddr:  the address of the futex to be modified
0251  * @newval: New value for the atomic_t
0252  *
0253  * Return the new futex value.
0254  */
0255 static inline u_int32_t
0256 futex_set(futex_t *uaddr, u_int32_t newval)
0257 {
0258     *uaddr = newval;
0259     return newval;
0260 }
0261
0262 #endif