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