Skip to contentSkip to conversation

btrfs-progs: add block-group-tree to the default mkfs/convert features

PATCH In review Qu Wenruo 3 participants 6 messages Nov 27, 2025 – Dec 2, 2025

Subsystems (2)
lore
Share & tools
lore

Qu Wenruo

author
#0 lore raw

v2 cover btrfs-progs: add block-group-tree to the default mkfs/convert features

[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

author
#1 lore raw

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

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

...

---
 Documentation/mkfs.btrfs.rst |  5 +++++
 convert/main.c               |  4 ++--
 mkfs/main.c                  | 10 +++++++---
 3 files changed, 14 insertions(+), 5 deletions(-)
Documentation/mkfs.btrfs.rst +5 -0
index 7734354fd6da..100449675597 100644
@@ -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
convert/main.c +2 -2
index 190f38a11924..116867fc9eff 100644
@@ -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) {
mkfs/main.c +7 -3
index f99e5486521d..cf77e192045b 100644
@@ -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);
 
Signature · 1 line
2.52.0
author
#2 lore raw

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

In reply to 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.

---
 tests/misc-tests/057-btrfstune-free-space-tree/test.sh | 8 ++++++++
 1 file changed, 8 insertions(+)
tests/misc-tests/057-btrfstune-free-space-tree/test.sh +8 -0
index 8d9a858ddc2f..8f6bcb8fc5b7 100755
@@ -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"
Signature · 1 line
2.52.0
author
#3 lore raw

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

In reply to 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.

---
 Documentation/mkfs.btrfs.rst | 2 +-
 common/fsfeatures.c          | 2 +-
 common/fsfeatures.h          | 3 ++-
 3 files changed, 4 insertions(+), 3 deletions(-)
Documentation/mkfs.btrfs.rst +1 -1
index 100449675597..fdaf035d8e20 100644
@@ -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
common/fsfeatures.c +1 -1
index 69a1b3934099..389d19b4d416 100644
@@ -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
common/fsfeatures.h +2 -1
index 3559076ba5dc..3ae8d2a5eed7 100644
@@ -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,
Signature · 1 line
2.52.0
#4 lore raw
In reply to Qu Wenruo

Hi Qu,

Quoted 10 lines · 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.

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

#5 lore raw
Quoted 10 lines · Nicholas D Steeves

Hi Qu,

Quoted 6 lines · 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.

Quoted 8 lines
Quoted 4 lines

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).

Quoted 4 lines

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

Quoted 3 lines

Best,
Nicholas