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