[PATCH v3 0/3] btrfs: zoned fix two long standing ENOSPC bugs

[PATCH v3 0/3] btrfs: zoned fix two long standing ENOSPC bugs

[Johannes Thumshirn]

This series fixes two long standing bugs with zoned BTRFS leading to
premature ENOSPC.

Patch 1 caps the amount of metadata reservations to not let
`bytes_may_use + bytes_zone_available` climb beyond a space_info's
capacity.

Patch 2 moves a block-group to the reclaim list, if it cannot be deleted
in btrfs_delete_unused_bgs() because there's still user data left.

Patch 3 adds a new zoned only state to the flush machinery performing
reclaim of block-groups that can be reclaimed.


For all these patches a single reproducer was used (and it can be turned
into a fstest):

```
#!/bin/sh

SCRATCH_DEV="/dev/vdb"
SCRATCH_MNT="/tmp/scratch"
MOUNT_OPTIONS="-o enospc_debug"

mkdir -p $SCRATCH_MNT
mkfs.btrfs -f $SCRATCH_DEV
mount $MOUNT_OPTIONS $SCRATCH_DEV $SCRATCH_MNT

blocks="$(df -TB 1G $SCRATCH_DEV | awk '/btrfs/ { print $3}')"

loops=$(echo "$blocks * 4 - 2" | bc)

for (( i = 0; i < $loops; i++)); do
	dd if=/dev/zero of=$SCRATCH_MNT/test bs=1M count=1024 > /dev/null
	if [ $? -ne 0 ]; then
		break
	fi
done

umount $SCRATCH_DEV
btrfs check $SCRATCH_DEV
```

Changes to v2:
- Refine locking in 1/3
- Add Filipe's R-b to 2/3 and 3/3

Link to v2:
https://lore.kernel.org/linux-btrfs/20260210073309.195274-1-johannes.thumshirn@wdc.com/

Changes to v1:
- Don't pass block_rsv to btrfs_zoned_cap_metadata_reservation()
- Hold space_info->lock in btrfs_zoned_cap_metadata_reservation()
- Don't divide by 2 but use '>> 1'
- ASSERT() the -EAGAIN return of btrfs_delayed_refs_rsv_refill() only happens on zoned
- Call btrfs_mark_bg_to_reclaim() after unlocking
- Fix comment in 2/3
- Add description of RECLAIM_ZONES flush state
- Reflow 'ret' assignment in RECLAIM_ZONES flush state

Link to v1:
https://lore.kernel.org/linux-btrfs/20260209143644.96411-1-johannes.thumshirn@wdc.com/


Johannes Thumshirn (3):
  btrfs: zoned: cap delayed refs metadata reservation to avoid
    overcommit
  btrfs: zoned: move partially zone_unusable block groups to reclaim
    list
  btrfs: zoned: add zone reclaim flush state for DATA space_info

 fs/btrfs/block-group.c | 18 ++++++++++++++++++
 fs/btrfs/delayed-ref.c | 28 ++++++++++++++++++++++++++++
 fs/btrfs/space-info.c  | 22 ++++++++++++++++++++++
 fs/btrfs/space-info.h  |  1 +
 fs/btrfs/transaction.c |  8 ++++++++
 5 files changed, 77 insertions(+)

-- 
2.53.0

[PATCH v3 1/3] btrfs: zoned: cap delayed refs metadata reservation to avoid overcommit

[Johannes Thumshirn]

On zoned filesystems metadata space accounting can become overly optimistic
due to delayed refs reservations growing without a hard upper bound.

The delayed_refs_rsv block reservation is allowed to speculatively grow and
is only backed by actual metadata space when refilled. On zoned devices this
can result in delayed_refs_rsv reserving a large portion of metadata space
that is already effectively unusable due to zone write pointer constraints.
As a result, space_info->may_use can grow far beyond the usable metadata
capacity, causing the allocator to believe space is available when it is not.

This leads to premature ENOSPC failures and "cannot satisfy tickets" reports
even though commits would be able to make progress by flushing delayed refs.

Analysis of "-o enospc_debug" dumps using a Python debug script
confirmed that delayed_refs_rsv was responsible for the majority of
metadata overcommit on zoned devices. By correlating space_info counters
(total, used, may_use, zone_unusable) across transactions, the analysis
showed that may_use continued to grow even after usable metadata space
was exhausted, with delayed refs refills accounting for the excess
reservations.

Here's the output of the analysis:

  ======================================================================
  Space Type: METADATA
  ======================================================================

  Raw Values:
    Total:                256.00 MB (268435456 bytes)
    Used:                 128.00 KB (131072 bytes)
    Pinned:                16.00 KB (16384 bytes)
    Reserved:             144.00 KB (147456 bytes)
    May Use:              255.48 MB (267894784 bytes)
    Zone Unusable:        192.00 KB (196608 bytes)

  Calculated Metrics:
    Actually Usable:       255.81 MB (total - zone_unusable)
    Committed:             255.77 MB (used + pinned + reserved + may_use)
    Consumed:              320.00 KB (used + zone_unusable)

  Percentages:
    Zone Unusable:    0.07% of total
    May Use:         99.80% of total

Fix this by adding a zoned-specific cap in btrfs_delayed_refs_rsv_refill():
Before reserving additional metadata bytes, limit the delayed refs
reservation based on the usable metadata space (total bytes minus
zone_unusable). If the reservation would exceed this cap, return -EAGAIN
to trigger the existing flush/commit logic instead of overcommitting
metadata space.

This preserves the existing reservation and flushing semantics while
preventing metadata overcommit on zoned devices. The change is limited to
metadata space and does not affect non-zoned filesystems.

This patch addresses premature metadata ENOSPC conditions on zoned devices
and ensures delayed refs are throttled before exhausting usable metadata.

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

If anyone's interested, if pushed the space_info analysis tool to:
https://github.com/morbidrsa/debug-scripts/blob/master/analyze-space_info.py
---
 fs/btrfs/delayed-ref.c | 28 ++++++++++++++++++++++++++++
 fs/btrfs/transaction.c |  8 ++++++++
 2 files changed, 36 insertions(+)

diff --git a/fs/btrfs/delayed-ref.c b/fs/btrfs/delayed-ref.c
index e8bc37453336..a4f968062fcd 100644
--- a/fs/btrfs/delayed-ref.c
+++ b/fs/btrfs/delayed-ref.c
@@ -207,6 +207,30 @@ void btrfs_dec_delayed_refs_rsv_bg_updates(struct btrfs_fs_info *fs_info)
  * This will refill the delayed block_rsv up to 1 items size worth of space and
  * will return -ENOSPC if we can't make the reservation.
  */
+static int btrfs_zoned_cap_metadata_reservation(struct btrfs_space_info *space_info)
+{
+	struct btrfs_fs_info *fs_info = space_info->fs_info;
+	struct btrfs_block_rsv *block_rsv = &fs_info->delayed_refs_rsv;
+	u64 usable;
+	u64 cap;
+	int ret = 0;
+
+	if (!btrfs_is_zoned(fs_info))
+		return 0;
+
+	spin_lock(&space_info->lock);
+	usable = space_info->total_bytes - space_info->bytes_zone_unusable;
+	spin_unlock(&space_info->lock);
+	cap = usable >> 1;
+
+	spin_lock(&block_rsv->lock);
+	if (block_rsv->size > cap)
+		ret = -EAGAIN;
+	spin_unlock(&block_rsv->lock);
+
+	return ret;
+}
+
 int btrfs_delayed_refs_rsv_refill(struct btrfs_fs_info *fs_info,
 				  enum btrfs_reserve_flush_enum flush)
 {
@@ -228,6 +252,10 @@ int btrfs_delayed_refs_rsv_refill(struct btrfs_fs_info *fs_info,
 	if (!num_bytes)
 		return 0;
 
+	ret = btrfs_zoned_cap_metadata_reservation(space_info);
+	if (ret)
+		return ret;
+
 	ret = btrfs_reserve_metadata_bytes(space_info, num_bytes, flush);
 	if (ret)
 		return ret;
diff --git a/fs/btrfs/transaction.c b/fs/btrfs/transaction.c
index aea84ac65ea7..746678044fed 100644
--- a/fs/btrfs/transaction.c
+++ b/fs/btrfs/transaction.c
@@ -678,6 +678,14 @@ start_transaction(struct btrfs_root *root, unsigned int num_items,
 		 * here.
 		 */
 		ret = btrfs_delayed_refs_rsv_refill(fs_info, flush);
+		if (ret == -EAGAIN) {
+			ASSERT(btrfs_is_zoned(fs_info));
+			ret = btrfs_commit_current_transaction(root);
+			if (ret)
+				goto reserve_fail;
+			ret = btrfs_delayed_refs_rsv_refill(fs_info, flush);
+		}
+
 		if (ret)
 			goto reserve_fail;
 	}
-- 
2.53.0

[PATCH v3 2/3] btrfs: zoned: move partially zone_unusable block groups to reclaim list

[Johannes Thumshirn]

On zoned block devices, block groups accumulate zone_unusable space
(space between the write pointer and zone end that cannot be allocated
until the zone is reset). When a block group becomes mostly
zone_unusable but still contains some valid data and it gets added to the
unused_bgs list it can never be deleted because it's not actually empty.

The deletion code (btrfs_delete_unused_bgs) skips these block groups
due to the btrfs_is_block_group_used() check, leaving them on the
unused_bgs list indefinitely. This causes two problems:
1. The block groups are never reclaimed, permanently wasting space
2. Eventually leads to ENOSPC even though reclaimable space exists

Fix by detecting block groups where zone_unusable exceeds 50% of the
block group size. Move these to the reclaim_bgs list instead of
skipping them. This triggers btrfs_reclaim_bgs_work() which:
1. Marks the block group read-only
2. Relocates the remaining valid data via btrfs_relocate_chunk()
3. Removes the emptied block group
4. Resets the zones, converting zone_unusable back to usable space

The 50% threshold ensures we only reclaim block groups where most space
is unusable, making relocation worthwhile. Block groups with less
zone_unusable are left on unused_bgs to potentially become fully empty
through normal deletion.

Reviewed-by: Filipe Manana <fdmanana@suse.com>
Signed-off-by: Johannes Thumshirn <johannes.thumshirn@wdc.com>
---
 fs/btrfs/block-group.c | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/fs/btrfs/block-group.c b/fs/btrfs/block-group.c
index 764caaf1d8b2..e3e7852dd3e0 100644
--- a/fs/btrfs/block-group.c
+++ b/fs/btrfs/block-group.c
@@ -1597,6 +1597,24 @@ void btrfs_delete_unused_bgs(struct btrfs_fs_info *fs_info)
 
 		spin_lock(&space_info->lock);
 		spin_lock(&block_group->lock);
+
+		if (btrfs_is_zoned(fs_info) && btrfs_is_block_group_used(block_group) &&
+		    block_group->zone_unusable >= div_u64(block_group->length, 2)) {
+			/*
+			 * If the block group has data left, but at least half
+			 * of the block group is zone_unusable, mark it as
+			 * reclaimable before continuing with the next block group.
+			 */
+
+			spin_unlock(&block_group->lock);
+			spin_unlock(&space_info->lock);
+			up_write(&space_info->groups_sem);
+
+			btrfs_mark_bg_to_reclaim(block_group);
+
+			goto next;
+		}
+
 		if (btrfs_is_block_group_used(block_group) ||
 		    (block_group->ro && !(block_group->flags & BTRFS_BLOCK_GROUP_REMAPPED)) ||
 		    list_is_singular(&block_group->list) ||
-- 
2.53.0

[PATCH v3 3/3] btrfs: zoned: add zone reclaim flush state for DATA space_info

[Johannes Thumshirn]

On zoned block devices, DATA block groups can accumulate large amounts
of zone_unusable space (space between the write pointer and zone end).
When zone_unusable reaches high levels (e.g., 98% of total space), new
allocations fail with ENOSPC even though space could be reclaimed by
relocating data and resetting zones.

The existing flush states don't handle this scenario effectively - they
either try to free cached space (which doesn't exist for zone_unusable)
or reset empty zones (which doesn't help when zones contain valid data
mixed with zone_unusable space).

Add a new RECLAIM_ZONES flush state that triggers the block group
reclaim machinery. This state:
- Calls btrfs_reclaim_sweep() to identify reclaimable block groups
- Calls btrfs_reclaim_bgs() to queue reclaim work
- Waits for reclaim_bgs_work to complete via flush_work()
- Commits the transaction to finalize changes

The reclaim work (btrfs_reclaim_bgs_work) safely relocates valid data
from fragmented block groups to other locations before resetting zones,
converting zone_unusable space back into usable space.

Insert RECLAIM_ZONES before RESET_ZONES in data_flush_states so that
we attempt to reclaim partially-used block groups before falling back
to resetting completely empty ones.

Reviewed-by: Filipe Manana <fdmanana@suse.com>
Signed-off-by: Johannes Thumshirn <johannes.thumshirn@wdc.com>
---
 fs/btrfs/space-info.c | 22 ++++++++++++++++++++++
 fs/btrfs/space-info.h |  1 +
 2 files changed, 23 insertions(+)

diff --git a/fs/btrfs/space-info.c b/fs/btrfs/space-info.c
index 243b2593d4bc..b174c68a5ebb 100644
--- a/fs/btrfs/space-info.c
+++ b/fs/btrfs/space-info.c
@@ -129,6 +129,15 @@
  *     churn a lot and we can avoid making some extent tree modifications if we
  *     are able to delay for as long as possible.
  *
+ *   RECLAIM_ZONES
+ *     This state only works for the zoned mode. In zoned mode, we cannot reuse
+ *     regions that have once been allocated and then been freed until we reset
+ *     the zone, due to the sequential write requirement. The RECLAIM_ZONES state
+ *     calls the reclaim machinery, evacuating the still valid data in these
+ *     block-groups and relocates it to the data_reloc_bg. Afterwards these
+ *     block-groups get deleted and the transaction is committed. This frees up
+ *     space to use for new allocations.
+ *
  *   RESET_ZONES
  *     This state works only for the zoned mode. On the zoned mode, we cannot
  *     reuse once allocated then freed region until we reset the zone, due to
@@ -905,6 +914,18 @@ static void flush_space(struct btrfs_space_info *space_info, u64 num_bytes,
 		if (ret > 0 || ret == -ENOSPC)
 			ret = 0;
 		break;
+	case RECLAIM_ZONES:
+		if (btrfs_is_zoned(fs_info)) {
+			btrfs_reclaim_sweep(fs_info);
+			btrfs_delete_unused_bgs(fs_info);
+			btrfs_reclaim_bgs(fs_info);
+			flush_work(&fs_info->reclaim_bgs_work);
+			ASSERT(current->journal_info == NULL);
+			ret = btrfs_commit_current_transaction(root);
+		} else {
+			ret = 0;
+		}
+		break;
 	case RUN_DELAYED_IPUTS:
 		/*
 		 * If we have pending delayed iputs then we could free up a
@@ -1403,6 +1424,7 @@ static const enum btrfs_flush_state data_flush_states[] = {
 	FLUSH_DELALLOC_FULL,
 	RUN_DELAYED_IPUTS,
 	COMMIT_TRANS,
+	RECLAIM_ZONES,
 	RESET_ZONES,
 	ALLOC_CHUNK_FORCE,
 };
diff --git a/fs/btrfs/space-info.h b/fs/btrfs/space-info.h
index 6f96cf48d7da..174b1ecf63be 100644
--- a/fs/btrfs/space-info.h
+++ b/fs/btrfs/space-info.h
@@ -113,6 +113,7 @@ enum btrfs_flush_state {
 	RUN_DELAYED_IPUTS	= 10,
 	COMMIT_TRANS		= 11,
 	RESET_ZONES		= 12,
+	RECLAIM_ZONES		= 13,
 };
 
 enum btrfs_space_info_sub_group {
-- 
2.53.0

Re: [PATCH v3 1/3] btrfs: zoned: cap delayed refs metadata reservation to avoid overcommit

[Filipe Manana]

On Tue, Feb 10, 2026 at 11:04 AM Johannes Thumshirn
<johannes.thumshirn@wdc.com> wrote:
>
> On zoned filesystems metadata space accounting can become overly optimistic
> due to delayed refs reservations growing without a hard upper bound.
>
> The delayed_refs_rsv block reservation is allowed to speculatively grow and
> is only backed by actual metadata space when refilled. On zoned devices this
> can result in delayed_refs_rsv reserving a large portion of metadata space
> that is already effectively unusable due to zone write pointer constraints.
> As a result, space_info->may_use can grow far beyond the usable metadata
> capacity, causing the allocator to believe space is available when it is not.
>
> This leads to premature ENOSPC failures and "cannot satisfy tickets" reports
> even though commits would be able to make progress by flushing delayed refs.
>
> Analysis of "-o enospc_debug" dumps using a Python debug script
> confirmed that delayed_refs_rsv was responsible for the majority of
> metadata overcommit on zoned devices. By correlating space_info counters
> (total, used, may_use, zone_unusable) across transactions, the analysis
> showed that may_use continued to grow even after usable metadata space
> was exhausted, with delayed refs refills accounting for the excess
> reservations.
>
> Here's the output of the analysis:
>
>   ======================================================================
>   Space Type: METADATA
>   ======================================================================
>
>   Raw Values:
>     Total:                256.00 MB (268435456 bytes)
>     Used:                 128.00 KB (131072 bytes)
>     Pinned:                16.00 KB (16384 bytes)
>     Reserved:             144.00 KB (147456 bytes)
>     May Use:              255.48 MB (267894784 bytes)
>     Zone Unusable:        192.00 KB (196608 bytes)
>
>   Calculated Metrics:
>     Actually Usable:       255.81 MB (total - zone_unusable)
>     Committed:             255.77 MB (used + pinned + reserved + may_use)
>     Consumed:              320.00 KB (used + zone_unusable)
>
>   Percentages:
>     Zone Unusable:    0.07% of total
>     May Use:         99.80% of total
>
> Fix this by adding a zoned-specific cap in btrfs_delayed_refs_rsv_refill():
> Before reserving additional metadata bytes, limit the delayed refs
> reservation based on the usable metadata space (total bytes minus
> zone_unusable). If the reservation would exceed this cap, return -EAGAIN
> to trigger the existing flush/commit logic instead of overcommitting
> metadata space.
>
> This preserves the existing reservation and flushing semantics while
> preventing metadata overcommit on zoned devices. The change is limited to
> metadata space and does not affect non-zoned filesystems.
>
> This patch addresses premature metadata ENOSPC conditions on zoned devices
> and ensures delayed refs are throttled before exhausting usable metadata.
>
> Signed-off-by: Johannes Thumshirn <johannes.thumshirn@wdc.com>

Reviewed-by: Filipe Manana <fdmanana@suse.com>

Looks good now, thanks.

> ---
>
> If anyone's interested, if pushed the space_info analysis tool to:
> https://github.com/morbidrsa/debug-scripts/blob/master/analyze-space_info.py
> ---
>  fs/btrfs/delayed-ref.c | 28 ++++++++++++++++++++++++++++
>  fs/btrfs/transaction.c |  8 ++++++++
>  2 files changed, 36 insertions(+)
>
> diff --git a/fs/btrfs/delayed-ref.c b/fs/btrfs/delayed-ref.c
> index e8bc37453336..a4f968062fcd 100644
> --- a/fs/btrfs/delayed-ref.c
> +++ b/fs/btrfs/delayed-ref.c
> @@ -207,6 +207,30 @@ void btrfs_dec_delayed_refs_rsv_bg_updates(struct btrfs_fs_info *fs_info)
>   * This will refill the delayed block_rsv up to 1 items size worth of space and
>   * will return -ENOSPC if we can't make the reservation.
>   */
> +static int btrfs_zoned_cap_metadata_reservation(struct btrfs_space_info *space_info)
> +{
> +       struct btrfs_fs_info *fs_info = space_info->fs_info;
> +       struct btrfs_block_rsv *block_rsv = &fs_info->delayed_refs_rsv;
> +       u64 usable;
> +       u64 cap;
> +       int ret = 0;
> +
> +       if (!btrfs_is_zoned(fs_info))
> +               return 0;
> +
> +       spin_lock(&space_info->lock);
> +       usable = space_info->total_bytes - space_info->bytes_zone_unusable;
> +       spin_unlock(&space_info->lock);
> +       cap = usable >> 1;
> +
> +       spin_lock(&block_rsv->lock);
> +       if (block_rsv->size > cap)
> +               ret = -EAGAIN;
> +       spin_unlock(&block_rsv->lock);
> +
> +       return ret;
> +}
> +
>  int btrfs_delayed_refs_rsv_refill(struct btrfs_fs_info *fs_info,
>                                   enum btrfs_reserve_flush_enum flush)
>  {
> @@ -228,6 +252,10 @@ int btrfs_delayed_refs_rsv_refill(struct btrfs_fs_info *fs_info,
>         if (!num_bytes)
>                 return 0;
>
> +       ret = btrfs_zoned_cap_metadata_reservation(space_info);
> +       if (ret)
> +               return ret;
> +
>         ret = btrfs_reserve_metadata_bytes(space_info, num_bytes, flush);
>         if (ret)
>                 return ret;
> diff --git a/fs/btrfs/transaction.c b/fs/btrfs/transaction.c
> index aea84ac65ea7..746678044fed 100644
> --- a/fs/btrfs/transaction.c
> +++ b/fs/btrfs/transaction.c
> @@ -678,6 +678,14 @@ start_transaction(struct btrfs_root *root, unsigned int num_items,
>                  * here.
>                  */
>                 ret = btrfs_delayed_refs_rsv_refill(fs_info, flush);
> +               if (ret == -EAGAIN) {
> +                       ASSERT(btrfs_is_zoned(fs_info));
> +                       ret = btrfs_commit_current_transaction(root);
> +                       if (ret)
> +                               goto reserve_fail;
> +                       ret = btrfs_delayed_refs_rsv_refill(fs_info, flush);
> +               }
> +
>                 if (ret)
>                         goto reserve_fail;
>         }
> --
> 2.53.0
>
>