Documentation/device-mapper/era.txt

   1 Introduction
   2 ============
   3
   4 dm-era is a target that behaves similar to the linear target.  In
   5 addition it keeps track of which blocks were written within a user
   6 defined period of time called an 'era'.  Each era target instance
   7 maintains the current era as a monotonically increasing 32-bit
   8 counter.
   9
  10 Use cases include tracking changed blocks for backup software, and
  11 partially invalidating the contents of a cache to restore cache
  12 coherency after rolling back a vendor snapshot.
  13
  14 Constructor
  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
  24 Messages
  25 ========
  26
  27 None of the dm messages take any arguments.
  28
  29 checkpoint
  30 ----------
  31
  32 Possibly move to a new era.  You shouldn't assume the era has
  33 incremented.  After sending this message, you should check the
  34 current era via the status line.
  35
  36 take_metadata_snap
  37 ------------------
  38
  39 Create a clone of the metadata, to allow a userland process to read it.
  40
  41 drop_metadata_snap
  42 ------------------
  43
  44 Drop the metadata snapshot.
  45
  46 Status
  47 ======
  48
  49 <metadata block size> <#used metadata blocks>/<#total metadata blocks>
  50 <current era> <held metadata root | '-'>
  51
  52 metadata 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
  56 current era              : The current era
  57 held 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
  61 Detailed use case
  62 =================
  63
  64 The scenario of invalidating a cache when rolling back a vendor
  65 snapshot was the primary use case when developing this target:
  66
  67 Taking 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
  75 Rolling 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
  86 Memory usage
  87 ============
  88
  89 The target uses a bitset to record writes in the current era.  It also
  90 has a spare bitset ready for switching over to a new era.  Other than
  91 that it uses a few 4k blocks for updating metadata.
  92
  93    (4 * nr_blocks) bytes + buffers
  94
  95 Resilience
  96 ==========
  97
  98 Metadata is updated on disk before a write to a previously unwritten
  99 block is performed.  As such dm-era should not be effected by a hard
 100 crash such as power failure.
 101
 102 Userland tools
 103 ==============
 104
 105 Userland tools are found in the increasingly poorly named
 106 thin-provisioning-tools project:
 107
 108     https://github.com/jthornber/thin-provisioning-tools