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