| Kyle Swenson | 8d8f654 | 2021-03-15 11:02:55 -0600 | [diff] [blame^] | 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 |