117 lines · plain
1======2dm-era3======4 5Introduction6============7 8dm-era is a target that behaves similar to the linear target. In9addition it keeps track of which blocks were written within a user10defined period of time called an 'era'. Each era target instance11maintains the current era as a monotonically increasing 32-bit12counter.13 14Use cases include tracking changed blocks for backup software, and15partially invalidating the contents of a cache to restore cache16coherency after rolling back a vendor snapshot.17 18Constructor19===========20 21era <metadata dev> <origin dev> <block size>22 23 ================ ======================================================24 metadata dev fast device holding the persistent metadata25 origin dev device holding data blocks that may change26 block size block size of origin data device, granularity that is27 tracked by the target28 ================ ======================================================29 30Messages31========32 33None of the dm messages take any arguments.34 35checkpoint36----------37 38Possibly move to a new era. You shouldn't assume the era has39incremented. After sending this message, you should check the40current era via the status line.41 42take_metadata_snap43------------------44 45Create a clone of the metadata, to allow a userland process to read it.46 47drop_metadata_snap48------------------49 50Drop the metadata snapshot.51 52Status53======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 in60 sectors61#used metadata blocks Number of metadata blocks used62#total metadata blocks Total number of metadata blocks63current era The current era64held metadata root The location, in blocks, of the metadata root65 that has been 'held' for userspace read66 access. '-' indicates there is no held root67========================= ==============================================68 69Detailed use case70=================71 72The scenario of invalidating a cache when rolling back a vendor73snapshot was the primary use case when developing this target:74 75Taking a vendor snapshot76------------------------77 78- Send a checkpoint message to the era target79- Make a note of the current era in its status line80- Take vendor snapshot (the era and snapshot should be forever81 associated now).82 83Rolling back to an vendor snapshot84----------------------------------85 86- Cache enters passthrough mode (see: dm-cache's docs in cache.txt)87- Rollback vendor storage88- Take metadata snapshot89- Ascertain which blocks have been written since the snapshot was taken90 by checking each block's era91- Invalidate those blocks in the caching software92- Cache returns to writeback/writethrough mode93 94Memory usage95============96 97The target uses a bitset to record writes in the current era. It also98has a spare bitset ready for switching over to a new era. Other than99that it uses a few 4k blocks for updating metadata::100 101 (4 * nr_blocks) bytes + buffers102 103Resilience104==========105 106Metadata is updated on disk before a write to a previously unwritten107block is performed. As such dm-era should not be effected by a hard108crash such as power failure.109 110Userland tools111==============112 113Userland tools are found in the increasingly poorly named114thin-provisioning-tools project:115 116 https://github.com/jthornber/thin-provisioning-tools117