era.rst

  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