0001 ======
0002 dm-era
0003 ======
0004
0005 Introduction
0006 ============
0007
0008 dm-era is a target that behaves similar to the linear target. In
0009 addition it keeps track of which blocks were written within a user
0010 defined period of time called an 'era'. Each era target instance
0011 maintains the current era as a monotonically increasing 32-bit
0012 counter.
0013
0014 Use cases include tracking changed blocks for backup software, and
0015 partially invalidating the contents of a cache to restore cache
0016 coherency after rolling back a vendor snapshot.
0017
0018 Constructor
0019 ===========
0020
0021 era <metadata dev> <origin dev> <block size>
0022
0023 ================ ======================================================
0024 metadata dev fast device holding the persistent metadata
0025 origin dev device holding data blocks that may change
0026 block size block size of origin data device, granularity that is
0027 tracked by the target
0028 ================ ======================================================
0029
0030 Messages
0031 ========
0032
0033 None of the dm messages take any arguments.
0034
0035 checkpoint
0036 ----------
0037
0038 Possibly move to a new era. You shouldn't assume the era has
0039 incremented. After sending this message, you should check the
0040 current era via the status line.
0041
0042 take_metadata_snap
0043 ------------------
0044
0045 Create a clone of the metadata, to allow a userland process to read it.
0046
0047 drop_metadata_snap
0048 ------------------
0049
0050 Drop the metadata snapshot.
0051
0052 Status
0053 ======
0054
0055 <metadata block size> <#used metadata blocks>/<#total metadata blocks>
0056 <current era> <held metadata root | '-'>
0057
0058 ========================= ==============================================
0059 metadata block size Fixed block size for each metadata block in
0060 sectors
0061 #used metadata blocks Number of metadata blocks used
0062 #total metadata blocks Total number of metadata blocks
0063 current era The current era
0064 held metadata root The location, in blocks, of the metadata root
0065 that has been 'held' for userspace read
0066 access. '-' indicates there is no held root
0067 ========================= ==============================================
0068
0069 Detailed use case
0070 =================
0071
0072 The scenario of invalidating a cache when rolling back a vendor
0073 snapshot was the primary use case when developing this target:
0074
0075 Taking a vendor snapshot
0076 ------------------------
0077
0078 - Send a checkpoint message to the era target
0079 - Make a note of the current era in its status line
0080 - Take vendor snapshot (the era and snapshot should be forever
0081 associated now).
0082
0083 Rolling back to an vendor snapshot
0084 ----------------------------------
0085
0086 - Cache enters passthrough mode (see: dm-cache's docs in cache.txt)
0087 - Rollback vendor storage
0088 - Take metadata snapshot
0089 - Ascertain which blocks have been written since the snapshot was taken
0090 by checking each block's era
0091 - Invalidate those blocks in the caching software
0092 - Cache returns to writeback/writethrough mode
0093
0094 Memory usage
0095 ============
0096
0097 The target uses a bitset to record writes in the current era. It also
0098 has a spare bitset ready for switching over to a new era. Other than
0099 that it uses a few 4k blocks for updating metadata::
0100
0101 (4 * nr_blocks) bytes + buffers
0102
0103 Resilience
0104 ==========
0105
0106 Metadata is updated on disk before a write to a previously unwritten
0107 block is performed. As such dm-era should not be effected by a hard
0108 crash such as power failure.
0109
0110 Userland tools
0111 ==============
0112
0113 Userland tools are found in the increasingly poorly named
0114 thin-provisioning-tools project:
0115
0116 https://github.com/jthornber/thin-provisioning-tools
