btrfs: hold block groups free for relocation
Relocating a block group needs somewhere to write its live data, and a
filesystem short of free space is exactly when block groups need to be
relocated: automatic reclaim, balance, device shrink and removal. When
ordinary writers have taken every free byte, relocation fails with
-ENOSPC and the space it would have recovered stays out of reach, so a
full filesystem can stay full until an administrator frees space by
hand. Zoned filesystems already avoid this for data by dedicating a
block group to relocation (data_reloc_bg); regular filesystems have
nothing, for data or metadata.
Keep, per space_info, a set of block groups held free for relocation:
- Only relocation allocates from them: the data relocation inode's
extents, and tree blocks allocated by the task running
btrfs_relocate_block_group(). That task is the one stripe_alloc
already records as fs_info->reloc_owner for the whole relocation
(tree blocks COWed in the COW-only roots during relocation cannot be
told apart by their root); btrfs_is_reloc_task() tests it.
- Their free bytes are accounted in space_info->bytes_reloc_reserve,
which btrfs_space_info_used() counts as used, so admission,
overcommit, chunk allocation and ticket granting treat the reserve as
unavailable -- except for reservations and tickets made by the
relocating task (btrfs_is_reloc_task(); a ticket carries it as
reloc_reserve). stripe_alloc's reloc flag, which also admits the
transaction machinery's bounded reservations (NO_FLUSH, FLUSH_LIMIT,
EMERGENCY) to the stripe_meta reserve, does not extend to this one:
stripe_alloc's btrfs_can_overcommit() takes the relocation reserve
off "used", after the stripe_meta reserve, only when that flag is set
and the caller is the relocating task. The per-group share is
adjusted where bytes are reserved, freed or unpinned in a held group,
so allocations the reserve serves are not counted twice.
- statfs does not offer their space, the cleaner does not delete them
while they are empty, balance without a conversion filter skips them
(relocating an empty held group only deletes the reserve), and a held
group that goes read-only leaves the set.
- The relocating task keeps its exemption through the removal of the
emptied chunk after relocation, which sets reloc_owner again around
that transaction: it reserves metadata too, and refused on a full
filesystem it failed a relocation whose data had already moved, and
kept the raw space the reserve refills from.
- A tree block that finds no room outside the reserve takes it from the
reserve rather than fail. The reservation layer admitted it already,
a failed tree block allocation aborts the transaction, and relocating
a metadata group leaves delayed refs and commit work that tasks other
than the relocating one run; without this their tree blocks aborted
the transaction on a full filesystem. Data allocations have no such
fallback: a data writer gets ENOSPC.
- A metadata group may go read-only for relocation when the reserve can
hold its live and reserved bytes, even if the rest of the space_info
cannot: without that the first, non-forced read-only step of reclaim
fails on exactly the full filesystems reclaim is needed for. An
empty group, or a space_info without a reserve, gets no exemption,
and neither does data: there the ordinary test fails only while
outstanding reservations depend on the group's free space, and data
writeback has no reserve to fall back on.
- A held group that goes read-only (scrub, device replace) leaves the
set and rejoins it when writable again, or at once if the read-only
transition fails; otherwise every scrub of a full filesystem handed
the reserve to whoever wrote next.
- The refill after a relocation commits the removal of the source group
first: its device extents can be allocated again only then, and a
refill before that claimed a sliver of a chunk from the leftovers.
- While a device shrink or removal runs, the reserve takes only empty
groups: allocating chunks for it would take back the room the shrink
is freeing (a raid6 shrink failed in merge_reloc_roots with -ENOSPC).
With stripe_alloc:
- A held group counts as reserve only its claimable whole stripes:
reloc_reserve_resync(), called from btrfs_scan_stripe_unusable() at
each commit-time rescan, resyncs its share to them. Its trapped
free space is in bytes_stripe_unusable already, and counting it in
the reserve too made the metadata space_info read over-full on a
full raid6 filesystem while relocation found no stripe to claim.
Between rescans the share is capped at the claimable stripes when a
group joins the reserve while armed or is armed while held, and a
claimed stripe run's remainder (bytes_stripe_open) leaves the share
with the claim.
- stripe_claimable_admit() leaves the held groups' stripes out of
ordinary writers' whole-stripe supply; relocation still sees them.
A held group's stripes are not counted again as the dedicated data
relocation group's (bytes_stripe_claimable_reloc), which the same
check subtracts.
- stripe_alloc's whole-stripe check in inc_block_group_ro() is for
data groups, which have no reserve exception (above).
stripe_meta's bytes_stripe_reserve is not reduced by the held groups: it
is an admission margin that keeps tree blocks off the reserve's
emergency fallback, and without it a metadata fill consumed the reserve
before any relocation (dhive sresmn raid5/raid5, 2026-09-29).
Relocation moves at most one block group's live data, so the set holds
at least as much as the largest block group of the space_info. That is
the largest existing group rather than the chunk allocator's caps: a new
chunk can come out smaller than the caps when the devices are nearly
full, and a target no chunk can reach would allocate another chunk for
the reserve on every retry. A larger group appearing later raises the
target by itself. Block groups differ in size (on RAID5/6 the stripe
width follows the devices that have free space), so the reserve is a
set of groups whose free bytes add up to the target, not one group.
It is established at read-write mount after log replay and orphan
cleanup, from empty groups (largest first) or a new chunk while
unallocated space exists; refilled after every relocation from the raw
space the relocated group released, and by the cleaner; and groups
leave it, the least free first, only while the rest still covers the
target. If it cannot be established the filesystem says so once and
carries on without it.
The reserve is off by default: allocation/<type>/reloc_reserve turns it
on (empty groups are taken at once, a chunk for the rest at the
cleaner's next pass), and allocation/<type>/{bytes_reloc_reserve,
reloc_reserve_target} show its state. It stays off on zoned
filesystems, which have their own data relocation block group, and for
system, remap tree and mixed block groups.
The cost is capacity: the reserve holds one largest block group's worth
of space per space_info -- up to 10% of the writable space on small
filesystems, where the chunk allocator caps a chunk at that -- and a
filesystem needs room for the reserve beside its working block groups.
[zygo: 7.3 port: 7.3 predates upstream
cd5e2d2f2ea2 (allocate additional
SYSTEM space earlier), so the unused-group check has no system space
target term next to the new test; context adjusted, the change itself is
unchanged]
Assisted-by: Claude:claude-opus-5-5