diff options
Diffstat (limited to 'Documentation/device-mapper/kcopyd.txt')
-rw-r--r-- | Documentation/device-mapper/kcopyd.txt | 47 |
1 files changed, 47 insertions, 0 deletions
diff --git a/Documentation/device-mapper/kcopyd.txt b/Documentation/device-mapper/kcopyd.txt new file mode 100644 index 000000000000..820382c4cecf --- /dev/null +++ b/Documentation/device-mapper/kcopyd.txt | |||
@@ -0,0 +1,47 @@ | |||
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 | |||