Merge tag 'tegra-for-5.2-arm64-dt-fixes' of git://git.kernel.org/pub/scm/linux/kernel...
[sfrench/cifs-2.6.git] / Documentation / device-mapper / era.txt
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