Merge tag 'for-5.3/dm-changes' of git://git.kernel.org/pub/scm/linux/kernel/git/devic...
authorLinus Torvalds <torvalds@linux-foundation.org>
Sat, 13 Jul 2019 22:24:31 +0000 (15:24 -0700)
committerLinus Torvalds <torvalds@linux-foundation.org>
Sat, 13 Jul 2019 22:24:31 +0000 (15:24 -0700)
Pull device mapper updates from Mike Snitzer:

 - Add encrypted byte-offset initialization vector (eboiv) to DM crypt.

 - Add optional discard features to DM snapshot which allow freeing
   space from a DM device whose free space was exhausted.

 - Various small improvements to use struct_size() and kzalloc().

 - Fix to check if DM thin metadata is in fail_io mode before attempting
   to update the superblock to set the needs_check flag. Otherwise the
   DM thin-pool can hang.

 - Fix DM bufio shrinker's potential for ABBA recursion deadlock with DM
   thin provisioning on loop usecase.

* tag 'for-5.3/dm-changes' of git://git.kernel.org/pub/scm/linux/kernel/git/device-mapper/linux-dm:
  dm bufio: fix deadlock with loop device
  dm snapshot: add optional discard support features
  dm crypt: implement eboiv - encrypted byte-offset initialization vector
  dm crypt: remove obsolete comment about plumb IV
  dm crypt: wipe private IV struct after key invalid flag is set
  dm integrity: use kzalloc() instead of kmalloc() + memset()
  dm: update stale comment in end_clone_bio()
  dm log writes: fix incorrect comment about the logged sequence example
  dm log writes: use struct_size() to calculate size of pending_block
  dm crypt: use struct_size() when allocating encryption context
  dm integrity: always set version on superblock update
  dm thin metadata: check if in fail_io mode when setting needs_check

1  2 
Documentation/device-mapper/snapshot.rst

index 4c53304e72f1b042fdab9b034771017a45f527d0,0000000000000000000000000000000000000000..ccdd8b587a74f6869e3e7d321c7b19b30a2a7476
mode 100644,000000..100644
--- /dev/null
@@@ -1,180 -1,0 +1,196 @@@
- * snapshot-merge <origin> <COW device> <persistent> <chunksize>
 +==============================
 +Device-mapper snapshot support
 +==============================
 +
 +Device-mapper allows you, without massive data copying:
 +
 +-  To create snapshots of any block device i.e. mountable, saved states of
 +   the block device which are also writable without interfering with the
 +   original content;
 +-  To create device "forks", i.e. multiple different versions of the
 +   same data stream.
 +-  To merge a snapshot of a block device back into the snapshot's origin
 +   device.
 +
 +In the first two cases, dm copies only the chunks of data that get
 +changed and uses a separate copy-on-write (COW) block device for
 +storage.
 +
 +For snapshot merge the contents of the COW storage are merged back into
 +the origin device.
 +
 +
 +There are three dm targets available:
 +snapshot, snapshot-origin, and snapshot-merge.
 +
 +-  snapshot-origin <origin>
 +
 +which will normally have one or more snapshots based on it.
 +Reads will be mapped directly to the backing device. For each write, the
 +original data will be saved in the <COW device> of each snapshot to keep
 +its visible content unchanged, at least until the <COW device> fills up.
 +
 +
 +-  snapshot <origin> <COW device> <persistent?> <chunksize>
++   [<# feature args> [<arg>]*]
 +
 +A snapshot of the <origin> block device is created. Changed chunks of
 +<chunksize> sectors will be stored on the <COW device>.  Writes will
 +only go to the <COW device>.  Reads will come from the <COW device> or
 +from <origin> for unchanged data.  <COW device> will often be
 +smaller than the origin and if it fills up the snapshot will become
 +useless and be disabled, returning errors.  So it is important to monitor
 +the amount of free space and expand the <COW device> before it fills up.
 +
 +<persistent?> is P (Persistent) or N (Not persistent - will not survive
 +after reboot).  O (Overflow) can be added as a persistent store option
 +to allow userspace to advertise its support for seeing "Overflow" in the
 +snapshot status.  So supported store types are "P", "PO" and "N".
 +
 +The difference between persistent and transient is with transient
 +snapshots less metadata must be saved on disk - they can be kept in
 +memory by the kernel.
 +
 +When loading or unloading the snapshot target, the corresponding
 +snapshot-origin or snapshot-merge target must be suspended. A failure to
 +suspend the origin target could result in data corruption.
 +
++Optional features:
 +
++   discard_zeroes_cow - a discard issued to the snapshot device that
++   maps to entire chunks to will zero the corresponding exception(s) in
++   the snapshot's exception store.
++
++   discard_passdown_origin - a discard to the snapshot device is passed
++   down to the snapshot-origin's underlying device.  This doesn't cause
++   copy-out to the snapshot exception store because the snapshot-origin
++   target is bypassed.
++
++   The discard_passdown_origin feature depends on the discard_zeroes_cow
++   feature being enabled.
++
++
++-  snapshot-merge <origin> <COW device> <persistent> <chunksize>
++   [<# feature args> [<arg>]*]
 +
 +takes the same table arguments as the snapshot target except it only
 +works with persistent snapshots.  This target assumes the role of the
 +"snapshot-origin" target and must not be loaded if the "snapshot-origin"
 +is still present for <origin>.
 +
 +Creates a merging snapshot that takes control of the changed chunks
 +stored in the <COW device> of an existing snapshot, through a handover
 +procedure, and merges these chunks back into the <origin>.  Once merging
 +has started (in the background) the <origin> may be opened and the merge
 +will continue while I/O is flowing to it.  Changes to the <origin> are
 +deferred until the merging snapshot's corresponding chunk(s) have been
 +merged.  Once merging has started the snapshot device, associated with
 +the "snapshot" target, will return -EIO when accessed.
 +
 +
 +How snapshot is used by LVM2
 +============================
 +When you create the first LVM2 snapshot of a volume, four dm devices are used:
 +
 +1) a device containing the original mapping table of the source volume;
 +2) a device used as the <COW device>;
 +3) a "snapshot" device, combining #1 and #2, which is the visible snapshot
 +   volume;
 +4) the "original" volume (which uses the device number used by the original
 +   source volume), whose table is replaced by a "snapshot-origin" mapping
 +   from device #1.
 +
 +A fixed naming scheme is used, so with the following commands::
 +
 +  lvcreate -L 1G -n base volumeGroup
 +  lvcreate -L 100M --snapshot -n snap volumeGroup/base
 +
 +we'll have this situation (with volumes in above order)::
 +
 +  # dmsetup table|grep volumeGroup
 +
 +  volumeGroup-base-real: 0 2097152 linear 8:19 384
 +  volumeGroup-snap-cow: 0 204800 linear 8:19 2097536
 +  volumeGroup-snap: 0 2097152 snapshot 254:11 254:12 P 16
 +  volumeGroup-base: 0 2097152 snapshot-origin 254:11
 +
 +  # ls -lL /dev/mapper/volumeGroup-*
 +  brw-------  1 root root 254, 11 29 ago 18:15 /dev/mapper/volumeGroup-base-real
 +  brw-------  1 root root 254, 12 29 ago 18:15 /dev/mapper/volumeGroup-snap-cow
 +  brw-------  1 root root 254, 13 29 ago 18:15 /dev/mapper/volumeGroup-snap
 +  brw-------  1 root root 254, 10 29 ago 18:14 /dev/mapper/volumeGroup-base
 +
 +
 +How snapshot-merge is used by LVM2
 +==================================
 +A merging snapshot assumes the role of the "snapshot-origin" while
 +merging.  As such the "snapshot-origin" is replaced with
 +"snapshot-merge".  The "-real" device is not changed and the "-cow"
 +device is renamed to <origin name>-cow to aid LVM2's cleanup of the
 +merging snapshot after it completes.  The "snapshot" that hands over its
 +COW device to the "snapshot-merge" is deactivated (unless using lvchange
 +--refresh); but if it is left active it will simply return I/O errors.
 +
 +A snapshot will merge into its origin with the following command::
 +
 +  lvconvert --merge volumeGroup/snap
 +
 +we'll now have this situation::
 +
 +  # dmsetup table|grep volumeGroup
 +
 +  volumeGroup-base-real: 0 2097152 linear 8:19 384
 +  volumeGroup-base-cow: 0 204800 linear 8:19 2097536
 +  volumeGroup-base: 0 2097152 snapshot-merge 254:11 254:12 P 16
 +
 +  # ls -lL /dev/mapper/volumeGroup-*
 +  brw-------  1 root root 254, 11 29 ago 18:15 /dev/mapper/volumeGroup-base-real
 +  brw-------  1 root root 254, 12 29 ago 18:16 /dev/mapper/volumeGroup-base-cow
 +  brw-------  1 root root 254, 10 29 ago 18:16 /dev/mapper/volumeGroup-base
 +
 +
 +How to determine when a merging is complete
 +===========================================
 +The snapshot-merge and snapshot status lines end with:
 +
 +  <sectors_allocated>/<total_sectors> <metadata_sectors>
 +
 +Both <sectors_allocated> and <total_sectors> include both data and metadata.
 +During merging, the number of sectors allocated gets smaller and
 +smaller.  Merging has finished when the number of sectors holding data
 +is zero, in other words <sectors_allocated> == <metadata_sectors>.
 +
 +Here is a practical example (using a hybrid of lvm and dmsetup commands)::
 +
 +  # lvs
 +    LV      VG          Attr   LSize Origin  Snap%  Move Log Copy%  Convert
 +    base    volumeGroup owi-a- 4.00g
 +    snap    volumeGroup swi-a- 1.00g base  18.97
 +
 +  # dmsetup status volumeGroup-snap
 +  0 8388608 snapshot 397896/2097152 1560
 +                                    ^^^^ metadata sectors
 +
 +  # lvconvert --merge -b volumeGroup/snap
 +    Merging of volume snap started.
 +
 +  # lvs volumeGroup/snap
 +    LV      VG          Attr   LSize Origin  Snap%  Move Log Copy%  Convert
 +    base    volumeGroup Owi-a- 4.00g          17.23
 +
 +  # dmsetup status volumeGroup-base
 +  0 8388608 snapshot-merge 281688/2097152 1104
 +
 +  # dmsetup status volumeGroup-base
 +  0 8388608 snapshot-merge 180480/2097152 712
 +
 +  # dmsetup status volumeGroup-base
 +  0 8388608 snapshot-merge 16/2097152 16
 +
 +Merging has finished.
 +
 +::
 +
 +  # lvs
 +    LV      VG          Attr   LSize Origin  Snap%  Move Log Copy%  Convert
 +    base    volumeGroup owi-a- 4.00g