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 #define WAIT_ATOMIC_T_BIT_NR    -1
  14         unsigned long           timeout;
  15 };
  16
  17 struct wait_bit_queue_entry {
  18         struct wait_bit_key     key;
  19         struct wait_queue_entry wq_entry;
  20 };
  21
  22 #define __WAIT_BIT_KEY_INITIALIZER(word, bit)                                   \
  23         { .flags = word, .bit_nr = bit, }
  24
  25 #define __WAIT_ATOMIC_T_KEY_INITIALIZER(p)                                      \
  26         { .flags = p, .bit_nr = WAIT_ATOMIC_T_BIT_NR, }
  27
  28 typedef int wait_bit_action_f(struct wait_bit_key *key, int mode);
  29 typedef int wait_atomic_t_action_f(atomic_t *counter, unsigned int mode);
  30
  31 void __wake_up_bit(struct wait_queue_head *wq_head, void *word, int bit);
  32 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);
  33 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);
  34 void wake_up_bit(void *word, int bit);
  35 void wake_up_atomic_t(atomic_t *p);
  36 int out_of_line_wait_on_bit(void *word, int, wait_bit_action_f *action, unsigned int mode);
  37 int out_of_line_wait_on_bit_timeout(void *word, int, wait_bit_action_f *action, unsigned int mode, unsigned long timeout);
  38 int out_of_line_wait_on_bit_lock(void *word, int, wait_bit_action_f *action, unsigned int mode);
  39 int out_of_line_wait_on_atomic_t(atomic_t *p, wait_atomic_t_action_f action, unsigned int mode);
  40 struct wait_queue_head *bit_waitqueue(void *word, int bit);
  41 extern void __init wait_bit_init(void);
  42
  43 int wake_bit_function(struct wait_queue_entry *wq_entry, unsigned mode, int sync, void *key);
  44
  45 #define DEFINE_WAIT_BIT(name, word, bit)                                        \
  46         struct wait_bit_queue_entry name = {                                    \
  47                 .key = __WAIT_BIT_KEY_INITIALIZER(word, bit),                   \
  48                 .wq_entry = {                                                   \
  49                         .private        = current,                              \
  50                         .func           = wake_bit_function,                    \
  51                         .entry          =                                       \
  52                                 LIST_HEAD_INIT((name).wq_entry.entry),          \
  53                 },                                                              \
  54         }
  55
  56 extern int bit_wait(struct wait_bit_key *key, int mode);
  57 extern int bit_wait_io(struct wait_bit_key *key, int mode);
  58 extern int bit_wait_timeout(struct wait_bit_key *key, int mode);
  59 extern int bit_wait_io_timeout(struct wait_bit_key *key, int mode);
  60 extern int atomic_t_wait(atomic_t *counter, unsigned int mode);
  61
  62 /**
  63  * wait_on_bit - wait for a bit to be cleared
  64  * @word: the word being waited on, a kernel virtual address
  65  * @bit: the bit of the word being waited on
  66  * @mode: the task state to sleep in
  67  *
  68  * There is a standard hashed waitqueue table for generic use. This
  69  * is the part of the hashtable's accessor API that waits on a bit.
  70  * For instance, if one were to have waiters on a bitflag, one would
  71  * call wait_on_bit() in threads waiting for the bit to clear.
  72  * One uses wait_on_bit() where one is waiting for the bit to clear,
  73  * but has no intention of setting it.
  74  * Returned value will be zero if the bit was cleared, or non-zero
  75  * if the process received a signal and the mode permitted wakeup
  76  * on that signal.
  77  */
  78 static inline int
  79 wait_on_bit(unsigned long *word, int bit, unsigned mode)
  80 {
  81         might_sleep();
  82         if (!test_bit(bit, word))
  83                 return 0;
  84         return out_of_line_wait_on_bit(word, bit,
  85                                        bit_wait,
  86                                        mode);
  87 }
  88
  89 /**
  90  * wait_on_bit_io - wait for a bit to be cleared
  91  * @word: the word being waited on, a kernel virtual address
  92  * @bit: the bit of the word being waited on
  93  * @mode: the task state to sleep in
  94  *
  95  * Use the standard hashed waitqueue table to wait for a bit
  96  * to be cleared.  This is similar to wait_on_bit(), but calls
  97  * io_schedule() instead of schedule() for the actual waiting.
  98  *
  99  * Returned value will be zero if the bit was cleared, or non-zero
 100  * if the process received a signal and the mode permitted wakeup
 101  * on that signal.
 102  */
 103 static inline int
 104 wait_on_bit_io(unsigned long *word, int bit, unsigned mode)
 105 {
 106         might_sleep();
 107         if (!test_bit(bit, word))
 108                 return 0;
 109         return out_of_line_wait_on_bit(word, bit,
 110                                        bit_wait_io,
 111                                        mode);
 112 }
 113
 114 /**
 115  * wait_on_bit_timeout - wait for a bit to be cleared or a timeout elapses
 116  * @word: the word being waited on, a kernel virtual address
 117  * @bit: the bit of the word being waited on
 118  * @mode: the task state to sleep in
 119  * @timeout: timeout, in jiffies
 120  *
 121  * Use the standard hashed waitqueue table to wait for a bit
 122  * to be cleared. This is similar to wait_on_bit(), except also takes a
 123  * timeout parameter.
 124  *
 125  * Returned value will be zero if the bit was cleared before the
 126  * @timeout elapsed, or non-zero if the @timeout elapsed or process
 127  * received a signal and the mode permitted wakeup on that signal.
 128  */
 129 static inline int
 130 wait_on_bit_timeout(unsigned long *word, int bit, unsigned mode,
 131                     unsigned long timeout)
 132 {
 133         might_sleep();
 134         if (!test_bit(bit, word))
 135                 return 0;
 136         return out_of_line_wait_on_bit_timeout(word, bit,
 137                                                bit_wait_timeout,
 138                                                mode, timeout);
 139 }
 140
 141 /**
 142  * wait_on_bit_action - wait for a bit to be cleared
 143  * @word: the word being waited on, a kernel virtual address
 144  * @bit: the bit of the word being waited on
 145  * @action: the function used to sleep, which may take special actions
 146  * @mode: the task state to sleep in
 147  *
 148  * Use the standard hashed waitqueue table to wait for a bit
 149  * to be cleared, and allow the waiting action to be specified.
 150  * This is like wait_on_bit() but allows fine control of how the waiting
 151  * is done.
 152  *
 153  * Returned value will be zero if the bit was cleared, or non-zero
 154  * if the process received a signal and the mode permitted wakeup
 155  * on that signal.
 156  */
 157 static inline int
 158 wait_on_bit_action(unsigned long *word, int bit, wait_bit_action_f *action,
 159                    unsigned mode)
 160 {
 161         might_sleep();
 162         if (!test_bit(bit, word))
 163                 return 0;
 164         return out_of_line_wait_on_bit(word, bit, action, mode);
 165 }
 166
 167 /**
 168  * wait_on_bit_lock - wait for a bit to be cleared, when wanting to set it
 169  * @word: the word being waited on, a kernel virtual address
 170  * @bit: the bit of the word being waited on
 171  * @mode: the task state to sleep in
 172  *
 173  * There is a standard hashed waitqueue table for generic use. This
 174  * is the part of the hashtable's accessor API that waits on a bit
 175  * when one intends to set it, for instance, trying to lock bitflags.
 176  * For instance, if one were to have waiters trying to set bitflag
 177  * and waiting for it to clear before setting it, one would call
 178  * wait_on_bit() in threads waiting to be able to set the bit.
 179  * One uses wait_on_bit_lock() where one is waiting for the bit to
 180  * clear with the intention of setting it, and when done, clearing it.
 181  *
 182  * Returns zero if the bit was (eventually) found to be clear and was
 183  * set.  Returns non-zero if a signal was delivered to the process and
 184  * the @mode allows that signal to wake the process.
 185  */
 186 static inline int
 187 wait_on_bit_lock(unsigned long *word, int bit, unsigned mode)
 188 {
 189         might_sleep();
 190         if (!test_and_set_bit(bit, word))
 191                 return 0;
 192         return out_of_line_wait_on_bit_lock(word, bit, bit_wait, mode);
 193 }
 194
 195 /**
 196  * wait_on_bit_lock_io - wait for a bit to be cleared, when wanting to set it
 197  * @word: the word being waited on, a kernel virtual address
 198  * @bit: the bit of the word being waited on
 199  * @mode: the task state to sleep in
 200  *
 201  * Use the standard hashed waitqueue table to wait for a bit
 202  * to be cleared and then to atomically set it.  This is similar
 203  * to wait_on_bit(), but calls io_schedule() instead of schedule()
 204  * for the actual waiting.
 205  *
 206  * Returns zero if the bit was (eventually) found to be clear and was
 207  * set.  Returns non-zero if a signal was delivered to the process and
 208  * the @mode allows that signal to wake the process.
 209  */
 210 static inline int
 211 wait_on_bit_lock_io(unsigned long *word, int bit, unsigned mode)
 212 {
 213         might_sleep();
 214         if (!test_and_set_bit(bit, word))
 215                 return 0;
 216         return out_of_line_wait_on_bit_lock(word, bit, bit_wait_io, mode);
 217 }
 218
 219 /**
 220  * wait_on_bit_lock_action - wait for a bit to be cleared, when wanting to set it
 221  * @word: the word being waited on, a kernel virtual address
 222  * @bit: the bit of the word being waited on
 223  * @action: the function used to sleep, which may take special actions
 224  * @mode: the task state to sleep in
 225  *
 226  * Use the standard hashed waitqueue table to wait for a bit
 227  * to be cleared and then to set it, and allow the waiting action
 228  * to be specified.
 229  * This is like wait_on_bit() but allows fine control of how the waiting
 230  * is done.
 231  *
 232  * Returns zero if the bit was (eventually) found to be clear and was
 233  * set.  Returns non-zero if a signal was delivered to the process and
 234  * the @mode allows that signal to wake the process.
 235  */
 236 static inline int
 237 wait_on_bit_lock_action(unsigned long *word, int bit, wait_bit_action_f *action,
 238                         unsigned mode)
 239 {
 240         might_sleep();
 241         if (!test_and_set_bit(bit, word))
 242                 return 0;
 243         return out_of_line_wait_on_bit_lock(word, bit, action, mode);
 244 }
 245
 246 /**
 247  * wait_on_atomic_t - Wait for an atomic_t to become 0
 248  * @val: The atomic value being waited on, a kernel virtual address
 249  * @action: the function used to sleep, which may take special actions
 250  * @mode: the task state to sleep in
 251  *
 252  * Wait for an atomic_t to become 0.  We abuse the bit-wait waitqueue table for
 253  * the purpose of getting a waitqueue, but we set the key to a bit number
 254  * outside of the target 'word'.
 255  */
 256 static inline
 257 int wait_on_atomic_t(atomic_t *val, wait_atomic_t_action_f action, unsigned mode)
 258 {
 259         might_sleep();
 260         if (atomic_read(val) == 0)
 261                 return 0;
 262         return out_of_line_wait_on_atomic_t(val, action, mode);
 263 }
 264
 265 /**
 266  * clear_and_wake_up_bit - clear a bit and wake up anyone waiting on that bit
 267  *
 268  * @bit: the bit of the word being waited on
 269  * @word: the word being waited on, a kernel virtual address
 270  *
 271  * You can use this helper if bitflags are manipulated atomically rather than
 272  * non-atomically under a lock.
 273  */
 274 static inline void clear_and_wake_up_bit(int bit, void *word)
 275 {
 276         clear_bit_unlock(bit, word);
 277         /* See wake_up_bit() for which memory barrier you need to use. */
 278         smp_mb__after_atomic();
 279         wake_up_bit(word, bit);
 280 }
 281
 282 #endif /* _LINUX_WAIT_BIT_H */