--- /dev/null
+# Testing: dev-stats
+
+The one patch makes btrfs write device stats that were counted while no
+transaction was running. Before the patch, only a transaction commit wrote
+the dev stats items, and nothing started one for them. So on a read-write
+mount whose workload only reads, every count since the last commit was lost
+at unmount: read errors, checksum failures, and read repair, which writes
+outside any transaction. After the patch, the transaction kthread starts
+and commits a transaction at its commit interval, and `btrfs_commit_super()`
+does the same at unmount and at remount read-only. This happens only when
+some device's stats are dirty, the filesystem was mounted read-write, and it
+is not read-only, frozen, shut down or in an error state. Read-only mounts
+still lose the counts.
+
+To verify, a test must show the following.
+- A count made by a cold read on a read-write mount reaches the on-disk item
+ in each case: at unmount, after an idle commit interval while still
+ mounted, and at remount read-only.
+- Nothing is written while the filesystem is frozen, and the count is
+ written after thaw.
+- A clean, idle filesystem gets no commits.
+- A read-only mount still loses the count, as documented.
+
+The symptom before the patch is on-disk corruption_errs unchanged after
+unmount, while `btrfs device stats` showed the new count before it.
+
+Promoted 2026-10-21: misc-next topic 55ade1cf195c, 6.18 topic 39b62b24ca95.
+The lane heads are zb64 e2c9218febf9 (misc-next) and c44a989df38f (6.18).
+Their fs/btrfs trees are identical to those of the tested candidates,
+90462373d107 and 20de268229cb (`refs/cand/j-devstat/*`).
+
+Kernel under test for the "Current" column: misc-next candidate zb64
+90462373d107 (zb64 3e1390a9de03 plus this patch, KASAN with
+`config-r5fix-mn-kasan`, uname 7.3.0-rc7+ #1), on ehive. The negative
+control is misc-next zb64 568c45b64012 (uname 7.3.0-rc7+ #5, KASAN), which
+does not have the patch.
+
+## Existing tests
+
+None. No harness test checked that device stats persist. The scrub and
+raid56 dev-stats tests (raid56-devstats, scrub-blame) read the in-memory
+counters only.
+
+## New tests
+
+| test | verifies | patch(es) | duration | last result | date | kernel | harness | evidence |
+|---|---|---|---|---|---|---|---|---|
+| `devstats-persist-test.sh` (single, raid1, raid5; arms F U K I R Z O) | counts made without a transaction reach the dev stats items; clean idle fs gets no commits; ro mount loses the counts | 1 | ~2 min per profile | PASS on every arm and profile, no KASAN/WARN/BUG | 2026-10-20 | misc-next cand zb64 90462373d107 (#1) | 936b15e | forensics/j-devstat-20261020/cand/, cand.log |
+| same, negative control | the count is lost without the patch | - | ~2 min per profile | FAIL as expected: U K R Z lose the count on all three profiles (on disk 0, in memory 1-2); I and O PASS | 2026-10-20 | misc-next zb64 568c45b64012 (#5) | 936b15e | forensics/j-devstat-20261020/neg5/, neg5.log |
+| W=1 `make fs/btrfs/`, parent vs patch | no new warnings; the kernel links | 1 | - | misc-next: 2 warnings before and after, none new; 6.18: 3 and 3, none new; KASAN bzImage links on both | 2026-10-20 | mn 90462373d107, 618 20de268229cb | b808776 | forensics/j-devstat-20261020/w1-*.w, build-*.out |
+| `claimable-trim-miss-test.sh` TM_ITERS=1 (regression) | an unrelated stripe-alloc test still passes with extra commits | - | ~10 min | PASS (0 WARNs, 0 data failures) | 2026-10-20 | misc-next cand zb64 90462373d107 (#1) | 936b15e | forensics/j-devstat-20261020/regress-cand.log |
+| `unwritten-readback-test.sh` raid5, raid6 (regression) | as above | - | ~6 min per profile | FAIL on the scrub check only, identical on the bare lane, so not caused by this patch (see below) | 2026-10-21 | cand 90462373d107 (#1) and bare lane zb64 3e1390a9de03 (#2) | b808776 | forensics/j-devstat-20261020/urb-cand/, urb-base/ |
+
+**devstats-persist-test.sh.**
+
+Fixture:
+- Loop images per profile: single (1 device), raid1 (2), raid5 (3).
+- mkfs -K, mount -o nodiscard.
+- Block group reclaim set to 0 on every mount and reclaim-regimen stopped
+ for the run, so relocation cannot start transactions behind the test.
+- A setup mount writes one 1 MiB file.
+
+Before each arm, the file's first 4K is overwritten on one image while the
+filesystem is unmounted:
+- raid1: the copy on devid 1;
+- single: the only copy, which stays bad;
+- raid5: the member holding that data strip.
+
+The arm mounts the filesystem fresh and reads the file cold. On raid1 it
+re-reads with new processes until the bad mirror is hit. The oracle compares
+two sources: the on-disk dev stats items, read with `dump-tree -t dev` after
+`blockdev --flushbufs`, and the in-memory counters from `btrfs device stats`.
+
+The arms:
+- **U**: commit=600, unmount right after the read. Tests the close_ctree
+ path.
+- **K**: commit=5, idle for 12 s while mounted. Tests the kthread.
+- **I**: clean filesystem, idle for 3 intervals. `commit_stats` and the
+ superblock generation must not change.
+- **R**: remount read-only after the read.
+- **Z**: freeze right after the read. The on-disk stats must not change
+ for 12 s while frozen, and the count must be written within 12 s after
+ thaw.
+- **O**: read-only mount. The count must rise in memory and the on-disk
+ item must stay unchanged.
+- **F** (report only): commits on a fresh filesystem's first idle mount.
+ The result is 1 on both kernels, so writing the missing dev stats items
+ adds no visible commit.
+
+Results:
+- On the candidate every arm passed on every profile. The on-disk counts
+ equal the in-memory counts after U, K, R and thaw, and the clean idle
+ filesystem made 0 commits.
+- On #5, U, K, R and Z failed on every profile (on disk 0, in memory 1 or
+ 2), which shows the test can fail.
+
+Limits:
+- Only corruption_errs from a data read is exercised. The other counters
+ and other counting paths (scrub, replace, write errors) take the same
+ commit path but are not driven here.
+- The 6.18 candidate was built and passed W=1, but it was not booted.
+- Crash and shutdown losses are documented, not tested.
+
+**unwritten-readback regression.**
+
+The test failed only at its "scrub: no errors" check, on raid5 and raid6.
+The bare lane zb64 3e1390a9de03, built with the same config, fails in the
+same way. The `scrub status -dR` fields are the same on both kernels:
+- raid5: corrected_errors 96 / 96 / 24 / 0 on devids 1-4, a total of 216.
+- raid6: corrected_errors 88 / 96 / 80 / 88 / 80, a total of 432, which is
+ 2 x 216 (P and Q).
+- read, csum, verify and uncorrectable errors are 0 everywhere.
+
+The progs summary line "3 corrected" counts devices with corrections, not
+errors.
+
+The 216 corrected sectors are the stale parity rows of the never-written
+tail stripes:
+- 12 whole-tail stripes (6 from arm R, 6 from arm C) x 16 rows;
+- plus the 3 arm-C Z stripes x 8 tail rows.
+
+#5 rewrote these rows without counting them. The lane's "count raid56
+parity mismatches as corruption errors" now counts them. The test's oracle
+needs updating; the lead is arranging that.
+
+## Not covered / open
+
+- 6.18 runtime: the 6.18 candidate was not booted.
+- Counters other than corruption_errs from reads are not tested, and
+ neither are concurrent device add or remove during the kthread's RCU walk.
+- Behaviour change: an otherwise read-only workload on a read-write mount
+ now causes commits and metadata writes when errors were counted. The
+ commit message tells reviewers they may reasonably reject it.
+- **Questions for Zygo:** none.