From f652a5b7548b1f902d8a8aab6ce13b9a60fcd9ce Mon Sep 17 00:00:00 2001 From: David Sterba Date: Tue, 6 Dec 2022 20:44:39 +0100 Subject: [PATCH] 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 --- Documentation/Swapfile.rst | 2 +- Documentation/btrfs-filesystem.rst | 3 +- Documentation/btrfs-inspect-internal.rst | 18 +++++++++ Documentation/ch-swapfile.rst | 50 ++++++++++++++++++++++-- 4 files changed, 68 insertions(+), 5 deletions(-) diff --git a/Documentation/Swapfile.rst b/Documentation/Swapfile.rst index 67ab8fe4..e20565f0 100644 --- a/Documentation/Swapfile.rst +++ b/Documentation/Swapfile.rst @@ -1,4 +1,4 @@ Swapfile --------- +======== .. include:: ch-swapfile.rst diff --git a/Documentation/btrfs-filesystem.rst b/Documentation/btrfs-filesystem.rst index b94756ae..4520a187 100644 --- a/Documentation/btrfs-filesystem.rst +++ b/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` description. ``Options`` diff --git a/Documentation/btrfs-inspect-internal.rst b/Documentation/btrfs-inspect-internal.rst index 48f21821..4a0f3698 100644 --- a/Documentation/btrfs-inspect-internal.rst +++ b/Documentation/btrfs-inspect-internal.rst @@ -169,6 +169,24 @@ logical-resolve [-Pvo] [-s ] -v (deprecated) alias for global *-v* option +map-swapfile [options] + (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` 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] (needs root privileges) diff --git a/Documentation/ch-swapfile.rst b/Documentation/ch-swapfile.rst index 6f7fe3db..551fc391 100644 --- a/Documentation/ch-swapfile.rst +++ b/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 ---------------