aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/device-mapper
diff options
context:
space:
mode:
authorJoe Thornber <ejt@redhat.com>2014-03-03 10:23:15 -0500
committerMike Snitzer <snitzer@redhat.com>2014-03-27 16:56:23 -0400
commiteec40579d84873dfb7021eb24c50360f073237c5 (patch)
treea294d43a2029ab02ceeab33396e7c948e374a571 /Documentation/device-mapper
parentb098d6726bbfb94c06d6e1097466187afddae61f (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.txt108
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 @@
1Introduction
2============
3
4dm-era is a target that behaves similar to the linear target. In
5addition it keeps track of which blocks were written within a user
6defined period of time called an 'era'. Each era target instance
7maintains the current era as a monotonically increasing 32-bit
8counter.
9
10Use cases include tracking changed blocks for backup software, and
11partially invalidating the contents of a cache to restore cache
12coherency after rolling back a vendor snapshot.
13
14Constructor
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
24Messages
25========
26
27None of the dm messages take any arguments.
28
29checkpoint
30----------
31
32Possibly move to a new era. You shouldn't assume the era has
33incremented. After sending this message, you should check the
34current era via the status line.
35
36take_metadata_snap
37------------------
38
39Create a clone of the metadata, to allow a userland process to read it.
40
41drop_metadata_snap
42------------------
43
44Drop the metadata snapshot.
45
46Status
47======
48
49<metadata block size> <#used metadata blocks>/<#total metadata blocks>
50<current era> <held metadata root | '-'>
51
52metadata 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
56current era : The current era
57held 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
61Detailed use case
62=================
63
64The scenario of invalidating a cache when rolling back a vendor
65snapshot was the primary use case when developing this target:
66
67Taking 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
75Rolling 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
86Memory usage
87============
88
89The target uses a bitset to record writes in the current era. It also
90has a spare bitset ready for switching over to a new era. Other than
91that it uses a few 4k blocks for updating metadata.
92
93 (4 * nr_blocks) bytes + buffers
94
95Resilience
96==========
97
98Metadata is updated on disk before a write to a previously unwritten
99block is performed. As such dm-era should not be effected by a hard
100crash such as power failure.
101
102Userland tools
103==============
104
105Userland tools are found in the increasingly poorly named
106thin-provisioning-tools project:
107
108 https://github.com/jthornber/thin-provisioning-tools