]> git.hungrycats.org Git - linux/commitdiff
balance-resume: cover: the limit_min fix as patch 1 (draft for Zygo's review)
authorZygo Blaxell <ce3g8jdj@umail.furryterror.org>
Tue, 10 Nov 2026 08:07:39 +0000 (03:07 -0500)
committerZygo Blaxell <ce3g8jdj@umail.furryterror.org>
Tue, 10 Nov 2026 08:07:39 +0000 (03:07 -0500)
"btrfs: apply the balance limit_min filter only to a limit range" goes
first in the series (Zygo 2026-11-09: "add that to the balance-resume
series"): a new paragraph for it, the later patches renumbered (vrange
2, limit write-back 3, legacy filters 4), and the limit test entry
gains the single-limit arms.  The headers, shortlog and diffstat follow
at the re-export.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
topics/balance-resume/0000-cover-letter.patch

index 881502adce327b946c9d787c89a92f7da87e4aea..95b121b168e9ccaad97c5ce13c810b9cd08552a4 100644 (file)
@@ -1,7 +1,7 @@
 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
@@ -25,11 +25,24 @@ block groups are (usually) created with higher bytenrs than the highest
 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
@@ -65,7 +78,7 @@ The vrange filter has been present in btrfs since balance filters were
 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
@@ -73,7 +86,7 @@ original values: a resume after an unmount or a crash starts counting
 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
@@ -89,8 +102,8 @@ can make the resumed balance relocate one chunk more than requested,
 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
@@ -102,15 +115,15 @@ start a new balance for it, as after any other balance error.  The
 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
@@ -154,9 +167,15 @@ Testing (KASAN kernels):
    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
@@ -169,7 +188,7 @@ Testing (KASAN kernels):
    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