1 /* SPDX-License-Identifier: GPL-2.0 */ 2 #ifndef __LINUX_COMPLETION_H 3 #define __LINUX_COMPLETION_H 4 5 /* 6 * (C) Copyright 2001 Linus Torvalds 7 * 8 * Atomic wait-for-completion handler data structures. 9 * See kernel/sched/completion.c for details. 10 */ 11 12 #include <linux/wait.h> 13 #ifdef CONFIG_LOCKDEP_COMPLETIONS 14 #include <linux/lockdep.h> 15 #endif 16 17 /* 18 * struct completion - structure used to maintain state for a "completion" 19 * 20 * This is the opaque structure used to maintain the state for a "completion". 21 * Completions currently use a FIFO to queue threads that have to wait for 22 * the "completion" event. 23 * 24 * See also: complete(), wait_for_completion() (and friends _timeout, 25 * _interruptible, _interruptible_timeout, and _killable), init_completion(), 26 * reinit_completion(), and macros DECLARE_COMPLETION(), 27 * DECLARE_COMPLETION_ONSTACK(). 28 */ 29 struct completion { 30 unsigned int done; 31 wait_queue_head_t wait; 32 #ifdef CONFIG_LOCKDEP_COMPLETIONS 33 struct lockdep_map_cross map; 34 #endif 35 }; 36 37 #ifdef CONFIG_LOCKDEP_COMPLETIONS 38 static inline void complete_acquire(struct completion *x) 39 { 40 lock_acquire_exclusive((struct lockdep_map *)&x->map, 0, 0, NULL, _RET_IP_); 41 } 42 43 static inline void complete_release(struct completion *x) 44 { 45 lock_release((struct lockdep_map *)&x->map, 0, _RET_IP_); 46 } 47 48 static inline void complete_release_commit(struct completion *x) 49 { 50 lock_commit_crosslock((struct lockdep_map *)&x->map); 51 } 52 53 #define init_completion_map(x, m) \ 54 do { \ 55 lockdep_init_map_crosslock((struct lockdep_map *)&(x)->map, \ 56 (m)->name, (m)->key, 0); \ 57 __init_completion(x); \ 58 } while (0) 59 60 #define init_completion(x) \ 61 do { \ 62 static struct lock_class_key __key; \ 63 lockdep_init_map_crosslock((struct lockdep_map *)&(x)->map, \ 64 "(completion)" #x, \ 65 &__key, 0); \ 66 __init_completion(x); \ 67 } while (0) 68 #else 69 #define init_completion_map(x, m) __init_completion(x) 70 #define init_completion(x) __init_completion(x) 71 static inline void complete_acquire(struct completion *x) {} 72 static inline void complete_release(struct completion *x) {} 73 static inline void complete_release_commit(struct completion *x) {} 74 #endif 75 76 #ifdef CONFIG_LOCKDEP_COMPLETIONS 77 #define COMPLETION_INITIALIZER(work) \ 78 { 0, __WAIT_QUEUE_HEAD_INITIALIZER((work).wait), \ 79 STATIC_CROSS_LOCKDEP_MAP_INIT("(completion)" #work, &(work)) } 80 #else 81 #define COMPLETION_INITIALIZER(work) \ 82 { 0, __WAIT_QUEUE_HEAD_INITIALIZER((work).wait) } 83 #endif 84 85 #define COMPLETION_INITIALIZER_ONSTACK_MAP(work, map) \ 86 (*({ init_completion_map(&(work), &(map)); &(work); })) 87 88 #define COMPLETION_INITIALIZER_ONSTACK(work) \ 89 (*({ init_completion(&work); &work; })) 90 91 /** 92 * DECLARE_COMPLETION - declare and initialize a completion structure 93 * @work: identifier for the completion structure 94 * 95 * This macro declares and initializes a completion structure. Generally used 96 * for static declarations. You should use the _ONSTACK variant for automatic 97 * variables. 98 */ 99 #define DECLARE_COMPLETION(work) \ 100 struct completion work = COMPLETION_INITIALIZER(work) 101 102 /* 103 * Lockdep needs to run a non-constant initializer for on-stack 104 * completions - so we use the _ONSTACK() variant for those that 105 * are on the kernel stack: 106 */ 107 /** 108 * DECLARE_COMPLETION_ONSTACK - declare and initialize a completion structure 109 * @work: identifier for the completion structure 110 * 111 * This macro declares and initializes a completion structure on the kernel 112 * stack. 113 */ 114 #ifdef CONFIG_LOCKDEP 115 # define DECLARE_COMPLETION_ONSTACK(work) \ 116 struct completion work = COMPLETION_INITIALIZER_ONSTACK(work) 117 # define DECLARE_COMPLETION_ONSTACK_MAP(work, map) \ 118 struct completion work = COMPLETION_INITIALIZER_ONSTACK_MAP(work, map) 119 #else 120 # define DECLARE_COMPLETION_ONSTACK(work) DECLARE_COMPLETION(work) 121 # define DECLARE_COMPLETION_ONSTACK_MAP(work, map) DECLARE_COMPLETION(work) 122 #endif 123 124 /** 125 * init_completion - Initialize a dynamically allocated completion 126 * @x: pointer to completion structure that is to be initialized 127 * 128 * This inline function will initialize a dynamically created completion 129 * structure. 130 */ 131 static inline void __init_completion(struct completion *x) 132 { 133 x->done = 0; 134 init_waitqueue_head(&x->wait); 135 } 136 137 /** 138 * reinit_completion - reinitialize a completion structure 139 * @x: pointer to completion structure that is to be reinitialized 140 * 141 * This inline function should be used to reinitialize a completion structure so it can 142 * be reused. This is especially important after complete_all() is used. 143 */ 144 static inline void reinit_completion(struct completion *x) 145 { 146 x->done = 0; 147 } 148 149 extern void wait_for_completion(struct completion *); 150 extern void wait_for_completion_io(struct completion *); 151 extern int wait_for_completion_interruptible(struct completion *x); 152 extern int wait_for_completion_killable(struct completion *x); 153 extern unsigned long wait_for_completion_timeout(struct completion *x, 154 unsigned long timeout); 155 extern unsigned long wait_for_completion_io_timeout(struct completion *x, 156 unsigned long timeout); 157 extern long wait_for_completion_interruptible_timeout( 158 struct completion *x, unsigned long timeout); 159 extern long wait_for_completion_killable_timeout( 160 struct completion *x, unsigned long timeout); 161 extern bool try_wait_for_completion(struct completion *x); 162 extern bool completion_done(struct completion *x); 163 164 extern void complete(struct completion *); 165 extern void complete_all(struct completion *); 166 167 #endif 168