1 /* SPDX-License-Identifier: GPL-2.0 */
2 #ifndef _LINUX_WAIT_BIT_H
3 #define _LINUX_WAIT_BIT_H
6 * Linux wait-bit related types and methods:
8 #include <linux/wait.h>
13 #define WAIT_ATOMIC_T_BIT_NR -1
14 unsigned long timeout;
17 struct wait_bit_queue_entry {
18 struct wait_bit_key key;
19 struct wait_queue_entry wq_entry;
22 #define __WAIT_BIT_KEY_INITIALIZER(word, bit) \
23 { .flags = word, .bit_nr = bit, }
25 #define __WAIT_ATOMIC_T_KEY_INITIALIZER(p) \
26 { .flags = p, .bit_nr = WAIT_ATOMIC_T_BIT_NR, }
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);
41 int wake_bit_function(struct wait_queue_entry *wq_entry, unsigned mode, int sync, void *key);
43 #define DEFINE_WAIT_BIT(name, word, bit) \
44 struct wait_bit_queue_entry name = { \
45 .key = __WAIT_BIT_KEY_INITIALIZER(word, bit), \
48 .func = wake_bit_function, \
50 LIST_HEAD_INIT((name).wq_entry.entry), \
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);
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
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
76 wait_on_bit(unsigned long *word, int bit, unsigned mode)
79 if (!test_bit(bit, word))
81 return out_of_line_wait_on_bit(word, bit,
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
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.
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
101 wait_on_bit_io(unsigned long *word, int bit, unsigned mode)
104 if (!test_bit(bit, word))
106 return out_of_line_wait_on_bit(word, bit,
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
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
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.
127 wait_on_bit_timeout(unsigned long *word, int bit, unsigned mode,
128 unsigned long timeout)
131 if (!test_bit(bit, word))
133 return out_of_line_wait_on_bit_timeout(word, bit,
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
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
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
155 wait_on_bit_action(unsigned long *word, int bit, wait_bit_action_f *action,
159 if (!test_bit(bit, word))
161 return out_of_line_wait_on_bit(word, bit, action, mode);
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
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.
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.
184 wait_on_bit_lock(unsigned long *word, int bit, unsigned mode)
187 if (!test_and_set_bit(bit, word))
189 return out_of_line_wait_on_bit_lock(word, bit, bit_wait, mode);
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
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.
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.
208 wait_on_bit_lock_io(unsigned long *word, int bit, unsigned mode)
211 if (!test_and_set_bit(bit, word))
213 return out_of_line_wait_on_bit_lock(word, bit, bit_wait_io, mode);
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
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
226 * This is like wait_on_bit() but allows fine control of how the waiting
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.
234 wait_on_bit_lock_action(unsigned long *word, int bit, wait_bit_action_f *action,
238 if (!test_and_set_bit(bit, word))
240 return out_of_line_wait_on_bit_lock(word, bit, action, mode);
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
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'.
254 int wait_on_atomic_t(atomic_t *val, int (*action)(atomic_t *), unsigned mode)
257 if (atomic_read(val) == 0)
259 return out_of_line_wait_on_atomic_t(val, action, mode);
263 * clear_and_wake_up_bit - clear a bit and wake up anyone waiting on that bit
265 * @bit: the bit of the word being waited on
266 * @word: the word being waited on, a kernel virtual address
268 * You can use this helper if bitflags are manipulated atomically rather than
269 * non-atomically under a lock.
271 static inline void clear_and_wake_up_bit(int bit, void *word)
273 clear_bit_unlock(bit, word);
274 /* See wake_up_bit() for which memory barrier you need to use. */
275 smp_mb__after_atomic();
276 wake_up_bit(word, bit);
279 #endif /* _LINUX_WAIT_BIT_H */