include/linux/wait_bit.h

   1 /* SPDX-License-Identifier: GPL-2.0 */
   2 #ifndef _LINUX_WAIT_BIT_H
   3 #define _LINUX_WAIT_BIT_H
   4
   5 /*
   6  * Linux wait-bit related types and methods:
   7  */
   8 #include <linux/wait.h>
   9
  10 struct wait_bit_key {
  11         void                    *flags;
  12         int                     bit_nr;
  13         unsigned long           timeout;
  14 };
  15
  16 struct wait_bit_queue_entry {
  17         struct wait_bit_key     key;
  18         struct wait_queue_entry wq_entry;
  19 };
  20
  21 #define __WAIT_BIT_KEY_INITIALIZER(word, bit)                                   \
  22         { .flags = word, .bit_nr = bit, }
  23
  24 typedef int wait_bit_action_f(struct wait_bit_key *key, int mode);
  25
  26 void __wake_up_bit(struct wait_queue_head *wq_head, void *word, int bit);
  27 int __wait_on_bit(struct wait_queue_head *wq_head, struct wait_bit_queue_entry *wbq_entry, wait_bit_action_f *action, unsigned int mode);
  28 int __wait_on_bit_lock(struct wait_queue_head *wq_head, struct wait_bit_queue_entry *wbq_entry, wait_bit_action_f *action, unsigned int mode);
  29 void wake_up_bit(void *word, int bit);
  30 int out_of_line_wait_on_bit(void *word, int, wait_bit_action_f *action, unsigned int mode);
  31 int out_of_line_wait_on_bit_timeout(void *word, int, wait_bit_action_f *action, unsigned int mode, unsigned long timeout);
  32 int out_of_line_wait_on_bit_lock(void *word, int, wait_bit_action_f *action, unsigned int mode);
  33 struct wait_queue_head *bit_waitqueue(void *word, int bit);
  34 extern void __init wait_bit_init(void);
  35
  36 int wake_bit_function(struct wait_queue_entry *wq_entry, unsigned mode, int sync, void *key);
  37
  38 #define DEFINE_WAIT_BIT(name, word, bit)                                        \
  39         struct wait_bit_queue_entry name = {                                    \
  40                 .key = __WAIT_BIT_KEY_INITIALIZER(word, bit),                   \
  41                 .wq_entry = {                                                   \
  42                         .private        = current,                              \
  43                         .func           = wake_bit_function,                    \
  44                         .entry          =                                       \
  45                                 LIST_HEAD_INIT((name).wq_entry.entry),          \
  46                 },                                                              \
  47         }
  48
  49 extern int bit_wait(struct wait_bit_key *key, int mode);
  50 extern int bit_wait_io(struct wait_bit_key *key, int mode);
  51 extern int bit_wait_timeout(struct wait_bit_key *key, int mode);
  52 extern int bit_wait_io_timeout(struct wait_bit_key *key, int mode);
  53
  54 /**
  55  * wait_on_bit - wait for a bit to be cleared
  56  * @word: the word being waited on, a kernel virtual address
  57  * @bit: the bit of the word being waited on
  58  * @mode: the task state to sleep in
  59  *
  60  * There is a standard hashed waitqueue table for generic use. This
  61  * is the part of the hashtable's accessor API that waits on a bit.
  62  * For instance, if one were to have waiters on a bitflag, one would
  63  * call wait_on_bit() in threads waiting for the bit to clear.
  64  * One uses wait_on_bit() where one is waiting for the bit to clear,
  65  * but has no intention of setting it.
  66  * Returned value will be zero if the bit was cleared, or non-zero
  67  * if the process received a signal and the mode permitted wakeup
  68  * on that signal.
  69  */
  70 static inline int
  71 wait_on_bit(unsigned long *word, int bit, unsigned mode)
  72 {
  73         might_sleep();
  74         if (!test_bit_acquire(bit, word))
  75                 return 0;
  76         return out_of_line_wait_on_bit(word, bit,
  77                                        bit_wait,
  78                                        mode);
  79 }
  80
  81 /**
  82  * wait_on_bit_io - wait for a bit to be cleared
  83  * @word: the word being waited on, a kernel virtual address
  84  * @bit: the bit of the word being waited on
  85  * @mode: the task state to sleep in
  86  *
  87  * Use the standard hashed waitqueue table to wait for a bit
  88  * to be cleared.  This is similar to wait_on_bit(), but calls
  89  * io_schedule() instead of schedule() for the actual waiting.
  90  *
  91  * Returned value will be zero if the bit was cleared, or non-zero
  92  * if the process received a signal and the mode permitted wakeup
  93  * on that signal.
  94  */
  95 static inline int
  96 wait_on_bit_io(unsigned long *word, int bit, unsigned mode)
  97 {
  98         might_sleep();
  99         if (!test_bit_acquire(bit, word))
 100                 return 0;
 101         return out_of_line_wait_on_bit(word, bit,
 102                                        bit_wait_io,
 103                                        mode);
 104 }
 105
 106 /**
 107  * wait_on_bit_timeout - wait for a bit to be cleared or a timeout elapses
 108  * @word: the word being waited on, a kernel virtual address
 109  * @bit: the bit of the word being waited on
 110  * @mode: the task state to sleep in
 111  * @timeout: timeout, in jiffies
 112  *
 113  * Use the standard hashed waitqueue table to wait for a bit
 114  * to be cleared. This is similar to wait_on_bit(), except also takes a
 115  * timeout parameter.
 116  *
 117  * Returned value will be zero if the bit was cleared before the
 118  * @timeout elapsed, or non-zero if the @timeout elapsed or process
 119  * received a signal and the mode permitted wakeup on that signal.
 120  */
 121 static inline int
 122 wait_on_bit_timeout(unsigned long *word, int bit, unsigned mode,
 123                     unsigned long timeout)
 124 {
 125         might_sleep();
 126         if (!test_bit_acquire(bit, word))
 127                 return 0;
 128         return out_of_line_wait_on_bit_timeout(word, bit,
 129                                                bit_wait_timeout,
 130                                                mode, timeout);
 131 }
 132
 133 /**
 134  * wait_on_bit_action - wait for a bit to be cleared
 135  * @word: the word being waited on, a kernel virtual address
 136  * @bit: the bit of the word being waited on
 137  * @action: the function used to sleep, which may take special actions
 138  * @mode: the task state to sleep in
 139  *
 140  * Use the standard hashed waitqueue table to wait for a bit
 141  * to be cleared, and allow the waiting action to be specified.
 142  * This is like wait_on_bit() but allows fine control of how the waiting
 143  * is done.
 144  *
 145  * Returned value will be zero if the bit was cleared, or non-zero
 146  * if the process received a signal and the mode permitted wakeup
 147  * on that signal.
 148  */
 149 static inline int
 150 wait_on_bit_action(unsigned long *word, int bit, wait_bit_action_f *action,
 151                    unsigned mode)
 152 {
 153         might_sleep();
 154         if (!test_bit_acquire(bit, word))
 155                 return 0;
 156         return out_of_line_wait_on_bit(word, bit, action, mode);
 157 }
 158
 159 /**
 160  * wait_on_bit_lock - wait for a bit to be cleared, when wanting to set it
 161  * @word: the word being waited on, a kernel virtual address
 162  * @bit: the bit of the word being waited on
 163  * @mode: the task state to sleep in
 164  *
 165  * There is a standard hashed waitqueue table for generic use. This
 166  * is the part of the hashtable's accessor API that waits on a bit
 167  * when one intends to set it, for instance, trying to lock bitflags.
 168  * For instance, if one were to have waiters trying to set bitflag
 169  * and waiting for it to clear before setting it, one would call
 170  * wait_on_bit() in threads waiting to be able to set the bit.
 171  * One uses wait_on_bit_lock() where one is waiting for the bit to
 172  * clear with the intention of setting it, and when done, clearing it.
 173  *
 174  * Returns zero if the bit was (eventually) found to be clear and was
 175  * set.  Returns non-zero if a signal was delivered to the process and
 176  * the @mode allows that signal to wake the process.
 177  */
 178 static inline int
 179 wait_on_bit_lock(unsigned long *word, int bit, unsigned mode)
 180 {
 181         might_sleep();
 182         if (!test_and_set_bit(bit, word))
 183                 return 0;
 184         return out_of_line_wait_on_bit_lock(word, bit, bit_wait, mode);
 185 }
 186
 187 /**
 188  * wait_on_bit_lock_io - wait for a bit to be cleared, when wanting to set it
 189  * @word: the word being waited on, a kernel virtual address
 190  * @bit: the bit of the word being waited on
 191  * @mode: the task state to sleep in
 192  *
 193  * Use the standard hashed waitqueue table to wait for a bit
 194  * to be cleared and then to atomically set it.  This is similar
 195  * to wait_on_bit(), but calls io_schedule() instead of schedule()
 196  * for the actual waiting.
 197  *
 198  * Returns zero if the bit was (eventually) found to be clear and was
 199  * set.  Returns non-zero if a signal was delivered to the process and
 200  * the @mode allows that signal to wake the process.
 201  */
 202 static inline int
 203 wait_on_bit_lock_io(unsigned long *word, int bit, unsigned mode)
 204 {
 205         might_sleep();
 206         if (!test_and_set_bit(bit, word))
 207                 return 0;
 208         return out_of_line_wait_on_bit_lock(word, bit, bit_wait_io, mode);
 209 }
 210
 211 /**
 212  * wait_on_bit_lock_action - wait for a bit to be cleared, when wanting to set it
 213  * @word: the word being waited on, a kernel virtual address
 214  * @bit: the bit of the word being waited on
 215  * @action: the function used to sleep, which may take special actions
 216  * @mode: the task state to sleep in
 217  *
 218  * Use the standard hashed waitqueue table to wait for a bit
 219  * to be cleared and then to set it, and allow the waiting action
 220  * to be specified.
 221  * This is like wait_on_bit() but allows fine control of how the waiting
 222  * is done.
 223  *
 224  * Returns zero if the bit was (eventually) found to be clear and was
 225  * set.  Returns non-zero if a signal was delivered to the process and
 226  * the @mode allows that signal to wake the process.
 227  */
 228 static inline int
 229 wait_on_bit_lock_action(unsigned long *word, int bit, wait_bit_action_f *action,
 230                         unsigned mode)
 231 {
 232         might_sleep();
 233         if (!test_and_set_bit(bit, word))
 234                 return 0;
 235         return out_of_line_wait_on_bit_lock(word, bit, action, mode);
 236 }
 237
 238 extern void init_wait_var_entry(struct wait_bit_queue_entry *wbq_entry, void *var, int flags);
 239 extern void wake_up_var(void *var);
 240 extern wait_queue_head_t *__var_waitqueue(void *p);
 241
 242 #define ___wait_var_event(var, condition, state, exclusive, ret, cmd)   \
 243 ({                                                                      \
 244         __label__ __out;                                                \
 245         struct wait_queue_head *__wq_head = __var_waitqueue(var);       \
 246         struct wait_bit_queue_entry __wbq_entry;                        \
 247         long __ret = ret; /* explicit shadow */                         \
 248                                                                         \
 249         init_wait_var_entry(&__wbq_entry, var,                          \
 250                             exclusive ? WQ_FLAG_EXCLUSIVE : 0);         \
 251         for (;;) {                                                      \
 252                 long __int = prepare_to_wait_event(__wq_head,           \
 253                                                    &__wbq_entry.wq_entry, \
 254                                                    state);              \
 255                 if (condition)                                          \
 256                         break;                                          \
 257                                                                         \
 258                 if (___wait_is_interruptible(state) && __int) {         \
 259                         __ret = __int;                                  \
 260                         goto __out;                                     \
 261                 }                                                       \
 262                                                                         \
 263                 cmd;                                                    \
 264         }                                                               \
 265         finish_wait(__wq_head, &__wbq_entry.wq_entry);                  \
 266 __out:  __ret;                                                          \
 267 })
 268
 269 #define __wait_var_event(var, condition)                                \
 270         ___wait_var_event(var, condition, TASK_UNINTERRUPTIBLE, 0, 0,   \
 271                           schedule())
 272
 273 #define wait_var_event(var, condition)                                  \
 274 do {                                                                    \
 275         might_sleep();                                                  \
 276         if (condition)                                                  \
 277                 break;                                                  \
 278         __wait_var_event(var, condition);                               \
 279 } while (0)
 280
 281 #define __wait_var_event_killable(var, condition)                       \
 282         ___wait_var_event(var, condition, TASK_KILLABLE, 0, 0,          \
 283                           schedule())
 284
 285 #define wait_var_event_killable(var, condition)                         \
 286 ({                                                                      \
 287         int __ret = 0;                                                  \
 288         might_sleep();                                                  \
 289         if (!(condition))                                               \
 290                 __ret = __wait_var_event_killable(var, condition);      \
 291         __ret;                                                          \
 292 })
 293
 294 #define __wait_var_event_timeout(var, condition, timeout)               \
 295         ___wait_var_event(var, ___wait_cond_timeout(condition),         \
 296                           TASK_UNINTERRUPTIBLE, 0, timeout,             \
 297                           __ret = schedule_timeout(__ret))
 298
 299 #define wait_var_event_timeout(var, condition, timeout)                 \
 300 ({                                                                      \
 301         long __ret = timeout;                                           \
 302         might_sleep();                                                  \
 303         if (!___wait_cond_timeout(condition))                           \
 304                 __ret = __wait_var_event_timeout(var, condition, timeout); \
 305         __ret;                                                          \
 306 })
 307
 308 #define __wait_var_event_interruptible(var, condition)                  \
 309         ___wait_var_event(var, condition, TASK_INTERRUPTIBLE, 0, 0,     \
 310                           schedule())
 311
 312 #define wait_var_event_interruptible(var, condition)                    \
 313 ({                                                                      \
 314         int __ret = 0;                                                  \
 315         might_sleep();                                                  \
 316         if (!(condition))                                               \
 317                 __ret = __wait_var_event_interruptible(var, condition); \
 318         __ret;                                                          \
 319 })
 320
 321 /**
 322  * clear_and_wake_up_bit - clear a bit and wake up anyone waiting on that bit
 323  *
 324  * @bit: the bit of the word being waited on
 325  * @word: the word being waited on, a kernel virtual address
 326  *
 327  * You can use this helper if bitflags are manipulated atomically rather than
 328  * non-atomically under a lock.
 329  */
 330 static inline void clear_and_wake_up_bit(int bit, void *word)
 331 {
 332         clear_bit_unlock(bit, word);
 333         /* See wake_up_bit() for which memory barrier you need to use. */
 334         smp_mb__after_atomic();
 335         wake_up_bit(word, bit);
 336 }
 337
 338 #endif /* _LINUX_WAIT_BIT_H */