0001 ======
0002 kcopyd
0003 ======
0004
0005 Kcopyd provides the ability to copy a range of sectors from one block-device
0006 to one or more other block-devices, with an asynchronous completion
0007 notification. It is used by dm-snapshot and dm-mirror.
0008
0009 Users of kcopyd must first create a client and indicate how many memory pages
0010 to set aside for their copy jobs. This is done with a call to
0011 kcopyd_client_create()::
0012
0013 int kcopyd_client_create(unsigned int num_pages,
0014 struct kcopyd_client **result);
0015
0016 To start a copy job, the user must set up io_region structures to describe
0017 the source and destinations of the copy. Each io_region indicates a
0018 block-device along with the starting sector and size of the region. The source
0019 of the copy is given as one io_region structure, and the destinations of the
0020 copy are given as an array of io_region structures::
0021
0022 struct io_region {
0023 struct block_device *bdev;
0024 sector_t sector;
0025 sector_t count;
0026 };
0027
0028 To start the copy, the user calls kcopyd_copy(), passing in the client
0029 pointer, pointers to the source and destination io_regions, the name of a
0030 completion callback routine, and a pointer to some context data for the copy::
0031
0032 int kcopyd_copy(struct kcopyd_client *kc, struct io_region *from,
0033 unsigned int num_dests, struct io_region *dests,
0034 unsigned int flags, kcopyd_notify_fn fn, void *context);
0035
0036 typedef void (*kcopyd_notify_fn)(int read_err, unsigned int write_err,
0037 void *context);
0038
0039 When the copy completes, kcopyd will call the user's completion routine,
0040 passing back the user's context pointer. It will also indicate if a read or
0041 write error occurred during the copy.
0042
0043 When a user is done with all their copy jobs, they should call
0044 kcopyd_client_destroy() to delete the kcopyd client, which will release the
0045 associated memory pages::
0046
0047 void kcopyd_client_destroy(struct kcopyd_client *kc);
