include/linux/wait_bit.h

0001 /* SPDX-License-Identifier: GPL-2.0 */
0002 #ifndef _LINUX_WAIT_BIT_H
0003 #define _LINUX_WAIT_BIT_H
0004
0005 /*
0006  * Linux wait-bit related types and methods:
0007  */
0008 #include <linux/wait.h>
0009
0010 struct wait_bit_key {
0011     void            *flags;
0012     int         bit_nr;
0013     unsigned long       timeout;
0014 };
0015
0016 struct wait_bit_queue_entry {
0017     struct wait_bit_key key;
0018     struct wait_queue_entry wq_entry;
0019 };
0020
0021 #define __WAIT_BIT_KEY_INITIALIZER(word, bit)                   \
0022     { .flags = word, .bit_nr = bit, }
0023
0024 typedef int wait_bit_action_f(struct wait_bit_key *key, int mode);
0025
0026 void __wake_up_bit(struct wait_queue_head *wq_head, void *word, int bit);
0027 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);
0028 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);
0029 void wake_up_bit(void *word, int bit);
0030 int out_of_line_wait_on_bit(void *word, int, wait_bit_action_f *action, unsigned int mode);
0031 int out_of_line_wait_on_bit_timeout(void *word, int, wait_bit_action_f *action, unsigned int mode, unsigned long timeout);
0032 int out_of_line_wait_on_bit_lock(void *word, int, wait_bit_action_f *action, unsigned int mode);
0033 struct wait_queue_head *bit_waitqueue(void *word, int bit);
0034 extern void __init wait_bit_init(void);
0035
0036 int wake_bit_function(struct wait_queue_entry *wq_entry, unsigned mode, int sync, void *key);
0037
0038 #define DEFINE_WAIT_BIT(name, word, bit)                    \
0039     struct wait_bit_queue_entry name = {                    \
0040         .key = __WAIT_BIT_KEY_INITIALIZER(word, bit),           \
0041         .wq_entry = {                           \
0042             .private    = current,              \
0043             .func       = wake_bit_function,            \
0044             .entry      =                   \
0045                 LIST_HEAD_INIT((name).wq_entry.entry),      \
0046         },                              \
0047     }
0048
0049 extern int bit_wait(struct wait_bit_key *key, int mode);
0050 extern int bit_wait_io(struct wait_bit_key *key, int mode);
0051 extern int bit_wait_timeout(struct wait_bit_key *key, int mode);
0052 extern int bit_wait_io_timeout(struct wait_bit_key *key, int mode);
0053
0054 /**
0055  * wait_on_bit - wait for a bit to be cleared
0056  * @word: the word being waited on, a kernel virtual address
0057  * @bit: the bit of the word being waited on
0058  * @mode: the task state to sleep in
0059  *
0060  * There is a standard hashed waitqueue table for generic use. This
0061  * is the part of the hashtable's accessor API that waits on a bit.
0062  * For instance, if one were to have waiters on a bitflag, one would
0063  * call wait_on_bit() in threads waiting for the bit to clear.
0064  * One uses wait_on_bit() where one is waiting for the bit to clear,
0065  * but has no intention of setting it.
0066  * Returned value will be zero if the bit was cleared, or non-zero
0067  * if the process received a signal and the mode permitted wakeup
0068  * on that signal.
0069  */
0070 static inline int
0071 wait_on_bit(unsigned long *word, int bit, unsigned mode)
0072 {
0073     might_sleep();
0074     if (!test_bit_acquire(bit, word))
0075         return 0;
0076     return out_of_line_wait_on_bit(word, bit,
0077                        bit_wait,
0078                        mode);
0079 }
0080
0081 /**
0082  * wait_on_bit_io - wait for a bit to be cleared
0083  * @word: the word being waited on, a kernel virtual address
0084  * @bit: the bit of the word being waited on
0085  * @mode: the task state to sleep in
0086  *
0087  * Use the standard hashed waitqueue table to wait for a bit
0088  * to be cleared.  This is similar to wait_on_bit(), but calls
0089  * io_schedule() instead of schedule() for the actual waiting.
0090  *
0091  * Returned value will be zero if the bit was cleared, or non-zero
0092  * if the process received a signal and the mode permitted wakeup
0093  * on that signal.
0094  */
0095 static inline int
0096 wait_on_bit_io(unsigned long *word, int bit, unsigned mode)
0097 {
0098     might_sleep();
0099     if (!test_bit_acquire(bit, word))
0100         return 0;
0101     return out_of_line_wait_on_bit(word, bit,
0102                        bit_wait_io,
0103                        mode);
0104 }
0105
0106 /**
0107  * wait_on_bit_timeout - wait for a bit to be cleared or a timeout elapses
0108  * @word: the word being waited on, a kernel virtual address
0109  * @bit: the bit of the word being waited on
0110  * @mode: the task state to sleep in
0111  * @timeout: timeout, in jiffies
0112  *
0113  * Use the standard hashed waitqueue table to wait for a bit
0114  * to be cleared. This is similar to wait_on_bit(), except also takes a
0115  * timeout parameter.
0116  *
0117  * Returned value will be zero if the bit was cleared before the
0118  * @timeout elapsed, or non-zero if the @timeout elapsed or process
0119  * received a signal and the mode permitted wakeup on that signal.
0120  */
0121 static inline int
0122 wait_on_bit_timeout(unsigned long *word, int bit, unsigned mode,
0123             unsigned long timeout)
0124 {
0125     might_sleep();
0126     if (!test_bit_acquire(bit, word))
0127         return 0;
0128     return out_of_line_wait_on_bit_timeout(word, bit,
0129                            bit_wait_timeout,
0130                            mode, timeout);
0131 }
0132
0133 /**
0134  * wait_on_bit_action - wait for a bit to be cleared
0135  * @word: the word being waited on, a kernel virtual address
0136  * @bit: the bit of the word being waited on
0137  * @action: the function used to sleep, which may take special actions
0138  * @mode: the task state to sleep in
0139  *
0140  * Use the standard hashed waitqueue table to wait for a bit
0141  * to be cleared, and allow the waiting action to be specified.
0142  * This is like wait_on_bit() but allows fine control of how the waiting
0143  * is done.
0144  *
0145  * Returned value will be zero if the bit was cleared, or non-zero
0146  * if the process received a signal and the mode permitted wakeup
0147  * on that signal.
0148  */
0149 static inline int
0150 wait_on_bit_action(unsigned long *word, int bit, wait_bit_action_f *action,
0151            unsigned mode)
0152 {
0153     might_sleep();
0154     if (!test_bit_acquire(bit, word))
0155         return 0;
0156     return out_of_line_wait_on_bit(word, bit, action, mode);
0157 }
0158
0159 /**
0160  * wait_on_bit_lock - wait for a bit to be cleared, when wanting to set it
0161  * @word: the word being waited on, a kernel virtual address
0162  * @bit: the bit of the word being waited on
0163  * @mode: the task state to sleep in
0164  *
0165  * There is a standard hashed waitqueue table for generic use. This
0166  * is the part of the hashtable's accessor API that waits on a bit
0167  * when one intends to set it, for instance, trying to lock bitflags.
0168  * For instance, if one were to have waiters trying to set bitflag
0169  * and waiting for it to clear before setting it, one would call
0170  * wait_on_bit() in threads waiting to be able to set the bit.
0171  * One uses wait_on_bit_lock() where one is waiting for the bit to
0172  * clear with the intention of setting it, and when done, clearing it.
0173  *
0174  * Returns zero if the bit was (eventually) found to be clear and was
0175  * set.  Returns non-zero if a signal was delivered to the process and
0176  * the @mode allows that signal to wake the process.
0177  */
0178 static inline int
0179 wait_on_bit_lock(unsigned long *word, int bit, unsigned mode)
0180 {
0181     might_sleep();
0182     if (!test_and_set_bit(bit, word))
0183         return 0;
0184     return out_of_line_wait_on_bit_lock(word, bit, bit_wait, mode);
0185 }
0186
0187 /**
0188  * wait_on_bit_lock_io - wait for a bit to be cleared, when wanting to set it
0189  * @word: the word being waited on, a kernel virtual address
0190  * @bit: the bit of the word being waited on
0191  * @mode: the task state to sleep in
0192  *
0193  * Use the standard hashed waitqueue table to wait for a bit
0194  * to be cleared and then to atomically set it.  This is similar
0195  * to wait_on_bit(), but calls io_schedule() instead of schedule()
0196  * for the actual waiting.
0197  *
0198  * Returns zero if the bit was (eventually) found to be clear and was
0199  * set.  Returns non-zero if a signal was delivered to the process and
0200  * the @mode allows that signal to wake the process.
0201  */
0202 static inline int
0203 wait_on_bit_lock_io(unsigned long *word, int bit, unsigned mode)
0204 {
0205     might_sleep();
0206     if (!test_and_set_bit(bit, word))
0207         return 0;
0208     return out_of_line_wait_on_bit_lock(word, bit, bit_wait_io, mode);
0209 }
0210
0211 /**
0212  * wait_on_bit_lock_action - wait for a bit to be cleared, when wanting to set it
0213  * @word: the word being waited on, a kernel virtual address
0214  * @bit: the bit of the word being waited on
0215  * @action: the function used to sleep, which may take special actions
0216  * @mode: the task state to sleep in
0217  *
0218  * Use the standard hashed waitqueue table to wait for a bit
0219  * to be cleared and then to set it, and allow the waiting action
0220  * to be specified.
0221  * This is like wait_on_bit() but allows fine control of how the waiting
0222  * is done.
0223  *
0224  * Returns zero if the bit was (eventually) found to be clear and was
0225  * set.  Returns non-zero if a signal was delivered to the process and
0226  * the @mode allows that signal to wake the process.
0227  */
0228 static inline int
0229 wait_on_bit_lock_action(unsigned long *word, int bit, wait_bit_action_f *action,
0230             unsigned mode)
0231 {
0232     might_sleep();
0233     if (!test_and_set_bit(bit, word))
0234         return 0;
0235     return out_of_line_wait_on_bit_lock(word, bit, action, mode);
0236 }
0237
0238 extern void init_wait_var_entry(struct wait_bit_queue_entry *wbq_entry, void *var, int flags);
0239 extern void wake_up_var(void *var);
0240 extern wait_queue_head_t *__var_waitqueue(void *p);
0241
0242 #define ___wait_var_event(var, condition, state, exclusive, ret, cmd)   \
0243 ({                                  \
0244     __label__ __out;                        \
0245     struct wait_queue_head *__wq_head = __var_waitqueue(var);   \
0246     struct wait_bit_queue_entry __wbq_entry;            \
0247     long __ret = ret; /* explicit shadow */             \
0248                                     \
0249     init_wait_var_entry(&__wbq_entry, var,              \
0250                 exclusive ? WQ_FLAG_EXCLUSIVE : 0);     \
0251     for (;;) {                          \
0252         long __int = prepare_to_wait_event(__wq_head,       \
0253                            &__wbq_entry.wq_entry, \
0254                            state);      \
0255         if (condition)                      \
0256             break;                      \
0257                                     \
0258         if (___wait_is_interruptible(state) && __int) {     \
0259             __ret = __int;                  \
0260             goto __out;                 \
0261         }                           \
0262                                     \
0263         cmd;                            \
0264     }                               \
0265     finish_wait(__wq_head, &__wbq_entry.wq_entry);          \
0266 __out:  __ret;                              \
0267 })
0268
0269 #define __wait_var_event(var, condition)                \
0270     ___wait_var_event(var, condition, TASK_UNINTERRUPTIBLE, 0, 0,   \
0271               schedule())
0272
0273 #define wait_var_event(var, condition)                  \
0274 do {                                    \
0275     might_sleep();                          \
0276     if (condition)                          \
0277         break;                          \
0278     __wait_var_event(var, condition);               \
0279 } while (0)
0280
0281 #define __wait_var_event_killable(var, condition)           \
0282     ___wait_var_event(var, condition, TASK_KILLABLE, 0, 0,      \
0283               schedule())
0284
0285 #define wait_var_event_killable(var, condition)             \
0286 ({                                  \
0287     int __ret = 0;                          \
0288     might_sleep();                          \
0289     if (!(condition))                       \
0290         __ret = __wait_var_event_killable(var, condition);  \
0291     __ret;                              \
0292 })
0293
0294 #define __wait_var_event_timeout(var, condition, timeout)       \
0295     ___wait_var_event(var, ___wait_cond_timeout(condition),     \
0296               TASK_UNINTERRUPTIBLE, 0, timeout,     \
0297               __ret = schedule_timeout(__ret))
0298
0299 #define wait_var_event_timeout(var, condition, timeout)         \
0300 ({                                  \
0301     long __ret = timeout;                       \
0302     might_sleep();                          \
0303     if (!___wait_cond_timeout(condition))               \
0304         __ret = __wait_var_event_timeout(var, condition, timeout); \
0305     __ret;                              \
0306 })
0307
0308 #define __wait_var_event_interruptible(var, condition)          \
0309     ___wait_var_event(var, condition, TASK_INTERRUPTIBLE, 0, 0, \
0310               schedule())
0311
0312 #define wait_var_event_interruptible(var, condition)            \
0313 ({                                  \
0314     int __ret = 0;                          \
0315     might_sleep();                          \
0316     if (!(condition))                       \
0317         __ret = __wait_var_event_interruptible(var, condition); \
0318     __ret;                              \
0319 })
0320
0321 /**
0322  * clear_and_wake_up_bit - clear a bit and wake up anyone waiting on that bit
0323  *
0324  * @bit: the bit of the word being waited on
0325  * @word: the word being waited on, a kernel virtual address
0326  *
0327  * You can use this helper if bitflags are manipulated atomically rather than
0328  * non-atomically under a lock.
0329  */
0330 static inline void clear_and_wake_up_bit(int bit, void *word)
0331 {
0332     clear_bit_unlock(bit, word);
0333     /* See wake_up_bit() for which memory barrier you need to use. */
0334     smp_mb__after_atomic();
0335     wake_up_bit(word, bit);
0336 }
0337
0338 #endif /* _LINUX_WAIT_BIT_H */