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 #endif /* _LINUX_WAIT_BIT_H */ 266