From d6d4e6fefdf82f5caebfdda64cde9fc838b72c32 Mon Sep 17 00:00:00 2001 From: Christoph Anton Mitterer Date: Thu, 27 Apr 2023 01:48:16 +0200 Subject: [PATCH 1/2] btrfs-progs: docs: further improve space cache documentation - For the btrfs check option of clearing, indicate that - since it's actually a full removing - a new space cache may be generated on the next mount. - In the summary of the `clear_cache` mount option, don't mention that it rebuilds the cache, as the option itself is in principle only about the clearing and the rebuilding happens "automatically" (unless other options are used). - In the details mention, however that there is rebuilding unless prevented by mount option. - Remove the "if something has gone wrong", as the mount option would also remove the cache if nothing went wrong. Signed-off-by: Christoph Anton Mitterer --- Documentation/btrfs-check.rst | 2 ++ Documentation/ch-mount-options.rst | 14 ++++++++------ 2 files changed, 10 insertions(+), 6 deletions(-) diff --git a/Documentation/btrfs-check.rst b/Documentation/btrfs-check.rst index 6ade9d51b4..43b1fa9a57 100644 --- a/Documentation/btrfs-check.rst +++ b/Documentation/btrfs-check.rst @@ -81,6 +81,8 @@ SAFE OR ADVISORY OPTIONS --clear-space-cache v1|v2 completely remove the free space cache of the given version + When the filesystem is mounted afterwards, a new space cache may be generated + depending on mount options and/or kernel defaults. See also the *clear_cache* mount option. --clear-ino-cache diff --git a/Documentation/ch-mount-options.rst b/Documentation/ch-mount-options.rst index 96d290fd66..9fb0112142 100644 --- a/Documentation/ch-mount-options.rst +++ b/Documentation/ch-mount-options.rst @@ -89,18 +89,20 @@ check_int, check_int_data, check_int_print_mask= for more information. clear_cache - Force clearing and rebuilding of the free space cache if something - has gone wrong. + Force clearing of the free space cache. - For free space cache *v1*, this only clears (and, unless *nospace_cache* is - used, rebuilds) the free space cache for block groups that are modified while - the filesystem is mounted with that option. To actually clear an entire free - space cache *v1*, see :command:`btrfs check --clear-space-cache v1`. + For free space cache *v1*, this only clears the free space cache for block + groups that are modified while the filesystem is mounted with that option. + To actually clear the entire free space cache *v1*, see + :command:`btrfs check --clear-space-cache v1`. For free space cache *v2*, this clears the entire free space cache. To do so without requiring to mounting the filesystem, see :command:`btrfs check --clear-space-cache v2`. + For both versions, unless *nospace_cache* is used, the cleared parts of + the free space cache are also rebuild. + See also: *space_cache*. commit= From e8a471c5e7dad388e1dda7c01fe46e89baef3ed4 Mon Sep 17 00:00:00 2001 From: Christoph Anton Mitterer Date: Thu, 27 Apr 2023 02:35:42 +0200 Subject: [PATCH 2/2] btrfs-progs: docs: improve space_cache mount option description Strcturise the details more clearly by: - What it does/implications. - The different versions an their details. - What happens if both versions are present. - What happens with kernels that cannot use v2. - How each version can be disabled, cleared or removed. - Make it more clear that the default of "space cache v2" applies also if the option isn't given at all. Signed-off-by: Christoph Anton Mitterer --- Documentation/ch-mount-options.rst | 36 ++++++++++++++++-------------- 1 file changed, 19 insertions(+), 17 deletions(-) diff --git a/Documentation/ch-mount-options.rst b/Documentation/ch-mount-options.rst index 9fb0112142..f581e15a55 100644 --- a/Documentation/ch-mount-options.rst +++ b/Documentation/ch-mount-options.rst @@ -355,27 +355,29 @@ space_cache, space_cache=, nospace_cache the space cache consumes some resources, including a small amount of disk space. - There are two implementations of the free space cache. The original - one, referred to as *v1*, used to be a safe default but has been - superseded by *v2*. The *v1* space cache can be disabled at mount time - with *nospace_cache* without clearing. - - On very large filesystems (many terabytes) and certain workloads, the - performance of the *v1* space cache may degrade drastically. The *v2* - implementation, which adds a new b-tree called the free space tree, addresses - this issue. Once enabled, the *v2* space cache will always be used and cannot - be disabled unless it is cleared. Use *clear_cache,space_cache=v1* or - *clear_cache,nospace_cache* to do so. If *v2* is enabled, and *v1* space - cache will be cleared (at the first mount) and kernels without *v2* - support will only be able to mount the filesystem in read-only mode. - On an unmounted filesystem the caches (both versions) can be cleared by - "btrfs check --clear-space-cache". + There are two implementations of the free space cache: + * *v1*, the original one, whose performance may degrade drastically on very + large filesystems (many terabytes) and certain workloads. + * *v2*, the newer one, which addresses the above issue and uses a new b-tree + called "free space tree". + + When *v2* is enabled, a *v1* space cache will be cleared (at the first mount). + + Kernels without *v2* support will only be able to mount filesystems with *v2* + space cache in read-only mode. + + The *v1* space cache can be disabled at mount time with *nospace_cache* without + clearing it. + The *v2* space cache, once enabled, cannot be disabled and will always be used + if present, unless it is cleared and the space cache is either disabled (via + *clear_cache,nospace_cache*) or changed to *v1* (via *clear_cache,space_cache=v1*). + Both versions can be removed, see :command:`btrfs check --clear-space-cache v2`. The :doc:`btrfs-check(8)` and `:doc:`mkfs.btrfs(8)` commands have full *v2* free space cache support since v4.19. - If a version is not explicitly specified, the default implementation will be - chosen, which is *v2*. + Unless *nospace_cache* is specified, if *space_cache* is not specified at all + or specified without version, the default (space cache *v2*) will be used. ssd, ssd_spread, nossd, nossd_spread (default: SSD autodetected)