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