]> git.hungrycats.org Git - btrfs-progs/commitdiff
btrfs-progs topic series: cover letters and TESTING.md
authorZygo Blaxell <ce3g8jdj@umail.furryterror.org>
Fri, 30 Oct 2026 13:38:46 +0000 (09:38 -0400)
committerZygo Blaxell <ce3g8jdj@umail.furryterror.org>
Fri, 30 Oct 2026 13:38:46 +0000 (09:38 -0400)
Cover letters for the three multi-patch series (scrub-limit-only-with-option,
logical-resolve-fixes, scrub-progress-socket) and a TESTING.md for every
topic, from the recorded runs in raid56-wh-harness forensics
(scrub-limit-20261029, logical-resolve-20261029, replace-resume-20261029,
replace-abort-20261016, replace-retrofit-20261016, t-ahive/t-dhive
topics-20261018, bhive-remap-balance-resume-20261013, r-rebase-20261023;
harness up to 7356cc6).  The full progs test suite section is pending in
each file.

Re-exported (scripts/export.sh keeps the cover text) from testing
3bc81a49b73f, devel 9d01fb77f46e: mkfs-remap-tree ae91bb721fd5 (1),
dump-tree-replace-stop-time 7246e18c809f (1), replace-abort-uncorrectable
2ee0ef38412e (1), scrub-limit-only-with-option 02e0c99bb36d (2),
logical-resolve-fixes 08cfeba28ba1 (4), scrub-progress-socket
0d535ece7a9a (2).  Verified as in the previous commit.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
topics/dump-tree-replace-stop-time/TESTING.md [new file with mode: 0644]
topics/logical-resolve-fixes/0000-cover-letter.patch
topics/logical-resolve-fixes/TESTING.md [new file with mode: 0644]
topics/mkfs-remap-tree/TESTING.md [new file with mode: 0644]
topics/replace-abort-uncorrectable/TESTING.md [new file with mode: 0644]
topics/scrub-limit-only-with-option/0000-cover-letter.patch
topics/scrub-limit-only-with-option/TESTING.md [new file with mode: 0644]
topics/scrub-progress-socket/0000-cover-letter.patch
topics/scrub-progress-socket/TESTING.md [new file with mode: 0644]

diff --git a/topics/dump-tree-replace-stop-time/TESTING.md b/topics/dump-tree-replace-stop-time/TESTING.md
new file mode 100644 (file)
index 0000000..bfc62d5
--- /dev/null
@@ -0,0 +1,28 @@
+# Testing: dump-tree-replace-stop-time
+
+One patch on devel 9d01fb77: 7246e18c "btrfs-progs: print-tree: print the
+dev-replace stop time, not the start time twice".  The bug came with the
+dev-replace item printer, 6ad89f67 ("btrfs-progs: print-tree: add support
+for dev-replace item", v6.8.1-43).
+
+No dedicated test.  Found while reading dump-tree output in
+replace-cancel-persist (raid56-wh-harness
+`forensics/replace-cancel-persist-20261016/README.md`).  The evidence is
+the dump-tree output that other tests record:
+
+| progs | what dump-tree printed | date | evidence |
+|---|---|---|---|
+| progs in use on 2026-10-04 (before the fix existed; the log does not name the version) | a STARTED item with `start time 1791121231` and `stop time 1791121231`: the same value twice | 2026-10-04 | raid56-wh-harness `forensics/kakra618-lockdep-rmdev-typestore-20261004/alloc-hints-replace-test.log` |
+| refs/cand/abortflag-progs/testing 9fed456c, which has this patch as 125a80e1 (diff identical to 7246e18c) | 52 dev_replace item dumps in the replace-abort runs (bhive #30, #31; dhive #119, #120): none with stop == start; `stop time 0` on every STARTED item (running, suspended, crash images); a stop time after the start time on every FINISHED and CANCELED item, e.g. FINISHED `start time 1792177900 (2026-10-16 15:11:40)`, `stop time 1792177921 (2026-10-16 15:12:01)` | 2026-10-16 | raid56-wh-harness `forensics/replace-abort-20261016/{bhive-mn30,dhive-618-119,af2-bhive-mn31,af2-dhive-618-120}/*/item-*.txt` |
+
+## Full test suite
+
+Pending: a separate run of the whole btrfs-progs test suite on ahive
+(testing 3bc81a49) is in progress; results will be in raid56-wh-harness
+`forensics/progs-testsuite-20261030/`.
+
+## Not covered / open
+
+- No test compares the printed stop time with the kernel's value directly;
+  the check above is that the two fields differ where the kernel sets them
+  differently.
index 64654031136a3f15f69fa7167e4e4511c8c2752f..54c120250d78895fc09ea276e8b4f4bf5d8e1556 100644 (file)
@@ -1,10 +1,76 @@
 From 08cfeba28ba1ab9b7c2336dd7f0ec906f46404f0 Mon Sep 17 00:00:00 2001
 From: Zygo Blaxell <ce3g8jdj@umail.furryterror.org>
-Date: Fri, 30 Oct 2026 09:33:57 -0400
-Subject: [PATCH 0/4] *** SUBJECT HERE ***
+Date: Fri, 30 Oct 2026 09:38:46 -0400
+Subject: [PATCH 0/4] btrfs-progs: inspect logical-resolve: find the file names again
 To: linux-btrfs@vger.kernel.org
 
-*** BLURB HERE ***
+"btrfs inspect-internal logical-resolve" prints no file names for most
+references since v5.10 (Issue #400).  The kernel returns every
+reference (-P lists them all); what fails is the step that turns a
+(subvolume, inode) pair into a path.  Six defects, all in user space:
+
+1. The mountinfo parser skips exactly one optional field, so mounts with
+   none (private propagation, e.g. in a container) or two ("shared:N
+   master:M") are not recognized as btrfs mounts (e31679c1ec3e, v5.11).
+2. Any btrfs filesystem that has a subvolume with the same path and id
+   is accepted, so names of unrelated files of another filesystem can be
+   printed (6b8fed9e798d, v5.10).
+3. A subvolume must be mounted by itself: nested subvolumes and
+   snapshots reached as directories of a mounted top level or of
+   another subvolume are reported as "not mounted" (6b8fed9e798d).
+4. Paths are printed under the mount point found, not under the path
+   argument as before v5.10 (6b8fed9e798d).
+5. References in the top level subvolume use the argument without
+   checking which subvolume it is, so with a subvol= mount or a
+   subvolume directory as the argument INO_PATHS runs in the wrong
+   subvolume and prints a wrong name or fails (6055e736045d).
+6. Hexadecimal addresses ("0x...") are rejected since v6.7
+   (8f8d94b8c932).
+
+Patch 1 fixes 1: skip optional fields up to the lone "-".
+
+Patch 2 fixes 6: arg_strtou64() parses with base 0 again, through a new
+parse_u64_base(); parse_u64() stays decimal for its other callers.
+
+Patch 3 fixes 2 to 5.  For each reference, open the subvolume below the
+path argument if it is there (and print paths relative to the argument
+as given, so "." gives "./subvol/file"), otherwise through the mount of
+its deepest mounted ancestor or of itself.  Every candidate is checked
+to be the root of that subvolume (inode 256, root id) on the same
+filesystem (fsid) before INO_PATHS is called on it.  That check also
+covers the bind mount case the mountinfo lookup was introduced for.
+find_mount_fsroot() and find_option() lose their only user and are
+replaced by iterate_btrfs_mounts().
+
+Patch 4 reports a reference whose subvolume cannot be reached at all as
+an error on stderr and exits with status 1, after printing all the other
+paths.  Today the message goes to stdout with status 0, so a script sees
+fewer paths, or none, and no error.  It updates misc-tests/042, which
+read the message from stdout and relied on status 0: the test now
+accepts status 1 only together with at least one such error, and
+requires the error whenever the status is 1.  This test is also why CI
+never caught defect 3: it counted a "could not be accessed" line as a
+pass.
+
+User-visible changes:
+- Patch 2: every option parsed by arg_strtou64() accepts hexadecimal,
+  and also octal (a leading 0) again, exactly as before v6.7.  No
+  cli-tests or misc-tests pass a number with a leading zero.
+- Patch 3: paths are printed relative to the path argument when the
+  subvolume is below it, which changes the output even of setups that
+  work today: with the top level at /mnt and subvol=/sv1 also mounted at
+  /mnt2, sv1's file is printed as /mnt/sv1/f1 (was /mnt2/f1) when /mnt
+  is the argument.  The mount point route is used only for subvolumes
+  outside the argument.
+- Patch 4: the "could not be accessed" message moves from stdout to
+  stderr, and the exit status becomes 1.  This patch is separable; the
+  others do not depend on it.
+
+Patch 3 depends on patch 1 only for mounts in namespaces whose
+propagation is not exactly one optional field; patch 4 changes the
+message that patch 3 leaves in place.  Apply in order.
+
+Link: https://github.com/kdave/btrfs-progs/issues/400
 
 Zygo Blaxell (4):
   btrfs-progs: utils: parse any number of optional fields in mountinfo
diff --git a/topics/logical-resolve-fixes/TESTING.md b/topics/logical-resolve-fixes/TESTING.md
new file mode 100644 (file)
index 0000000..9ab6ae9
--- /dev/null
@@ -0,0 +1,62 @@
+# Testing: logical-resolve-fixes
+
+Four patches on devel 9d01fb77 (btrfs-progs Issue #400):
+4bd84e5a mountinfo optional fields, 09299b6d arg_strtou64() base 0,
+35045fc7 subvolume lookup, 08cfeba2 unreachable reference = error (with
+the misc-tests/042 update).
+
+Not a kernel bug: on the misc-next lane kernel `-P` (inode, offset, root)
+returns every expected reference in every case below.  Only the user
+space step from (root, inode) to a path fails.
+
+Rig: ahive, kernel `7.3.0-rc7+ #7 SMP PREEMPT_DYNAMIC Wed Oct 28 21:00:00
+EDT 2026` (misc-next lane plus a debug knob, KASAN).  Builds compared:
+system v6.14, `/usr/local/btrfs-progs-exp` (stock v7.1), and the topic.
+The topic build was first devel 9d01fb77 plus the four patches
+(`/mnt/linux/progs-lr`, patches in `patches/`), then progs `testing`
+25b77be8 (devel + the 5 topics of that day); its matrix lines are identical
+to the first build's.  The ahive build was removed afterwards.
+Evidence: raid56-wh-harness `forensics/logical-resolve-20261029/`.
+
+## New tests
+
+| test | verifies | patch(es) | last result | date | progs | harness | evidence |
+|---|---|---|---|---|---|---|---|
+| `logical-resolve-repro.sh` (matrix: layouts top, top with ".", top with a subvolume directory argument, hex, both, sub, sub with ".", priv, 2opt, wrongfs, wrongfs with a bind mount first; plain, reflinked, zstd-compressed and nested-subvolume extents, at the extent start and mid-extent, with and without -o) | every reference resolves to the right file under the right filesystem; paths relative to the argument; hex addresses | 1-4 | 99 cases per build.  v6.14: 28/99 fully resolved; stock v7.1: 28/99.  Topic: 87/99; the other 12 are the `sub` layout's references that are really unreachable (root 5 and snap1 with only subvol=/sv1 mounted): reported as `ERROR: ... could not be accessed: not mounted` on stderr, rc 1.  wrongfs: stock prints `/mnt/wh/lr-mnt3/WRONG-FS-B-f1` (another filesystem's file), topic resolves fs A through both routes.  hex: stock `ERROR: 0xd00000 is not a valid numeric value`, topic 2/2 | 2026-10-30 | v6.14, v7.1, testing 25b77be8 | 09b7609 | `run-ahive-testing-25b77be8.txt`, `run-ahive-mn759c6b78edf4.txt` |
+| the same with patches 1-3 only | | 1-3 | identical, except that the unreachable references printed to stdout with rc 0 | 2026-10-30 | devel + 0001-0003 | b863822 | README |
+| misc-tests `042-inspect-internal-logical-resolve` (updated by patch 4) | paths, and unreachable references with rc 1 | 4 | PASS: 8 path lines, 4 unreachable references (@/snap1, @/vol1/snapshot1) with rc 1 on 4 offsets | 2026-10-30 | testing 25b77be8 | 09b7609 | `misc-042-results-testing-25b77be8.txt` |
+| same, control | the new 042 against the stock binary | none | FAIL as expected: "inode 257 subvol @/snap1 could not be accessed" read as a path | 2026-10-30 | stock v7.1 as TOP/btrfs | 09b7609 | same file |
+
+## Existing tests
+
+Every test that runs an inspect-internal resolve or rootid command:
+
+| test | last result | date | progs | evidence |
+|---|---|---|---|---|
+| misc-tests 024-inspect-internal-rootid, 013-subvolume-sync-crash, 040-subvolume-delete-default, 043-subvolume-set-default-toplevel, 055-qgroup-clear-stale | PASS (rc 0 each) | 2026-10-30 | testing 25b77be8 | `progs-tests-ahive-testing-25b77be8.txt` |
+| cli-tests 008-subvolume-get-set-default | PASS | 2026-10-30 | testing 25b77be8 | same |
+
+`make testsuite` was not built on ahive at the time (fsstress needs
+liburing, which ahive did not have); `make all` and `TEST=...
+./misc-tests.sh` were used.  None of the tests above need fsstress.
+
+## Full test suite
+
+Pending: a separate run of the whole btrfs-progs test suite on ahive
+(testing 3bc81a49, liburing installed) is in progress; results will be in
+raid56-wh-harness `forensics/progs-testsuite-20261030/`.
+
+## Not covered / open
+
+- Patch 2 restores base 0 for every arg_strtou64() caller, octal
+  included.  No cli-tests or misc-tests pass a number with a leading zero
+  to one (the only such tokens in them are a label and a file name); the
+  other callers were not exercised beyond the test suite.
+- `-o` has no separate defect on devel: it resolves exactly what the
+  plain command resolves in every case.
+- Bind mounts of directories inside a subvolume were tested only in the
+  wrongfs layout (`/sv1/bdir` mounted first); the mount route skips it.
+- Kernel lanes ruled out: logical-ino-costs (COMMIT_ROOT flag, default
+  off; progs never sets it) and the add_all_parents rewind-cycle check,
+  which would surface as `ERROR: logical ino ioctl: Resource temporarily
+  unavailable`, not as missing names.
diff --git a/topics/mkfs-remap-tree/TESTING.md b/topics/mkfs-remap-tree/TESTING.md
new file mode 100644 (file)
index 0000000..22884d5
--- /dev/null
@@ -0,0 +1,41 @@
+# Testing: mkfs-remap-tree
+
+One patch on devel 9d01fb77: ae91bb72 "btrfs-progs: do not write a NULL
+remap root during mkfs".  `mkfs.btrfs -O remap-tree` (experimental builds)
+commits before setup_remap_tree_root() has created the remap tree, and
+write_ctree_super() dereferenced `remap_root->node`: mkfs segfaulted.  The
+dereference came with 9f887733 ("btrfs-progs: write remap root details to
+superblock", v6.19-5).
+
+Found by `remap-balance-resume-test.sh` (raid56-wh-harness), a kernel test
+that needs a remap-tree filesystem: on 2026-10-13 stock devel 6c406ee7
+`mkfs -O remap-tree` segfaulted in write_ctree_super().  Every run below
+used a progs build with the fix; its diff is identical to ae91bb72 in each
+case: the harness fixture
+`fixtures/btrfs-progs/0001-do-not-write-a-NULL-remap-root-during-mkfs.patch`
+(383df3f6) on devel 6c406ee7, and then the experimental build of testing
+35e1e5f4 (the first version of this topic), installed at
+`/usr/local/btrfs-progs-exp` on all four VMs on 2026-10-16.
+
+| test | verifies | last result | date | kernel | evidence |
+|---|---|---|---|---|---|
+| `remap-balance-resume-test.sh` | mkfs -O remap-tree creates a filesystem with one METADATA_REMAP chunk that the kernel mounts (the test's kernel checks follow) | mkfs and mount OK in all 5 runs (3 fixed-kernel, 2 control-kernel runs; the kernel verdicts are about the kernel) | 2026-10-13 | bhive misc-next candidates #21, #22 (KASAN) | raid56-wh-harness `forensics/bhive-remap-balance-resume-20261013/` |
+| same | | mkfs and mount OK (the script's default progs, `/usr/local/btrfs-progs-exp`); test PASS (rc 0) | 2026-10-18 | dhive misc-next zb64 568c45b64012 (`7.3.0-rc7+ #5`) | `forensics/t-dhive-topics-20261018/results.txt` |
+| same | | mkfs and mount OK; `REMAP_BALANCE_RESUME_RC=0` | 2026-10-23 | ehive, misc-next rebase candidate | `forensics/r-rebase-20261023/tests/ehive/tests-mn-p2-2-0251/rv/directed.log` |
+| `remap-growth-experiment.sh` | mkfs -O remap-tree on 5 devices (`-d raid5 -m raid1`), then a full balance | mkfs OK; the full run (110,000 extent pairs) and its baselines completed | 2026-10-14 | bhive #24, progs `/usr/local/btrfs-progs-exp` with the fix | `forensics/bhive-remap-growth-20261014/` |
+
+On 6.18 the test SKIPs: that kernel cannot mount a remap-tree
+filesystem (expected).
+
+## Full test suite
+
+Pending: a separate run of the whole btrfs-progs test suite on ahive
+(testing 3bc81a49) is in progress; results will be in raid56-wh-harness
+`forensics/progs-testsuite-20261030/`.
+
+## Not covered / open
+
+- The fix was not run against stock devel 9d01fb77 itself; the code it
+  touches is the same in 6c406ee7, 9d01fb77 and testing.
+- Only mkfs was exercised.  Other callers of write_ctree_super() on a
+  remap-tree filesystem always have the remap root node.
diff --git a/topics/replace-abort-uncorrectable/TESTING.md b/topics/replace-abort-uncorrectable/TESTING.md
new file mode 100644 (file)
index 0000000..49db2fc
--- /dev/null
@@ -0,0 +1,73 @@
+# Testing: replace-abort-uncorrectable
+
+One patch on devel 9d01fb77: 2ee0ef38 "btrfs-progs: replace: add
+--abort-on-uncorrectable".  It is the user space half of the kernel patch
+"btrfs: dev-replace: optionally abort on uncorrectable read errors"
+(kernel topic replace-fixes; export in `~/share/linux-upstream/topics/replace-fixes/`),
+which defines BTRFS_IOCTL_DEV_REPLACE_ABORT_ON_UNCORRECTABLE (bit 32 of
+`cont_reading_from_srcdev_mode`) and persists it in the dev_replace item.
+The tests below test the two together.
+
+Tested progs: refs/cand/abortflag-progs/testing 9fed456c (v7.1,
+`--enable-experimental`), which has this patch as ad871e7d on an older
+devel; its diff is identical to 2ee0ef38.  Built on bhive
+`/mnt/linux/progs-abortflag`, installed at `/usr/local/btrfs-progs-abortflag`
+on bhive, dhive and ehive.  mkfs was the system v6.14; every other btrfs
+command was the candidate progs.
+
+Kernels: misc-next candidate refs/cand/abortflag2-mn/zb64 ed5be532ae6d
+(bhive `7.3.0-rc7+ #31`) and 6.18 candidate refs/cand/abortflag2-618/zb64
+737ae238bc42 (dhive `6.18.57+ #120`), KASAN + PROVE_LOCKING; old kernels
+for the refusal case: stock Debian `6.12.90+deb13.1-amd64` and the
+misc-next base 0c48d26d46bd (ehive `7.3.0-rc7+ #2`).  Evidence:
+raid56-wh-harness `forensics/replace-abort-20261016/`,
+`forensics/replace-retrofit-20261016/`, `forensics/t-ahive-topics-20261018/`.
+
+## New tests
+
+`replace-abort-test.sh`: a fresh filesystem on 16 GiB sparse loop
+devices per case, devid 1 replaced by a spare, one 4 GiB file (6 GiB for
+raid5), 3 data sectors unreadable from every copy in the block group that
+comes first in devid 1's physical order.
+
+| case | verifies | last result (bhive #31 / dhive #120) | date | harness | evidence |
+|---|---|---|---|---|---|
+| clean | raid1, flag, healthy: finishes; dump-tree shows mode `ALWAYS\|ABORT_ON_UNCORRECTABLE` while running and after; the start log line says it aborts on uncorrectable read errors | PASS / PASS | 2026-10-16 | a8dcf29 + 03796d4 | `af2-bhive-mn31/`, `af2-dhive-618-120/` |
+| abort-raid1 | raid1, 3 bad, flag: `-B` fails with EIO and canceled at the end of the bad block group (progress 7.9% = expected 7.9%); the source stays a member, the target is released; scrub after remount finds only the planted sectors | PASS / PASS | 2026-10-16 | as above | as above |
+| noflag-raid1 | no flag: finishes, 3 uncorrectable counted | PASS / PASS | 2026-10-16 | | |
+| avoid-abort-raid1, avoid-clean, avoid-flag-clean | `-r` with and without the flag: AVOID is still honoured with the flag set (source read 12 KiB to 1.49 MB vs 8.60 GB from the others) | PASS / PASS | 2026-10-16 | | |
+| abort-raid5 | raid5 data, flag: aborts at 6.3% = 6.3% | PASS / PASS | 2026-10-16 | | |
+| badflag (raw ioctl) | bit 33: EOPNOTSUPP, nothing started | PASS / PASS | 2026-10-16 | | |
+| persist | the flag survives suspend and resume in the item; the resumed replace aborts (39.2% / 20.4% = expected); no WARN, taint 0 | PASS / PASS | 2026-10-16 | | |
+| resume-werr | target write errors on a resumed replace cancel with -EIO, no WARN | PASS / PASS | 2026-10-16 | | |
+| oldkernel: `replace start -B --abort-on-uncorrectable` | old kernel: rc 1, `ERROR: ioctl(DEV_REPLACE_START) failed ...: Invalid argument` plus `WARNING: this kernel may not support --abort-on-uncorrectable`; status "Never started"; nothing started | PASS on stock 6.12.90 and on the misc-next base (ehive #2) | 2026-10-16 | | `ehive-6.12-oldkernel/`, README "Case 8" |
+| all cases, full size, poison + `-K` retrofit | the same verdicts with labelled poison on every member and target, `mkfs -K`, nodiscard, `replace -K` | PASS: dhive #120 (persist and resume-werr rerun alone after a scratch ENOSPC in `cp`), ehive #31; ahive misc-next #5 (zb64 568c45b64012): all 10 cases PASS, taint 0 | 2026-10-16, 2026-10-18 | 1b61552, b8405be | `replace-retrofit-20261016/`, `t-ahive-topics-20261018/long/ra/` |
+
+The verdicts in the persist case came first from the abortflag kernels
+(#30 / #119), where the resumed abort tripped a WARN_ON in
+btrfs_dev_replace_kthread; that was a kernel problem, fixed in the kernel
+series, not in this patch.
+
+## Existing tests
+
+| test | last result | date | evidence |
+|---|---|---|---|
+| replace-status-test, replace-uncorrectable-test, replace-cancel-persist-test, each with the system v6.14 and with the candidate progs | identical to the replace-status "after" results, except the replace-cancel-persist cancel line (the test's own change a141ee1: `start -B` run as a shell job); 12 cancel runs per rig, umount rc 0 every time | 2026-10-16 | `replace-abort-20261016/` "Regressions" |
+| scrub-uncorrectable-rc-test | identical | 2026-10-16 | same |
+
+## Full test suite
+
+Pending: a separate run of the whole btrfs-progs test suite on ahive
+(testing 3bc81a49) is in progress; results will be in raid56-wh-harness
+`forensics/progs-testsuite-20261030/`.
+
+## Not covered / open
+
+- On 6.12, progs runs the full-device TRIM of the target before the start
+  ioctl, so a start that the kernel refuses has still discarded the
+  target.  Existing progs ordering, not changed here.
+- A canceled `-B` replace prints `Operation canceled, <illegal result
+  value>`.  Existing progs output, not changed here.
+- Downgrade: an old kernel resuming a replace that was started with the
+  flag ignores the flag and treats AVOID|flag as ALWAYS (kernel side; not
+  tested).
index 28e5f0d064bd230a121f2097885a303fb3612fb3..054001ce59b0cca204a107399e1b5a35f3e96802 100644 (file)
@@ -1,10 +1,48 @@
 From 02e0c99bb36dc27b9d652b69ba4192794ec0c55e Mon Sep 17 00:00:00 2001
 From: Zygo Blaxell <ce3g8jdj@umail.furryterror.org>
-Date: Fri, 30 Oct 2026 09:33:57 -0400
-Subject: [PATCH 0/2] *** SUBJECT HERE ***
+Date: Fri, 30 Oct 2026 09:38:46 -0400
+Subject: [PATCH 0/2] btrfs-progs: scrub: leave the device limits alone without --limit
 To: linux-btrfs@vger.kernel.org
 
-*** BLURB HERE ***
+Since the --limit option was added (7c1c88e41668, v6.13), "btrfs scrub
+start" writes the --limit value to every device's sysfs scrub_speed_max
+before the scrub and writes the old value back afterwards, whether or
+not --limit was given.  Without --limit the value written is 0, so a
+plain scrub runs unthrottled and ignores the limits set with "btrfs
+scrub limit" or through sysfs.  In v6.14 the old value went back just
+before each device's thread was joined, so only devid 1 stayed
+throttled; 01c8277d ("btrfs-progs: scrub: only restore the old scrub
+limit after scrub is finished", Issue #1165) moved the restore after all
+the joins, so now no device is throttled during a scrub without --limit.
+
+This was found because a kernel test that throttles scrub through sysfs
+measured only devid 1: devid 2 of a two-device filesystem scrubbed at
+1.25 GiB/s with a 16 MiB/s limit.
+
+Patch 1 reads, writes and restores the limits only when --limit is
+given.  Without it the scrub runs with whatever limits the devices
+already have.
+
+Patch 2 makes every exit restore what was changed.  With --limit, the
+exits between the write and the restore ("nothing to resume", "scrub
+already running", a failed pthread_mutex_init(), fork() or
+pthread_create()) left the --limit value on the devices.  The old value
+is now written back from the common exit path, only to the devices
+whose limit was actually changed; the parent of a background scrub
+leaves that to its child.
+
+User-visible change: a "btrfs scrub start" without --limit now honours
+the limits already configured, so on a system that has them it is
+slower than with v6.13 to v7.1.  "--limit 0" still runs unthrottled for
+that scrub and restores the old limits afterwards.
+
+Patch 2 depends on patch 1.  The series is independent of the other
+scrub series ("btrfs-progs: scrub: progress socket fixes"), but
+conflicts with it in scrub_start() when both are applied: keep both
+hunks in the parent's branch after the fork, the limit_changed reset
+first.
+
+Link: https://github.com/kdave/btrfs-progs/issues/1165
 
 Zygo Blaxell (2):
   btrfs-progs: scrub: only change the device limits when --limit is
diff --git a/topics/scrub-limit-only-with-option/TESTING.md b/topics/scrub-limit-only-with-option/TESTING.md
new file mode 100644 (file)
index 0000000..b90ae22
--- /dev/null
@@ -0,0 +1,69 @@
+# Testing: scrub-limit-only-with-option
+
+Two patches on devel 9d01fb77: p1 7e8ddeba "btrfs-progs: scrub: only change
+the device limits when --limit is given", p2 02e0c99b "btrfs-progs: scrub:
+restore the device limits on every exit".  The runs below were made before
+the committer rewrite of 2026-10-30 and name the SHAs tested.  The trees
+are the same: p1 8c87ba8f = 7e8ddeba, p2 80de235d = 02e0c99b, testing
+3ac57456 = a4d31e74.
+
+Found by the kernel replace-resume tests (harness
+`forensics/replace-resume-20261029/`, "Throttle note"): a scrub arm
+throttled through sysfs measured only devid 1.  `thr-check.log` there:
+system progs v6.14, `scrub start -B` without --limit, both devices at
+16 MiB/s in sysfs, devid 1 scrubbed at 15.30 MiB/s, devid 2 at 1.25 GiB/s
+(loop device read counters agree).  The kernel test now passes --limit
+(harness f1484a1).
+
+To verify, a test must sample every device's `scrub_speed_max` while the
+scrub runs, not only before and after (the bug restores the old value at
+the end), and must sample only while a device thread exists: the write at
+the start and the restore at the end make one device look wrong for a
+moment.  The rate printed by `scrub status` is a second, independent
+detector.
+
+Rig: ehive, kernel `7.3.0-rc7+` (the build number is not in the logs),
+two-device loop filesystem, data single.  Fixed progs built in
+`/mnt/linux/progs-scrublimit` (configure `--disable-lzo --disable-convert
+--disable-libudev --disable-documentation --disable-python`; ehive lacks the
+libraries) and installed at `/usr/local/btrfs-progs-scrublimit`.  Control:
+`/usr/local/btrfs-progs-exp` (v7.1, unfixed; it contains 01c8277d).
+Evidence: raid56-wh-harness `forensics/scrub-limit-20261029/`.
+
+## New tests
+
+| test | verifies | patch(es) | last result | date | progs | harness | evidence |
+|---|---|---|---|---|---|---|---|
+| `scrub-limit-repro.sh` | the bug on released progs | none | v6.14: devid 1 33.46 MiB/s, devid 2 400.75 MiB/s with 32 MiB/s set on both; v7.1 (progs-exp): 200/400 MiB/s, both unthrottled | 2026-10-29 | system v6.14, progs-exp | 71c2d59 | `scrub-limit-repro.out` |
+| `scrub-limit-test.sh` (arms A-H fixed, X-Y control; foreground -B and background + `scrub status`; equal and different per-device limits; --limit above, equal and 0) | without --limit the device limits stay as configured during and after the scrub; with --limit they are the --limit value during and the old value after; the status rate follows the limit | 1 (2 regression) | PASS: fixed-arm failures 0 in 3 runs on p1 (testing f015cf72) and in 2 runs on p2 (testing 3ac57456); control failures 6 every run (X, Y: limits 0/0 during the scrub, 200.8/400.8 MiB/s) | 2026-10-30 | as listed | 71c2d59, c3e5933 | `scrub-limit-test.run{1,2,3}.out`, `scrub-limit-test.p2-run{1,2}.out` |
+| `scrub-limit-exits.sh` (+ `scrub-shim.c` LD_PRELOAD shim, `scrub-running.c`) | every exit after the limit write restores the old limits, on the changed devices only: nothing-to-resume, already-running, -f against a background scrub, fork failure (TasksMax=1), device thread failures (TasksMax=1, 2), progress thread failure (TasksMax=3), pthread_mutex_init failure on device 1 or 2, write failure on device 2 | 2 | PASS: failures 0 in 2 runs on testing 3ac57456; p1-only control: failures 18 (every forced exit leaves 64M/64M, or 64M on device 1 only) | 2026-10-30 | as listed; p1 control built at `/mnt/linux/progs-scrublimit/ctl-p1` | c3e5933 | `exits-p2-run{1,2}.out`, `exits-p1-control.out` |
+| the same three, after `scrub-progress-socket` was added (candidate 4de739d4 = a4d31e74 + that topic) | no regression from the socket series | 1, 2 | PASS: exits failures 0 ("force-on-bg" now reaches "scrub already running", because the background scrub keeps its socket); scrub-limit-test 0 / control 6 | 2026-10-30 | 4de739d4 | 7356cc6 | `exits-4de739d4.out`, `scrub-limit-test.4de739d4.out` |
+
+Each `exits` arm checks that the run reached the intended exit (its
+message), that sysfs after equals sysfs before (32M/48M), and how many
+times the shim saw each device's `scrub_speed_max` opened for writing (set
+plus restore = 2; 0 for a device the start never reached; 1 when the set
+itself failed).
+
+## Existing tests
+
+| test | verifies | last result | date | progs | evidence |
+|---|---|---|---|---|---|
+| cli-tests `024-scrub-limit` | `scrub limit` and `--limit` command line handling | PASS (RC=0) on testing f015cf72, 4de739d4 and 3bc81a49 | 2026-10-30 | as listed | `build-and-cli.txt`, README |
+
+## Full test suite
+
+Pending: a separate run of the whole btrfs-progs test suite on ahive
+(testing 3bc81a49) is in progress; results will be in raid56-wh-harness
+`forensics/progs-testsuite-20261030/`.
+
+## Not covered / open
+
+- A scrub process killed by a signal other than SIGINT (which cancels and
+  restores normally) still cannot restore the limits.
+- The parent of a background scrub never restores: its child owns the
+  limits.  The background parent's wait() paths need `do_wait` together
+  with `do_background`, which no option sets, so they were not exercised.
+- A pthread_join() failure is counted and the normal restore follows; it
+  was not forced.
+- Runs used one rig and one kernel; the patches touch only user space.
index ec48795a432f75760cfc80f873b536c297d3d4d3..b620fc50d4bfa2bc1574d71ee97694478506a0d3 100644 (file)
@@ -1,10 +1,52 @@
 From 0d535ece7a9a10a11abadf6e81e9eabbb3ad244e Mon Sep 17 00:00:00 2001
 From: Zygo Blaxell <ce3g8jdj@umail.furryterror.org>
-Date: Fri, 30 Oct 2026 09:33:58 -0400
-Subject: [PATCH 0/2] *** SUBJECT HERE ***
+Date: Fri, 30 Oct 2026 09:38:46 -0400
+Subject: [PATCH 0/2] btrfs-progs: scrub: progress socket fixes
 To: linux-btrfs@vger.kernel.org
 
-*** BLURB HERE ***
+Two bugs in the progress socket of "btrfs scrub start", both from the
+original scrub implementation (4ba165318745):
+
+- A client that connects to the progress socket and closes the
+  connection without reading kills the scrub: the progress thread's
+  write raises SIGPIPE.  "btrfs scrub start" is such a client itself:
+  when the socket is in use it connects to check whether a scrub is
+  running and closes at once.  So "btrfs scrub start -f" while a
+  "btrfs scrub start -B" runs on the same filesystem kills the running
+  one (exit status 141), and if that one was started with --limit, its
+  limit stays on the devices.
+
+- A background scrub has no live progress socket.  The parent creates
+  and binds it, forks, and then leaves through the common exit path,
+  which closes the socket and unlinks it, while the child is still
+  scrubbing.  "btrfs scrub status" falls back to the status file
+  (written every 5 seconds), and the "scrub already running" check of
+  another "btrfs scrub start -f" does not see the background scrub.
+
+Patch 1 blocks SIGPIPE in the progress thread and treats a failed write
+to a client as that client's problem: close the connection and go on.
+Before, a write error also ended the progress thread, so the rest of the
+scrub's progress was not recorded.
+
+Patch 2 makes the parent of a background scrub close its copy of the
+socket without unlinking it; the child unlinks it when the scrub is
+finished.
+
+The order matters: with patch 2 alone, the "already running" probe
+would reach background scrubs too, and kill them the way it kills
+foreground ones today.
+
+The series applies to devel on its own and its socket behaviour does
+not depend on anything else.  But a "scrub start -f" probe on devel
+still zeroes the running scrub's device limits and never restores them;
+that is fixed by the series "btrfs-progs: scrub: leave the device limits
+alone without --limit", which this one conflicts with in scrub_start()
+when both are applied (keep both hunks in the parent's branch after the
+fork, the limit_changed reset first).  Applying that series first is
+recommended.
+
+Not changed: the "scrub already running" exit still returns status 0.
+Changing it could break scripts that start a scrub unconditionally.
 
 Zygo Blaxell (2):
   btrfs-progs: scrub: survive a progress client that closes early
diff --git a/topics/scrub-progress-socket/TESTING.md b/topics/scrub-progress-socket/TESTING.md
new file mode 100644 (file)
index 0000000..b1655ae
--- /dev/null
@@ -0,0 +1,53 @@
+# Testing: scrub-progress-socket
+
+Two patches on devel 9d01fb77: 8c8475d7 "btrfs-progs: scrub: survive a
+progress client that closes early" and 0d535ece "btrfs-progs: scrub: keep
+the progress socket of a background scrub".  Both Fixes: 4ba165318745.
+
+Found while testing scrub-limit-only-with-option patch 2 (the
+"already running" exit).  To verify, a test must:
+- show the socket of a background scrub is present while it runs, and that
+  `scrub status` really connects to it (strace), not only reads the status
+  file;
+- show the "scrub already running" probe of `scrub start -f` sees a
+  background scrub, and that the scrub survives the probe;
+- probe a foreground `scrub start -B` several times and show it survives,
+  finishes with status 0, restores its limits, and records the finished
+  scrub.
+
+Rig: ehive, kernel `7.3.0-rc7+` (the build number is not in the logs),
+two-device loop filesystem, sysfs limits 48M/48M, every scrub with
+`--limit 32M` (about 10 s).  Progs built in `/mnt/linux/progs-scrublimit`
+as for scrub-limit-only-with-option.  Evidence: raid56-wh-harness
+`forensics/scrub-limit-20261029/` (README section
+"topics/scrub-progress-socket").
+
+## New tests
+
+| test | verifies | patch(es) | last result | date | progs | harness | evidence |
+|---|---|---|---|---|---|---|---|
+| `scrub-socket-test.sh` bg-socket, fg-sigpipe | as above | 1, 2 | PASS: failures 0 on testing 3bc81a49 (final) and on candidate 4de739d4 (a4d31e74 + this topic) | 2026-10-30 | 3bc81a49, 4de739d4 | 7356cc6 | `socket-testing-3bc81a49.out`, `socket-4de739d4.out` |
+| same, control | the bugs on the lane without this topic | none | FAIL as expected, failures 10 on testing a4d31e74: socket missing while the background scrub runs, `scrub status` connect() ENOENT and falls back to the file, the probe misses the background scrub; the `-B` owner is killed by SIGPIPE (rc 141) after probe 1 and leaves its --limit (32M/32M) on the devices | 2026-10-30 | a4d31e74 | 7356cc6 | `socket-a4d31e74-control.out` |
+| same, topic only | the topic on devel without scrub-limit-only-with-option | 1, 2 | failures 6, all from devel's limit bugs: every socket check made while a scrub ran passes (socket present, live status, the probe sees the scrub, the owner survives probe 1 with rc 0), then the scrubs end early, because devel's probe sets the running scrub's limits to 0 and never restores them | 2026-10-30 | devel + 0d535ece | 7356cc6 | `socket-topic-only-0d535ece.out` |
+| build of each commit alone | 8c8475d7 and 0d535ece each build on their own | 1, 2 | 0 warnings | 2026-10-30 | | 7356cc6 | README |
+
+## Existing tests
+
+| test | verifies | last result | date | progs | evidence |
+|---|---|---|---|---|---|
+| `scrub-limit-exits.sh` | scrub start exits restore the limits (regression) | PASS, failures 0; "force-on-bg" now reaches "scrub already running" (the background scrub keeps its socket) and the already-running owner survives with rc 0 | 2026-10-30 | 4de739d4 | `exits-4de739d4.out` |
+| `scrub-limit-test.sh` | the limit arms (regression) | PASS, 0 / control 6 | 2026-10-30 | 4de739d4 | `scrub-limit-test.4de739d4.out` |
+| cli-tests `024-scrub-limit` | | PASS (RC=0) on 4de739d4 and 3bc81a49 | 2026-10-30 | | README |
+
+## Full test suite
+
+Pending: a separate run of the whole btrfs-progs test suite on ahive
+(testing 3bc81a49) is in progress; results will be in raid56-wh-harness
+`forensics/progs-testsuite-20261030/`.
+
+## Not covered / open
+
+- The "scrub already running" exit still returns 0 (Zygo 2026-10-30: not
+  changed, it may break someone's workflow).
+- Only `scrub start` as the closing client was tested; any other client
+  that closes early takes the same path.