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