dm-io.txt 3.2 KB

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