[PATCH] bio documentation update

From: Jens Axboe <axboe@suse.de>

Although it was an established part of the current bio api, it was never
documented that bio_add_page() and merge_bvec_fn() must accept to add at
least one page to an empty bio.

diff --git a/drivers/block/ll_rw_blk.c b/drivers/block/ll_rw_blk.c
index 530f6c5962aa3cc6c882a82c88f0f8324952fcfe..c23382abd4f548c41d76839ced4ac5096aa27681 100644 (file)
--- a/drivers/block/ll_rw_blk.c
+++ b/drivers/block/ll_rw_blk.c
@@ -173,9 +173,11 @@ EXPORT_SYMBOL(blk_queue_prep_rq);
  * are dynamic, and thus we have to query the queue whether it is ok to
  * add a new bio_vec to a bio at a given offset or not. If the block device
  * has such limitations, it needs to register a merge_bvec_fn to control
- * the size of bio's sent to it. Per default now merge_bvec_fn is defined for
- * a queue, and only the fixed limits are honored.
- *
+ * the size of bio's sent to it. Note that a block device *must* allow a
+ * single page to be added to an empty bio. The block device driver may want
+ * to use the bio_split() function to deal with these bio's. By default
+ * no merge_bvec_fn is defined for a queue, and only the fixed limits are
+ * honored.
  */
 void blk_queue_merge_bvec(request_queue_t *q, merge_bvec_fn *mbfn)
 {

diff --git a/fs/bio.c b/fs/bio.c
index 390d862325b9ef05dfc01f7e8ab219d95992a25c..048e274084bae57a4573da26124357a8cad9e8f1 100644 (file)
--- a/fs/bio.c
+++ b/fs/bio.c
@@ -290,7 +290,9 @@ int bio_get_nr_vecs(struct block_device *bdev)
  *
  *     Attempt to add a page to the bio_vec maplist. This can fail for a
  *     number of reasons, such as the bio being full or target block
- *     device limitations.
+ *     device limitations. The target block device must allow bio's
+ *      smaller than PAGE_SIZE, so it is always possible to add a single
+ *      page to an empty bio.
  */
 int bio_add_page(struct bio *bio, struct page *page, unsigned int len,
                 unsigned int offset)