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 | #include <linux/wait.h> | 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 | struct completion { | 25 | struct completion { |
| 14 | unsigned int done; | 26 | unsigned int done; |
| 15 | wait_queue_head_t wait; | 27 | wait_queue_head_t wait; |
| @@ -21,6 +33,14 @@ struct completion { · 5 unmodified lines | |||
| 21 | #define COMPLETION_INITIALIZER_ONSTACK(work) \ | 33 | #define COMPLETION_INITIALIZER_ONSTACK(work) \ |
| 22 | ({ init_completion(&work); work; }) | 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 | #define DECLARE_COMPLETION(work) \ | 44 | #define DECLARE_COMPLETION(work) \ |
| 25 | struct completion work = COMPLETION_INITIALIZER(work) | 45 | struct completion work = COMPLETION_INITIALIZER(work) |
| 26 | 46 | ||
| @@ -29,6 +49,13 @@ struct completion { · 2 unmodified lines | |||
| 29 | * completions - so we use the _ONSTACK() variant for those that | 49 | * completions - so we use the _ONSTACK() variant for those that |
| 30 | * are on the kernel stack: | 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 | #ifdef CONFIG_LOCKDEP | 59 | #ifdef CONFIG_LOCKDEP |
| 33 | # define DECLARE_COMPLETION_ONSTACK(work) \ | 60 | # define DECLARE_COMPLETION_ONSTACK(work) \ |
| 34 | struct completion work = COMPLETION_INITIALIZER_ONSTACK(work) | 61 | struct completion work = COMPLETION_INITIALIZER_ONSTACK(work) |
| @@ -36,6 +63,13 @@ struct completion { · 1 unmodified line | |||
| 36 | # define DECLARE_COMPLETION_ONSTACK(work) DECLARE_COMPLETION(work) | 63 | # define DECLARE_COMPLETION_ONSTACK(work) DECLARE_COMPLETION(work) |
| 37 | #endif | 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 | static inline void init_completion(struct completion *x) | 73 | static inline void init_completion(struct completion *x) |
| 40 | { | 74 | { |
| 41 | x->done = 0; | 75 | x->done = 0; |
| @@ -55,6 +89,13 @@ extern bool completion_done(struct completion *x); · 13 unmodified lines | |||
| 55 | extern void complete(struct completion *); | 89 | extern void complete(struct completion *); |
| 56 | extern void complete_all(struct completion *); | 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 | #define INIT_COMPLETION(x) ((x).done = 0) | 99 | #define INIT_COMPLETION(x) ((x).done = 0) |
| 59 | 100 | ||
| 60 | 101 | ||