Merge tag 'for-5.7-rc1-tag' of git://git.kernel.org/pub/scm/linux/kernel/git/kdave...
[linux-2.6-microblaze.git] / kernel / sched / completion.c
1 // SPDX-License-Identifier: GPL-2.0
2 /*
3  * Generic wait-for-completion handler;
4  *
5  * It differs from semaphores in that their default case is the opposite,
6  * wait_for_completion default blocks whereas semaphore default non-block. The
7  * interface also makes it easy to 'complete' multiple waiting threads,
8  * something which isn't entirely natural for semaphores.
9  *
10  * But more importantly, the primitive documents the usage. Semaphores would
11  * typically be used for exclusion which gives rise to priority inversion.
12  * Waiting for completion is a typically sync point, but not an exclusion point.
13  */
14 #include "sched.h"
15
16 /**
17  * complete: - signals a single thread waiting on this completion
18  * @x:  holds the state of this particular completion
19  *
20  * This will wake up a single thread waiting on this completion. Threads will be
21  * awakened in the same order in which they were queued.
22  *
23  * See also complete_all(), wait_for_completion() and related routines.
24  *
25  * If this function wakes up a task, it executes a full memory barrier before
26  * accessing the task state.
27  */
28 void complete(struct completion *x)
29 {
30         unsigned long flags;
31
32         raw_spin_lock_irqsave(&x->wait.lock, flags);
33
34         if (x->done != UINT_MAX)
35                 x->done++;
36         swake_up_locked(&x->wait);
37         raw_spin_unlock_irqrestore(&x->wait.lock, flags);
38 }
39 EXPORT_SYMBOL(complete);
40
41 /**
42  * complete_all: - signals all threads waiting on this completion
43  * @x:  holds the state of this particular completion
44  *
45  * This will wake up all threads waiting on this particular completion event.
46  *
47  * If this function wakes up a task, it executes a full memory barrier before
48  * accessing the task state.
49  *
50  * Since complete_all() sets the completion of @x permanently to done
51  * to allow multiple waiters to finish, a call to reinit_completion()
52  * must be used on @x if @x is to be used again. The code must make
53  * sure that all waiters have woken and finished before reinitializing
54  * @x. Also note that the function completion_done() can not be used
55  * to know if there are still waiters after complete_all() has been called.
56  */
57 void complete_all(struct completion *x)
58 {
59         unsigned long flags;
60
61         lockdep_assert_RT_in_threaded_ctx();
62
63         raw_spin_lock_irqsave(&x->wait.lock, flags);
64         x->done = UINT_MAX;
65         swake_up_all_locked(&x->wait);
66         raw_spin_unlock_irqrestore(&x->wait.lock, flags);
67 }
68 EXPORT_SYMBOL(complete_all);
69
70 static inline long __sched
71 do_wait_for_common(struct completion *x,
72                    long (*action)(long), long timeout, int state)
73 {
74         if (!x->done) {
75                 DECLARE_SWAITQUEUE(wait);
76
77                 do {
78                         if (signal_pending_state(state, current)) {
79                                 timeout = -ERESTARTSYS;
80                                 break;
81                         }
82                         __prepare_to_swait(&x->wait, &wait);
83                         __set_current_state(state);
84                         raw_spin_unlock_irq(&x->wait.lock);
85                         timeout = action(timeout);
86                         raw_spin_lock_irq(&x->wait.lock);
87                 } while (!x->done && timeout);
88                 __finish_swait(&x->wait, &wait);
89                 if (!x->done)
90                         return timeout;
91         }
92         if (x->done != UINT_MAX)
93                 x->done--;
94         return timeout ?: 1;
95 }
96
97 static inline long __sched
98 __wait_for_common(struct completion *x,
99                   long (*action)(long), long timeout, int state)
100 {
101         might_sleep();
102
103         complete_acquire(x);
104
105         raw_spin_lock_irq(&x->wait.lock);
106         timeout = do_wait_for_common(x, action, timeout, state);
107         raw_spin_unlock_irq(&x->wait.lock);
108
109         complete_release(x);
110
111         return timeout;
112 }
113
114 static long __sched
115 wait_for_common(struct completion *x, long timeout, int state)
116 {
117         return __wait_for_common(x, schedule_timeout, timeout, state);
118 }
119
120 static long __sched
121 wait_for_common_io(struct completion *x, long timeout, int state)
122 {
123         return __wait_for_common(x, io_schedule_timeout, timeout, state);
124 }
125
126 /**
127  * wait_for_completion: - waits for completion of a task
128  * @x:  holds the state of this particular completion
129  *
130  * This waits to be signaled for completion of a specific task. It is NOT
131  * interruptible and there is no timeout.
132  *
133  * See also similar routines (i.e. wait_for_completion_timeout()) with timeout
134  * and interrupt capability. Also see complete().
135  */
136 void __sched wait_for_completion(struct completion *x)
137 {
138         wait_for_common(x, MAX_SCHEDULE_TIMEOUT, TASK_UNINTERRUPTIBLE);
139 }
140 EXPORT_SYMBOL(wait_for_completion);
141
142 /**
143  * wait_for_completion_timeout: - waits for completion of a task (w/timeout)
144  * @x:  holds the state of this particular completion
145  * @timeout:  timeout value in jiffies
146  *
147  * This waits for either a completion of a specific task to be signaled or for a
148  * specified timeout to expire. The timeout is in jiffies. It is not
149  * interruptible.
150  *
151  * Return: 0 if timed out, and positive (at least 1, or number of jiffies left
152  * till timeout) if completed.
153  */
154 unsigned long __sched
155 wait_for_completion_timeout(struct completion *x, unsigned long timeout)
156 {
157         return wait_for_common(x, timeout, TASK_UNINTERRUPTIBLE);
158 }
159 EXPORT_SYMBOL(wait_for_completion_timeout);
160
161 /**
162  * wait_for_completion_io: - waits for completion of a task
163  * @x:  holds the state of this particular completion
164  *
165  * This waits to be signaled for completion of a specific task. It is NOT
166  * interruptible and there is no timeout. The caller is accounted as waiting
167  * for IO (which traditionally means blkio only).
168  */
169 void __sched wait_for_completion_io(struct completion *x)
170 {
171         wait_for_common_io(x, MAX_SCHEDULE_TIMEOUT, TASK_UNINTERRUPTIBLE);
172 }
173 EXPORT_SYMBOL(wait_for_completion_io);
174
175 /**
176  * wait_for_completion_io_timeout: - waits for completion of a task (w/timeout)
177  * @x:  holds the state of this particular completion
178  * @timeout:  timeout value in jiffies
179  *
180  * This waits for either a completion of a specific task to be signaled or for a
181  * specified timeout to expire. The timeout is in jiffies. It is not
182  * interruptible. The caller is accounted as waiting for IO (which traditionally
183  * means blkio only).
184  *
185  * Return: 0 if timed out, and positive (at least 1, or number of jiffies left
186  * till timeout) if completed.
187  */
188 unsigned long __sched
189 wait_for_completion_io_timeout(struct completion *x, unsigned long timeout)
190 {
191         return wait_for_common_io(x, timeout, TASK_UNINTERRUPTIBLE);
192 }
193 EXPORT_SYMBOL(wait_for_completion_io_timeout);
194
195 /**
196  * wait_for_completion_interruptible: - waits for completion of a task (w/intr)
197  * @x:  holds the state of this particular completion
198  *
199  * This waits for completion of a specific task to be signaled. It is
200  * interruptible.
201  *
202  * Return: -ERESTARTSYS if interrupted, 0 if completed.
203  */
204 int __sched wait_for_completion_interruptible(struct completion *x)
205 {
206         long t = wait_for_common(x, MAX_SCHEDULE_TIMEOUT, TASK_INTERRUPTIBLE);
207         if (t == -ERESTARTSYS)
208                 return t;
209         return 0;
210 }
211 EXPORT_SYMBOL(wait_for_completion_interruptible);
212
213 /**
214  * wait_for_completion_interruptible_timeout: - waits for completion (w/(to,intr))
215  * @x:  holds the state of this particular completion
216  * @timeout:  timeout value in jiffies
217  *
218  * This waits for either a completion of a specific task to be signaled or for a
219  * specified timeout to expire. It is interruptible. The timeout is in jiffies.
220  *
221  * Return: -ERESTARTSYS if interrupted, 0 if timed out, positive (at least 1,
222  * or number of jiffies left till timeout) if completed.
223  */
224 long __sched
225 wait_for_completion_interruptible_timeout(struct completion *x,
226                                           unsigned long timeout)
227 {
228         return wait_for_common(x, timeout, TASK_INTERRUPTIBLE);
229 }
230 EXPORT_SYMBOL(wait_for_completion_interruptible_timeout);
231
232 /**
233  * wait_for_completion_killable: - waits for completion of a task (killable)
234  * @x:  holds the state of this particular completion
235  *
236  * This waits to be signaled for completion of a specific task. It can be
237  * interrupted by a kill signal.
238  *
239  * Return: -ERESTARTSYS if interrupted, 0 if completed.
240  */
241 int __sched wait_for_completion_killable(struct completion *x)
242 {
243         long t = wait_for_common(x, MAX_SCHEDULE_TIMEOUT, TASK_KILLABLE);
244         if (t == -ERESTARTSYS)
245                 return t;
246         return 0;
247 }
248 EXPORT_SYMBOL(wait_for_completion_killable);
249
250 /**
251  * wait_for_completion_killable_timeout: - waits for completion of a task (w/(to,killable))
252  * @x:  holds the state of this particular completion
253  * @timeout:  timeout value in jiffies
254  *
255  * This waits for either a completion of a specific task to be
256  * signaled or for a specified timeout to expire. It can be
257  * interrupted by a kill signal. The timeout is in jiffies.
258  *
259  * Return: -ERESTARTSYS if interrupted, 0 if timed out, positive (at least 1,
260  * or number of jiffies left till timeout) if completed.
261  */
262 long __sched
263 wait_for_completion_killable_timeout(struct completion *x,
264                                      unsigned long timeout)
265 {
266         return wait_for_common(x, timeout, TASK_KILLABLE);
267 }
268 EXPORT_SYMBOL(wait_for_completion_killable_timeout);
269
270 /**
271  *      try_wait_for_completion - try to decrement a completion without blocking
272  *      @x:     completion structure
273  *
274  *      Return: 0 if a decrement cannot be done without blocking
275  *               1 if a decrement succeeded.
276  *
277  *      If a completion is being used as a counting completion,
278  *      attempt to decrement the counter without blocking. This
279  *      enables us to avoid waiting if the resource the completion
280  *      is protecting is not available.
281  */
282 bool try_wait_for_completion(struct completion *x)
283 {
284         unsigned long flags;
285         bool ret = true;
286
287         /*
288          * Since x->done will need to be locked only
289          * in the non-blocking case, we check x->done
290          * first without taking the lock so we can
291          * return early in the blocking case.
292          */
293         if (!READ_ONCE(x->done))
294                 return false;
295
296         raw_spin_lock_irqsave(&x->wait.lock, flags);
297         if (!x->done)
298                 ret = false;
299         else if (x->done != UINT_MAX)
300                 x->done--;
301         raw_spin_unlock_irqrestore(&x->wait.lock, flags);
302         return ret;
303 }
304 EXPORT_SYMBOL(try_wait_for_completion);
305
306 /**
307  *      completion_done - Test to see if a completion has any waiters
308  *      @x:     completion structure
309  *
310  *      Return: 0 if there are waiters (wait_for_completion() in progress)
311  *               1 if there are no waiters.
312  *
313  *      Note, this will always return true if complete_all() was called on @X.
314  */
315 bool completion_done(struct completion *x)
316 {
317         unsigned long flags;
318
319         if (!READ_ONCE(x->done))
320                 return false;
321
322         /*
323          * If ->done, we need to wait for complete() to release ->wait.lock
324          * otherwise we can end up freeing the completion before complete()
325          * is done referencing it.
326          */
327         raw_spin_lock_irqsave(&x->wait.lock, flags);
328         raw_spin_unlock_irqrestore(&x->wait.lock, flags);
329         return true;
330 }
331 EXPORT_SYMBOL(completion_done);