1*4882a593Smuzhiyun====== 2*4882a593Smuzhiyundm-era 3*4882a593Smuzhiyun====== 4*4882a593Smuzhiyun 5*4882a593SmuzhiyunIntroduction 6*4882a593Smuzhiyun============ 7*4882a593Smuzhiyun 8*4882a593Smuzhiyundm-era is a target that behaves similar to the linear target. In 9*4882a593Smuzhiyunaddition it keeps track of which blocks were written within a user 10*4882a593Smuzhiyundefined period of time called an 'era'. Each era target instance 11*4882a593Smuzhiyunmaintains the current era as a monotonically increasing 32-bit 12*4882a593Smuzhiyuncounter. 13*4882a593Smuzhiyun 14*4882a593SmuzhiyunUse cases include tracking changed blocks for backup software, and 15*4882a593Smuzhiyunpartially invalidating the contents of a cache to restore cache 16*4882a593Smuzhiyuncoherency after rolling back a vendor snapshot. 17*4882a593Smuzhiyun 18*4882a593SmuzhiyunConstructor 19*4882a593Smuzhiyun=========== 20*4882a593Smuzhiyun 21*4882a593Smuzhiyunera <metadata dev> <origin dev> <block size> 22*4882a593Smuzhiyun 23*4882a593Smuzhiyun ================ ====================================================== 24*4882a593Smuzhiyun metadata dev fast device holding the persistent metadata 25*4882a593Smuzhiyun origin dev device holding data blocks that may change 26*4882a593Smuzhiyun block size block size of origin data device, granularity that is 27*4882a593Smuzhiyun tracked by the target 28*4882a593Smuzhiyun ================ ====================================================== 29*4882a593Smuzhiyun 30*4882a593SmuzhiyunMessages 31*4882a593Smuzhiyun======== 32*4882a593Smuzhiyun 33*4882a593SmuzhiyunNone of the dm messages take any arguments. 34*4882a593Smuzhiyun 35*4882a593Smuzhiyuncheckpoint 36*4882a593Smuzhiyun---------- 37*4882a593Smuzhiyun 38*4882a593SmuzhiyunPossibly move to a new era. You shouldn't assume the era has 39*4882a593Smuzhiyunincremented. After sending this message, you should check the 40*4882a593Smuzhiyuncurrent era via the status line. 41*4882a593Smuzhiyun 42*4882a593Smuzhiyuntake_metadata_snap 43*4882a593Smuzhiyun------------------ 44*4882a593Smuzhiyun 45*4882a593SmuzhiyunCreate a clone of the metadata, to allow a userland process to read it. 46*4882a593Smuzhiyun 47*4882a593Smuzhiyundrop_metadata_snap 48*4882a593Smuzhiyun------------------ 49*4882a593Smuzhiyun 50*4882a593SmuzhiyunDrop the metadata snapshot. 51*4882a593Smuzhiyun 52*4882a593SmuzhiyunStatus 53*4882a593Smuzhiyun====== 54*4882a593Smuzhiyun 55*4882a593Smuzhiyun<metadata block size> <#used metadata blocks>/<#total metadata blocks> 56*4882a593Smuzhiyun<current era> <held metadata root | '-'> 57*4882a593Smuzhiyun 58*4882a593Smuzhiyun========================= ============================================== 59*4882a593Smuzhiyunmetadata block size Fixed block size for each metadata block in 60*4882a593Smuzhiyun sectors 61*4882a593Smuzhiyun#used metadata blocks Number of metadata blocks used 62*4882a593Smuzhiyun#total metadata blocks Total number of metadata blocks 63*4882a593Smuzhiyuncurrent era The current era 64*4882a593Smuzhiyunheld metadata root The location, in blocks, of the metadata root 65*4882a593Smuzhiyun that has been 'held' for userspace read 66*4882a593Smuzhiyun access. '-' indicates there is no held root 67*4882a593Smuzhiyun========================= ============================================== 68*4882a593Smuzhiyun 69*4882a593SmuzhiyunDetailed use case 70*4882a593Smuzhiyun================= 71*4882a593Smuzhiyun 72*4882a593SmuzhiyunThe scenario of invalidating a cache when rolling back a vendor 73*4882a593Smuzhiyunsnapshot was the primary use case when developing this target: 74*4882a593Smuzhiyun 75*4882a593SmuzhiyunTaking a vendor snapshot 76*4882a593Smuzhiyun------------------------ 77*4882a593Smuzhiyun 78*4882a593Smuzhiyun- Send a checkpoint message to the era target 79*4882a593Smuzhiyun- Make a note of the current era in its status line 80*4882a593Smuzhiyun- Take vendor snapshot (the era and snapshot should be forever 81*4882a593Smuzhiyun associated now). 82*4882a593Smuzhiyun 83*4882a593SmuzhiyunRolling back to an vendor snapshot 84*4882a593Smuzhiyun---------------------------------- 85*4882a593Smuzhiyun 86*4882a593Smuzhiyun- Cache enters passthrough mode (see: dm-cache's docs in cache.txt) 87*4882a593Smuzhiyun- Rollback vendor storage 88*4882a593Smuzhiyun- Take metadata snapshot 89*4882a593Smuzhiyun- Ascertain which blocks have been written since the snapshot was taken 90*4882a593Smuzhiyun by checking each block's era 91*4882a593Smuzhiyun- Invalidate those blocks in the caching software 92*4882a593Smuzhiyun- Cache returns to writeback/writethrough mode 93*4882a593Smuzhiyun 94*4882a593SmuzhiyunMemory usage 95*4882a593Smuzhiyun============ 96*4882a593Smuzhiyun 97*4882a593SmuzhiyunThe target uses a bitset to record writes in the current era. It also 98*4882a593Smuzhiyunhas a spare bitset ready for switching over to a new era. Other than 99*4882a593Smuzhiyunthat it uses a few 4k blocks for updating metadata:: 100*4882a593Smuzhiyun 101*4882a593Smuzhiyun (4 * nr_blocks) bytes + buffers 102*4882a593Smuzhiyun 103*4882a593SmuzhiyunResilience 104*4882a593Smuzhiyun========== 105*4882a593Smuzhiyun 106*4882a593SmuzhiyunMetadata is updated on disk before a write to a previously unwritten 107*4882a593Smuzhiyunblock is performed. As such dm-era should not be effected by a hard 108*4882a593Smuzhiyuncrash such as power failure. 109*4882a593Smuzhiyun 110*4882a593SmuzhiyunUserland tools 111*4882a593Smuzhiyun============== 112*4882a593Smuzhiyun 113*4882a593SmuzhiyunUserland tools are found in the increasingly poorly named 114*4882a593Smuzhiyunthin-provisioning-tools project: 115*4882a593Smuzhiyun 116*4882a593Smuzhiyun https://github.com/jthornber/thin-provisioning-tools 117