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