include/linux/wait_bit.h

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