This patch adds kernel doc for the completion feature. An error in the split-man.pl PERL snippet in kernel-doc-nano-HOWTO.txt is also fixed.
Showing the changes to include/linux/completion.h (1 of 3 files). Show all
Unified · Split
| @@ -10,6 +10,18 @@ · 9 unmodified lines | ||
| 10 | 10 | |
| 11 | 11 | #include <linux/wait.h> |
| 12 | 12 | |
| 13 | +/** | |
| 14 | + * struct completion - structure used to maintain state for a "completion" | |
| 15 | + * | |
| 16 | + * This is the opaque structure used to maintain the state for a "completion". | |
| 17 | + * Completions currently use a FIFO to queue threads that have to wait for | |
| 18 | + * the "completion" event. | |
| 19 | + * | |
| 20 | + * See also: complete(), wait_for_completion() (and friends _timeout, | |
| 21 | + * _interruptible, _interruptible_timeout, and _killable), init_completion(), | |
| 22 | + * and macros DECLARE_COMPLETION(), DECLARE_COMPLETION_ONSTACK(), and | |
| 23 | + * INIT_COMPLETION(). | |
| 24 | + */ | |
| 13 | 25 | struct completion { |
| 14 | 26 | unsigned int done; |
| 15 | 27 | wait_queue_head_t wait; |
| @@ -21,6 +33,14 @@ struct completion { · 5 unmodified lines | ||
| 21 | 33 | #define COMPLETION_INITIALIZER_ONSTACK(work) \ |
| 22 | 34 | ({ init_completion(&work); work; }) |
| 23 | 35 | |
| 36 | +/** | |
| 37 | + * DECLARE_COMPLETION: - declare and initialize a completion structure | |
| 38 | + * @work: identifier for the completion structure | |
| 39 | + * | |
| 40 | + * This macro declares and initializes a completion structure. Generally used | |
| 41 | + * for static declarations. You should use the _ONSTACK variant for automatic | |
| 42 | + * variables. | |
| 43 | + */ | |
| 24 | 44 | #define DECLARE_COMPLETION(work) \ |
| 25 | 45 | struct completion work = COMPLETION_INITIALIZER(work) |
| 26 | 46 | |
| @@ -29,6 +49,13 @@ struct completion { · 2 unmodified lines | ||
| 29 | 49 | * completions - so we use the _ONSTACK() variant for those that |
| 30 | 50 | * are on the kernel stack: |
| 31 | 51 | */ |
| 52 | +/** | |
| 53 | + * DECLARE_COMPLETION_ONSTACK: - declare and initialize a completion structure | |
| 54 | + * @work: identifier for the completion structure | |
| 55 | + * | |
| 56 | + * This macro declares and initializes a completion structure on the kernel | |
| 57 | + * stack. | |
| 58 | + */ | |
| 32 | 59 | #ifdef CONFIG_LOCKDEP |
| 33 | 60 | # define DECLARE_COMPLETION_ONSTACK(work) \ |
| 34 | 61 | struct completion work = COMPLETION_INITIALIZER_ONSTACK(work) |
| @@ -36,6 +63,13 @@ struct completion { · 1 unmodified line | ||
| 36 | 63 | # define DECLARE_COMPLETION_ONSTACK(work) DECLARE_COMPLETION(work) |
| 37 | 64 | #endif |
| 38 | 65 | |
| 66 | +/** | |
| 67 | + * init_completion: - Initialize a dynamically allocated completion | |
| 68 | + * @x: completion structure that is to be initialized | |
| 69 | + * | |
| 70 | + * This inline function will initialize a dynamically created completion | |
| 71 | + * structure. | |
| 72 | + */ | |
| 39 | 73 | static inline void init_completion(struct completion *x) |
| 40 | 74 | { |
| 41 | 75 | x->done = 0; |
| @@ -55,6 +89,13 @@ extern bool completion_done(struct completion *x); · 13 unmodified lines | ||
| 55 | 89 | extern void complete(struct completion *); |
| 56 | 90 | extern void complete_all(struct completion *); |
| 57 | 91 | |
| 92 | +/** | |
| 93 | + * INIT_COMPLETION: - reinitialize a completion structure | |
| 94 | + * @x: completion structure to be reinitialized | |
| 95 | + * | |
| 96 | + * This macro should be used to reinitialize a completion structure so it can | |
| 97 | + * be reused. This is especially important after complete_all() is used. | |
| 98 | + */ | |
| 58 | 99 | #define INIT_COMPLETION(x) ((x).done = 0) |
| 59 | 100 | |
| 60 | 101 | |