[lkml]   [2009]   [Apr]   [24]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
Messages in this thread
    Patch in this message
    Subject[PATCH 02/14] kmemleak: Add documentation on the memory leak detector
    This patch adds the Documentation/kmemleak.txt file with some
    information about how kmemleak works.

    Signed-off-by: Catalin Marinas <>
    Documentation/kernel-parameters.txt | 4 +
    Documentation/kmemleak.txt | 142 +++++++++++++++++++++++++++++++++++
    2 files changed, 146 insertions(+), 0 deletions(-)
    create mode 100644 Documentation/kmemleak.txt

    diff --git a/Documentation/kernel-parameters.txt b/Documentation/kernel-parameters.txt
    index 600cdd7..242ffc9 100644
    --- a/Documentation/kernel-parameters.txt
    +++ b/Documentation/kernel-parameters.txt
    @@ -1066,6 +1066,10 @@ and is between 256 and 4096 characters. It is defined in the file
    Configure the RouterBoard 532 series on-chip
    Ethernet adapter MAC address.

    + kmemleak= [KNL] Boot-time kmemleak enable/disable
    + Valid arguments: on, off
    + Default: on
    kstack=N [X86] Print N words from the kernel stack
    in oops dumps.

    diff --git a/Documentation/kmemleak.txt b/Documentation/kmemleak.txt
    new file mode 100644
    index 0000000..0112da3
    --- /dev/null
    +++ b/Documentation/kmemleak.txt
    @@ -0,0 +1,142 @@
    +Kernel Memory Leak Detector
    +Kmemleak provides a way of detecting possible kernel memory leaks in a
    +way similar to a tracing garbage collector
    +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
    +user-space applications.
    +CONFIG_DEBUG_KMEMLEAK in "Kernel hacking" has to be enabled. A kernel
    +thread scans the memory every 10 minutes (by default) and prints any new
    +unreferenced objects found. To trigger an intermediate scan and display
    +all the possible memory leaks:
    + # mount -t debugfs nodev /sys/kernel/debug/
    + # cat /sys/kernel/debug/kmemleak
    +Note that the orphan objects are listed in the order they were allocated
    +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
    + stack=off - disable the tasks stacks scanning
    + scan=on - start the automatic memory scanning thread
    + scan=off - stop the automatic memory scanning thread
    + scan=<secs> - set the automatic memory scanning period in seconds (0
    + to disable it)
    +Kmemleak can also be disabled at boot-time by passing "kmemleak=off" on
    +the kernel command line.
    +Basic Algorithm
    +The memory allocations via kmalloc, vmalloc, kmem_cache_alloc and
    +friends are traced and the pointers, together with additional
    +information like size and stack trace, are stored in a prio search tree.
    +The corresponding freeing function calls are tracked and the pointers
    +removed from the kmemleak data structures.
    +An allocated block of memory is considered orphan if no pointer to its
    +start address or to any location inside the block can be found by
    +scanning the memory (including saved registers). This means that there
    +might be no way for the kernel to pass the address of the allocated
    +block to a freeing function and therefore the block is considered a
    +memory leak.
    +The scanning algorithm steps:
    + 1. mark all objects as white (remaining white objects will later be
    + considered orphan)
    + 2. scan the memory starting with the data section and stacks, checking
    + the values against the addresses stored in the prio search tree. If
    + a pointer to a white object is found, the object is added to the
    + gray list
    + 3. scan the gray objects for matching addresses (some white objects
    + can become gray and added at the end of the gray list) until the
    + gray set is finished
    + 4. the remaining white objects are considered orphan and reported via
    + /sys/kernel/debug/kmemleak
    +Some allocated memory blocks have pointers stored in the kernel's
    +internal data structures and they cannot be detected as orphans. To
    +avoid this, kmemleak can also store the number of values pointing to an
    +address inside the block address range that need to be found so that the
    +block is not considered a leak. One example is __vmalloc().
    +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_free - notify of a memory block freeing
    +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
    +The false negatives are real memory leaks (orphan objects) but not
    +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.
    +The false positives are objects wrongly reported as being memory leaks
    +(orphan). For objects known not to be leaks, kmemleak provides the
    +kmemleak_not_leak function. The kmemleak_ignore could also be used if
    +the memory block is known not to contain other pointers and it will no
    +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
    +the minimum age of an object to be reported as a memory leak.
    +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
    +intended for debugging purposes where the performance might not be the
    +most important requirement.
    +To keep the algorithm simple, kmemleak scans for values pointing to any
    +address inside a block's address range. This may lead to an increased
    +number of false negatives. However, it is likely that a real memory leak
    +will eventually become visible.
    +Another source of false negatives is the data stored in non-pointer
    +values. In a future version, kmemleak could only scan the pointer
    +members in the allocated structures. This feature would solve many of
    +the false negative cases described above.
    +The tool can report false positives. These are cases where an allocated
    +block doesn't need to be freed (some cases in the init_call functions),
    +the pointer is calculated by other methods than the usual container_of
    +macro or the pointer is stored in a location not scanned by kmemleak.
    +Page allocations and ioremap are not tracked. Only the ARM and x86
    +architectures are currently supported.

     \ /
      Last update: 2009-04-24 18:45    [W:0.031 / U:136.236 seconds]
    ©2003-2016 Jasper Spaans. hosted at Digital OceanAdvertise on this site