btrfs-progs: docs: swapfile and hibernation

Document the new swapfile commands and how it could be used for hibernation.

Issue: #533
Issue: #544
Signed-off-by: David Sterba <dsterba@suse.com>

Documentation/Swapfile.rst

@@ -1,4 +1,4 @@
 Swapfile
---------
+========
 
 .. include:: ch-swapfile.rst

Documentation/btrfs-filesystem.rst

@@ -197,7 +197,8 @@ mkswapfile [-s size] file
         activated swapfile cannot be balanced.
 
         Swapfile creation can be achieved by standalone commands too. Activation
-        needs to be done by command ``swapon(8)``.
+        needs to be done by command ``swapon(8)``. See also command ``btrfs
+        inspect-internal map-swapfile`` and the :doc:`Swapfile feature<Swapfile>` description.
 
         ``Options``
 

Documentation/btrfs-inspect-internal.rst

@@ -169,6 +169,24 @@ logical-resolve [-Pvo] [-s <bufsize>] <logical> <path>
         -v
                 (deprecated) alias for global *-v* option
 
+map-swapfile [options] <file>
+        (needs root privileges)
+
+        Find device-specific physical offset of *file* that can be used for
+        hibernation. Also verify that the *file* is suitable as a swapfile.
+        See also command ``btrfs filesystem mkswapfile`` and the
+        :doc:`Swapfile feature<Swapfile>` description.
+
+        .. note::
+                Do not use ``filefrag`` or *FIEMAP* ioctl values reported as
+                physical, this is different due to internal filesystem mappings.
+                The hibernation expects offset relative to the physical block device.
+
+        ``Options``
+
+        -r|--resume-offset
+                print only the value suitable as resume offset for file */sys/power/resume_offset*
+
 min-dev-size [options] <path>
         (needs root privileges)
 

Documentation/ch-swapfile.rst

@@ -6,13 +6,14 @@ swap subsystem:
 * filesystem - must be only single device
 * filesystem - must have only *single* data profile
 * swapfile - the containing subvolume cannot be snapshotted
-* swapfile - must be preallocated
+* swapfile - must be preallocated (ie. no holes)
 * swapfile - must be nodatacow (ie. also nodatasum, no compression)
 
 The limitations come namely from the COW-based design and mapping layer of
 blocks that allows the advanced features like relocation and multi-device
 filesystems. However, the swap subsystem expects simpler mapping and no
-background changes of the file blocks once they've been attached to swap.
+background changes of the file block location once they've been assigned to
+swap.
 
 With active swapfiles, the following whole-filesystem operations will skip
 swapfile extents or may fail:
@@ -41,6 +42,14 @@ To create and activate a swapfile run the following commands:
         # mkswap swapfile
         # swapon swapfile
 
+Since version 6.1 it's possible to create the swapfile in a single command
+(except the activation):
+
+.. code-block:: bash
+
+        # btrfs filesystem mkswapfile swapfile
+        # swapon swapfile
+
 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.
@@ -52,7 +61,6 @@ The file will appear in */proc/swaps*:
         # cat /proc/swaps
         Filename          Type          Size           Used      Priority
         /path/swapfile    file          2097152        0         -2
-        --------------------
 
 The swapfile can be created as one-time operation or, once properly created,
 activated on each boot by the **swapon -a** command (usually started by the
@@ -65,6 +73,42 @@ priority, not the BTRFS mount options).
 
         /path/swapfile        none        swap        defaults      0 0
 
+Hibernation
+-----------
+
+A swapfile can be used for hibernation but it's not straightforward. Before
+hibernation a resume offset must be written to file */sys/power/resume_offset*
+or the kernel command line parameter *resume_offset* must be set.
+
+The value is the physical offset on the device. Note that **this is not the same
+value that** ``filefrag`` **prints as physical offset!**
+
+Btrfs filesystem uses mapping between logical and physical addresses but here
+the physical can still map to one or more device-specific physical block
+addresses. It's the device-specific physical offset that is suitable as resume
+offset.
+
+Since version 6.1 there's a command ``btrfs inspect-internal map-swapfile`` that will
+print the device physical offset and the adjusted value for */sys/power/resume_offset*.
+Note that the value is divided by page size, ie. it's not the offset itself.
+
+.. code-block:: bash
+
+        # btrfs filesystem mkswapfile swapfile
+        # btrfs inspect-internal map-swapfile swapfile
+        Physical start: 811511726080
+        Resume offset:     198122980
+
+For scripting and convenience the option *-r* will print just the offset:
+
+.. code-block:: bash
+
+        # btrfs inspect-internal map-swapfile -r swapfile
+        198122980
+
+The command *map-swapfile* also verifies all the requirements, ie. no holes,
+single device, etc.
+
 
 Troubleshooting
 ---------------