era.rst 3.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116
  1. ======
  2. dm-era
  3. ======
  4. Introduction
  5. ============
  6. dm-era is a target that behaves similar to the linear target. In
  7. addition it keeps track of which blocks were written within a user
  8. defined period of time called an 'era'. Each era target instance
  9. maintains the current era as a monotonically increasing 32-bit
  10. counter.
  11. Use cases include tracking changed blocks for backup software, and
  12. partially invalidating the contents of a cache to restore cache
  13. coherency after rolling back a vendor snapshot.
  14. Constructor
  15. ===========
  16. era <metadata dev> <origin dev> <block size>
  17. ================ ======================================================
  18. metadata dev fast device holding the persistent metadata
  19. origin dev device holding data blocks that may change
  20. block size block size of origin data device, granularity that is
  21. tracked by the target
  22. ================ ======================================================
  23. Messages
  24. ========
  25. None of the dm messages take any arguments.
  26. checkpoint
  27. ----------
  28. Possibly move to a new era. You shouldn't assume the era has
  29. incremented. After sending this message, you should check the
  30. current era via the status line.
  31. take_metadata_snap
  32. ------------------
  33. Create a clone of the metadata, to allow a userland process to read it.
  34. drop_metadata_snap
  35. ------------------
  36. Drop the metadata snapshot.
  37. Status
  38. ======
  39. <metadata block size> <#used metadata blocks>/<#total metadata blocks>
  40. <current era> <held metadata root | '-'>
  41. ========================= ==============================================
  42. metadata block size Fixed block size for each metadata block in
  43. sectors
  44. #used metadata blocks Number of metadata blocks used
  45. #total metadata blocks Total number of metadata blocks
  46. current era The current era
  47. held metadata root The location, in blocks, of the metadata root
  48. that has been 'held' for userspace read
  49. access. '-' indicates there is no held root
  50. ========================= ==============================================
  51. Detailed use case
  52. =================
  53. The scenario of invalidating a cache when rolling back a vendor
  54. snapshot was the primary use case when developing this target:
  55. Taking a vendor snapshot
  56. ------------------------
  57. - Send a checkpoint message to the era target
  58. - Make a note of the current era in its status line
  59. - Take vendor snapshot (the era and snapshot should be forever
  60. associated now).
  61. Rolling back to an vendor snapshot
  62. ----------------------------------
  63. - Cache enters passthrough mode (see: dm-cache's docs in cache.txt)
  64. - Rollback vendor storage
  65. - Take metadata snapshot
  66. - Ascertain which blocks have been written since the snapshot was taken
  67. by checking each block's era
  68. - Invalidate those blocks in the caching software
  69. - Cache returns to writeback/writethrough mode
  70. Memory usage
  71. ============
  72. The target uses a bitset to record writes in the current era. It also
  73. has a spare bitset ready for switching over to a new era. Other than
  74. that it uses a few 4k blocks for updating metadata::
  75. (4 * nr_blocks) bytes + buffers
  76. Resilience
  77. ==========
  78. Metadata is updated on disk before a write to a previously unwritten
  79. block is performed. As such dm-era should not be effected by a hard
  80. crash such as power failure.
  81. Userland tools
  82. ==============
  83. Userland tools are found in the increasingly poorly named
  84. thin-provisioning-tools project:
  85. https://github.com/jthornber/thin-provisioning-tools