btrfs-progs: docs: improve swapfile

Documentation/ch-swapfile.rst

@@ -1,11 +1,14 @@
-A swapfile is file-backed memory that the system uses to temporarily offload
-the RAM.  It is supported since kernel 5.0. Use ``swapon(8)`` to activate the
-swapfile. There are some limitations of the implementation in BTRFS and Linux
-swap subsystem:
+A swapfile, when active, is a file-backed swap area.  It is supported since kernel 5.0.
+Use ``swapon(8)`` to activate it, until then (respectively again after deactivating it
+with ``swapoff(8)``) it's just a normal file (with NODATACOW set), for which the special
+restrictions for active swapfiles don't apply.
+
+There are some limitations of the implementation in BTRFS and Linux swap
+subsystem:
 
 * filesystem - must be only single device
 * filesystem - must have only *single* data profile
-* swapfile - the containing subvolume cannot be snapshotted
+* subvolume - cannot be snapshotted if it contains any active swapfiles
 * swapfile - must be preallocated (i.e. no holes)
 * swapfile - must be NODATACOW (i.e. also NODATASUM, no compression)
 
@@ -18,12 +21,14 @@ swap.
 With active swapfiles, the following whole-filesystem operations will skip
 swapfile extents or may fail:
 
-* balance - block groups with swapfile extents are skipped and reported, the
-  rest will be processed normally
+* balance - block groups with extents of any active swapfiles are skipped and
+  reported, the rest will be processed normally
 * resize grow - unaffected
-* resize shrink - works as long as the extents are outside of the shrunk range
-* device add - a new device does not interfere with existing swapfile and this
-  operation will work, though no new swapfile can be activated afterwards
+* resize shrink - works as long as the extents of any active swapfiles are
+  outside of the shrunk range
+* device add - if the new devices do not interfere with any already active swapfiles
+  this operation will work, though no new swapfile can be activated
+  afterwards
 * device delete - if the device has been added as above, it can be also deleted
 * device replace - ditto
 
@@ -54,7 +59,7 @@ Please note that the UUID returned by the *mkswap* utility identifies the swap
 "filesystem" and because it's stored in a file, it's not generally visible and
 usable as an identifier unlike if it was on a block device.
 
-The file will appear in */proc/swaps*:
+Once activated the file will appear in */proc/swaps*:
 
 .. code-block:: none
 
@@ -73,6 +78,16 @@ priority, not the BTRFS mount options).
 
         /path/swapfile        none        swap        defaults      0 0
 
+From now on the subvolume with the active swapfile cannot be snapshotted until
+the swapfile is deactivated again by ``swapoff``. Then the swapfile is a
+regular file and the subvolume can be snapshotted again, though this would prevent
+another activation any swapfile that has been snapshotted. New swapfiles (not
+snapshotted) can be created and activated.
+
+Otherwise, an inactive swapfile does not affect the containing subvolume. Activation
+creates a temporary in-memory status and prevents some file operations, but is
+not stored permanently.
+
 Hibernation
 -----------