[PATCH 0/2] fstests: btrfs: make space cache related tests future proof

[PATCH 0/2] fstests: btrfs: make space cache related tests future proof

[Qu Wenruo]

The existing btrfs/131 is testing no space cache, v1 space cache and v2
space cache mount options.

It's fine for LTS kernels as they will stay there for a long time with
v1 space cache support.

However v1 space cache is already deprecated since commit 1e7bec1f7d65
("btrfs: emit a warning about space cache v1 being deprecated"), and the
kernel support for v1 cache will drop soon.

In that case btrfs/131 will cause false alerts, and we will have no test
case covering no space cache and v2 space cache mount options.

The series will:

- Enhance btrfs/131 to skip the test if the kernel has no v1 cache support
  This is done by a more explicit check.

- Add a new test case without v1 cache
  The newer one can cover cases which is not covered before, including:
  * bs > ps cases
  * bs < ps cases
  * zoned devices

Qu Wenruo (2):
  fstests: btrfs/131: add explicit v1 space cache requirement
  fstests: btrfs: add a new test case that is future-proof

 common/btrfs        |  25 +++++++++++
 tests/btrfs/131     |  12 +++---
 tests/btrfs/340     | 103 ++++++++++++++++++++++++++++++++++++++++++++
 tests/btrfs/340.out |  15 +++++++
 4 files changed, 148 insertions(+), 7 deletions(-)
 create mode 100755 tests/btrfs/340
 create mode 100644 tests/btrfs/340.out

-- 
2.51.2

[PATCH 1/2] fstests: btrfs/131: add explicit v1 space cache requirement

[Qu Wenruo]

The test case is utilizing v1 space cache, meanwhile v1 space cache
is already marked deprecated for a while since kernel commit
1e7bec1f7d65 ("btrfs: emit a warning about space cache v1 being
deprecated").

Furthermore quite some features are not compatible with v1 cache,
including the soon-to-be-default block-group-tree, and hardware
dependent zoned features.

Currently we reject those features for btrfs/131, but what we really
want is to only run the test case for supported features/kernels.
The current way to reject will not handle future kernels that completely
rejects v1 space cache.

Add a new helper, _require_btrfs_v1_cache() to do the check, which
checks the following criteria:

- "space_cache=v1" mount option is supported
  And to handle default v2 cache behavior, also add "clear_cache".
  If the kernel has completely dropped v1 cache support, such mount
  should fail.

- Check if FREE_SPACE_TREE feature exists after above mount
  For bs != ps cases, v2 cache is enforced to replace v1 cache, thus
  we need to double check to make sure above mount didn't result v2
  cache.

- Check if cache generation is correct
  If v1 cache is working, the cache_generation should be some valid
  value other than 0 nor (u64)-1.

And replace the existing checks on zoned and block-group-tree with the
new one.

Signed-off-by: Qu Wenruo <wqu@suse.com>
---
 common/btrfs    | 25 +++++++++++++++++++++++++
 tests/btrfs/131 |  7 +------
 2 files changed, 26 insertions(+), 6 deletions(-)

diff --git a/common/btrfs b/common/btrfs
index 6a1095ff..c2d616aa 100644
--- a/common/btrfs
+++ b/common/btrfs
@@ -630,6 +630,31 @@ _btrfs_no_v1_cache_opt()
 	echo -n "-onospace_cache"
 }
 
+# v1 space cache is already deprecated and will be removed soon. Furthermore
+# the soon-to-be-default block-group-tree has dependency on v2 space cache, and
+# will reject v1 cache mount option.
+# Make sure v1 space cache is still supported for test cases still utilizing
+# v1 space cache.
+_require_btrfs_v1_cache()
+{
+	_scratch_mkfs &> /dev/null
+	_try_scratch_mount -o clear_cache,space_cache=v1 || _notrun "v1 space cache is not supported"
+	_scratch_unmount
+
+	# Make sure no FREE_SPACE_TREE enabled.
+	if $BTRFS_UTIL_PROG inspect-internal dump-super $SCRATCH_DEV |\
+	   grep -q "FREE_SPACE_TREE"; then
+		_notrun "v1 space cache is not supported"
+	fi
+
+	# Make sure the cache generation is not 0 nor -1.
+	local cache_gen=$($BTRFS_UTIL_PROG inspect-internal dump-super $SCRATCH_DEV |\
+			  grep "cache_generation" | $AWK_PROG '{ print $2 }' )
+	if [ "$cache_gen" -eq 0 -o $(( $test_num + 1 )) -eq 0 ]; then
+		_notrun "v1 space cache is not supported"
+	fi
+}
+
 # Require certain sectorsize support
 _require_btrfs_support_sectorsize()
 {
diff --git a/tests/btrfs/131 b/tests/btrfs/131
index b4756a5f..026d11e6 100755
--- a/tests/btrfs/131
+++ b/tests/btrfs/131
@@ -14,14 +14,9 @@ _begin_fstest auto quick
 _require_scratch
 _require_btrfs_command inspect-internal dump-super
 _require_btrfs_fs_feature free_space_tree
-# Zoned btrfs does not support space_cache(v1)
-_require_non_zoned_device "${SCRATCH_DEV}"
-# Block group tree does not support space_cache(v1)
-_require_btrfs_no_block_group_tree
+_require_btrfs_v1_cache
 
 _scratch_mkfs >/dev/null 2>&1
-[ "$(_get_page_size)" -gt "$(_scratch_btrfs_sectorsize)" ] && \
-	_notrun "cannot run with subpage sectorsize"
 
 mkfs_v1()
 {
-- 
2.51.2

[PATCH 2/2] fstests: btrfs: add a new test case that is future-proof

[Qu Wenruo]

Btrfs' v1 space cache is marked deprecated since commit 1e7bec1f7d65
("btrfs: emit a warning about space cache v1 being deprecated"), and
soon the v1 space cache mount option will be fully dropped.

Furthermore existing features like block-group-tree, zoned, and bs != ps
support are all rejecting v1 space cache or forcing the switch to v2
space cache.

The existing btrfs/131 is not going to handle the future well, and that
test case is mostly for LTS kernel testing now.

Add a new test case that is completely v1 cache free, so that it will
support the future where v1 cache is completely dropped, meanwhile still
keep the coverage for v2 cache and nospace_cache mount options.

Signed-off-by: Qu Wenruo <wqu@suse.com>
---
 tests/btrfs/131     |   5 ++-
 tests/btrfs/340     | 103 ++++++++++++++++++++++++++++++++++++++++++++
 tests/btrfs/340.out |  15 +++++++
 3 files changed, 122 insertions(+), 1 deletion(-)
 create mode 100755 tests/btrfs/340
 create mode 100644 tests/btrfs/340.out

diff --git a/tests/btrfs/131 b/tests/btrfs/131
index 026d11e6..b54b8326 100755
--- a/tests/btrfs/131
+++ b/tests/btrfs/131
@@ -4,7 +4,10 @@
 #
 # FS QA Test 131
 #
-# Test free space tree mount options.
+# Test free space tree mount options, 3 options involved:
+# - No space cache
+# - Old (deprecated) v1 space cache
+# - New (default) v2 space cache
 #
 . ./common/preamble
 _begin_fstest auto quick
diff --git a/tests/btrfs/340 b/tests/btrfs/340
new file mode 100755
index 00000000..0d558422
--- /dev/null
+++ b/tests/btrfs/340
@@ -0,0 +1,103 @@
+#! /bin/bash
+# SPDX-License-Identifier: GPL-2.0
+# Copyright (c) 2025 SUSE S.A.  All Rights Reserved.
+#
+# FS QA Test 340
+#
+# Test free space tree mount options, for newer kernels with only 2 options involed:
+# - No space cache
+# - New (default) v2 space cache
+#
+. ./common/preamble
+_begin_fstest auto quick
+
+_require_scratch
+_require_btrfs_command inspect-internal dump-super
+_require_btrfs_fs_feature free_space_tree
+
+# The block-group-tree feature relies on v2 cache, thus it doesn't support
+# "nospace_cache" mount option.
+_require_btrfs_no_block_group_tree
+
+mkfs_nocache()
+{
+	_scratch_mkfs >/dev/null 2>&1
+	_scratch_mount -o clear_cache,nospace_cache
+	_scratch_unmount
+}
+
+mkfs_v2()
+{
+	_scratch_mkfs >/dev/null 2>&1
+	_scratch_mount -o space_cache=v2
+	_scratch_unmount
+}
+
+check_fst_compat()
+{
+	compat_ro="$($BTRFS_UTIL_PROG inspect-internal dump-super "$SCRATCH_DEV" | \
+		     sed -rn 's/^compat_ro_flags\s+(.*)$/\1/p')"
+	if ((compat_ro & 0x1)); then
+		echo "free space tree is enabled"
+	else
+		echo "free space tree is disabled"
+	fi
+}
+
+# Mount options might interfere.
+export MOUNT_OPTIONS=""
+
+# When the free space tree is not enabled:
+# -o space_cache=v2: enable the free space tree
+# -o clear_cache,space_cache=v2: clear the old space cache and enable the free space tree
+# We don't check the no options case or plain space_cache as that will change
+# in the future to turn on space_cache=v2.
+
+mkfs_nocache
+echo "Using no space cache"
+_scratch_mount -o nospace_cache
+check_fst_compat
+_scratch_unmount
+
+mkfs_nocache
+echo "Enabling free space tree"
+_scratch_mount -o space_cache=v2
+check_fst_compat
+_scratch_unmount
+
+# When the free space tree is enabled:
+# -o nospace_cache: error
+# no options, -o space_cache=v2: keep using the free space tree
+# -o clear_cache, -o clear_cache,space_cache=v2: clear and recreate the free space tree
+# -o clear_cache,nospace_cache: clear the free space tree
+
+mkfs_v2
+echo "Trying to mount without free space tree"
+_try_scratch_mount -o nospace_cache >/dev/null 2>&1 || echo "mount failed"
+
+mkfs_v2
+echo "Mounting existing free space tree"
+_scratch_mount
+check_fst_compat
+_scratch_unmount
+_scratch_mount -o space_cache=v2
+check_fst_compat
+_scratch_unmount
+
+mkfs_v2
+echo "Recreating free space tree"
+_scratch_mount -o clear_cache,space_cache=v2
+check_fst_compat
+_scratch_unmount
+mkfs_v2
+_scratch_mount -o clear_cache
+check_fst_compat
+_scratch_unmount
+
+mkfs_v2
+echo "Disabling free space tree"
+_scratch_mount -o clear_cache,nospace_cache
+check_fst_compat
+_scratch_unmount
+
+_exit 0
diff --git a/tests/btrfs/340.out b/tests/btrfs/340.out
new file mode 100644
index 00000000..d8b99b3b
--- /dev/null
+++ b/tests/btrfs/340.out
@@ -0,0 +1,15 @@
+QA output created by 340
+Using no space cache
+free space tree is disabled
+Enabling free space tree
+free space tree is enabled
+Trying to mount without free space tree
+mount failed
+Mounting existing free space tree
+free space tree is enabled
+free space tree is enabled
+Recreating free space tree
+free space tree is enabled
+free space tree is enabled
+Disabling free space tree
+free space tree is disabled
-- 
2.51.2

Re: [PATCH 1/2] fstests: btrfs/131: add explicit v1 space cache requirement

[Zorro Lang]

On Fri, Dec 26, 2025 at 08:45:52AM +1030, Qu Wenruo wrote:
> The test case is utilizing v1 space cache, meanwhile v1 space cache
> is already marked deprecated for a while since kernel commit
> 1e7bec1f7d65 ("btrfs: emit a warning about space cache v1 being
> deprecated").
> 
> Furthermore quite some features are not compatible with v1 cache,
> including the soon-to-be-default block-group-tree, and hardware
> dependent zoned features.
> 
> Currently we reject those features for btrfs/131, but what we really
> want is to only run the test case for supported features/kernels.
> The current way to reject will not handle future kernels that completely
> rejects v1 space cache.
> 
> Add a new helper, _require_btrfs_v1_cache() to do the check, which
> checks the following criteria:
> 
> - "space_cache=v1" mount option is supported
>   And to handle default v2 cache behavior, also add "clear_cache".
>   If the kernel has completely dropped v1 cache support, such mount
>   should fail.
> 
> - Check if FREE_SPACE_TREE feature exists after above mount
>   For bs != ps cases, v2 cache is enforced to replace v1 cache, thus
>   we need to double check to make sure above mount didn't result v2
>   cache.
> 
> - Check if cache generation is correct
>   If v1 cache is working, the cache_generation should be some valid
>   value other than 0 nor (u64)-1.
> 
> And replace the existing checks on zoned and block-group-tree with the
> new one.
> 
> Signed-off-by: Qu Wenruo <wqu@suse.com>
> ---

This patchset is good to me, if there's not more review points from btrfs
list, I'll merge it.

Reviewed-by: Zorro Lang <zlang@redhat.com>

>  common/btrfs    | 25 +++++++++++++++++++++++++
>  tests/btrfs/131 |  7 +------
>  2 files changed, 26 insertions(+), 6 deletions(-)
> 
> diff --git a/common/btrfs b/common/btrfs
> index 6a1095ff..c2d616aa 100644
> --- a/common/btrfs
> +++ b/common/btrfs
> @@ -630,6 +630,31 @@ _btrfs_no_v1_cache_opt()
>  	echo -n "-onospace_cache"
>  }
>  
> +# v1 space cache is already deprecated and will be removed soon. Furthermore
> +# the soon-to-be-default block-group-tree has dependency on v2 space cache, and
> +# will reject v1 cache mount option.
> +# Make sure v1 space cache is still supported for test cases still utilizing
> +# v1 space cache.
> +_require_btrfs_v1_cache()
> +{
> +	_scratch_mkfs &> /dev/null
> +	_try_scratch_mount -o clear_cache,space_cache=v1 || _notrun "v1 space cache is not supported"
> +	_scratch_unmount
> +
> +	# Make sure no FREE_SPACE_TREE enabled.
> +	if $BTRFS_UTIL_PROG inspect-internal dump-super $SCRATCH_DEV |\
> +	   grep -q "FREE_SPACE_TREE"; then
> +		_notrun "v1 space cache is not supported"
> +	fi
> +
> +	# Make sure the cache generation is not 0 nor -1.
> +	local cache_gen=$($BTRFS_UTIL_PROG inspect-internal dump-super $SCRATCH_DEV |\
> +			  grep "cache_generation" | $AWK_PROG '{ print $2 }' )
> +	if [ "$cache_gen" -eq 0 -o $(( $test_num + 1 )) -eq 0 ]; then
> +		_notrun "v1 space cache is not supported"
> +	fi
> +}
> +
>  # Require certain sectorsize support
>  _require_btrfs_support_sectorsize()
>  {
> diff --git a/tests/btrfs/131 b/tests/btrfs/131
> index b4756a5f..026d11e6 100755
> --- a/tests/btrfs/131
> +++ b/tests/btrfs/131
> @@ -14,14 +14,9 @@ _begin_fstest auto quick
>  _require_scratch
>  _require_btrfs_command inspect-internal dump-super
>  _require_btrfs_fs_feature free_space_tree
> -# Zoned btrfs does not support space_cache(v1)
> -_require_non_zoned_device "${SCRATCH_DEV}"
> -# Block group tree does not support space_cache(v1)
> -_require_btrfs_no_block_group_tree
> +_require_btrfs_v1_cache
>  
>  _scratch_mkfs >/dev/null 2>&1
> -[ "$(_get_page_size)" -gt "$(_scratch_btrfs_sectorsize)" ] && \
> -	_notrun "cannot run with subpage sectorsize"
>  
>  mkfs_v1()
>  {
> -- 
> 2.51.2
> 
> 

Re: [PATCH 2/2] fstests: btrfs: add a new test case that is future-proof

[Zorro Lang]

On Fri, Dec 26, 2025 at 08:45:53AM +1030, Qu Wenruo wrote:
> Btrfs' v1 space cache is marked deprecated since commit 1e7bec1f7d65
> ("btrfs: emit a warning about space cache v1 being deprecated"), and
> soon the v1 space cache mount option will be fully dropped.
> 
> Furthermore existing features like block-group-tree, zoned, and bs != ps
> support are all rejecting v1 space cache or forcing the switch to v2
> space cache.
> 
> The existing btrfs/131 is not going to handle the future well, and that
> test case is mostly for LTS kernel testing now.
> 
> Add a new test case that is completely v1 cache free, so that it will
> support the future where v1 cache is completely dropped, meanwhile still
> keep the coverage for v2 cache and nospace_cache mount options.
> 
> Signed-off-by: Qu Wenruo <wqu@suse.com>
> ---

Reviewed-by: Zorro Lang <zlang@redhat.com>

>  tests/btrfs/131     |   5 ++-
>  tests/btrfs/340     | 103 ++++++++++++++++++++++++++++++++++++++++++++
>  tests/btrfs/340.out |  15 +++++++
>  3 files changed, 122 insertions(+), 1 deletion(-)
>  create mode 100755 tests/btrfs/340
>  create mode 100644 tests/btrfs/340.out
> 
> diff --git a/tests/btrfs/131 b/tests/btrfs/131
> index 026d11e6..b54b8326 100755
> --- a/tests/btrfs/131
> +++ b/tests/btrfs/131
> @@ -4,7 +4,10 @@
>  #
>  # FS QA Test 131
>  #
> -# Test free space tree mount options.
> +# Test free space tree mount options, 3 options involved:
> +# - No space cache
> +# - Old (deprecated) v1 space cache
> +# - New (default) v2 space cache
>  #
>  . ./common/preamble
>  _begin_fstest auto quick
> diff --git a/tests/btrfs/340 b/tests/btrfs/340
> new file mode 100755
> index 00000000..0d558422
> --- /dev/null
> +++ b/tests/btrfs/340
> @@ -0,0 +1,103 @@
> +#! /bin/bash
> +# SPDX-License-Identifier: GPL-2.0
> +# Copyright (c) 2025 SUSE S.A.  All Rights Reserved.
> +#
> +# FS QA Test 340
> +#
> +# Test free space tree mount options, for newer kernels with only 2 options involed:
> +# - No space cache
> +# - New (default) v2 space cache
> +#
> +. ./common/preamble
> +_begin_fstest auto quick
> +
> +_require_scratch
> +_require_btrfs_command inspect-internal dump-super
> +_require_btrfs_fs_feature free_space_tree
> +
> +# The block-group-tree feature relies on v2 cache, thus it doesn't support
> +# "nospace_cache" mount option.
> +_require_btrfs_no_block_group_tree
> +
> +mkfs_nocache()
> +{
> +	_scratch_mkfs >/dev/null 2>&1
> +	_scratch_mount -o clear_cache,nospace_cache
> +	_scratch_unmount
> +}
> +
> +mkfs_v2()
> +{
> +	_scratch_mkfs >/dev/null 2>&1
> +	_scratch_mount -o space_cache=v2
> +	_scratch_unmount
> +}
> +
> +check_fst_compat()
> +{
> +	compat_ro="$($BTRFS_UTIL_PROG inspect-internal dump-super "$SCRATCH_DEV" | \
> +		     sed -rn 's/^compat_ro_flags\s+(.*)$/\1/p')"
> +	if ((compat_ro & 0x1)); then
> +		echo "free space tree is enabled"
> +	else
> +		echo "free space tree is disabled"
> +	fi
> +}
> +
> +# Mount options might interfere.
> +export MOUNT_OPTIONS=""
> +
> +# When the free space tree is not enabled:
> +# -o space_cache=v2: enable the free space tree
> +# -o clear_cache,space_cache=v2: clear the old space cache and enable the free space tree
> +# We don't check the no options case or plain space_cache as that will change
> +# in the future to turn on space_cache=v2.
> +
> +mkfs_nocache
> +echo "Using no space cache"
> +_scratch_mount -o nospace_cache
> +check_fst_compat
> +_scratch_unmount
> +
> +mkfs_nocache
> +echo "Enabling free space tree"
> +_scratch_mount -o space_cache=v2
> +check_fst_compat
> +_scratch_unmount
> +
> +# When the free space tree is enabled:
> +# -o nospace_cache: error
> +# no options, -o space_cache=v2: keep using the free space tree
> +# -o clear_cache, -o clear_cache,space_cache=v2: clear and recreate the free space tree
> +# -o clear_cache,nospace_cache: clear the free space tree
> +
> +mkfs_v2
> +echo "Trying to mount without free space tree"
> +_try_scratch_mount -o nospace_cache >/dev/null 2>&1 || echo "mount failed"
> +
> +mkfs_v2
> +echo "Mounting existing free space tree"
> +_scratch_mount
> +check_fst_compat
> +_scratch_unmount
> +_scratch_mount -o space_cache=v2
> +check_fst_compat
> +_scratch_unmount
> +
> +mkfs_v2
> +echo "Recreating free space tree"
> +_scratch_mount -o clear_cache,space_cache=v2
> +check_fst_compat
> +_scratch_unmount
> +mkfs_v2
> +_scratch_mount -o clear_cache
> +check_fst_compat
> +_scratch_unmount
> +
> +mkfs_v2
> +echo "Disabling free space tree"
> +_scratch_mount -o clear_cache,nospace_cache
> +check_fst_compat
> +_scratch_unmount
> +
> +_exit 0
> diff --git a/tests/btrfs/340.out b/tests/btrfs/340.out
> new file mode 100644
> index 00000000..d8b99b3b
> --- /dev/null
> +++ b/tests/btrfs/340.out
> @@ -0,0 +1,15 @@
> +QA output created by 340
> +Using no space cache
> +free space tree is disabled
> +Enabling free space tree
> +free space tree is enabled
> +Trying to mount without free space tree
> +mount failed
> +Mounting existing free space tree
> +free space tree is enabled
> +free space tree is enabled
> +Recreating free space tree
> +free space tree is enabled
> +free space tree is enabled
> +Disabling free space tree
> +free space tree is disabled
> -- 
> 2.51.2
> 
>