async: Add some documentation.

Add some kerneldoc to the async interface. Signed-off-by: Cornelia Huck <cornelia.huck@de.ibm.com> Signed-off-by: Arjan van de Ven <arjan@linux.intel.com>

async: Add some documentation.
Add some kerneldoc to the async interface. Signed-off-by: Cornelia Huck <cornelia.huck@de.ibm.com> Signed-off-by: Arjan van de Ven <arjan@linux.intel.com>
Cornelia Huck · Arjan van de Ven
1 parent 86532d8b16
Showing 1 changed file with 47 additions and 0 deletions Side-by-side Diff
kernel/async.c
@@ -209,18 +209,43 @@
 	return newcookie;
 }
  
+/**
+ * async_schedule - schedule a function for asynchronous execution
+ * @ptr: function to execute asynchronously
+ * @data: data pointer to pass to the function
+ *
+ * Returns an async_cookie_t that may be used for checkpointing later.
+ * Note: This function may be called from atomic or non-atomic contexts.
+ */
 async_cookie_t async_schedule(async_func_ptr *ptr, void *data)
 {
 	return __async_schedule(ptr, data, &async_running);
 }
 EXPORT_SYMBOL_GPL(async_schedule);
  
+/**
+ * async_schedule_special - schedule a function for asynchronous execution with a special running queue
+ * @ptr: function to execute asynchronously
+ * @data: data pointer to pass to the function
+ * @running: list head to add to while running
+ *
+ * Returns an async_cookie_t that may be used for checkpointing later.
+ * @running may be used in the async_synchronize_*_special() functions
+ * to wait on a special running queue rather than on the global running
+ * queue.
+ * Note: This function may be called from atomic or non-atomic contexts.
+ */
 async_cookie_t async_schedule_special(async_func_ptr *ptr, void *data, struct list_head *running)
 {
 	return __async_schedule(ptr, data, running);
 }
 EXPORT_SYMBOL_GPL(async_schedule_special);
  
+/**
+ * async_synchronize_full - synchronize all asynchronous function calls
+ *
+ * This function waits until all asynchronous function calls have been done.
+ */
 void async_synchronize_full(void)
 {
 	do {
  
@@ -229,12 +254,27 @@
 }
 EXPORT_SYMBOL_GPL(async_synchronize_full);
  
+/**
+ * async_synchronize_full_special - synchronize all asynchronous function calls for a running list
+ * @list: running list to synchronize on
+ *
+ * This function waits until all asynchronous function calls for the running
+ * list @list have been done.
+ */
 void async_synchronize_full_special(struct list_head *list)
 {
 	async_synchronize_cookie_special(next_cookie, list);
 }
 EXPORT_SYMBOL_GPL(async_synchronize_full_special);
  
+/**
+ * async_synchronize_cookie_special - synchronize asynchronous function calls on a running list with cookie checkpointing
+ * @cookie: async_cookie_t to use as checkpoint
+ * @running: running list to synchronize on
+ *
+ * This function waits until all asynchronous function calls for the running
+ * list @list submitted prior to @cookie have been done.
+ */
 void async_synchronize_cookie_special(async_cookie_t cookie, struct list_head *running)
 {
 	ktime_t starttime, delta, endtime;
@@ -257,6 +297,13 @@
 }
 EXPORT_SYMBOL_GPL(async_synchronize_cookie_special);
  
+/**
+ * async_synchronize_cookie - synchronize asynchronous function calls with cookie checkpointing
+ * @cookie: async_cookie_t to use as checkpoint
+ *
+ * This function waits until all asynchronous function calls prior to @cookie
+ * have been done.
+ */
 void async_synchronize_cookie(async_cookie_t cookie)
 {
 	async_synchronize_cookie_special(cookie, &async_running);
...	...	@@ -209,18 +209,43 @@
209	209	return newcookie;
210	210	}
211	211
	212	+/**
	213	+ * async_schedule - schedule a function for asynchronous execution
	214	+ * @ptr: function to execute asynchronously
	215	+ * @data: data pointer to pass to the function
	216	+ *
	217	+ * Returns an async_cookie_t that may be used for checkpointing later.
	218	+ * Note: This function may be called from atomic or non-atomic contexts.
	219	+ */
212	220	async_cookie_t async_schedule(async_func_ptr ptr, void data)
213	221	{
214	222	return __async_schedule(ptr, data, &async_running);
215	223	}
216	224	EXPORT_SYMBOL_GPL(async_schedule);
217	225
	226	+/**
	227	+ * async_schedule_special - schedule a function for asynchronous execution with a special running queue
	228	+ * @ptr: function to execute asynchronously
	229	+ * @data: data pointer to pass to the function
	230	+ * @running: list head to add to while running
	231	+ *
	232	+ * Returns an async_cookie_t that may be used for checkpointing later.
	233	+ * @running may be used in the async_synchronize_*_special() functions
	234	+ * to wait on a special running queue rather than on the global running
	235	+ * queue.
	236	+ * Note: This function may be called from atomic or non-atomic contexts.
	237	+ */
218	238	async_cookie_t async_schedule_special(async_func_ptr ptr, void data, struct list_head *running)
219	239	{
220	240	return __async_schedule(ptr, data, running);
221	241	}
222	242	EXPORT_SYMBOL_GPL(async_schedule_special);
223	243
	244	+/**
	245	+ * async_synchronize_full - synchronize all asynchronous function calls
	246	+ *
	247	+ * This function waits until all asynchronous function calls have been done.
	248	+ */
224	249	void async_synchronize_full(void)
225	250	{
226	251	do {
227	252
...	...	@@ -229,12 +254,27 @@
229	254	}
230	255	EXPORT_SYMBOL_GPL(async_synchronize_full);
231	256
	257	+/**
	258	+ * async_synchronize_full_special - synchronize all asynchronous function calls for a running list
	259	+ * @list: running list to synchronize on
	260	+ *
	261	+ * This function waits until all asynchronous function calls for the running
	262	+ * list @list have been done.
	263	+ */
232	264	void async_synchronize_full_special(struct list_head *list)
233	265	{
234	266	async_synchronize_cookie_special(next_cookie, list);
235	267	}
236	268	EXPORT_SYMBOL_GPL(async_synchronize_full_special);
237	269
	270	+/**
	271	+ * async_synchronize_cookie_special - synchronize asynchronous function calls on a running list with cookie checkpointing
	272	+ * @cookie: async_cookie_t to use as checkpoint
	273	+ * @running: running list to synchronize on
	274	+ *
	275	+ * This function waits until all asynchronous function calls for the running
	276	+ * list @list submitted prior to @cookie have been done.
	277	+ */
238	278	void async_synchronize_cookie_special(async_cookie_t cookie, struct list_head *running)
239	279	{
240	280	ktime_t starttime, delta, endtime;
...	...	@@ -257,6 +297,13 @@
257	297	}
258	298	EXPORT_SYMBOL_GPL(async_synchronize_cookie_special);
259	299
	300	+/**
	301	+ * async_synchronize_cookie - synchronize asynchronous function calls with cookie checkpointing
	302	+ * @cookie: async_cookie_t to use as checkpoint
	303	+ *
	304	+ * This function waits until all asynchronous function calls prior to @cookie
	305	+ * have been done.
	306	+ */
260	307	void async_synchronize_cookie(async_cookie_t cookie)
261	308	{
262	309	async_synchronize_cookie_special(cookie, &async_running);