From: Jonathan Corbet Date: Sun, 7 Aug 2016 21:46:10 +0000 (-0600) Subject: docs: sphinxify kmemleak.txt and move it to dev-tools X-Git-Tag: v4.13~2199^2~78^2~2 X-Git-Url: https://git.proxmox.com/?a=commitdiff_plain;h=ca90a7a38741adf5ce450572952fbbda35055ea4;hp=1ead009cd622bc4c3c2cf1036d8e71d7f063838e;p=mirror_ubuntu-bionic-kernel.git docs: sphinxify kmemleak.txt and move it to dev-tools Acked-by: Catalin Marinas Signed-off-by: Jonathan Corbet --- diff --git a/Documentation/dev-tools/kmemleak.rst b/Documentation/dev-tools/kmemleak.rst new file mode 100644 index 000000000000..1788722d5495 --- /dev/null +++ b/Documentation/dev-tools/kmemleak.rst @@ -0,0 +1,210 @@ +Kernel Memory Leak Detector +=========================== + +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 +user-space applications. +Kmemleak is supported on x86, arm, powerpc, sparc, sh, microblaze, ppc, mips, s390, metag and tile. + +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:: + + # mount -t debugfs nodev /sys/kernel/debug/ + # cat /sys/kernel/debug/kmemleak + +To trigger an intermediate memory scan:: + + # echo scan > /sys/kernel/debug/kmemleak + +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`` +again. + +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 (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 +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 +line enables the function. + +Basic Algorithm +--------------- + +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 +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 rbtree. 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(). + +Testing specific sections with kmemleak +--------------------------------------- + +Upon initial bootup your /sys/kernel/debug/kmemleak output page may be +quite extensive. This can also be the case if you have very buggy code +when doing development. To work around these situations you can use the +'clear' command to clear all reported unreferenced objects from the +/sys/kernel/debug/kmemleak output. By issuing a 'scan' after a 'clear' +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:: + + # 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:: + + # cat /sys/kernel/debug/kmemleak + +Freeing kmemleak internal objects +--------------------------------- + +To allow access to previously found memory leaks after kmemleak has been +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:: + + # echo clear > /sys/kernel/debug/kmemleak + +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 + +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. diff --git a/Documentation/dev-tools/tools.rst b/Documentation/dev-tools/tools.rst index 2d1129789753..3b6382a58301 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/Documentation/kmemleak.txt b/Documentation/kmemleak.txt deleted file mode 100644 index 18e24abb3ecf..000000000000 --- a/Documentation/kmemleak.txt +++ /dev/null @@ -1,203 +0,0 @@ -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 -user-space applications. -Kmemleak is supported on x86, arm, powerpc, sparc, sh, microblaze, ppc, mips, s390, metag and tile. - -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: - - # mount -t debugfs nodev /sys/kernel/debug/ - # cat /sys/kernel/debug/kmemleak - -To trigger an intermediate memory scan: - - # echo scan > /sys/kernel/debug/kmemleak - -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 -again. - -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 (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 -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 -line enables the function. - -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 rbtree. -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 rbtree. 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(). - -Testing specific sections with kmemleak ---------------------------------------- - -Upon initial bootup your /sys/kernel/debug/kmemleak output page may be -quite extensive. This can also be the case if you have very buggy code -when doing development. To work around these situations you can use the -'clear' command to clear all reported unreferenced objects from the -/sys/kernel/debug/kmemleak output. By issuing a 'scan' after a 'clear' -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: - - # 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: - - # cat /sys/kernel/debug/kmemleak - -Freeing kmemleak internal objects ---------------------------------- - -To allow access to previously found memory leaks after kmemleak has been -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: - - # echo clear > /sys/kernel/debug/kmemleak - -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 - -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. diff --git a/MAINTAINERS b/MAINTAINERS index 2ffd7ed40162..b235e0d53449 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