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