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