Merge branch 'stable/bug-fixes-rc2' of git://git.kernel.org/pub/scm/linux/kernel...

[mirror_ubuntu-bionic-kernel.git] / Documentation / kmemleak.txt

diff --git a/Documentation/kmemleak.txt b/Documentation/kmemleak.txt
index 0112da3b9ab87f731006993c76e1a7fdc4eddcaa..090e6ee04536285398a81257e1f9a1f9d34e398d 100644 (file)
--- a/Documentation/kmemleak.txt
+++ b/Documentation/kmemleak.txt
@@ -11,18 +11,30 @@ 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 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 any new
-unreferenced objects found. To trigger an intermediate scan and display
-all the possible memory leaks:
+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.
@@ -31,16 +43,24 @@ 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=on     - enable the task stacks scanning (default)
   stack=off    - disable the tasks stacks scanning
-  scan=on      - start the automatic memory scanning thread
+  scan=on      - start the automatic memory scanning thread (default)
   scan=off     - stop the automatic memory scanning thread
-  scan=<secs>  - set the automatic memory scanning period in seconds (0
-                 to disable it)
+  scan=<secs>  - 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
+  dump=<addr>  - dump information about the object found at <addr>
 
 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.
+
 Basic Algorithm
 ---------------
 
@@ -77,6 +97,27 @@ 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
+
 Kmemleak API
 ------------
 
@@ -138,5 +179,4 @@ 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.
+Page allocations and ioremap are not tracked.