Commit | Line | Data |
---|---|---|
f0ba4377 | 1 | ====== |
1da177e4 LT |
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 | |
f0ba4377 | 11 | kcopyd_client_create():: |
1da177e4 LT |
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 | |
f0ba4377 | 20 | copy are given as an array of io_region structures:: |
1da177e4 LT |
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 | |
f0ba4377 | 30 | completion callback routine, and a pointer to some context data for the copy:: |
1da177e4 LT |
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 | |
f0ba4377 | 45 | associated memory pages:: |
1da177e4 LT |
46 | |
47 | void kcopyd_client_destroy(struct kcopyd_client *kc); |