From 968195f996534fe154954da3246b2b2a3920a653 Mon Sep 17 00:00:00 2001
From: Zygo Blaxell <ce3g8jdj@umail.furryterror.org>
Date: Mon, 9 Nov 2026 08:41:05 -0500
-Subject: [PATCH 0/3] btrfs: balance resume selects what the original request selected
+Subject: [PATCH 0/4] btrfs: balance resume selects what the original request selected
To: linux-btrfs@vger.kernel.org
When a paused or interrupted balance is resumed, the kernel alters the
existing block group, a `vrange` filter can be added, or the end of an
existing vrange limited, without changing any other filter parameter.
Adding vrange to any balance filter makes it idempotent, except for the
-limit filter which is handled in the second patch. This eliminates the
+limit filter which is handled in the third patch. This eliminates the
need for guesswork, and with the floor described below, this guarantees a
correct balance resume result.
-Patch 1 in this series removes the surprising heuristics and replaces
+Patch 1 fixes an older bug in the limit filter. A single `limit=N`
+shares its bytes with the min and max of a `limit=min..max` range, and
+balance applies the range minimum to every limited balance, on the
+assumption that it is 0 when no range was given. With a single limit it
+is not: the check reads part of the limit itself, after the limit has
+already been counted down for the chunk being checked. A `limit=L` with
+only M < L matching chunks skips the first L - M - 1 of them, while
+still counting them against the limit, and relocates 2M + 1 - L chunks
+instead of M, or none when L >= 2M + 1. For example, `limit=9` with 7
+matching data chunks relocates 6. The patch applies the minimum only to
+a limit range. The bug dates from the addition of the limit range in
+v4.4, and the patch does not depend on the rest of the series.
+
+Patch 2 in this series removes the surprising heuristics and replaces
them with a `vrange` filter, leaving the remaining filter parameters
unmodified. Before the balance item is written, the vrange filter of
each chunk type is limited to the addresses below the next chunk to be
introduced in 2012, so there is no compatibility issue arising from
its use.
-Patch 2 handles the limit filter. A limit counts chunks instead of
+Patch 3 handles the limit filter. A limit counts chunks instead of
selecting them by address, so no vrange can make it idempotent. Balance
counts the limit down in memory as it selects chunks, and a resume after
a pause continues with what is left, but the balance item keeps the
again, and can relocate up to the full limit a second time. A
`limit=min..max` range has a second problem: the resumed balance counts
only the chunks that are left, which can be fewer than min, and then it
-relocates nothing. Patch 2 counts each chunk the balance processes,
+relocates nothing. Patch 3 counts each chunk the balance processes,
relocated or left in place by ENOSPC or an active swapfile (as the
in-memory count always did), against the limit, or against both ends of
a range (min stops at 0), and writes the remaining limits to the balance
never fewer.
If one of the new balance item writes fails (the one-time write-back of
-a bounded item at resume in patch 1, or a limit update after a chunk in
-patch 2), the balance ends with the error and its item is deleted, the
+a bounded item at resume in patch 2, or a limit update after a chunk in
+patch 3), the balance ends with the error and its item is deleted, the
same as for any other error at that point in the existing code. We
considered keeping the item and leaving the balance paused so the
resume could be retried, but chose to stay consistent with the existing
failed write-back at resume is logged, because the mount-time resume
thread would otherwise drop the error silently.
-Patch 3 is optional. I offer it for completeness, but there's a tradeoff
+Patch 4 is optional. I offer it for completeness, but there's a tradeoff
that might not be worth the cost. It can be dropped without breaking
the rest of the series.
A balance item written by an older kernel has no vrange, so with patch
-1, a balance that starts on an old kernel and resumes on a new kernel
+2, a balance that starts on an old kernel and resumes on a new kernel
restarts from the beginning, redoing much of the work already done.
That behavior may be an unpleasant surprise for some users, so for each
-chunk type without a `vrange` filter, patch 3 resumes with the old
+chunk type without a `vrange` filter, patch 4 resumes with the old
usage=90 and convert-soft heuristics. The cost is keeping a layer of
surprising behavior and code in the kernel to avoid a one-time issue
that affects few users, is relatively easy to recover from, and will
chunk. A limited balance is also recorded with dm-log-writes and
replayed to every flush point: in every replayed state with a balance
item, the chunks already relocated plus the remaining limit must equal
- the request, or exceed it by one. Without patch 2, the resume after an
+ the request, or exceed it by one. Without patch 3, the resume after an
unmount relocates up to the full limit again, and the `limit=M..M`
- resumes relocate nothing.
+ resumes relocate nothing. Single limits larger than the number of
+ matching chunks (`limit=M+2`, `limit=2M` and `limit=2M+1`) must
+ relocate all M chunks; without patch 1 they relocate M-1, 1 and none.
+ A `limit=M+2` balance paused, unmounted and resumed must show the
+ limit minus the chunks relocated; without patch 1 the skipped first
+ chunk is counted too. A limit range whose minimum is above the number
+ of matching chunks must still relocate none.
- remap-balance-resume-test.sh (remap-tree filesystems): a
METADATA_REMAP chunk placed above slow data chunks, a full -d -m
kernel, then resumed on the patched kernel. Every item must show,
already before the resume, a vrange ending at the end of the last
chunk: added to a plain or convert item, lowered from a user-given
- end of 1 TiB or U64_MAX. With patch 3 a plain item also resumes with
+ end of 1 TiB or U64_MAX. With patch 4 a plain item also resumes with
usage=90 and a convert item with soft, and an item with a user-given
vrange, converting or not, with neither. The resumed balance is
paused again and the filesystem remounted: it must resume with the