Documentation/admin-guide/device-mapper/kcopyd.rst

   1 ======
   2 kcopyd
   3 ======
   4
   5 Kcopyd provides the ability to copy a range of sectors from one block-device
   6 to one or more other block-devices, with an asynchronous completion
   7 notification. It is used by dm-snapshot and dm-mirror.
   8
   9 Users of kcopyd must first create a client and indicate how many memory pages
  10 to set aside for their copy jobs. This is done with a call to
  11 kcopyd_client_create()::
  12
  13    int kcopyd_client_create(unsigned int num_pages,
  14                             struct kcopyd_client **result);
  15
  16 To start a copy job, the user must set up io_region structures to describe
  17 the source and destinations of the copy. Each io_region indicates a
  18 block-device along with the starting sector and size of the region. The source
  19 of the copy is given as one io_region structure, and the destinations of the
  20 copy are given as an array of io_region structures::
  21
  22    struct io_region {
  23       struct block_device *bdev;
  24       sector_t sector;
  25       sector_t count;
  26    };
  27
  28 To start the copy, the user calls kcopyd_copy(), passing in the client
  29 pointer, pointers to the source and destination io_regions, the name of a
  30 completion callback routine, and a pointer to some context data for the copy::
  31
  32    int kcopyd_copy(struct kcopyd_client *kc, struct io_region *from,
  33                    unsigned int num_dests, struct io_region *dests,
  34                    unsigned int flags, kcopyd_notify_fn fn, void *context);
  35
  36    typedef void (*kcopyd_notify_fn)(int read_err, unsigned int write_err,
  37                                     void *context);
  38
  39 When the copy completes, kcopyd will call the user's completion routine,
  40 passing back the user's context pointer. It will also indicate if a read or
  41 write error occurred during the copy.
  42
  43 When a user is done with all their copy jobs, they should call
  44 kcopyd_client_destroy() to delete the kcopyd client, which will release the
  45 associated memory pages::
  46
  47    void kcopyd_client_destroy(struct kcopyd_client *kc);