0001 =====
0002 dm-io
0003 =====
0004
0005 Dm-io provides synchronous and asynchronous I/O services. There are three
0006 types of I/O services available, and each type has a sync and an async
0007 version.
0008
0009 The user must set up an io_region structure to describe the desired location
0010 of the I/O. Each io_region indicates a block-device along with the starting
0011 sector and size of the region::
0012
0013 struct io_region {
0014 struct block_device *bdev;
0015 sector_t sector;
0016 sector_t count;
0017 };
0018
0019 Dm-io can read from one io_region or write to one or more io_regions. Writes
0020 to multiple regions are specified by an array of io_region structures.
0021
0022 The first I/O service type takes a list of memory pages as the data buffer for
0023 the I/O, along with an offset into the first page::
0024
0025 struct page_list {
0026 struct page_list *next;
0027 struct page *page;
0028 };
0029
0030 int dm_io_sync(unsigned int num_regions, struct io_region *where, int rw,
0031 struct page_list *pl, unsigned int offset,
0032 unsigned long *error_bits);
0033 int dm_io_async(unsigned int num_regions, struct io_region *where, int rw,
0034 struct page_list *pl, unsigned int offset,
0035 io_notify_fn fn, void *context);
0036
0037 The second I/O service type takes an array of bio vectors as the data buffer
0038 for the I/O. This service can be handy if the caller has a pre-assembled bio,
0039 but wants to direct different portions of the bio to different devices::
0040
0041 int dm_io_sync_bvec(unsigned int num_regions, struct io_region *where,
0042 int rw, struct bio_vec *bvec,
0043 unsigned long *error_bits);
0044 int dm_io_async_bvec(unsigned int num_regions, struct io_region *where,
0045 int rw, struct bio_vec *bvec,
0046 io_notify_fn fn, void *context);
0047
0048 The third I/O service type takes a pointer to a vmalloc'd memory buffer as the
0049 data buffer for the I/O. This service can be handy if the caller needs to do
0050 I/O to a large region but doesn't want to allocate a large number of individual
0051 memory pages::
0052
0053 int dm_io_sync_vm(unsigned int num_regions, struct io_region *where, int rw,
0054 void *data, unsigned long *error_bits);
0055 int dm_io_async_vm(unsigned int num_regions, struct io_region *where, int rw,
0056 void *data, io_notify_fn fn, void *context);
0057
0058 Callers of the asynchronous I/O services must include the name of a completion
0059 callback routine and a pointer to some context data for the I/O::
0060
0061 typedef void (*io_notify_fn)(unsigned long error, void *context);
0062
0063 The "error" parameter in this callback, as well as the `*error` parameter in
0064 all of the synchronous versions, is a bitset (instead of a simple error value).
0065 In the case of an write-I/O to multiple regions, this bitset allows dm-io to
0066 indicate success or failure on each individual region.
0067
0068 Before using any of the dm-io services, the user should call dm_io_get()
0069 and specify the number of pages they expect to perform I/O on concurrently.
0070 Dm-io will attempt to resize its mempool to make sure enough pages are
0071 always available in order to avoid unnecessary waiting while performing I/O.
0072
0073 When the user is finished using the dm-io services, they should call
0074 dm_io_put() and specify the same number of pages that were given on the
0075 dm_io_get() call.
