Commit | Line | Data |
---|---|---|
eec40579 JT |
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 |