From patchwork Mon Aug 8 23:35:00 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jonathan Corbet X-Patchwork-Id: 73491 Delivered-To: patch@linaro.org Received: by 10.140.29.52 with SMTP id a49csp210267qga; Mon, 8 Aug 2016 16:36:51 -0700 (PDT) X-Received: by 10.98.129.5 with SMTP id t5mr166080009pfd.32.1470699411804; Mon, 08 Aug 2016 16:36:51 -0700 (PDT) Return-Path: Received: from vger.kernel.org (vger.kernel.org. [209.132.180.67]) by mx.google.com with ESMTP id g4si39333939pax.227.2016.08.08.16.36.51; Mon, 08 Aug 2016 16:36:51 -0700 (PDT) Received-SPF: pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67; Authentication-Results: mx.google.com; spf=pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1752581AbcHHXgl (ORCPT + 27 others); Mon, 8 Aug 2016 19:36:41 -0400 Received: from tex.lwn.net ([70.33.254.29]:44621 "EHLO vena.lwn.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1752288AbcHHXf1 (ORCPT ); Mon, 8 Aug 2016 19:35:27 -0400 Received: from localhost.localdomain (localhost.localdomain [127.0.0.1]) by vena.lwn.net (Postfix) with ESMTP id 9F9AA154004D; Mon, 8 Aug 2016 17:35:26 -0600 (MDT) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Jani Nikula , Jonathan Corbet , Catalin Marinas Subject: [PATCH 08/10] docs: sphinxify kmemleak.txt and move it to dev-tools Date: Mon, 8 Aug 2016 17:35:00 -0600 Message-Id: <20160808233502.16950-9-corbet@lwn.net> X-Mailer: git-send-email 2.9.2 In-Reply-To: <20160808233502.16950-1-corbet@lwn.net> References: <20160808233502.16950-1-corbet@lwn.net> Sender: linux-kernel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Cc: Catalin Marinas Signed-off-by: Jonathan Corbet --- .../{kmemleak.txt => dev-tools/kmemleak.rst} | 93 ++++++++++++---------- Documentation/dev-tools/tools.rst | 1 + MAINTAINERS | 2 +- 3 files changed, 52 insertions(+), 44 deletions(-) rename Documentation/{kmemleak.txt => dev-tools/kmemleak.rst} (73%) -- 2.9.2 Acked-by: Catalin Marinas diff --git a/Documentation/kmemleak.txt b/Documentation/dev-tools/kmemleak.rst similarity index 73% rename from Documentation/kmemleak.txt rename to Documentation/dev-tools/kmemleak.rst index 18e24ab..1788722 100644 --- a/Documentation/kmemleak.txt +++ b/Documentation/dev-tools/kmemleak.rst @@ -1,15 +1,12 @@ Kernel Memory Leak Detector =========================== -Introduction ------------- - Kmemleak provides a way of detecting possible kernel memory leaks in a way similar to a tracing garbage collector (https://en.wikipedia.org/wiki/Garbage_collection_%28computer_science%29#Tracing_garbage_collectors), with the difference that the orphan objects are not freed but only reported via /sys/kernel/debug/kmemleak. A similar method is used by the -Valgrind tool (memcheck --leak-check) to detect the memory leaks in +Valgrind tool (``memcheck --leak-check``) to detect the memory leaks in user-space applications. Kmemleak is supported on x86, arm, powerpc, sparc, sh, microblaze, ppc, mips, s390, metag and tile. @@ -19,20 +16,20 @@ Usage CONFIG_DEBUG_KMEMLEAK in "Kernel hacking" has to be enabled. A kernel thread scans the memory every 10 minutes (by default) and prints the number of new unreferenced objects found. To display the details of all -the possible memory leaks: +the possible memory leaks:: # mount -t debugfs nodev /sys/kernel/debug/ # cat /sys/kernel/debug/kmemleak -To trigger an intermediate memory scan: +To trigger an intermediate memory scan:: # echo scan > /sys/kernel/debug/kmemleak -To clear the list of all current possible memory leaks: +To clear the list of all current possible memory leaks:: # echo clear > /sys/kernel/debug/kmemleak -New leaks will then come up upon reading /sys/kernel/debug/kmemleak +New leaks will then come up upon reading ``/sys/kernel/debug/kmemleak`` again. Note that the orphan objects are listed in the order they were allocated @@ -40,22 +37,31 @@ and one object at the beginning of the list may cause other subsequent objects to be reported as orphan. Memory scanning parameters can be modified at run-time by writing to the -/sys/kernel/debug/kmemleak file. The following parameters are supported: - - off - disable kmemleak (irreversible) - stack=on - enable the task stacks scanning (default) - stack=off - disable the tasks stacks scanning - scan=on - start the automatic memory scanning thread (default) - scan=off - stop the automatic memory scanning thread - scan= - set the automatic memory scanning period in seconds - (default 600, 0 to stop the automatic scanning) - scan - trigger a memory scan - clear - clear list of current memory leak suspects, done by - marking all current reported unreferenced objects grey, - or free all kmemleak objects if kmemleak has been disabled. - dump= - dump information about the object found at - -Kmemleak can also be disabled at boot-time by passing "kmemleak=off" on +``/sys/kernel/debug/kmemleak`` file. The following parameters are supported: + +- off + disable kmemleak (irreversible) +- stack=on + enable the task stacks scanning (default) +- stack=off + disable the tasks stacks scanning +- scan=on + start the automatic memory scanning thread (default) +- scan=off + stop the automatic memory scanning thread +- scan= + set the automatic memory scanning period in seconds + (default 600, 0 to stop the automatic scanning) +- scan + trigger a memory scan +- clear + clear list of current memory leak suspects, done by + marking all current reported unreferenced objects grey, + or free all kmemleak objects if kmemleak has been disabled. +- dump= + dump information about the object found at + +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 @@ -63,13 +69,14 @@ these actions are stored in an early log buffer. The size of this buffer is configured via the CONFIG_DEBUG_KMEMLEAK_EARLY_LOG_SIZE option. If CONFIG_DEBUG_KMEMLEAK_DEFAULT_OFF are enabled, the kmemleak is -disabled by default. Passing "kmemleak=on" on the kernel command +disabled by default. Passing ``kmemleak=on`` on the kernel command line enables the function. Basic Algorithm --------------- -The memory allocations via kmalloc, vmalloc, kmem_cache_alloc and +The memory allocations via :c:func:`kmalloc`, :c:func:`vmalloc`, +:c:func:`kmem_cache_alloc` and friends are traced and the pointers, together with additional information like size and stack trace, are stored in a rbtree. The corresponding freeing function calls are tracked and the pointers @@ -113,13 +120,13 @@ when doing development. To work around these situations you can use the you can find new unreferenced objects; this should help with testing specific sections of code. -To test a critical section on demand with a clean kmemleak do: +To test a critical section on demand with a clean kmemleak do:: # echo clear > /sys/kernel/debug/kmemleak ... test your kernel or modules ... # echo scan > /sys/kernel/debug/kmemleak -Then as usual to get your report with: +Then as usual to get your report with:: # cat /sys/kernel/debug/kmemleak @@ -131,7 +138,7 @@ disabled by the user or due to an fatal error, internal kmemleak objects won't be freed when kmemleak is disabled, and those objects may occupy a large part of physical memory. -In this situation, you may reclaim memory with: +In this situation, you may reclaim memory with:: # echo clear > /sys/kernel/debug/kmemleak @@ -140,20 +147,20 @@ Kmemleak API See the include/linux/kmemleak.h header for the functions prototype. -kmemleak_init - initialize kmemleak -kmemleak_alloc - notify of a memory block allocation -kmemleak_alloc_percpu - notify of a percpu memory block allocation -kmemleak_free - notify of a memory block freeing -kmemleak_free_part - notify of a partial memory block freeing -kmemleak_free_percpu - notify of a percpu memory block freeing -kmemleak_update_trace - update object allocation stack trace -kmemleak_not_leak - mark an object as not a leak -kmemleak_ignore - do not scan or report an object as leak -kmemleak_scan_area - add scan areas inside a memory block -kmemleak_no_scan - do not scan a memory block -kmemleak_erase - erase an old value in a pointer variable -kmemleak_alloc_recursive - as kmemleak_alloc but checks the recursiveness -kmemleak_free_recursive - as kmemleak_free but checks the recursiveness +- ``kmemleak_init`` - initialize kmemleak +- ``kmemleak_alloc`` - notify of a memory block allocation +- ``kmemleak_alloc_percpu`` - notify of a percpu memory block allocation +- ``kmemleak_free`` - notify of a memory block freeing +- ``kmemleak_free_part`` - notify of a partial memory block freeing +- ``kmemleak_free_percpu`` - notify of a percpu memory block freeing +- ``kmemleak_update_trace`` - update object allocation stack trace +- ``kmemleak_not_leak`` - mark an object as not a leak +- ``kmemleak_ignore`` - do not scan or report an object as leak +- ``kmemleak_scan_area`` - add scan areas inside a memory block +- ``kmemleak_no_scan`` - do not scan a memory block +- ``kmemleak_erase`` - erase an old value in a pointer variable +- ``kmemleak_alloc_recursive`` - as kmemleak_alloc but checks the recursiveness +- ``kmemleak_free_recursive`` - as kmemleak_free but checks the recursiveness Dealing with false positives/negatives -------------------------------------- diff --git a/Documentation/dev-tools/tools.rst b/Documentation/dev-tools/tools.rst index 2d11297..3b6382a 100644 --- a/Documentation/dev-tools/tools.rst +++ b/Documentation/dev-tools/tools.rst @@ -20,3 +20,4 @@ whole; patches welcome! gcov kasan ubsan + kmemleak diff --git a/MAINTAINERS b/MAINTAINERS index 2ffd7ed..b235e0d 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -6812,7 +6812,7 @@ F: mm/kmemcheck.c KMEMLEAK M: Catalin Marinas S: Maintained -F: Documentation/kmemleak.txt +F: Documentation/dev-tools/kmemleak.rst F: include/linux/kmemleak.h F: mm/kmemleak.c F: mm/kmemleak-test.c