1===== 2dm-io 3===== 4 5Dm-io provides synchronous and asynchronous I/O services. There are three 6types of I/O services available, and each type has a sync and an async 7version. 8 9The user must set up an io_region structure to describe the desired location 10of the I/O. Each io_region indicates a block-device along with the starting 11sector and size of the region:: 12 13 struct io_region { 14 struct block_device *bdev; 15 sector_t sector; 16 sector_t count; 17 }; 18 19Dm-io can read from one io_region or write to one or more io_regions. Writes 20to multiple regions are specified by an array of io_region structures. 21 22The first I/O service type takes a list of memory pages as the data buffer for 23the I/O, along with an offset into the first page:: 24 25 struct page_list { 26 struct page_list *next; 27 struct page *page; 28 }; 29 30 int dm_io_sync(unsigned int num_regions, struct io_region *where, int rw, 31 struct page_list *pl, unsigned int offset, 32 unsigned long *error_bits); 33 int dm_io_async(unsigned int num_regions, struct io_region *where, int rw, 34 struct page_list *pl, unsigned int offset, 35 io_notify_fn fn, void *context); 36 37The second I/O service type takes an array of bio vectors as the data buffer 38for the I/O. This service can be handy if the caller has a pre-assembled bio, 39but wants to direct different portions of the bio to different devices:: 40 41 int dm_io_sync_bvec(unsigned int num_regions, struct io_region *where, 42 int rw, struct bio_vec *bvec, 43 unsigned long *error_bits); 44 int dm_io_async_bvec(unsigned int num_regions, struct io_region *where, 45 int rw, struct bio_vec *bvec, 46 io_notify_fn fn, void *context); 47 48The third I/O service type takes a pointer to a vmalloc'd memory buffer as the 49data buffer for the I/O. This service can be handy if the caller needs to do 50I/O to a large region but doesn't want to allocate a large number of individual 51memory pages:: 52 53 int dm_io_sync_vm(unsigned int num_regions, struct io_region *where, int rw, 54 void *data, unsigned long *error_bits); 55 int dm_io_async_vm(unsigned int num_regions, struct io_region *where, int rw, 56 void *data, io_notify_fn fn, void *context); 57 58Callers of the asynchronous I/O services must include the name of a completion 59callback routine and a pointer to some context data for the I/O:: 60 61 typedef void (*io_notify_fn)(unsigned long error, void *context); 62 63The "error" parameter in this callback, as well as the `*error` parameter in 64all of the synchronous versions, is a bitset (instead of a simple error value). 65In the case of an write-I/O to multiple regions, this bitset allows dm-io to 66indicate success or failure on each individual region. 67 68Before using any of the dm-io services, the user should call dm_io_get() 69and specify the number of pages they expect to perform I/O on concurrently. 70Dm-io will attempt to resize its mempool to make sure enough pages are 71always available in order to avoid unnecessary waiting while performing I/O. 72 73When the user is finished using the dm-io services, they should call 74dm_io_put() and specify the same number of pages that were given on the 75dm_io_get() call. 76