Skip to contentSkip to conversation

btrfs-progs: allowing 2K block size for experimental builds

PATCH In review Qu Wenruo 2 participants 8 messages Feb 26, 2025 – Mar 19, 2025

Subsystems (2)
lore
Share & tools
lore

Qu Wenruo

author
#0 lore raw

cover btrfs-progs: allowing 2K block size for experimental builds

Btrfs always has its minimal block size as 4K, but that means on the most common architecture, x86_64, we can not utilize the subpage block size routine at all.

Although the future larger folios support will allow us to utilize subpage routines, the support is still not yet there.

On the other hand, lowering the block size for experimental/debug builds is much easier, there is only one major bug (fixed by the first patch) in btrfs-progs at least.

Kernel sides enablement is not huge either, but it has dependency on the subpage related backlog patches to pass most fstests, which is not small.

However since we're not pushing this 2K block size for end users, we can accept some limitations on the 2K block size support:

- No 2K node size mkfs support
This is mostly caused by how we create the initial temporaray fs. The initial temporaray fs contains at least 6 root items. But one root item is 439 bytes, we need a level 1 root tree for the initial temporaray fs.

But we do not support multi-level trees for the initial fs, thus no such support for now.

- No mixed block groups mkfs support
Caused by the missing 2K node size support

Qu Wenruo (3):
btrfs-progs: fix the incorrect buffer size for super block
btrfs-progs: support 2k block size
btrfs-progs: convert: check the sectorsize against BTRFS_MIN_BLOCKSIZE

 common/device-scan.c    |  2 +-
 common/fsfeatures.c     | 11 ++++++++---
 convert/main.c          |  2 +-
 kernel-shared/ctree.h   |  6 ++++++
 kernel-shared/disk-io.c | 11 ++++-------
 mkfs/main.c             |  7 -------
 6 files changed, 20 insertions(+), 19 deletions(-)

--
2.48.1

author
#1 lore raw

PATCH 1/1 btrfs-progs: docs: add an extra note to btrfs data checksum and directIO

In v6.14 kernel release, btrfs will force a direct IO to fall back to a buffered one if the inode requires a data checksum.

This will cause a small performance drop, to solve the false data checksum mismatch problem caused by direct IOs.

Although such a change is small to most end users, for those requiring such a zero-copy direct IO this will be a behavior change, and this requires a proper documentation update.

---
 Documentation/ch-checksumming.rst | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)
Documentation/ch-checksumming.rst +18 -0
index 5e47a6bfb492..b7fde46fe902 100644
@@ -3,6 +3,24 @@ writing and verified after reading the blocks from devices. The whole metadata
 block has an inline checksum stored in the b-tree node header. Each data block
 has a detached checksum stored in the checksum tree.
 
+.. note::
+   Since a data checksum is calculated just before submitting to the block
+   device, btrfs has a strong requirement that the coresponding data block must
+   not be modified until the writeback is finished.
+
+   This requirement is met for a buffered write as btrfs has the full control on
+   its page caches, but a direct write (``O_DIRECT``) bypasses page caches, and
+   btrfs can not control the direct IO buffer (as it can be in user space memory),
+   thus it's possible that a user space program modifies its direct write buffer
+   before the buffer is fully written back, and this can lead to a data checksum mismatch.
+
+   To avoid such a checksum mismatch, since v6.14 btrfs will force a direct
+   write to fall back to a buffered one, if the inode requires a data checksum.
+   This will bring a small performance penalty, and if the end user requires true
+   zero-copy direct writes, they should set the ``NODATASUM`` flag for the inode
+   and make sure the direct IO buffer is fully aligned to btrfs block size.
+
+
 There are several checksum algorithms supported. The default and backward
 compatible algorithm is *crc32c*. Since kernel 5.5 there are three more with different
 characteristics and trade-offs regarding speed and strength. The following list
Signature · 1 line
2.48.1
author
#2 lore raw

PATCH 1/3 btrfs-progs: fix the incorrect buffer size for super block

In reply to Qu Wenruo

Inside the function btrfs_add_to_fsid(), we allocate a buffer to write the superblock to the disk.

However the buffer size is based on block size, which can cause two problems:

- 2K block size
The block size is too small for the super block, and we will write beyond the buffer and corrupt the memory.

- 16/64K block size
The block size will be larger than super block size, this will not cause any problem but waste some memory.

Fix the bug by using BTRFS_SUPER_INFO_SIZE as the correct buffer size.

---
 common/device-scan.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
common/device-scan.c +1 -1
index a34d86652f06..7d7d67fb5b71 100644
@@ -148,7 +148,7 @@ int btrfs_add_to_fsid(struct btrfs_trans_handle *trans,
 	if (!device)
 		return -ENOMEM;
 
-	buf = calloc(1, sectorsize);
+	buf = calloc(1, BTRFS_SUPER_INFO_SIZE);
 	if (!buf) {
 		ret = -ENOMEM;
 		goto out;
Signature · 1 line
2.48.1
author
#3 lore raw

PATCH 2/3 btrfs-progs: support 2k block size

In reply to Qu Wenruo

Since btrfs only supports block size 4K and PAGE_SIZE, on x86_64 it means we can not test subpage block size easily.

With the recent kernel change to support 2K block size for debug builds, also add 2K block size support for btrfs-progs, so that we can do proper subpage block size testing on x86_64, without acquiring an aarch64 machine.

There is a limit:

- No support for 2K node size
The limit is from the initial mkfs tree root, which can only have a single leaf to contain all root items.
But 2K leaf can not handle all the root items, thus we have to disable it.

---
 common/fsfeatures.c     | 11 ++++++++---
 kernel-shared/ctree.h   |  6 ++++++
 kernel-shared/disk-io.c | 11 ++++-------
 mkfs/main.c             |  7 -------
 4 files changed, 18 insertions(+), 17 deletions(-)
common/fsfeatures.c +8 -3
index 7aaddab6a192..398065dbea86 100644
@@ -628,7 +628,8 @@ int btrfs_check_sectorsize(u32 sectorsize)
 		error("invalid sectorsize %u, must be power of 2", sectorsize);
 		return -EINVAL;
 	}
-	if (sectorsize < SZ_4K || sectorsize > SZ_64K) {
+	if (sectorsize < BTRFS_MIN_BLOCKSIZE ||
+	    sectorsize > BTRFS_MAX_METADATA_BLOCKSIZE) {
 		error("invalid sectorsize %u, expected range is [4K, 64K]",
 		      sectorsize);
 		return -EINVAL;
@@ -650,9 +651,13 @@ int btrfs_check_sectorsize(u32 sectorsize)
 int btrfs_check_nodesize(u32 nodesize, u32 sectorsize,
 			 struct btrfs_mkfs_features *features)
 {
-	if (nodesize < sectorsize) {
+	if (nodesize < sectorsize || nodesize < SZ_4K) {
+		/*
+		 * Although we support 2K block size, we can not support 2K
+		 * nodesize, as it's too small to contain all the needed root items.
+		 */
 		error("illegal nodesize %u (smaller than %u)",
-				nodesize, sectorsize);
+		      nodesize, max_t(u32, sectorsize, SZ_4K));
 		return -1;
 	} else if (nodesize > BTRFS_MAX_METADATA_BLOCKSIZE) {
 		error("illegal nodesize %u (larger than %u)",
kernel-shared/ctree.h +6 -0
index 8c923be96705..c3d66c99c78d 100644
@@ -63,6 +63,12 @@ static inline u32 __BTRFS_LEAF_DATA_SIZE(u32 nodesize)
 	return nodesize - sizeof(struct btrfs_header);
 }
 
+#if EXPERIMENTAL
+#define BTRFS_MIN_BLOCKSIZE	(SZ_2K)
+#else
+#define BTRFS_MIN_BLOCKSIZE	(SZ_4K)
+#endif
+
 #define BTRFS_LEAF_DATA_SIZE(fs_info) (fs_info->leaf_data_size)
 
 #define BTRFS_SUPER_INFO_OFFSET			(65536)
kernel-shared/disk-io.c +4 -7
index a4f91d10fa4e..b7d478007ae8 100644
@@ -1816,13 +1816,10 @@ int btrfs_check_super(struct btrfs_super_block *sb, unsigned sbflags)
 		error("nodesize unaligned: %u", btrfs_super_nodesize(sb));
 		goto error_out;
 	}
-	if (btrfs_super_sectorsize(sb) < 4096) {
-		error("sectorsize too small: %u < 4096",
-			btrfs_super_sectorsize(sb));
-		goto error_out;
-	}
-	if (!IS_ALIGNED(btrfs_super_sectorsize(sb), 4096)) {
-		error("sectorsize unaligned: %u", btrfs_super_sectorsize(sb));
+	if (!is_power_of_2(btrfs_super_sectorsize(sb)) ||
+	    btrfs_super_sectorsize(sb) < BTRFS_MIN_BLOCKSIZE ||
+	    btrfs_super_sectorsize(sb) > BTRFS_MAX_METADATA_BLOCKSIZE) {
+		error("invalid sectorsize: %u", btrfs_super_sectorsize(sb));
 		goto error_out;
 	}
 	if (btrfs_super_total_bytes(sb) == 0) {
mkfs/main.c +0 -7
index dc73de47a710..c7968540e8af 100644
@@ -1669,13 +1669,6 @@ int BOX_MAIN(mkfs)(int argc, char **argv)
 	if (nodesize > sysconf(_SC_PAGE_SIZE))
 		features.incompat_flags |= BTRFS_FEATURE_INCOMPAT_BIG_METADATA;
 
-	if (sectorsize < sizeof(struct btrfs_super_block)) {
-		error("sectorsize smaller than superblock: %u < %zu",
-				sectorsize, sizeof(struct btrfs_super_block));
-		ret = 1;
-		goto error;
-	}
-
 	min_dev_size = btrfs_min_dev_size(nodesize, mixed,
 					  opt_zoned ? zone_size(file) : 0,
 					  metadata_profile, data_profile);
Signature · 1 line
2.48.1
author
#4 lore raw

PATCH 3/3 btrfs-progs: convert: check the sectorsize against BTRFS_MIN_BLOCKSIZE

In reply to Qu Wenruo

This allow experimental btrfs-convert builds to handle 2K block sized ext4, which is needed to pass convert related test cases in fstests.

---
 convert/main.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
convert/main.c +1 -1
index edc2c0d97c29..0dc75c9eb1c6 100644
@@ -1201,7 +1201,7 @@ static int do_convert(const char *devname, u32 convert_flags, u32 nodesize,
 
 	UASSERT(cctx.total_bytes != 0);
 	blocksize = cctx.blocksize;
-	if (blocksize < 4096) {
+	if (blocksize < BTRFS_MIN_BLOCKSIZE) {
 		error("block size is too small: %u < 4096", blocksize);
 		goto fail;
 	}
Signature · 1 line
2.48.1
#5 lore raw
In reply to Qu Wenruo
Quoted 26 lines · Qu Wenruo

Btrfs always has its minimal block size as 4K, but that means on the most common architecture, x86_64, we can not utilize the subpage block size routine at all.

Although the future larger folios support will allow us to utilize subpage routines, the support is still not yet there.

On the other hand, lowering the block size for experimental/debug builds is much easier, there is only one major bug (fixed by the first patch) in btrfs-progs at least.

Kernel sides enablement is not huge either, but it has dependency on the subpage related backlog patches to pass most fstests, which is not small.

However since we're not pushing this 2K block size for end users, we can accept some limitations on the 2K block size support:

- No 2K node size mkfs support
This is mostly caused by how we create the initial temporaray fs. The initial temporaray fs contains at least 6 root items. But one root item is 439 bytes, we need a level 1 root tree for the initial temporaray fs.

But we do not support multi-level trees for the initial fs, thus no such support for now.

Quoted 7 lines

- No mixed block groups mkfs support
Caused by the missing 2K node size support

Qu Wenruo (3):
btrfs-progs: fix the incorrect buffer size for super block
btrfs-progs: support 2k block size
btrfs-progs: convert: check the sectorsize against BTRFS_MIN_BLOCKSIZE

Thanks, added to devel. I've enabled the 2k case for convert but it fails, I haven't analyzed it as it does not seem to be important right now.

author
#6 lore raw
Quoted 30 lines · David Sterba
Quoted 29 lines · Qu Wenruo

Btrfs always has its minimal block size as 4K, but that means on the most common architecture, x86_64, we can not utilize the subpage block size routine at all.

Although the future larger folios support will allow us to utilize subpage routines, the support is still not yet there.

On the other hand, lowering the block size for experimental/debug builds is much easier, there is only one major bug (fixed by the first patch) in btrfs-progs at least.

Kernel sides enablement is not huge either, but it has dependency on the subpage related backlog patches to pass most fstests, which is not small.

However since we're not pushing this 2K block size for end users, we can accept some limitations on the 2K block size support:

- No 2K node size mkfs support
This is mostly caused by how we create the initial temporaray fs. The initial temporaray fs contains at least 6 root items. But one root item is 439 bytes, we need a level 1 root tree for the initial temporaray fs.

But we do not support multi-level trees for the initial fs, thus no such support for now.

- No mixed block groups mkfs support
Caused by the missing 2K node size support

Quoted 8 lines
Quoted 4 lines

Qu Wenruo (3):
btrfs-progs: fix the incorrect buffer size for super block
btrfs-progs: support 2k block size
btrfs-progs: convert: check the sectorsize against BTRFS_MIN_BLOCKSIZE

Thanks, added to devel. I've enabled the 2k case for convert but it fails, I haven't analyzed it as it does not seem to be important right now.

2K convert needs the ext4 to use 2K block size too, which is only lightly tested here.

E.g. at least it works here:

./btrfs-convert ~/test.img
btrfs-convert from btrfs-progs v6.12

WARNING: blocksize 2048 is not equal to the page size 4096, converted filesystem won't mount on this system Source filesystem:
Type: ext2
Label:
Blocksize: 2048
UUID: e004c54c-7a86-4c71-be87-a8ff707c3948
Target filesystem:
Label:

  Blocksize:      2048
  Nodesize:       16384
  UUID:           b54b8947-7f7a-4e3b-a658-d344a1d47766
  Checksum:       crc32c
  Features:       extref, skinny-metadata, no-holes, free-space-tree 
(default)
    Data csum:    yes
    Inline data:  yes
    Copy xattr:   yes

Reported stats:
Total space: 5368709120
Free space: 4693164032 (87.42%)
Inode count: 327680
Free inodes: 327668
Block count: 2621440
Create initial btrfs filesystem
Create ext2 image file
Create btrfs metadata
Copy inodes [o] [ 0/ 12]
Free space cache cleared
Conversion complete

But it should not be considered a feature for end users.

Thanks,
Qu

#7 lore raw
Quoted 38 lines · Qu Wenruo
Quoted 35 lines · David Sterba
Quoted 33 lines · Qu Wenruo

Btrfs always has its minimal block size as 4K, but that means on the most common architecture, x86_64, we can not utilize the subpage block size routine at all.

Although the future larger folios support will allow us to utilize subpage routines, the support is still not yet there.

On the other hand, lowering the block size for experimental/debug builds is much easier, there is only one major bug (fixed by the first patch) in btrfs-progs at least.

Kernel sides enablement is not huge either, but it has dependency on the subpage related backlog patches to pass most fstests, which is not small.

However since we're not pushing this 2K block size for end users, we can accept some limitations on the 2K block size support:

- No 2K node size mkfs support
This is mostly caused by how we create the initial temporaray fs. The initial temporaray fs contains at least 6 root items. But one root item is 439 bytes, we need a level 1 root tree for the initial temporaray fs.

But we do not support multi-level trees for the initial fs, thus no such support for now.

- No mixed block groups mkfs support
Caused by the missing 2K node size support

Qu Wenruo (3):
btrfs-progs: fix the incorrect buffer size for super block
btrfs-progs: support 2k block size
btrfs-progs: convert: check the sectorsize against BTRFS_MIN_BLOCKSIZE

Quoted 6 lines
Quoted 3 lines

Thanks, added to devel. I've enabled the 2k case for convert but it fails, I haven't analyzed it as it does not seem to be important right now.

2K convert needs the ext4 to use 2K block size too, which is only lightly tested here.

So the failure I was observing was because I extended ext2 test (001), ext4 works.

Quoted 29 lines

E.g. at least it works here:

./btrfs-convert ~/test.img
btrfs-convert from btrfs-progs v6.12

WARNING: blocksize 2048 is not equal to the page size 4096, converted filesystem won't mount on this system
Source filesystem:

   Type:           ext2
   Label:
   Blocksize:      2048
   UUID:           e004c54c-7a86-4c71-be87-a8ff707c3948
Target filesystem:
   Label:
   Blocksize:      2048
   Nodesize:       16384
   UUID:           b54b8947-7f7a-4e3b-a658-d344a1d47766
   Checksum:       crc32c
   Features:       extref, skinny-metadata, no-holes, free-space-tree 
(default)
     Data csum:    yes
     Inline data:  yes
     Copy xattr:   yes
Reported stats:
   Total space:      5368709120
   Free space:       4693164032 (87.42%)
   Inode count:          327680
   Free inodes:          327668
   Block count:         2621440
Quoted 8 lines

Create initial btrfs filesystem
Create ext2 image file
Create btrfs metadata
Copy inodes [o] [ 0/ 12]
Free space cache cleared
Conversion complete

But it should not be considered a feature for end users.

Agreed.