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