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 109