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