biodoc.txt

linux 内核源代码

The normal i/o submission interfaces, e.g submit_bio, could be bypassed
for specially crafted requests which such ioctl or diagnostics
interfaces would typically use, and the elevator add_request routine
can instead be used to directly insert such requests in the queue or preferably
the blk_do_rq routine can be used to place the request on the queue and
wait for completion. Alternatively, sometimes the caller might just
invoke a lower level driver specific interface with the request as a
parameter.

If the request is a means for passing on special information associated with
the command, then such information is associated with the request->special
field (rather than misuse the request->buffer field which is meant for the
request data buffer's virtual mapping).

For passing request data, the caller must build up a bio descriptor
representing the concerned memory buffer if the underlying driver interprets
bio segments or uses the block layer end*request* functions for i/o
completion. Alternatively one could directly use the request->buffer field to
specify the virtual address of the buffer, if the driver expects buffer
addresses passed in this way and ignores bio entries for the request type
involved. In the latter case, the driver would modify and manage the
request->buffer, request->sector and request->nr_sectors or
request->current_nr_sectors fields itself rather than using the block layer
end_request or end_that_request_first completion interfaces.
(See 2.3 or Documentation/block/request.txt for a brief explanation of
the request structure fields)

[TBD: end_that_request_last should be usable even in this case;
Perhaps an end_that_direct_request_first routine could be implemented to make
handling direct requests easier for such drivers; Also for drivers that
expect bios, a helper function could be provided for setting up a bio
corresponding to a data buffer]

<JENS: I dont understand the above, why is end_that_request_first() not
usable? Or _last for that matter. I must be missing something>
<SUP: What I meant here was that if the request doesn't have a bio, then
 end_that_request_first doesn't modify nr_sectors or current_nr_sectors,
 and hence can't be used for advancing request state settings on the
 completion of partial transfers. The driver has to modify these fields 
 directly by hand.
 This is because end_that_request_first only iterates over the bio list,
 and always returns 0 if there are none associated with the request.
 _last works OK in this case, and is not a problem, as I mentioned earlier
>

1.3.1 Pre-built Commands

A request can be created with a pre-built custom command  to be sent directly
to the device. The cmd block in the request structure has room for filling
in the command bytes. (i.e rq->cmd is now 16 bytes in size, and meant for
command pre-building, and the type of the request is now indicated
through rq->flags instead of via rq->cmd)

The request structure flags can be set up to indicate the type of request
in such cases (REQ_PC: direct packet command passed to driver, REQ_BLOCK_PC:
packet command issued via blk_do_rq, REQ_SPECIAL: special request).

It can help to pre-build device commands for requests in advance.
Drivers can now specify a request prepare function (q->prep_rq_fn) that the
block layer would invoke to pre-build device commands for a given request,
or perform other preparatory processing for the request. This is routine is
called by elv_next_request(), i.e. typically just before servicing a request.
(The prepare function would not be called for requests that have REQ_DONTPREP
enabled)

Aside:
  Pre-building could possibly even be done early, i.e before placing the
  request on the queue, rather than construct the command on the fly in the
  driver while servicing the request queue when it may affect latencies in
  interrupt context or responsiveness in general. One way to add early
  pre-building would be to do it whenever we fail to merge on a request.
  Now REQ_NOMERGE is set in the request flags to skip this one in the future,
  which means that it will not change before we feed it to the device. So
  the pre-builder hook can be invoked there.


2. Flexible and generic but minimalist i/o structure/descriptor.

2.1 Reason for a new structure and requirements addressed

Prior to 2.5, buffer heads were used as the unit of i/o at the generic block
layer, and the low level request structure was associated with a chain of
buffer heads for a contiguous i/o request. This led to certain inefficiencies
when it came to large i/o requests and readv/writev style operations, as it
forced such requests to be broken up into small chunks before being passed
on to the generic block layer, only to be merged by the i/o scheduler
when the underlying device was capable of handling the i/o in one shot.
Also, using the buffer head as an i/o structure for i/os that didn't originate
from the buffer cache unnecessarily added to the weight of the descriptors
which were generated for each such chunk.

The following were some of the goals and expectations considered in the
redesign of the block i/o data structure in 2.5.

i.  Should be appropriate as a descriptor for both raw and buffered i/o  -
    avoid cache related fields which are irrelevant in the direct/page i/o path,
    or filesystem block size alignment restrictions which may not be relevant
    for raw i/o.
ii. Ability to represent high-memory buffers (which do not have a virtual
    address mapping in kernel address space).
iii.Ability to represent large i/os w/o unnecessarily breaking them up (i.e
    greater than PAGE_SIZE chunks in one shot)
iv. At the same time, ability to retain independent identity of i/os from
    different sources or i/o units requiring individual completion (e.g. for
    latency reasons)
v.  Ability to represent an i/o involving multiple physical memory segments
    (including non-page aligned page fragments, as specified via readv/writev)
    without unnecessarily breaking it up, if the underlying device is capable of
    handling it.
vi. Preferably should be based on a memory descriptor structure that can be
    passed around different types of subsystems or layers, maybe even
    networking, without duplication or extra copies of data/descriptor fields
    themselves in the process
vii.Ability to handle the possibility of splits/merges as the structure passes
    through layered drivers (lvm, md, evms), with minimal overhead.

The solution was to define a new structure (bio)  for the block layer,
instead of using the buffer head structure (bh) directly, the idea being
avoidance of some associated baggage and limitations. The bio structure
is uniformly used for all i/o at the block layer ; it forms a part of the
bh structure for buffered i/o, and in the case of raw/direct i/o kiobufs are
mapped to bio structures.

2.2 The bio struct

The bio structure uses a vector representation pointing to an array of tuples
of <page, offset, len> to describe the i/o buffer, and has various other
fields describing i/o parameters and state that needs to be maintained for
performing the i/o.

Notice that this representation means that a bio has no virtual address
mapping at all (unlike buffer heads).

struct bio_vec {
       struct page     *bv_page;
       unsigned short  bv_len;
       unsigned short  bv_offset;
};

/*
 * main unit of I/O for the block layer and lower layers (ie drivers)
 */
struct bio {
       sector_t            bi_sector;
       struct bio          *bi_next;    /* request queue link */
       struct block_device *bi_bdev;	/* target device */
       unsigned long       bi_flags;    /* status, command, etc */
       unsigned long       bi_rw;       /* low bits: r/w, high: priority */

       unsigned int	bi_vcnt;     /* how may bio_vec's */
       unsigned int	bi_idx;		/* current index into bio_vec array */

       unsigned int	bi_size;     /* total size in bytes */
       unsigned short 	bi_phys_segments; /* segments after physaddr coalesce*/
       unsigned short	bi_hw_segments; /* segments after DMA remapping */
       unsigned int	bi_max;	     /* max bio_vecs we can hold
                                        used as index into pool */
       struct bio_vec   *bi_io_vec;  /* the actual vec list */
       bio_end_io_t	*bi_end_io;  /* bi_end_io (bio) */
       atomic_t		bi_cnt;	     /* pin count: free when it hits zero */
       void             *bi_private;
       bio_destructor_t *bi_destructor; /* bi_destructor (bio) */
};

With this multipage bio design:

- Large i/os can be sent down in one go using a bio_vec list consisting
  of an array of <page, offset, len> fragments (similar to the way fragments
  are represented in the zero-copy network code)
- Splitting of an i/o request across multiple devices (as in the case of
  lvm or raid) is achieved by cloning the bio (where the clone points to
  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 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)
  [TBD: Should preferably also have a bi_voffset and bi_vlen to avoid modifying
   bi_offset an len fields]

(*) unrelated merges -- a request ends up containing two or more bios that
    didn't originate from the same place.

bi_end_io() i/o callback gets called on i/o completion of the entire bio.

At a lower level, drivers build a scatter gather list from the merged bios.
The scatter gather list is in the form of an array of <page, offset, len>
entries with their corresponding dma address mappings filled in at the
appropriate time. As an optimization, contiguous physical pages can be
covered by a single entry where <page> refers to the first page and <len>
covers the range of pages (upto 16 contiguous pages could be covered this
way). There is a helper routine (blk_rq_map_sg) which drivers can use to build
the sg list.

Note: Right now the only user of bios with more than one page is ll_rw_kio,
which in turn means that only raw I/O uses it (direct i/o may not work
right now). The intent however is to enable clustering of pages etc to
become possible. The pagebuf abstraction layer from SGI also uses multi-page
bios, but that is currently not included in the stock development kernels.
The same is true of Andrew Morton's work-in-progress multipage bio writeout 
and readahead patches.

2.3 Changes in the Request Structure

The request structure is the structure that gets passed down to low level
drivers. The block layer make_request function builds up a request structure,
places it on the queue and invokes the drivers request_fn. The driver makes
use of block layer helper routine elv_next_request to pull the next request
off the queue. Control or diagnostic functions might bypass block and directly
invoke underlying driver entry points passing in a specially constructed
request structure.

Only some relevant fields (mainly those which changed or may be referred
to in some of the discussion here) are listed below, not necessarily in
the order in which they occur in the structure (see include/linux/blkdev.h)
Refer to Documentation/block/request.txt for details about all the request
structure fields and a quick reference about the layers which are
supposed to use or modify those fields.

struct request {
	struct list_head queuelist;  /* Not meant to be directly accessed by
					the driver.
					Used by q->elv_next_request_fn
					rq->queue is gone
					*/
	.
	.
	unsigned char cmd[16]; /* prebuilt command data block */
	unsigned long flags;   /* also includes earlier rq->cmd settings */
	.
	.
	sector_t sector; /* this field is now of type sector_t instead of int
			    preparation for 64 bit sectors */
	.
	.

	/* Number of scatter-gather DMA addr+len pairs after
	 * physical address coalescing is performed.
	 */
	unsigned short nr_phys_segments;

	/* Number of scatter-gather addr+len pairs after
	 * physical and DMA remapping hardware coalescing is performed.
	 * This is the number of scatter-gather entries the driver
	 * will actually have to deal with after DMA mapping is done.
	 */
	unsigned short nr_hw_segments;

	/* Various sector counts */
	unsigned long nr_sectors;  /* no. of sectors left: driver modifiable */
	unsigned long hard_nr_sectors;  /* block internal copy of above */
	unsigned int current_nr_sectors; /* no. of sectors left in the
					   current segment:driver modifiable */
	unsigned long hard_cur_sectors; /* block internal copy of the above */
	.
	.
	int tag;	/* command tag associated with request */
	void *special;  /* same as before */
	char *buffer;   /* valid only for low memory buffers upto
			 current_nr_sectors */
	.
	.
	struct bio *bio, *biotail;  /* bio list instead of bh */
	struct request_list *rl;
}
	
See the rq_flag_bits definitions for an explanation of the various flags
available. Some bits are used by the block layer or i/o scheduler.
	
The behaviour of the various sector counts are almost the same as before,
except that since we have multi-segment bios, current_nr_sectors refers
to the numbers of sectors in the current segment being processed which could
be one of the many segments in the current bio (i.e i/o completion unit).
The nr_sectors value refers to the total number of sectors in the whole
request that remain to be transferred (no change). The purpose of the
hard_xxx values is for block to remember these counts every time it hands
over the request to the driver. These values are updated by block on
end_that_request_first, i.e. every time the driver completes a part of the
transfer and invokes block end*request helpers to mark this. The
driver should not modify these values. The block layer sets up the
nr_sectors and current_nr_sectors fields (based on the corresponding
hard_xxx values and the number of bytes transferred) and updates it on
every transfer that invokes end_that_request_first. It does the same for the
buffer, bio, bio->bi_idx fields too.

The buffer field is just a virtual address mapping of the current segment
of the i/o buffer in cases where the buffer resides in low-memory. For high
memory i/o, this field is not valid and must not be used by drivers.

Code that sets up its own request structures and passes them down to
a driver needs to be careful about interoperation with the block layer helper
functions which the driver uses. (Section 1.3)

3. Using bios

3.1 Setup/Teardown

There are routines for managing the allocation, and reference counting, and
freeing of bios (bio_alloc, bio_get, bio_put).