[PATCH v2 0/3] btrfs-progs: add block-group-tree to the default mkfs/convert features

[PATCH v2 0/3] btrfs-progs: add block-group-tree to the default mkfs/convert features

[Qu Wenruo]

[CHANGELOG]
v2:
- Automatically remove bgt feature when dependent feature is missing
  Instead of erroring out. This will allow us to run the existing
  no-holes/v1 free space cache test cases without any modification.

I was planning to do this during v6.12 but forgot it and now the next
LTS kernel release is not that far away, it's finally time to make the
switch.

The first patch is to change mkfs/btrfs-convert from rejecting
"bgt,^no-holes" to disabling bgt when no-holes/fst feature is not
selected.
This allows the existing "mkfs.btrfs ^no-holes" to be executed without
extra modification.

The second patch is a large page-size specific fix, where on 64K page
size systems misc/057 will fail due to subpage mounts always enable v2
free space cache, resulting later conversion failure to fst (as it's
already fst).

The final patch is the one enabling new default block-group-tree feature
for mkfs and convert.

Qu Wenruo (3):
  btrfs-progs: disable block-group-tree feature if dependency is missing
  btrfs-progs: misc-tests: check if free space tree is enabled after
    mount
  btrfs-progs: add block-group-tree to the default mkfs features

 Documentation/mkfs.btrfs.rst                           |  7 ++++++-
 common/fsfeatures.c                                    |  2 +-
 common/fsfeatures.h                                    |  3 ++-
 convert/main.c                                         |  4 ++--
 mkfs/main.c                                            | 10 +++++++---
 tests/misc-tests/057-btrfstune-free-space-tree/test.sh |  8 ++++++++
 6 files changed, 26 insertions(+), 8 deletions(-)

--
2.52.0

[PATCH v2 1/3] btrfs-progs: disable block-group-tree feature if dependency is missing

[Qu Wenruo]

Currently mkfs.btrfs will fail with the following features:

  # mkfs.btrfs -O block-group-tree,^no-holes $dev
  btrfs-progs v6.17.1
  See https://btrfs.readthedocs.io for more information.

  ERROR: block group tree requires no-holes and free-space-tree features

That's due to the artificial feature requirements from block-group-tree,
which requires no-holes and free-space-tree.

But such mandatory rejection will block our migration to the new default
block-group-tree tree features as a lot of no-holes test cases will cause
false alerts (and we do not have plan to deprecate explicit holes yet,
or do we?).

So to avoid the new default block-group-tree feature from causing tons of
false alerts, automatically disable block-group-tree feature if the end user
disables no-holes or free-space-tree features.

Now the above command will success, but with extra warnings and
block-group-tree disabled.

  # mkfs.btrfs -O block-group-tree,^no-holes $dev
  btrfs-progs v6.17.1
  See https://btrfs.readthedocs.io for more information.

  WARNING: disabling block-group-tree feature due to missing no-holes and free-space-tree features
  Label:              (null)
  UUID:               3c7adb81-c0c3-4980-8ef3-485019e5d8c4
  Node size:          16384
  Sector size:        4096	(CPU page size: 4096)
  Filesystem size:    1.00GiB
  Block group profiles:
    Data:             single            8.00MiB
    Metadata:         DUP              51.19MiB
    System:           DUP               8.00MiB
  SSD detected:       no
  Zoned device:       no
  Features:           extref, skinny-metadata, free-space-tree
  Checksum:           crc32c
  ...

Signed-off-by: Qu Wenruo <wqu@suse.com>
---
 Documentation/mkfs.btrfs.rst |  5 +++++
 convert/main.c               |  4 ++--
 mkfs/main.c                  | 10 +++++++---
 3 files changed, 14 insertions(+), 5 deletions(-)

diff --git a/Documentation/mkfs.btrfs.rst b/Documentation/mkfs.btrfs.rst
index 7734354fd6da..100449675597 100644
--- a/Documentation/mkfs.btrfs.rst
+++ b/Documentation/mkfs.btrfs.rst
@@ -436,6 +436,11 @@ block-group-tree
         enabled at *mkfs* time is possible, see :doc:`btrfstune`. Online
         conversion is not possible.
 
+	.. note::
+		This feature requires ``no-holes`` and ``free-space-tree``
+		features, if those dependency features are disabled,
+		``block-group-tree`` feature will also be disabled automatically.
+
 .. _mkfs-feature-raid-stripe-tree:
 
 raid-stripe-tree
diff --git a/convert/main.c b/convert/main.c
index 190f38a11924..116867fc9eff 100644
--- a/convert/main.c
+++ b/convert/main.c
@@ -1214,8 +1214,8 @@ static int do_convert(const char *devname, u32 convert_flags, u32 nodesize,
 	if ((features->compat_ro_flags & BTRFS_FEATURE_COMPAT_RO_BLOCK_GROUP_TREE) &&
 	    (!(features->incompat_flags & BTRFS_FEATURE_INCOMPAT_NO_HOLES) ||
 	     !(features->compat_ro_flags & BTRFS_FEATURE_COMPAT_RO_FREE_SPACE_TREE))) {
-		error("block group tree requires no-holes and free-space-tree features");
-		goto fail;
+		warning("disabling block-group-tree feature due to missing no-holes and free-space-tree features");
+		features->compat_ro_flags &= ~BTRFS_FEATURE_COMPAT_RO_BLOCK_GROUP_TREE;
 	}
 	fd = open(devname, O_RDWR);
 	if (fd < 0) {
diff --git a/mkfs/main.c b/mkfs/main.c
index f99e5486521d..cf77e192045b 100644
--- a/mkfs/main.c
+++ b/mkfs/main.c
@@ -1849,13 +1849,17 @@ int BOX_MAIN(mkfs)(int argc, char **argv)
 		}
 	}
 
-	/* Block group tree feature requires no-holes and free-space-tree. */
+	/*
+	 * Block group tree feature requires no-holes and free-space-tree.
+	 * And if those dependency is disabled, also disable block-group-tree feature.
+	 */
 	if (features.compat_ro_flags & BTRFS_FEATURE_COMPAT_RO_BLOCK_GROUP_TREE &&
 	    (!(features.incompat_flags & BTRFS_FEATURE_INCOMPAT_NO_HOLES) ||
 	     !(features.compat_ro_flags & BTRFS_FEATURE_COMPAT_RO_FREE_SPACE_TREE))) {
-		error("block group tree requires no-holes and free-space-tree features");
-		exit(1);
+		warning("disabling block-group-tree feature due to missing no-holes and free-space-tree features");
+		features.compat_ro_flags &= ~BTRFS_FEATURE_COMPAT_RO_BLOCK_GROUP_TREE;
 	}
+
 	if (opt_zoned) {
 		const int blkid_version =  blkid_get_library_version(NULL, NULL);
 
-- 
2.52.0

[PATCH v2 2/3] btrfs-progs: misc-tests: check if free space tree is enabled after mount

[Qu Wenruo]

For bs < ps cases, a mount will always enable free-space-tree due to the
limitation of v1 space cache.

Test case misc/057 will lead to false failure if the page size is larger
than the default 4K sector size.

Add an extra check on free-space-tree after fs population, and skip the
test case if so.

Signed-off-by: Qu Wenruo <wqu@suse.com>
---
 tests/misc-tests/057-btrfstune-free-space-tree/test.sh | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/tests/misc-tests/057-btrfstune-free-space-tree/test.sh b/tests/misc-tests/057-btrfstune-free-space-tree/test.sh
index 8d9a858ddc2f..8f6bcb8fc5b7 100755
--- a/tests/misc-tests/057-btrfstune-free-space-tree/test.sh
+++ b/tests/misc-tests/057-btrfstune-free-space-tree/test.sh
@@ -17,6 +17,14 @@ run_check_mount_test_dev
 populate_fs
 run_check_umount_test_dev
 
+# Check if the fs has free space tree already. Currently bs < ps mount
+# will always enable free-space-tree (no support for v1 free space cache)
+if run_check_stdout "$TOP/btrfs" inspect-internal dump-super "$TEST_DEV" |\
+	grep -q "FREE_SPACE_TREE"; then
+	_not_run "free-space-tree is always enabled for page size $(getconf PAGESIZE)"
+fi
+
 run_check $SUDO_HELPER "$TOP/btrfstune" --convert-to-free-space-tree "$TEST_DEV"
 
+
 run_check "$TOP/btrfs" check "$TEST_DEV"
-- 
2.52.0

[PATCH v2 3/3] btrfs-progs: add block-group-tree to the default mkfs features

[Qu Wenruo]

The block-group-tree feature is already considered safe since v6.6
kernels, and btrfs-progs have also improved its off-line conversion
ability (btrfstune --convert-to|from-block-group-tree).

Now it's time to make bgt feature as the default mkfs features.
This affects both mkfs and btrfs-convert.

The target merge window is v6.18.

Signed-off-by: Qu Wenruo <wqu@suse.com>
---
 Documentation/mkfs.btrfs.rst | 2 +-
 common/fsfeatures.c          | 2 +-
 common/fsfeatures.h          | 3 ++-
 3 files changed, 4 insertions(+), 3 deletions(-)

diff --git a/Documentation/mkfs.btrfs.rst b/Documentation/mkfs.btrfs.rst
index 100449675597..fdaf035d8e20 100644
--- a/Documentation/mkfs.btrfs.rst
+++ b/Documentation/mkfs.btrfs.rst
@@ -424,7 +424,7 @@ free-space-tree
 .. _mkfs-feature-block-group-tree:
 
 block-group-tree
-        (kernel support since 6.1)
+        (default since btrfs-progs v6.19, kernel support since 6.1)
 
         Enable a dedicated b-tree for block group items, this greatly reduces
         mount time for large filesystems due to better data locality that
diff --git a/common/fsfeatures.c b/common/fsfeatures.c
index 69a1b3934099..389d19b4d416 100644
--- a/common/fsfeatures.c
+++ b/common/fsfeatures.c
@@ -219,7 +219,7 @@ static const struct btrfs_feature mkfs_features[] = {
 		.sysfs_name	= "block_group_tree",
 		VERSION_TO_STRING2(compat, 6,1),
 		VERSION_TO_STRING2(safe, 6,6),
-		VERSION_NULL(default),
+		VERSION_TO_STRING2(default, 6,19),
 		.desc		= "block group tree, more efficient block group tracking to reduce mount time"
 	},
 #if EXPERIMENTAL
diff --git a/common/fsfeatures.h b/common/fsfeatures.h
index 3559076ba5dc..3ae8d2a5eed7 100644
--- a/common/fsfeatures.h
+++ b/common/fsfeatures.h
@@ -46,7 +46,8 @@ struct btrfs_mkfs_features {
 
 static const struct btrfs_mkfs_features btrfs_mkfs_default_features = {
 	.compat_ro_flags = BTRFS_FEATURE_COMPAT_RO_FREE_SPACE_TREE |
-			   BTRFS_FEATURE_COMPAT_RO_FREE_SPACE_TREE_VALID,
+			   BTRFS_FEATURE_COMPAT_RO_FREE_SPACE_TREE_VALID |
+			   BTRFS_FEATURE_COMPAT_RO_BLOCK_GROUP_TREE,
 	.incompat_flags	 = BTRFS_FEATURE_INCOMPAT_EXTENDED_IREF |
 			   BTRFS_FEATURE_INCOMPAT_NO_HOLES |
 			   BTRFS_FEATURE_INCOMPAT_SKINNY_METADATA,
-- 
2.52.0

Re: [PATCH v2 0/3] btrfs-progs: add block-group-tree to the default mkfs/convert features

[Nicholas D Steeves]

[-- Attachment #1: Type: text/plain, Size: 787 bytes --]

Hi Qu,

Qu Wenruo <wqu@suse.com> writes:

> [CHANGELOG]
> v2:
> - Automatically remove bgt feature when dependent feature is missing
>   Instead of erroring out. This will allow us to run the existing
>   no-holes/v1 free space cache test cases without any modification.
>
> I was planning to do this during v6.12 but forgot it and now the next
> LTS kernel release is not that far away, it's finally time to make the
> switch.
>

Does this also mean that block-group-tree is considered recommended and
production-ready for users of linux-6.12 LTS, or that it will only be
recommended for the next LTS kernel series?

Also, are there any known disadvantages that result from having used
btrfstune compared with a pristine FS created with
mkfs.btrfs -O block-group-tree ?

Best,
Nicholas

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 861 bytes --]

Re: [PATCH v2 0/3] btrfs-progs: add block-group-tree to the default mkfs/convert features

[Qu Wenruo]

在 2025/12/2 11:51, Nicholas D Steeves 写道:
> Hi Qu,
> 
> Qu Wenruo <wqu@suse.com> writes:
> 
>> [CHANGELOG]
>> v2:
>> - Automatically remove bgt feature when dependent feature is missing
>>    Instead of erroring out. This will allow us to run the existing
>>    no-holes/v1 free space cache test cases without any modification.
>>
>> I was planning to do this during v6.12 but forgot it and now the next
>> LTS kernel release is not that far away, it's finally time to make the
>> switch.
>>
> 
> Does this also mean that block-group-tree is considered recommended and
> production-ready for users of linux-6.12 LTS, or that it will only be
> recommended for the next LTS kernel series?

I think 6.12 is already safe enough (the current safe version is 6.6).

> 
> Also, are there any known disadvantages that result from having used
> btrfstune compared with a pristine FS created with
> mkfs.btrfs -O block-group-tree ?

I can only come up with the disadvantage of btrfstune itself, e.g:

- Older bugs in btrfstune that failed to resume interrupted conversion

- Certain ENOSPC bugs if the fs is really full

- Offline conversion

As long as the fs can be safely converted, there should be no difference.

Thanks,
Qu

> 
> Best,
> Nicholas