1 ====== 2 dm-era 3 ====== 4 5 Introduction 6 ============ 7 8 dm-era is a target that behaves similar to the linear target. In 9 addition it keeps track of which blocks were written within a user 10 defined period of time called an 'era'. Each era target instance 11 maintains the current era as a monotonically increasing 32-bit 12 counter. 13 14 Use cases include tracking changed blocks for backup software, and 15 partially invalidating the contents of a cache to restore cache 16 coherency after rolling back a vendor snapshot. 17 18 Constructor 19 =========== 20 21 era <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 30 Messages 31 ======== 32 33 None of the dm messages take any arguments. 34 35 checkpoint 36 ---------- 37 38 Possibly move to a new era. You shouldn't assume the era has 39 incremented. After sending this message, you should check the 40 current era via the status line. 41 42 take_metadata_snap 43 ------------------ 44 45 Create a clone of the metadata, to allow a userland process to read it. 46 47 drop_metadata_snap 48 ------------------ 49 50 Drop the metadata snapshot. 51 52 Status 53 ====== 54 55 <metadata block size> <#used metadata blocks>/<#total metadata blocks> 56 <current era> <held metadata root | '-'> 57 58 ========================= ============================================== 59 metadata 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 63 current era The current era 64 held 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 69 Detailed use case 70 ================= 71 72 The scenario of invalidating a cache when rolling back a vendor 73 snapshot was the primary use case when developing this target: 74 75 Taking 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 83 Rolling 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 94 Memory usage 95 ============ 96 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 a new era. Other than 99 that it uses a few 4k blocks for updating metadata:: 100 101 (4 * nr_blocks) bytes + buffers 102 103 Resilience 104 ========== 105 106 Metadata is updated on disk before a write to a previously unwritten 107 block is performed. As such dm-era should not be effected by a hard 108 crash such as power failure. 109 110 Userland tools 111 ============== 112 113 Userland tools are found in the increasingly poorly named 114 thin-provisioning-tools project: 115 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.