diff options
author | Ingo Molnar <mingo@elte.hu> | 2009-06-11 17:31:52 -0400 |
---|---|---|
committer | Ingo Molnar <mingo@elte.hu> | 2009-06-11 17:31:52 -0400 |
commit | 0d5959723e1db3fd7323c198a50c16cecf96c7a9 (patch) | |
tree | 802b623fff261ebcbbddadf84af5524398364a18 /Documentation/kmemleak.txt | |
parent | 62fdac5913f71f8f200bd2c9bd59a02e9a1498e9 (diff) | |
parent | 512626a04e72aca60effe111fa0333ed0b195d21 (diff) |
Merge branch 'linus' into x86/mce3
Conflicts:
arch/x86/kernel/cpu/mcheck/mce_64.c
arch/x86/kernel/irq.c
Merge reason: Resolve the conflicts above.
Signed-off-by: Ingo Molnar <mingo@elte.hu>
Diffstat (limited to 'Documentation/kmemleak.txt')
-rw-r--r-- | Documentation/kmemleak.txt | 142 |
1 files changed, 142 insertions, 0 deletions
diff --git a/Documentation/kmemleak.txt b/Documentation/kmemleak.txt new file mode 100644 index 00000000000..0112da3b9ab --- /dev/null +++ b/Documentation/kmemleak.txt | |||
@@ -0,0 +1,142 @@ | |||
1 | Kernel Memory Leak Detector | ||
2 | =========================== | ||
3 | |||
4 | Introduction | ||
5 | ------------ | ||
6 | |||
7 | Kmemleak provides a way of detecting possible kernel memory leaks in a | ||
8 | way similar to a tracing garbage collector | ||
9 | (http://en.wikipedia.org/wiki/Garbage_collection_%28computer_science%29#Tracing_garbage_collectors), | ||
10 | with the difference that the orphan objects are not freed but only | ||
11 | reported via /sys/kernel/debug/kmemleak. A similar method is used by the | ||
12 | Valgrind tool (memcheck --leak-check) to detect the memory leaks in | ||
13 | user-space applications. | ||
14 | |||
15 | Usage | ||
16 | ----- | ||
17 | |||
18 | CONFIG_DEBUG_KMEMLEAK in "Kernel hacking" has to be enabled. A kernel | ||
19 | thread scans the memory every 10 minutes (by default) and prints any new | ||
20 | unreferenced objects found. To trigger an intermediate scan and display | ||
21 | all the possible memory leaks: | ||
22 | |||
23 | # mount -t debugfs nodev /sys/kernel/debug/ | ||
24 | # cat /sys/kernel/debug/kmemleak | ||
25 | |||
26 | Note that the orphan objects are listed in the order they were allocated | ||
27 | and one object at the beginning of the list may cause other subsequent | ||
28 | objects to be reported as orphan. | ||
29 | |||
30 | Memory scanning parameters can be modified at run-time by writing to the | ||
31 | /sys/kernel/debug/kmemleak file. The following parameters are supported: | ||
32 | |||
33 | off - disable kmemleak (irreversible) | ||
34 | stack=on - enable the task stacks scanning | ||
35 | stack=off - disable the tasks stacks scanning | ||
36 | scan=on - start the automatic memory scanning thread | ||
37 | scan=off - stop the automatic memory scanning thread | ||
38 | scan=<secs> - set the automatic memory scanning period in seconds (0 | ||
39 | to disable it) | ||
40 | |||
41 | Kmemleak can also be disabled at boot-time by passing "kmemleak=off" on | ||
42 | the kernel command line. | ||
43 | |||
44 | Basic Algorithm | ||
45 | --------------- | ||
46 | |||
47 | The memory allocations via kmalloc, vmalloc, kmem_cache_alloc and | ||
48 | friends are traced and the pointers, together with additional | ||
49 | information like size and stack trace, are stored in a prio search tree. | ||
50 | The corresponding freeing function calls are tracked and the pointers | ||
51 | removed from the kmemleak data structures. | ||
52 | |||
53 | An allocated block of memory is considered orphan if no pointer to its | ||
54 | start address or to any location inside the block can be found by | ||
55 | scanning the memory (including saved registers). This means that there | ||
56 | might be no way for the kernel to pass the address of the allocated | ||
57 | block to a freeing function and therefore the block is considered a | ||
58 | memory leak. | ||
59 | |||
60 | The scanning algorithm steps: | ||
61 | |||
62 | 1. mark all objects as white (remaining white objects will later be | ||
63 | considered orphan) | ||
64 | 2. scan the memory starting with the data section and stacks, checking | ||
65 | the values against the addresses stored in the prio search tree. If | ||
66 | a pointer to a white object is found, the object is added to the | ||
67 | gray list | ||
68 | 3. scan the gray objects for matching addresses (some white objects | ||
69 | can become gray and added at the end of the gray list) until the | ||
70 | gray set is finished | ||
71 | 4. the remaining white objects are considered orphan and reported via | ||
72 | /sys/kernel/debug/kmemleak | ||
73 | |||
74 | Some allocated memory blocks have pointers stored in the kernel's | ||
75 | internal data structures and they cannot be detected as orphans. To | ||
76 | avoid this, kmemleak can also store the number of values pointing to an | ||
77 | address inside the block address range that need to be found so that the | ||
78 | block is not considered a leak. One example is __vmalloc(). | ||
79 | |||
80 | Kmemleak API | ||
81 | ------------ | ||
82 | |||
83 | See the include/linux/kmemleak.h header for the functions prototype. | ||
84 | |||
85 | kmemleak_init - initialize kmemleak | ||
86 | kmemleak_alloc - notify of a memory block allocation | ||
87 | kmemleak_free - notify of a memory block freeing | ||
88 | kmemleak_not_leak - mark an object as not a leak | ||
89 | kmemleak_ignore - do not scan or report an object as leak | ||
90 | kmemleak_scan_area - add scan areas inside a memory block | ||
91 | kmemleak_no_scan - do not scan a memory block | ||
92 | kmemleak_erase - erase an old value in a pointer variable | ||
93 | kmemleak_alloc_recursive - as kmemleak_alloc but checks the recursiveness | ||
94 | kmemleak_free_recursive - as kmemleak_free but checks the recursiveness | ||
95 | |||
96 | Dealing with false positives/negatives | ||
97 | -------------------------------------- | ||
98 | |||
99 | The false negatives are real memory leaks (orphan objects) but not | ||
100 | reported by kmemleak because values found during the memory scanning | ||
101 | point to such objects. To reduce the number of false negatives, kmemleak | ||
102 | provides the kmemleak_ignore, kmemleak_scan_area, kmemleak_no_scan and | ||
103 | kmemleak_erase functions (see above). The task stacks also increase the | ||
104 | amount of false negatives and their scanning is not enabled by default. | ||
105 | |||
106 | The false positives are objects wrongly reported as being memory leaks | ||
107 | (orphan). For objects known not to be leaks, kmemleak provides the | ||
108 | kmemleak_not_leak function. The kmemleak_ignore could also be used if | ||
109 | the memory block is known not to contain other pointers and it will no | ||
110 | longer be scanned. | ||
111 | |||
112 | Some of the reported leaks are only transient, especially on SMP | ||
113 | systems, because of pointers temporarily stored in CPU registers or | ||
114 | stacks. Kmemleak defines MSECS_MIN_AGE (defaulting to 1000) representing | ||
115 | the minimum age of an object to be reported as a memory leak. | ||
116 | |||
117 | Limitations and Drawbacks | ||
118 | ------------------------- | ||
119 | |||
120 | The main drawback is the reduced performance of memory allocation and | ||
121 | freeing. To avoid other penalties, the memory scanning is only performed | ||
122 | when the /sys/kernel/debug/kmemleak file is read. Anyway, this tool is | ||
123 | intended for debugging purposes where the performance might not be the | ||
124 | most important requirement. | ||
125 | |||
126 | To keep the algorithm simple, kmemleak scans for values pointing to any | ||
127 | address inside a block's address range. This may lead to an increased | ||
128 | number of false negatives. However, it is likely that a real memory leak | ||
129 | will eventually become visible. | ||
130 | |||
131 | Another source of false negatives is the data stored in non-pointer | ||
132 | values. In a future version, kmemleak could only scan the pointer | ||
133 | members in the allocated structures. This feature would solve many of | ||
134 | the false negative cases described above. | ||
135 | |||
136 | The tool can report false positives. These are cases where an allocated | ||
137 | block doesn't need to be freed (some cases in the init_call functions), | ||
138 | the pointer is calculated by other methods than the usual container_of | ||
139 | macro or the pointer is stored in a location not scanned by kmemleak. | ||
140 | |||
141 | Page allocations and ioremap are not tracked. Only the ARM and x86 | ||
142 | architectures are currently supported. | ||