]> git.hungrycats.org Git - linux/commit
btrfs: stripe_alloc: add stripe_reclaim_now to reclaim stripes on demand
authorZygo Blaxell <ce3g8jdj@umail.furryterror.org>
Tue, 20 Oct 2026 18:41:37 +0000 (14:41 -0400)
committerZygo Blaxell <ce3g8jdj@umail.furryterror.org>
Wed, 21 Oct 2026 07:27:55 +0000 (03:27 -0400)
commitbcadbfc8ac020ccc7fddf79e5530322e3fb98747
treed39cc792e5e647bd6d0639d2ad2c6539f6c3fd98
parent0900c2bcd6b290ba88d4bdea5d4f68477ad74aee
btrfs: stripe_alloc: add stripe_reclaim_now to reclaim stripes on demand

Background reclaim of stripe_alloc / stripe_meta raid56 groups runs when a
commit-time rescan, or the cleaner's tick at most every five minutes per
group, finds a group past bg_reclaim_threshold.  Nothing lets an operator
say "reclaim now": during an idle period, before a large write, or for one
group seen trapped.  The only tool is balance, which relocates whole groups
whatever their state and cannot compact.

Add /sys/fs/btrfs/<uuid>/stripe_reclaim_now (write-only, root):

  echo all > stripe_reclaim_now       (or "1")
Queue every stripe_alloc / stripe_meta raid56 group that the
reclaim predicate picks: relocate below the threshold once enough
of its free space is trapped, compact above it once stripe_compact
percent of its length is trapped.  The five-minute hysteresis is
ignored.

  echo <start> > stripe_reclaim_now
Reclaim the group at that logical start (decimal or 0x hex, as
`btrfs inspect-internal dump-tree -t chunk` and the "reclaim: "
debug lines print it) whatever its trapped space:
compact it if it is above the threshold and has trapped stripes,
relocate it otherwise.

The threshold is the space_info's bg_reclaim_threshold, or 75
(BTRFS_DEFAULT_RECLAIM_THRESH) where that is 0, the non-zoned default,
since the request is explicit.  Both forms keep the room check: the other
groups' claimable stripes, plus the one chunk the worker allocates when
those fall short, must take what moves.  The write returns once the groups
are queued; it does not wait for the reclaim.  The worker re-checks its
thresholds and would drop a group it was asked to reclaim, so a group
queued by this knob carries the kind of reclaim to do
(stripe_reclaim_forced), which the worker honours once and clears.

Errors: -ENOENT when no group starts there; -EINVAL for anything but a
stripe_alloc / stripe_meta raid56 group (balance's vrange filter relocates
the others); -EBUSY when the group is read-only (a balance or scrub has
it); -EAGAIN when it is already on a list (queued, unused or new);
-ENOSPC when there is no room; -EROFS on a read-only or errored
filesystem.  The worker takes the balance exclusive operation and gives the
list back when another holds it, so a request made while a balance,
replace, resize or device add/remove runs would wait unseen: it fails at
once with -EAGAIN and nothing is queued; retry when the operation is done.
The reclaim worker's own hold (a balance with no balance control) is not
refused, as the worker picks up the new entries.

Expected use: an idle-time job (cron) writes "all"; an operator writes the
start of one group taken from the "reclaim: " debug lines or from the
chunk tree.  The queued groups are logged at debug level with the same
"reclaim: " prefix.

There is no in-tree btrfs sysfs documentation; the btrfs-progs sysfs
chapter should list the file.

Tested with stripe-reclaim-now-test.sh (raid56-wh-harness): with
background reclaim off nothing moves; one group is relocated alone, and a
group above the threshold with trapped stripes is compacted; "all"
reclaims and trapped space falls; no such group, not a number, a raid1
metadata group and a read-only mount fail with the codes above, and a
paused balance and a running replace fail with -EAGAIN; data verifies and
btrfs check is clean.

Assisted-by: Claude:claude-opus-5-5
fs/btrfs/block-group.c
fs/btrfs/block-group.h
fs/btrfs/free-space-cache.c
fs/btrfs/free-space-cache.h
fs/btrfs/sysfs.c