[PATCH 0/2] btrfs: add free space tree checks except for FREE_SPACE_BITMAP

[PATCH 0/2] btrfs: add free space tree checks except for FREE_SPACE_BITMAP

[Qu Wenruo]

There is a fuzzed image report (*) that a bad item size for
FREE_SPACE_BITMAP item can lead to various problems.

And I'm surprised that we do not have any checks for such critical tree,
so let's add the proper checks for FREE_SPACE_INFO and
FREE_SPACE_EXTENT items

The check for FREE_SPACE_BITMAP item is reserved for the reporter, whose
initial fix is not properly put into tree-checker, and also as an
example for the reporter to follow.

Qu Wenruo (2):
  btrfs: tree-checker: introduce checks for FREE_SPACE_INFO
  btrfs: tree-checker: introduce checks for FREE_SPACE_EXTENT

 fs/btrfs/tree-checker.c         | 70 +++++++++++++++++++++++++++++++++
 include/uapi/linux/btrfs_tree.h |  3 +-
 2 files changed, 72 insertions(+), 1 deletion(-)

-- 
2.53.0

[PATCH 1/2] btrfs: tree-checker: introduce checks for FREE_SPACE_INFO

[Qu Wenruo]

Introduce checks for FREE_SPACE_INFO item, which include:

- Key alignment check
  The objectid is the logical bytenr of the chunk/bg, and offset is the
  length of the chunk/bg, thus they should all be aligned to the fs
  block size.

- Item size check
  The FREE_SPACE_INFO should a fix size.

- Flags check
  The flags member should has no other flags than
  BTRFS_FREE_SPACE_USING_BITMAPS.

  For future expansion, introduce a new macro
  BTRFS_FREE_SPACE_FLAGS_MASK for such checks.

  And since we're here, the BTRFS_FREE_SPACE_USING_BITMAPS should not
  use unsigned long long, as the flags is only 32 bits wide.
  So fix that to use unsigned long.

- Extent count check
  That member shows how many free space bitmap/extent items there are
  inside the chunk/bg.

  And we know the chunk size (from key->offset), thus there should be at
  most (key->offset >> sectorsize_bits) blocks inside the chunk.
  Use that value as the upper limit and if that counter is larger than
  that, there is a high chance it's a bitflip in high bits.

Signed-off-by: Qu Wenruo <wqu@suse.com>
---
 fs/btrfs/tree-checker.c         | 45 +++++++++++++++++++++++++++++++++
 include/uapi/linux/btrfs_tree.h |  3 ++-
 2 files changed, 47 insertions(+), 1 deletion(-)

diff --git a/fs/btrfs/tree-checker.c b/fs/btrfs/tree-checker.c
index ac4c4573ee39..980e4d52061f 100644
--- a/fs/btrfs/tree-checker.c
+++ b/fs/btrfs/tree-checker.c
@@ -1928,6 +1928,48 @@ static int check_dev_extent_item(const struct extent_buffer *leaf,
 	return 0;
 }
 
+static int check_free_space_info(struct extent_buffer *leaf, struct btrfs_key *key,
+				 int slot)
+{
+	struct btrfs_fs_info *fs_info = leaf->fs_info;
+	struct btrfs_free_space_info *fsi;
+	const u32 blocksize = fs_info->sectorsize;
+	u32 flags;
+
+	if (unlikely(!IS_ALIGNED(key->objectid, blocksize) ||
+		     !IS_ALIGNED(key->offset, blocksize))) {
+		generic_err(leaf, slot,
+		"free space info key range is not aligned to %u, has (%llu %u %llu)",
+			    blocksize, key->objectid, key->type, key->offset);
+		return -EUCLEAN;
+	}
+	if (unlikely(btrfs_item_size(leaf, slot) !=
+		     sizeof(struct btrfs_free_space_info))) {
+		generic_err(leaf, slot,
+		"invalid item size for free space info, has %u expect %zu",
+			    btrfs_item_size(leaf, slot),
+			    sizeof(struct btrfs_free_space_info));
+		return -EUCLEAN;
+	}
+	fsi = btrfs_item_ptr(leaf, slot, struct btrfs_free_space_info);
+	flags = btrfs_free_space_flags(leaf, fsi);
+	if (unlikely(flags & ~BTRFS_FREE_SPACE_FLAGS_MASK)) {
+		generic_err(leaf, slot,
+		"unknown flags for free space info, has 0x%x valid mask 0x%lx",
+			    flags, BTRFS_FREE_SPACE_FLAGS_MASK);
+		return -EUCLEAN;
+	}
+	if (unlikely(btrfs_free_space_extent_count(leaf, fsi) >
+		     key->offset >> fs_info->sectorsize_bits)) {
+		generic_err(leaf, slot,
+		"suspicious extent count, has %u max valid %llu",
+			    btrfs_free_space_extent_count(leaf, fsi),
+			    key->offset >> fs_info->sectorsize_bits);
+		return -EUCLEAN;
+	}
+	return 0;
+}
+
 /*
  * Common point to switch the item-specific validation.
  */
@@ -1991,6 +2033,9 @@ static enum btrfs_tree_block_status check_leaf_item(struct extent_buffer *leaf,
 	case BTRFS_RAID_STRIPE_KEY:
 		ret = check_raid_stripe_extent(leaf, key, slot);
 		break;
+	case BTRFS_FREE_SPACE_INFO_KEY:
+		ret = check_free_space_info(leaf, key, slot);
+		break;
 	}
 
 	if (unlikely(ret))
diff --git a/include/uapi/linux/btrfs_tree.h b/include/uapi/linux/btrfs_tree.h
index f7843e6bb978..cf0c95140299 100644
--- a/include/uapi/linux/btrfs_tree.h
+++ b/include/uapi/linux/btrfs_tree.h
@@ -1245,7 +1245,8 @@ struct btrfs_free_space_info {
 	__le32 flags;
 } __attribute__ ((__packed__));
 
-#define BTRFS_FREE_SPACE_USING_BITMAPS (1ULL << 0)
+#define BTRFS_FREE_SPACE_USING_BITMAPS (1UL << 0)
+#define BTRFS_FREE_SPACE_FLAGS_MASK	(BTRFS_FREE_SPACE_USING_BITMAPS)
 
 #define BTRFS_QGROUP_LEVEL_SHIFT		48
 static inline __u16 btrfs_qgroup_level(__u64 qgroupid)
-- 
2.53.0

[PATCH 2/2] btrfs: tree-checker: introduce checks for FREE_SPACE_EXTENT

[Qu Wenruo]

Introduce FREE_SPACE_EXTENT checks, which include:

- The key alignment check
  The objectid is the logical bytenr of the free space, and offset is the
  length of the free space, thus they should all be aligned to the fs
  block size.

- The item size check
  The FREE_SPACE_EXTENT item has zero size.

Signed-off-by: Qu Wenruo <wqu@suse.com>
---
 fs/btrfs/tree-checker.c | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/fs/btrfs/tree-checker.c b/fs/btrfs/tree-checker.c
index 980e4d52061f..15810902c813 100644
--- a/fs/btrfs/tree-checker.c
+++ b/fs/btrfs/tree-checker.c
@@ -1970,6 +1970,28 @@ static int check_free_space_info(struct extent_buffer *leaf, struct btrfs_key *k
 	return 0;
 }
 
+static int check_free_space_extent(struct extent_buffer *leaf, struct btrfs_key *key,
+				   int slot)
+{
+	struct btrfs_fs_info *fs_info = leaf->fs_info;
+	const u32 blocksize = fs_info->sectorsize;
+
+	if (unlikely(!IS_ALIGNED(key->objectid, blocksize) ||
+		     !IS_ALIGNED(key->offset, blocksize))) {
+		generic_err(leaf, slot,
+		"free space extent key range is not aligned to %u, has (%llu %u %llu)",
+			    blocksize, key->objectid, key->type, key->offset);
+		return -EUCLEAN;
+	}
+	if (unlikely(btrfs_item_size(leaf, slot) != 0)) {
+		generic_err(leaf, slot,
+		"invalid item size for free space info, has %u expect 0",
+			    btrfs_item_size(leaf, slot));
+		return -EUCLEAN;
+	}
+	return 0;
+}
+
 /*
  * Common point to switch the item-specific validation.
  */
@@ -2036,6 +2058,9 @@ static enum btrfs_tree_block_status check_leaf_item(struct extent_buffer *leaf,
 	case BTRFS_FREE_SPACE_INFO_KEY:
 		ret = check_free_space_info(leaf, key, slot);
 		break;
+	case BTRFS_FREE_SPACE_EXTENT_KEY:
+		ret = check_free_space_extent(leaf, key, slot);
+		break;
 	}
 
 	if (unlikely(ret))
-- 
2.53.0

Re: [PATCH 1/2] btrfs: tree-checker: introduce checks for FREE_SPACE_INFO

[Johannes Thumshirn]

On 3/9/26 11:20 PM, Qu Wenruo wrote:
> Introduce checks for FREE_SPACE_INFO item, which include:
>
> - Key alignment check
>    The objectid is the logical bytenr of the chunk/bg, and offset is the
>    length of the chunk/bg, thus they should all be aligned to the fs
>    block size.
>
> - Item size check
>    The FREE_SPACE_INFO should a fix size.
                                       have ~^
>
> - Flags check
>    The flags member should has no other flags than

s/has/have/

[...]

> +static int check_free_space_info(struct extent_buffer *leaf, struct btrfs_key *key,
> +				 int slot)
> +{
> +	struct btrfs_fs_info *fs_info = leaf->fs_info;
> +	struct btrfs_free_space_info *fsi;
> +	const u32 blocksize = fs_info->sectorsize;
> +	u32 flags;
> +
> +	if (unlikely(!IS_ALIGNED(key->objectid, blocksize) ||
> +		     !IS_ALIGNED(key->offset, blocksize))) {
> +		generic_err(leaf, slot,
> +		"free space info key range is not aligned to %u, has (%llu %u %llu)",
> +			    blocksize, key->objectid, key->type, key->offset);
> +		return -EUCLEAN;
> +	}


I'd split that into two if()s, one for the objectid one for the offset. 
That'll help figuring out which of these two is unaligned without doing 
the math again on a possible bug report.

Thanks,

     Johannes

Re: [PATCH 2/2] btrfs: tree-checker: introduce checks for FREE_SPACE_EXTENT

[Johannes Thumshirn]

On 3/9/26 11:20 PM, Qu Wenruo wrote:
[...]
>   to the fs
>    block size.
>
> - The item size check
>    The FREE_SPACE_EXTENT item has zero size.

Perhaps: The FREE_SPACE_EXTENT item has a size of zero?

[...]
> +	if (unlikely(!IS_ALIGNED(key->objectid, blocksize) ||
> +		     !IS_ALIGNED(key->offset, blocksize))) {
> +		generic_err(leaf, slot,
> +		"free space extent key range is not aligned to %u, has (%llu %u %llu)",
> +			    blocksize, key->objectid, key->type, key->offset);
> +		return -EUCLEAN;
> +	}
> +
Again I'd do 2 separate if()s to have better error reporting.

Re: [PATCH 0/2] btrfs: add free space tree checks except for FREE_SPACE_BITMAP

[Johannes Thumshirn]

Apart from small nitpicks:

Reviewed-by: Johannes Thumshirn <johannes.thumshirn@wdc.com>

Re: [PATCH 1/2] btrfs: tree-checker: introduce checks for FREE_SPACE_INFO

[David Sterba]

On Tue, Mar 10, 2026 at 08:49:25AM +1030, Qu Wenruo wrote:
> Introduce checks for FREE_SPACE_INFO item, which include:
> 
> - Key alignment check
>   The objectid is the logical bytenr of the chunk/bg, and offset is the
>   length of the chunk/bg, thus they should all be aligned to the fs
>   block size.
> 
> - Item size check
>   The FREE_SPACE_INFO should a fix size.
> 
> - Flags check
>   The flags member should has no other flags than
>   BTRFS_FREE_SPACE_USING_BITMAPS.
> 
>   For future expansion, introduce a new macro
>   BTRFS_FREE_SPACE_FLAGS_MASK for such checks.
> 
>   And since we're here, the BTRFS_FREE_SPACE_USING_BITMAPS should not
>   use unsigned long long, as the flags is only 32 bits wide.
>   So fix that to use unsigned long.
> 
> - Extent count check
>   That member shows how many free space bitmap/extent items there are
>   inside the chunk/bg.
> 
>   And we know the chunk size (from key->offset), thus there should be at
>   most (key->offset >> sectorsize_bits) blocks inside the chunk.
>   Use that value as the upper limit and if that counter is larger than
>   that, there is a high chance it's a bitflip in high bits.
> 
> Signed-off-by: Qu Wenruo <wqu@suse.com>
> ---
>  fs/btrfs/tree-checker.c         | 45 +++++++++++++++++++++++++++++++++
>  include/uapi/linux/btrfs_tree.h |  3 ++-
>  2 files changed, 47 insertions(+), 1 deletion(-)
> 
> diff --git a/fs/btrfs/tree-checker.c b/fs/btrfs/tree-checker.c
> index ac4c4573ee39..980e4d52061f 100644
> --- a/fs/btrfs/tree-checker.c
> +++ b/fs/btrfs/tree-checker.c
> @@ -1928,6 +1928,48 @@ static int check_dev_extent_item(const struct extent_buffer *leaf,
>  	return 0;
>  }
>  
> +static int check_free_space_info(struct extent_buffer *leaf, struct btrfs_key *key,
> +				 int slot)
> +{
> +	struct btrfs_fs_info *fs_info = leaf->fs_info;
> +	struct btrfs_free_space_info *fsi;
> +	const u32 blocksize = fs_info->sectorsize;
> +	u32 flags;
> +
> +	if (unlikely(!IS_ALIGNED(key->objectid, blocksize) ||
> +		     !IS_ALIGNED(key->offset, blocksize))) {
> +		generic_err(leaf, slot,
> +		"free space info key range is not aligned to %u, has (%llu %u %llu)",

Please use the BTRFS_KEY_FMT macro for key specifier, I'll fix it in
git, thanks.