diff options
author | Joe Thornber <ejt@redhat.com> | 2014-03-03 10:23:15 -0500 |
---|---|---|
committer | Mike Snitzer <snitzer@redhat.com> | 2014-03-27 16:56:23 -0400 |
commit | eec40579d84873dfb7021eb24c50360f073237c5 (patch) | |
tree | a294d43a2029ab02ceeab33396e7c948e374a571 /Documentation/device-mapper | |
parent | b098d6726bbfb94c06d6e1097466187afddae61f (diff) |
dm: add era target
dm-era is a target that behaves similar to the linear target. In
addition it keeps track of which blocks were written within a user
defined period of time called an 'era'. Each era target instance
maintains the current era as a monotonically increasing 32-bit
counter.
Use cases include tracking changed blocks for backup software, and
partially invalidating the contents of a cache to restore cache
coherency after rolling back a vendor snapshot.
dm-era is primarily expected to be paired with the dm-cache target.
Signed-off-by: Joe Thornber <ejt@redhat.com>
Signed-off-by: Mike Snitzer <snitzer@redhat.com>
Diffstat (limited to 'Documentation/device-mapper')
-rw-r--r-- | Documentation/device-mapper/era.txt | 108 |
1 files changed, 108 insertions, 0 deletions
diff --git a/Documentation/device-mapper/era.txt b/Documentation/device-mapper/era.txt new file mode 100644 index 000000000000..3c6d01be3560 --- /dev/null +++ b/Documentation/device-mapper/era.txt | |||
@@ -0,0 +1,108 @@ | |||
1 | Introduction | ||
2 | ============ | ||
3 | |||
4 | dm-era is a target that behaves similar to the linear target. In | ||
5 | addition it keeps track of which blocks were written within a user | ||
6 | defined period of time called an 'era'. Each era target instance | ||
7 | maintains the current era as a monotonically increasing 32-bit | ||
8 | counter. | ||
9 | |||
10 | Use cases include tracking changed blocks for backup software, and | ||
11 | partially invalidating the contents of a cache to restore cache | ||
12 | coherency after rolling back a vendor snapshot. | ||
13 | |||
14 | Constructor | ||
15 | =========== | ||
16 | |||
17 | era <metadata dev> <origin dev> <block size> | ||
18 | |||
19 | metadata dev : fast device holding the persistent metadata | ||
20 | origin dev : device holding data blocks that may change | ||
21 | block size : block size of origin data device, granularity that is | ||
22 | tracked by the target | ||
23 | |||
24 | Messages | ||
25 | ======== | ||
26 | |||
27 | None of the dm messages take any arguments. | ||
28 | |||
29 | checkpoint | ||
30 | ---------- | ||
31 | |||
32 | Possibly move to a new era. You shouldn't assume the era has | ||
33 | incremented. After sending this message, you should check the | ||
34 | current era via the status line. | ||
35 | |||
36 | take_metadata_snap | ||
37 | ------------------ | ||
38 | |||
39 | Create a clone of the metadata, to allow a userland process to read it. | ||
40 | |||
41 | drop_metadata_snap | ||
42 | ------------------ | ||
43 | |||
44 | Drop the metadata snapshot. | ||
45 | |||
46 | Status | ||
47 | ====== | ||
48 | |||
49 | <metadata block size> <#used metadata blocks>/<#total metadata blocks> | ||
50 | <current era> <held metadata root | '-'> | ||
51 | |||
52 | metadata block size : Fixed block size for each metadata block in | ||
53 | sectors | ||
54 | #used metadata blocks : Number of metadata blocks used | ||
55 | #total metadata blocks : Total number of metadata blocks | ||
56 | current era : The current era | ||
57 | held metadata root : The location, in blocks, of the metadata root | ||
58 | that has been 'held' for userspace read | ||
59 | access. '-' indicates there is no held root | ||
60 | |||
61 | Detailed use case | ||
62 | ================= | ||
63 | |||
64 | The scenario of invalidating a cache when rolling back a vendor | ||
65 | snapshot was the primary use case when developing this target: | ||
66 | |||
67 | Taking a vendor snapshot | ||
68 | ------------------------ | ||
69 | |||
70 | - Send a checkpoint message to the era target | ||
71 | - Make a note of the current era in its status line | ||
72 | - Take vendor snapshot (the era and snapshot should be forever | ||
73 | associated now). | ||
74 | |||
75 | Rolling back to an vendor snapshot | ||
76 | ---------------------------------- | ||
77 | |||
78 | - Cache enters passthrough mode (see: dm-cache's docs in cache.txt) | ||
79 | - Rollback vendor storage | ||
80 | - Take metadata snapshot | ||
81 | - Ascertain which blocks have been written since the snapshot was taken | ||
82 | by checking each block's era | ||
83 | - Invalidate those blocks in the caching software | ||
84 | - Cache returns to writeback/writethrough mode | ||
85 | |||
86 | Memory usage | ||
87 | ============ | ||
88 | |||
89 | The target uses a bitset to record writes in the current era. It also | ||
90 | has a spare bitset ready for switching over to a new era. Other than | ||
91 | that it uses a few 4k blocks for updating metadata. | ||
92 | |||
93 | (4 * nr_blocks) bytes + buffers | ||
94 | |||
95 | Resilience | ||
96 | ========== | ||
97 | |||
98 | Metadata is updated on disk before a write to a previously unwritten | ||
99 | block is performed. As such dm-era should not be effected by a hard | ||
100 | crash such as power failure. | ||
101 | |||
102 | Userland tools | ||
103 | ============== | ||
104 | |||
105 | Userland tools are found in the increasingly poorly named | ||
106 | thin-provisioning-tools project: | ||
107 | |||
108 | https://github.com/jthornber/thin-provisioning-tools | ||