Documentation/admin-guide/device-mapper/dm-io.rst

   1 =====
   2 dm-io
   3 =====
   4
   5 Dm-io provides synchronous and asynchronous I/O services. There are three
   6 types of I/O services available, and each type has a sync and an async
   7 version.
   8
   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-device along with the starting
  11 sector 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
  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 of io_region structures.
  21
  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 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
  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 caller has a pre-assembled bio,
  39 but 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
  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 handy if the caller needs to do
  50 I/O to a large region but doesn't want to allocate a large number of individual
  51 memory 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
  58 Callers of the asynchronous I/O services must include the name of a completion
  59 callback 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
  63 The "error" parameter in this callback, as well as the `*error` parameter in
  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 regions, this bitset allows dm-io to
  66 indicate success or failure on each individual region.
  67
  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 perform I/O on concurrently.
  70 Dm-io will attempt to resize its mempool to make sure enough pages are
  71 always available in order to avoid unnecessary waiting while performing I/O.
  72
  73 When the user is finished using the dm-io services, they should call
  74 dm_io_put() and specify the same number of pages that were given on the
  75 dm_io_get() call.