mm/kmemleak: add min_unref_scans to suppress transient false positives

kmemleak reports an object the first scan it is found unreferenced. Its mark phase runs without stopping the rest of the kernel and without a write barrier, so a live object whose only reference is briefly invisible during a concurrent RCU update -- e.g. a VMA moved between maple tree nodes, or a page-cache xa_node -- can be seen as unreferenced for that one scan. Because an object is flagged as reported only once, such a transient race turns into a permanent false positive.

Track how many consecutive scans each object has been seen unreferenced and only report it once that reaches min_unref_scans, a new module parameter. It defaults to 1, leaving the behaviour unchanged; setting it higher (e.g. 2) still reports a genuine leak, one scan later, while an object referenced again before the threshold restarts its run and is never reported.

min_unref_scans can be set at boot with kmemleak.min_unref_scans=<n> or at run-time via /sys/module/kmemleak/parameters/min_unref_scans.

Signed-off-by Breno Leitao <[email protected]>

mm/kmemleak.c +2 -0

index 7c7ba17ce7af0..5b14ccb36f95b 100644
@@ -151,6 +151,8 @@ struct kmemleak_object {
 	int min_count;
 	/* the total number of pointers found pointing to this object */
 	int count;
+	/* consecutive scans the object has been seen unreferenced */
+	unsigned int unref_scans;
 	/* checksum for detecting modified objects */
 	u32 checksum;
 	depot_stack_handle_t trace_handle;

tools/testing/selftests/mm/ksft_kmemleak_confirm.sh new file +101 -0

@@ -0,0 +1,111 @@
+#!/bin/bash
+# SPDX-License-Identifier: GPL-2.0
+#
+# Functional test for kmemleak's N-consecutive-scan leak confirmation
+# (the min_unref_scans module parameter).
+#
+# kmemleak only reports an object once it has stayed unreferenced for
+# min_unref_scans consecutive scans. The default of 1 reports on the first
+# scan (historical behaviour); higher values filter transient false
+# positives where a live object's only reference is briefly invisible to a
+# single scan (e.g. an RCU tree update in flight while the scan runs). The
+# test loads samples/kmemleak's helper module to create orphan allocations
+# and, counting only those orphans (matched by their [kmemleak_test]
+# backtrace so unrelated leaks already present on the system are ignored),
+# checks that:
+#   - min_unref_scans=1 reports them on the first scan,
+#   - min_unref_scans=2 reports nothing on the first scan but does on the
+#     second,
+#   - the parameter reads back what was written.
+#
+# The "nothing on the first scan" check is the core regression test: with
+# min_unref_scans=2 no object can be reported in fewer than two scans. Like
+# ksft_kmemleak_dedup.sh, if the module yields no detectable orphan at all
+# in the running environment the test skips rather than failing.
+#
+# Author: Breno Leitao <[email protected]>
+
+ksft_skip=4
+KMEMLEAK=/sys/kernel/debug/kmemleak
+PARAM=/sys/module/kmemleak/parameters/min_unref_scans
+MODULE=kmemleak-test
+AGE=6		# seconds; must exceed kmemleak's 5s minimum object age
+
+skip() { echo "SKIP: $*"; exit $ksft_skip; }
+fail() { echo "FAIL: $*"; exit 1; }
+pass() { echo "PASS: $*"; exit 0; }
+
+[ "$(id -u)" -eq 0 ] || skip "must run as root"
+[ -r "$KMEMLEAK" ] || skip "no kmemleak debugfs (CONFIG_DEBUG_KMEMLEAK)"
+[ -w "$PARAM" ] || skip "min_unref_scans module parameter not present"
+modinfo "$MODULE" >/dev/null 2>&1 ||
+	skip "$MODULE not built (CONFIG_SAMPLE_KMEMLEAK)"
+
+# kmemleak can be present but disabled at runtime (kmemleak=off boot arg,
+# or it self-disabled after an internal error); a "scan" then returns
+# EPERM. Probe once and skip if so.
+echo scan > "$KMEMLEAK" 2>/dev/null ||
+	skip "kmemleak is disabled (check dmesg or kmemleak= boot arg)"
+
+prev=$(cat "$PARAM")
+# shellcheck disable=SC2317  # invoked indirectly via trap
+cleanup() {
+	echo "$prev" > "$PARAM" 2>/dev/null		# restore the parameter
+	echo scan=on > "$KMEMLEAK" 2>/dev/null		# re-enable auto scan
+	rmmod "$MODULE" 2>/dev/null
+	echo clear > "$KMEMLEAK" 2>/dev/null
+}
+trap cleanup EXIT
+
+# Stop the automatic scan thread: only our manual scans should advance an
+# object's consecutive-unreferenced run. An auto scan landing between two
+# manual scans would change the result and make the test flaky.
+echo scan=off > "$KMEMLEAK" 2>/dev/null
+
+# Create a fresh, aged set of orphan objects from the helper module's init
+# path (its kmalloc/vmalloc/percpu allocations are dropped right away).
+# Pre-existing reported leaks are greyed first ("clear") so only our
+# orphans are counted. The module is left loaded on purpose: once it is
+# unloaded its symbols are gone, so the orphan backtraces no longer resolve
+# to [kmemleak_test] and could not be matched below.
+gen_orphans() {
+	rmmod "$MODULE" 2>/dev/null
+	echo clear > "$KMEMLEAK"
+	modprobe "$MODULE" || skip "failed to load $MODULE"
+	sleep "$AGE"
+}
+
+scan() { echo scan > "$KMEMLEAK"; }
+
+# Number of helper-module orphans currently reported by kmemleak. Matching
+# the module's own backtrace ([kmemleak_test]) keeps the count immune to
+# unrelated leaks on the running system. kmemleak only lists an object here
+# once it has been reported, so this reflects the confirmation gating.
+count_orphans() {
+	c=$(grep -c '\[kmemleak_test\]' "$KMEMLEAK" 2>/dev/null)
+	echo "${c:-0}"
+}
+
+# 0) the parameter reads back what was written.
+echo 3 > "$PARAM"
+[ "$(cat "$PARAM")" = "3" ] || fail "min_unref_scans did not read back as 3"
+
+# 1) min_unref_scans=1 (default): orphans reported on the first scan. This
+#    also establishes that the helper produces detectable orphans here.
+echo 1 > "$PARAM"
+gen_orphans
+scan
+first=$(count_orphans)
+[ "$first" -gt 0 ] ||
+	skip "$MODULE produced no detectable orphans (cannot test min_unref_scans)"
+

Quoted 1 line · Breno Leitao

+pass "min_unref_scans=1 immediate; =2 gated to 2nd scan (counts $first/$s1/$s2); param read-back ok"

Are these off by one?

Kmemleak has a mechanism to detect live objects
via the checksum. A side effect is that on allocation, the checksum is 0 and only after the first scan the checksum is changed.

On checksum mismatch (i.e. the first scan), we mark the object gray temporarily and won't increment unref_scans. So we already have an implicit two scans required to report an object as unreferenced during its early life.

I think this test needs a priming scan to update the checksums followed by the actual check for min_unref_scans (with scan=off, otherwise random scanning will skew the results).

Quoted 4 lines · Catalin Marinas

Quoted 1 line · Breno Leitao

+pass "min_unref_scans=1 immediate; =2 gated to 2nd scan (counts $first/$s1/$s2); param read-back ok"

Are these off by one?

They seem to be OK, and I've tested it multiple times.

Quoted 3 lines

Kmemleak has a mechanism to detect live objects
via the checksum. A side effect is that on allocation, the checksum is 0 and only after the first scan the checksum is changed.

I got the impression that checksum continues to be zero for these objects during the whole life time? (weird).

Quoted 6 lines · Breno Leitao

Quoted 4 lines · Catalin Marinas

Quoted 1 line · Breno Leitao

+pass "min_unref_scans=1 immediate; =2 gated to 2nd scan (counts $first/$s1/$s2); param read-back ok"

Are these off by one?

Quoted 8 lines

They seem to be OK, and I've tested it multiple times.

Quoted 3 lines

Kmemleak has a mechanism to detect live objects
via the checksum. A side effect is that on allocation, the checksum is 0 and only after the first scan the checksum is changed.

I got the impression that checksum continues to be zero for these objects during the whole life time? (weird).

I've investigated this a bit more and I found something interesting, in our per_pcu checksum. The code in update_checksum() is:

	for_each_possible_cpu(cpu) {
		void *ptr = per_cpu_ptr((void __percpu *)object->pointer, cpu);

		object->checksum ^= crc32(0, kasan_reset_tag((void *)ptr), object->size);
	}

From my naive view, this has two concerns:

1) In the kernel, crc32(0, <64 zero bytes>, 64) is zero, and the samples' test I am using (kmemleak-test.c) has:

	pr_info("__alloc_percpu(64, 4) = 0x%px\n", __alloc_percpu(64, 4)); 

alloc_percpu returns ZEROed memory, so, we are checkingsuming zero content. Because we are using 0 as seed, that is returning zero.

object->checksum is a bunch of 0 XOR 0 XOR 0 and so forth.

2) that XOR above seems very weird. Basically we want to detect if some of
those per-cpu areas changed, here, but, if checksum goes to zero if two object content is similar.

Let me give you a simple example. We have SMP=2, and both objects have crc32 = 0x42. At the end of that function, object->checksum will be zero, given 0x42 XOR 0x42 is zero.

If both object changes their content at the same time, object->checksum will continue to be zero (although the content (and checksum) HAS changed).

I understand we want to detect any change in any of these per cpu field and catch it independent of the CPU. I am inclined toward that.

	--- a/mm/kmemleak.c
	+++ b/mm/kmemleak.c
	@@ -1409,8 +1409,9 @@ static bool update_checksum(struct kmemleak_object *object)
			object->checksum = 0;
			for_each_possible_cpu(cpu) {
				void *ptr = per_cpu_ptr((void __percpu *)object->pointer, cpu);
	+                       u32 seed = object->checksum + cpu;

	-                       object->checksum ^= crc32(0, kasan_reset_tag((void *)ptr), object->size);
	+                       object->checksum ^= crc32(seed, kasan_reset_tag((void *)ptr), object->size);

Quoted 13 lines

I understand we want to detect any change in any of these per cpu field and catch it independent of the CPU. I am inclined toward that.

	--- a/mm/kmemleak.c
	+++ b/mm/kmemleak.c
	@@ -1409,8 +1409,9 @@ static bool update_checksum(struct kmemleak_object *object)
			object->checksum = 0;
			for_each_possible_cpu(cpu) {
				void *ptr = per_cpu_ptr((void __percpu *)object->pointer, cpu);
	+                       u32 seed = object->checksum + cpu;

	-                       object->checksum ^= crc32(0, kasan_reset_tag((void *)ptr), object->size);
	+                       object->checksum ^= crc32(seed, kasan_reset_tag((void *)ptr), object->size);

Yeah, the xor wasn't a great idea. What about initialising the checksum value on object allocation to ~0 (for the two-scans idea) and for per-cpu, just build the crc on top of the previous crc, something like:

mm/kmemleak.c +2 -2

index 7c7ba17ce7af..e196f53f9b46 100644
@@ -687,7 +687,7 @@ static struct kmemleak_object *__alloc_object(gfp_t gfp)
 	atomic_set(&object->use_count, 1);
 	object->excess_ref = 0;
 	object->count = 0;			/* white color initially */
-	object->checksum = 0;
+	object->checksum = ~0;
 	object->del_state = 0;
 
 	/* task information */

@@ -981,7 +981,7 @@ static void reset_checksum(unsigned long ptr)
 	}
 
 	raw_spin_lock_irqsave(&object->lock, flags);
-	object->checksum = 0;
+	object->checksum = ~0;
 	raw_spin_unlock_irqrestore(&object->lock, flags);
 	put_object(object);
 }

On Fri, Jul 03, 2026 at 03:55:52PM +0100, Catalin Marinas wrote:

I will spin this "fix" separated (CCing stable), and send a v2 for this selftest with priming enabled.