[PATCH 0/3] kmemleak: fix stale documentation and raise the verbose default

[PATCH 0/3] kmemleak: fix stale documentation and raise the verbose default

[Breno Leitao]

The first two patches fix statements in
Documentation/dev-tools/kmemleak.rst that do not match mm/kmemleak.c.

The third requires one more consecutive unreferenced scan before a
CONFIG_DEBUG_KMEMLEAK_VERBOSE kernel reports a leak on the console, to
avoid the last false positives I am seeing when running
CONFIG_DEBUG_KMEMLEAK_VERBOSE on a daily basis.

Signed-off-by: Breno Leitao <leitao@debian.org>
---
Breno Leitao (3):
      Documentation: kmemleak: describe the metadata pool, not the early log
      Documentation: kmemleak: fix stale statements about scanning
      mm: kmemleak: raise min_unref_scans to 3 for verbose auto-scan

 Documentation/dev-tools/kmemleak.rst | 24 ++++++++++++++++--------
 mm/kmemleak.c                        |  2 +-
 2 files changed, 17 insertions(+), 9 deletions(-)
---
base-commit: 587858367581b9c55c3690f4e63382ad622719d4
change-id: 20260917-b4-kmemleak-doc-1232546f4225

Best regards,
--  
Breno Leitao <leitao@debian.org>

[PATCH 1/3] Documentation: kmemleak: describe the metadata pool, not the early log

[Breno Leitao]

commit c5665868183f ("mm: kmemleak: use the memory pool for early
allocations") removed the early log buffer in favour of a static pool of
kmemleak_object structures, but the documentation still describes the
old mechanism.

Fix the documentation by describing what the pool actually is, matching
the Kconfig help text.

Fixes: c5665868183f ("mm: kmemleak: use the memory pool for early allocations")
Signed-off-by: Breno Leitao <leitao@debian.org>
---
 Documentation/dev-tools/kmemleak.rst | 11 ++++++++---
 1 file changed, 8 insertions(+), 3 deletions(-)

diff --git a/Documentation/dev-tools/kmemleak.rst b/Documentation/dev-tools/kmemleak.rst
index d1b690b171696..8dad7647742d3 100644
--- a/Documentation/dev-tools/kmemleak.rst
+++ b/Documentation/dev-tools/kmemleak.rst
@@ -66,9 +66,14 @@ Memory scanning parameters can be modified at run-time by writing to the
 Kmemleak can also be disabled at boot-time by passing ``kmemleak=off`` on
 the kernel command line.
 
-Memory may be allocated or freed before kmemleak is initialised and
-these actions are stored in an early log buffer. The size of this buffer
-is configured via the CONFIG_DEBUG_KMEMLEAK_MEM_POOL_SIZE option.
+Memory may be allocated or freed before kmemleak is initialised, so a
+static pool of metadata objects is used to track those allocations. Once
+kmemleak is fully initialised the pool becomes an emergency reserve, used
+whenever a metadata object cannot be allocated from the slab. The number
+of objects in the pool is configured via the
+CONFIG_DEBUG_KMEMLEAK_MEM_POOL_SIZE option. Exhausting it at run time
+prints "Cannot allocate a kmemleak_object structure" and disables
+kmemleak.
 
 If CONFIG_DEBUG_KMEMLEAK_DEFAULT_OFF are enabled, the kmemleak is
 disabled by default. Passing ``kmemleak=on`` on the kernel command

-- 
2.53.0-Meta

Re: [PATCH 1/3] Documentation: kmemleak: describe the metadata pool, not the early log

[Catalin Marinas]

On Thu, Sep 17, 2026 at 06:47:35AM -0700, Breno Leitao wrote:
> commit c5665868183f ("mm: kmemleak: use the memory pool for early
> allocations") removed the early log buffer in favour of a static pool of
> kmemleak_object structures, but the documentation still describes the
> old mechanism.
> 
> Fix the documentation by describing what the pool actually is, matching
> the Kconfig help text.
> 
> Fixes: c5665868183f ("mm: kmemleak: use the memory pool for early allocations")
> Signed-off-by: Breno Leitao <leitao@debian.org>

Reviewed-by: Catalin Marinas <catalin.marinas@arm.com>

[PATCH 2/3] Documentation: kmemleak: fix stale statements about scanning

[Breno Leitao]

Three statements in the "false positives/negatives" and "Limitations"
sections have never matched the code:

 - task stack scanning is on by default (kmemleak_stack_scan = 1), as
   the parameter list earlier in the same document already states;

 - MSECS_MIN_AGE has been 5000, not 1000, since the initial commit;

 - scanning is done by a periodic kthread. Reading the debugfs file
   only lists what the last scan found; kmemleak_open() calls
   seq_open() and never scans.

Fixes: 04f70336c80c ("kmemleak: Add documentation on the memory leak detector")
Fixes: e0a2a1601bec ("kmemleak: Enable task stacks scanning by default")
Signed-off-by: Breno Leitao <leitao@debian.org>
---
 Documentation/dev-tools/kmemleak.rst | 11 +++++++----
 1 file changed, 7 insertions(+), 4 deletions(-)

diff --git a/Documentation/dev-tools/kmemleak.rst b/Documentation/dev-tools/kmemleak.rst
index 8dad7647742d3..b5fe7e671d0f8 100644
--- a/Documentation/dev-tools/kmemleak.rst
+++ b/Documentation/dev-tools/kmemleak.rst
@@ -190,7 +190,8 @@ reported by kmemleak because values found during the memory scanning
 point to such objects. To reduce the number of false negatives, kmemleak
 provides the kmemleak_ignore, kmemleak_scan_area, kmemleak_no_scan and
 kmemleak_erase functions (see above). The task stacks also increase the
-amount of false negatives and their scanning is not enabled by default.
+amount of false negatives and their scanning is enabled by default; it
+can be turned off with ``stack=off``.
 
 The false positives are objects wrongly reported as being memory leaks
 (orphan). For objects known not to be leaks, kmemleak provides the
@@ -200,7 +201,7 @@ longer be scanned.
 
 Some of the reported leaks are only transient, especially on SMP
 systems, because of pointers temporarily stored in CPU registers or
-stacks. Kmemleak defines MSECS_MIN_AGE (defaulting to 1000) representing
+stacks. Kmemleak defines MSECS_MIN_AGE (defaulting to 5000) representing
 the minimum age of an object to be reported as a memory leak.
 
 The ``min_unref_scans`` module parameter requires an object to be seen
@@ -217,8 +218,10 @@ Limitations and Drawbacks
 -------------------------
 
 The main drawback is the reduced performance of memory allocation and
-freeing. To avoid other penalties, the memory scanning is only performed
-when the /sys/kernel/debug/kmemleak file is read. Anyway, this tool is
+freeing. To avoid other penalties, the memory scanning is performed by a
+periodic thread rather than on every allocation. Reading the
+/sys/kernel/debug/kmemleak file only lists the objects found by the last
+scan; writing ``scan`` to it triggers a new one. Anyway, this tool is
 intended for debugging purposes where the performance might not be the
 most important requirement.
 

-- 
2.53.0-Meta

Re: [PATCH 2/3] Documentation: kmemleak: fix stale statements about scanning

[Catalin Marinas]

On Thu, Sep 17, 2026 at 06:47:36AM -0700, Breno Leitao wrote:
> Three statements in the "false positives/negatives" and "Limitations"
> sections have never matched the code:
> 
>  - task stack scanning is on by default (kmemleak_stack_scan = 1), as
>    the parameter list earlier in the same document already states;
> 
>  - MSECS_MIN_AGE has been 5000, not 1000, since the initial commit;
> 
>  - scanning is done by a periodic kthread. Reading the debugfs file
>    only lists what the last scan found; kmemleak_open() calls
>    seq_open() and never scans.
> 
> Fixes: 04f70336c80c ("kmemleak: Add documentation on the memory leak detector")
> Fixes: e0a2a1601bec ("kmemleak: Enable task stacks scanning by default")
> Signed-off-by: Breno Leitao <leitao@debian.org>

Reviewed-by: Catalin Marinas <catalin.marinas@arm.com>

[PATCH 3/3] mm: kmemleak: raise min_unref_scans to 3 for verbose auto-scan

[Breno Leitao]

CONFIG_DEBUG_KMEMLEAK_VERBOSE sends every report to the console, so a
transient false positive there is broadcast to whatever collects the
kernel log rather than sitting in the debugfs file until someone looks.
That asymmetry justifies being more conservative than the general case.

Require one more consecutive unreferenced scan before reporting. The
only cost is that a genuine leak is reported one scan interval later
(600s by default); the value stays writable at run time through the
module parameter.

Kernels without CONFIG_DEBUG_KMEMLEAK_VERBOSE keep reporting on the
first unreferenced scan.

I've been running constant upstream kernel with
CONFIG_DEBUG_KMEMLEAK_VERBOSE set, and I am still seeing some rare false
positive, that goes away with min_unref_scans=3, so, making it the
default based on my heuristic.

Signed-off-by: Breno Leitao <leitao@debian.org>
---
 Documentation/dev-tools/kmemleak.rst | 2 +-
 mm/kmemleak.c                        | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/dev-tools/kmemleak.rst b/Documentation/dev-tools/kmemleak.rst
index b5fe7e671d0f8..c0d3293723425 100644
--- a/Documentation/dev-tools/kmemleak.rst
+++ b/Documentation/dev-tools/kmemleak.rst
@@ -206,7 +206,7 @@ the minimum age of an object to be reported as a memory leak.
 
 The ``min_unref_scans`` module parameter requires an object to be seen
 unreferenced in that many consecutive scans before it is reported. It
-defaults to 2 when CONFIG_DEBUG_KMEMLEAK_VERBOSE is enabled, where the
+defaults to 3 when CONFIG_DEBUG_KMEMLEAK_VERBOSE is enabled, where the
 periodic scan thread confirms a leak on its own, and to 1 otherwise. A
 value of 1 preserves the historical behaviour; higher values filter the
 transient false positives described above, at the cost of delaying genuine
diff --git a/mm/kmemleak.c b/mm/kmemleak.c
index 8fa409a4f9fb2..5d0daea93c471 100644
--- a/mm/kmemleak.c
+++ b/mm/kmemleak.c
@@ -238,7 +238,7 @@ static struct task_struct *scan_thread;
 static unsigned long jiffies_min_age;
 /* consecutive scans an object must stay unreferenced before reporting */
 static unsigned int min_unref_scans =
-	IS_ENABLED(CONFIG_DEBUG_KMEMLEAK_VERBOSE) ? 2 : 1;
+	IS_ENABLED(CONFIG_DEBUG_KMEMLEAK_VERBOSE) ? 3 : 1;
 module_param(min_unref_scans, uint, 0644);
 static unsigned long jiffies_last_scan;
 /* delay between automatic memory scannings */

-- 
2.53.0-Meta

Re: [PATCH 3/3] mm: kmemleak: raise min_unref_scans to 3 for verbose auto-scan

[Andrew Morton]

On Thu, 17 Sep 2026 06:47:37 -0700 Breno Leitao <leitao@debian.org> wrote:

> CONFIG_DEBUG_KMEMLEAK_VERBOSE sends every report to the console, so a
> transient false positive there is broadcast to whatever collects the
> kernel log rather than sitting in the debugfs file until someone looks.
> That asymmetry justifies being more conservative than the general case.
> 
> Require one more consecutive unreferenced scan before reporting. The
> only cost is that a genuine leak is reported one scan interval later
> (600s by default); the value stays writable at run time through the
> module parameter.
> 
> Kernels without CONFIG_DEBUG_KMEMLEAK_VERBOSE keep reporting on the
> first unreferenced scan.
> 
> I've been running constant upstream kernel with
> CONFIG_DEBUG_KMEMLEAK_VERBOSE set, and I am still seeing some rare false
> positive, that goes away with min_unref_scans=3, so, making it the
> default based on my heuristic.

I'm guessing going from 2 to 3 reduces the false-positive reporting
rate, but they're still possible.

It all sounds rather rubbery.  Why do these false positives occur,
anyway?  Are we papering over a fundamental problem by filtering out
its user-visible effects?

Re: [PATCH 3/3] mm: kmemleak: raise min_unref_scans to 3 for verbose auto-scan

[Catalin Marinas]

On Thu, Sep 17, 2026 at 03:04:43PM -0700, Andrew Morton wrote:
> On Thu, 17 Sep 2026 06:47:37 -0700 Breno Leitao <leitao@debian.org> wrote:
> 
> > CONFIG_DEBUG_KMEMLEAK_VERBOSE sends every report to the console, so a
> > transient false positive there is broadcast to whatever collects the
> > kernel log rather than sitting in the debugfs file until someone looks.
> > That asymmetry justifies being more conservative than the general case.
> > 
> > Require one more consecutive unreferenced scan before reporting. The
> > only cost is that a genuine leak is reported one scan interval later
> > (600s by default); the value stays writable at run time through the
> > module parameter.
> > 
> > Kernels without CONFIG_DEBUG_KMEMLEAK_VERBOSE keep reporting on the
> > first unreferenced scan.
> > 
> > I've been running constant upstream kernel with
> > CONFIG_DEBUG_KMEMLEAK_VERBOSE set, and I am still seeing some rare false
> > positive, that goes away with min_unref_scans=3, so, making it the
> > default based on my heuristic.
> 
> I'm guessing going from 2 to 3 reduces the false-positive reporting
> rate, but they're still possible.
> 
> It all sounds rather rubbery.  Why do these false positives occur,
> anyway?  Are we papering over a fundamental problem by filtering out
> its user-visible effects?

The fundamental problem is that we can't do a stop-machine for the
kmemleak scanning. When scanning takes tens of seconds, pointers may
move around memory or registers on other CPUs, so kmemleak could miss
them. It's all probabilistic, hoping that we won't hit the same object
two or three times in a row, 10min apart (for lack of better ideas). We
have other heuristics like checksumming but they don't seem to be
sufficient when testing on a large scale.

-- 
Catalin

Re: [PATCH 3/3] mm: kmemleak: raise min_unref_scans to 3 for verbose auto-scan

[Breno Leitao]

On Fri, Sep 18, 2026 at 10:21:09AM +0100, Catalin Marinas wrote:
> On Thu, Sep 17, 2026 at 03:04:43PM -0700, Andrew Morton wrote:
> > On Thu, 17 Sep 2026 06:47:37 -0700 Breno Leitao <leitao@debian.org> wrote:
> >
> > > CONFIG_DEBUG_KMEMLEAK_VERBOSE sends every report to the console, so a
> > > transient false positive there is broadcast to whatever collects the
> > > kernel log rather than sitting in the debugfs file until someone looks.
> > > That asymmetry justifies being more conservative than the general case.
> > >
> > > Require one more consecutive unreferenced scan before reporting. The
> > > only cost is that a genuine leak is reported one scan interval later
> > > (600s by default); the value stays writable at run time through the
> > > module parameter.
> > >
> > > Kernels without CONFIG_DEBUG_KMEMLEAK_VERBOSE keep reporting on the
> > > first unreferenced scan.
> > >
> > > I've been running constant upstream kernel with
> > > CONFIG_DEBUG_KMEMLEAK_VERBOSE set, and I am still seeing some rare false
> > > positive, that goes away with min_unref_scans=3, so, making it the
> > > default based on my heuristic.
> >
> > I'm guessing going from 2 to 3 reduces the false-positive reporting
> > rate, but they're still possible.
> >
> > It all sounds rather rubbery.  Why do these false positives occur,
> > anyway?  Are we papering over a fundamental problem by filtering out
> > its user-visible effects?
>
> The fundamental problem is that we can't do a stop-machine for the
> kmemleak scanning. When scanning takes tens of seconds, pointers may
> move around memory or registers on other CPUs, so kmemleak could miss
> them. It's all probabilistic, hoping that we won't hit the same object
> two or three times in a row, 10min apart (for lack of better ideas). We
> have other heuristics like checksumming but they don't seem to be
> sufficient when testing on a large scale.

In fact, in my investigation there's only a single use case where I
actually see this false positive, which go away with this new approch.

And I have a very solidy test setup where linux-next is deployed daily
and run for 24 hours, until the next kernel replaces it. This is on real
hardware with some basic workloads, so, in fact the false positive
(given the design above) is quite low.

Re: [PATCH 3/3] mm: kmemleak: raise min_unref_scans to 3 for verbose auto-scan

[Catalin Marinas]

On Thu, Sep 17, 2026 at 06:47:37AM -0700, Breno Leitao wrote:
> CONFIG_DEBUG_KMEMLEAK_VERBOSE sends every report to the console, so a
> transient false positive there is broadcast to whatever collects the
> kernel log rather than sitting in the debugfs file until someone looks.
> That asymmetry justifies being more conservative than the general case.
> 
> Require one more consecutive unreferenced scan before reporting. The
> only cost is that a genuine leak is reported one scan interval later
> (600s by default); the value stays writable at run time through the
> module parameter.
> 
> Kernels without CONFIG_DEBUG_KMEMLEAK_VERBOSE keep reporting on the
> first unreferenced scan.
> 
> I've been running constant upstream kernel with
> CONFIG_DEBUG_KMEMLEAK_VERBOSE set, and I am still seeing some rare false
> positive, that goes away with min_unref_scans=3, so, making it the
> default based on my heuristic.
> 
> Signed-off-by: Breno Leitao <leitao@debian.org>

Until someone comes up with a better idea to reduce the false positives,

Reviewed-by: Catalin Marinas <catalin.marinas@arm.com>