[patch]block: document blk_plug

[Shaohua Li <shaohua.li@intel.com>]

Andrew Morton is asking to document blk_plug, so here is my attempt.

Signed-off-by: Shaohua Li <shaohua.li@intel.com>
---
 include/linux/blkdev.h |   11 +++++++++++
 1 file changed, 11 insertions(+)

Index: linux/include/linux/blkdev.h
===================================================================
--- linux.orig/include/linux/blkdev.h	2011-07-29 10:51:29.000000000 +0800
+++ linux/include/linux/blkdev.h	2011-07-29 11:07:49.000000000 +0800
@@ -858,6 +858,17 @@ struct request_queue *blk_alloc_queue_no
 extern void blk_put_queue(struct request_queue *);
 
 /*
+ * blk_plug gives each task a request list. Since blk_start_plug() called,
+ * requests from the task will be added to the per-task list and then moved
+ * to global request_queue in a batch way at appropriate time(either
+ * blk_finish_plug() is called or task goes to sleep). blk_plug has some
+ * advantages:
+ * 1. Better request merge. The assumption here is requests from a task have
+ *    better chances to be merged.
+ * 2. Better scalability. Requests are moved from per-task list to global
+ *    request_queue in a batch way, so the total times grabing global
+ *    request_queue lock are reduced.
+ *
  * Note: Code in between changing the blk_plug list/cb_list or element of such
  * lists is preemptable, but such code can't do sleep (or be very careful),
  * otherwise data is corrupted. For details, please check schedule() where