dm-io.rst 3.2 KB

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