Merge master.kernel.org:/pub/scm/linux/kernel/git/torvalds/linux-2.6

[linux-2.6] / Documentation / block / biodoc.txt

diff --git a/Documentation/block/biodoc.txt b/Documentation/block/biodoc.txt
index c6c9a9c10d7f88b5f894990e45878acadbb2ea64..dc3f49e3e5392891f10d700567363b3446358b67 100644 (file)
--- a/Documentation/block/biodoc.txt
+++ b/Documentation/block/biodoc.txt
@@ -477,9 +477,9 @@ With this multipage bio design:
   the same bi_io_vec array, but with the index and size accordingly modified)
 - A linked list of bios is used as before for unrelated merges (*) - this
   avoids reallocs and makes independent completions easier to handle.
   the same bi_io_vec array, but with the index and size accordingly modified)
 - A linked list of bios is used as before for unrelated merges (*) - this
   avoids reallocs and makes independent completions easier to handle.

-- Code that traverses the req list needs to make a distinction between
-  segments of a request (bio_for_each_segment) and the distinct completion
-  units/bios (rq_for_each_bio).
+- Code that traverses the req list can find all the segments of a bio
+  by using rq_for_each_segment.  This handles the fact that a request
+  has multiple bios, each of which can have multiple segments.

 - Drivers which can't process a large bio in one shot can use the bi_idx
   field to keep track of the next bio_vec entry to process.
   (e.g a 1MB bio_vec needs to be handled in max 128kB chunks for IDE)
 - Drivers which can't process a large bio in one shot can use the bi_idx
   field to keep track of the next bio_vec entry to process.
   (e.g a 1MB bio_vec needs to be handled in max 128kB chunks for IDE)


@@ -664,14 +664,14 @@ in lvm or md.
 
 3.2.1 Traversing segments and completion units in a request
 
 
 3.2.1 Traversing segments and completion units in a request
 

-The macros bio_for_each_segment() and rq_for_each_bio() should be used for
-traversing the bios in the request list (drivers should avoid directly
-trying to do it themselves). Using these helpers should also make it easier
-to cope with block changes in the future.
+The macro rq_for_each_segment() should be used for traversing the bios
+in the request list (drivers should avoid directly trying to do it
+themselves). Using these helpers should also make it easier to cope
+with block changes in the future.

 
 

-       rq_for_each_bio(bio, rq)
-               bio_for_each_segment(bio_vec, bio, i)
-                       /* bio_vec is now current segment */
+       struct req_iterator iter;
+       rq_for_each_segment(bio_vec, rq, iter)
+               /* bio_vec is now current segment */

 
 I/O completion callbacks are per-bio rather than per-segment, so drivers
 that traverse bio chains on completion need to keep that in mind. Drivers
 
 I/O completion callbacks are per-bio rather than per-segment, so drivers
 that traverse bio chains on completion need to keep that in mind. Drivers


@@ -740,12 +740,12 @@ Block now offers some simple generic functionality to help support command
 queueing (typically known as tagged command queueing), ie manage more than
 one outstanding command on a queue at any given time.
 
 queueing (typically known as tagged command queueing), ie manage more than
 one outstanding command on a queue at any given time.
 

-       blk_queue_init_tags(request_queue_t *q, int depth)
+       blk_queue_init_tags(struct request_queue *q, int depth)

 
        Initialize internal command tagging structures for a maximum
        depth of 'depth'.
 
 
        Initialize internal command tagging structures for a maximum
        depth of 'depth'.
 

-       blk_queue_free_tags((request_queue_t *q)
+       blk_queue_free_tags((struct request_queue *q)

 
        Teardown tag info associated with the queue. This will be done
        automatically by block if blk_queue_cleanup() is called on a queue
 
        Teardown tag info associated with the queue. This will be done
        automatically by block if blk_queue_cleanup() is called on a queue


@@ -754,7 +754,7 @@ one outstanding command on a queue at any given time.
 The above are initialization and exit management, the main helpers during
 normal operations are:
 
 The above are initialization and exit management, the main helpers during
 normal operations are:
 

-       blk_queue_start_tag(request_queue_t *q, struct request *rq)
+       blk_queue_start_tag(struct request_queue *q, struct request *rq)

 
        Start tagged operation for this request. A free tag number between
        0 and 'depth' is assigned to the request (rq->tag holds this number),
 
        Start tagged operation for this request. A free tag number between
        0 and 'depth' is assigned to the request (rq->tag holds this number),


@@ -762,7 +762,7 @@ normal operations are:
        for this queue is already achieved (or if the tag wasn't started for
        some other reason), 1 is returned. Otherwise 0 is returned.
 
        for this queue is already achieved (or if the tag wasn't started for
        some other reason), 1 is returned. Otherwise 0 is returned.
 

-       blk_queue_end_tag(request_queue_t *q, struct request *rq)
+       blk_queue_end_tag(struct request_queue *q, struct request *rq)

 
        End tagged operation on this request. 'rq' is removed from the internal
        book keeping structures.
 
        End tagged operation on this request. 'rq' is removed from the internal
        book keeping structures.


@@ -781,7 +781,7 @@ queue. For instance, on IDE any tagged request error needs to clear both
 the hardware and software block queue and enable the driver to sanely restart
 all the outstanding requests. There's a third helper to do that:
 
 the hardware and software block queue and enable the driver to sanely restart
 all the outstanding requests. There's a third helper to do that:
 

-       blk_queue_invalidate_tags(request_queue_t *q)
+       blk_queue_invalidate_tags(struct request_queue *q)

 
        Clear the internal block tag queue and re-add all the pending requests
        to the request queue. The driver will receive them again on the
 
        Clear the internal block tag queue and re-add all the pending requests
        to the request queue. The driver will receive them again on the


@@ -946,6 +946,13 @@ elevator_merged_fn         called when a request in the scheduler has been
                                scheduler for example, to reposition the request
                                if its sorting order has changed.
 
                                scheduler for example, to reposition the request
                                if its sorting order has changed.
 

+elevator_allow_merge_fn                called whenever the block layer determines
+                               that a bio can be merged into an existing
+                               request safely. The io scheduler may still
+                               want to stop a merge at this point if it
+                               results in some sort of conflict internally,
+                               this hook allows it to do that.
+

 elevator_dispatch_fn           fills the dispatch queue with ready requests.
                                I/O schedulers are free to postpone requests by
                                not filling the dispatch queue unless @force
 elevator_dispatch_fn           fills the dispatch queue with ready requests.
                                I/O schedulers are free to postpone requests by
                                not filling the dispatch queue unless @force