]>
Commit | Line | Data |
---|---|---|
04f70336 CM |
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. | |
21b86bd5 | 14 | Kmemleak is supported on x86, arm, powerpc, sparc, sh, microblaze and tile. |
04f70336 CM |
15 | |
16 | Usage | |
17 | ----- | |
18 | ||
19 | CONFIG_DEBUG_KMEMLEAK in "Kernel hacking" has to be enabled. A kernel | |
bab4a34a | 20 | thread scans the memory every 10 minutes (by default) and prints the |
4698c1f2 CM |
21 | number of new unreferenced objects found. To display the details of all |
22 | the possible memory leaks: | |
04f70336 CM |
23 | |
24 | # mount -t debugfs nodev /sys/kernel/debug/ | |
25 | # cat /sys/kernel/debug/kmemleak | |
26 | ||
4698c1f2 CM |
27 | To trigger an intermediate memory scan: |
28 | ||
29 | # echo scan > /sys/kernel/debug/kmemleak | |
30 | ||
30b37101 LR |
31 | To clear the list of all current possible memory leaks: |
32 | ||
33 | # echo clear > /sys/kernel/debug/kmemleak | |
34 | ||
35 | New leaks will then come up upon reading /sys/kernel/debug/kmemleak | |
36 | again. | |
37 | ||
04f70336 CM |
38 | Note that the orphan objects are listed in the order they were allocated |
39 | and one object at the beginning of the list may cause other subsequent | |
40 | objects to be reported as orphan. | |
41 | ||
42 | Memory scanning parameters can be modified at run-time by writing to the | |
43 | /sys/kernel/debug/kmemleak file. The following parameters are supported: | |
44 | ||
45 | off - disable kmemleak (irreversible) | |
e0a2a160 | 46 | stack=on - enable the task stacks scanning (default) |
04f70336 | 47 | stack=off - disable the tasks stacks scanning |
e0a2a160 | 48 | scan=on - start the automatic memory scanning thread (default) |
04f70336 | 49 | scan=off - stop the automatic memory scanning thread |
e0a2a160 CM |
50 | scan=<secs> - set the automatic memory scanning period in seconds |
51 | (default 600, 0 to stop the automatic scanning) | |
4698c1f2 | 52 | scan - trigger a memory scan |
30b37101 LR |
53 | clear - clear list of current memory leak suspects, done by |
54 | marking all current reported unreferenced objects grey | |
189d84ed | 55 | dump=<addr> - dump information about the object found at <addr> |
04f70336 CM |
56 | |
57 | Kmemleak can also be disabled at boot-time by passing "kmemleak=off" on | |
58 | the kernel command line. | |
59 | ||
a9d9058a CM |
60 | Memory may be allocated or freed before kmemleak is initialised and |
61 | these actions are stored in an early log buffer. The size of this buffer | |
62 | is configured via the CONFIG_DEBUG_KMEMLEAK_EARLY_LOG_SIZE option. | |
63 | ||
04f70336 CM |
64 | Basic Algorithm |
65 | --------------- | |
66 | ||
67 | The memory allocations via kmalloc, vmalloc, kmem_cache_alloc and | |
68 | friends are traced and the pointers, together with additional | |
69 | information like size and stack trace, are stored in a prio search tree. | |
70 | The corresponding freeing function calls are tracked and the pointers | |
71 | removed from the kmemleak data structures. | |
72 | ||
73 | An allocated block of memory is considered orphan if no pointer to its | |
74 | start address or to any location inside the block can be found by | |
75 | scanning the memory (including saved registers). This means that there | |
76 | might be no way for the kernel to pass the address of the allocated | |
77 | block to a freeing function and therefore the block is considered a | |
78 | memory leak. | |
79 | ||
80 | The scanning algorithm steps: | |
81 | ||
82 | 1. mark all objects as white (remaining white objects will later be | |
83 | considered orphan) | |
84 | 2. scan the memory starting with the data section and stacks, checking | |
85 | the values against the addresses stored in the prio search tree. If | |
86 | a pointer to a white object is found, the object is added to the | |
87 | gray list | |
88 | 3. scan the gray objects for matching addresses (some white objects | |
89 | can become gray and added at the end of the gray list) until the | |
90 | gray set is finished | |
91 | 4. the remaining white objects are considered orphan and reported via | |
92 | /sys/kernel/debug/kmemleak | |
93 | ||
94 | Some allocated memory blocks have pointers stored in the kernel's | |
95 | internal data structures and they cannot be detected as orphans. To | |
96 | avoid this, kmemleak can also store the number of values pointing to an | |
97 | address inside the block address range that need to be found so that the | |
98 | block is not considered a leak. One example is __vmalloc(). | |
99 | ||
30b37101 LR |
100 | Testing specific sections with kmemleak |
101 | --------------------------------------- | |
102 | ||
103 | Upon initial bootup your /sys/kernel/debug/kmemleak output page may be | |
104 | quite extensive. This can also be the case if you have very buggy code | |
105 | when doing development. To work around these situations you can use the | |
106 | 'clear' command to clear all reported unreferenced objects from the | |
107 | /sys/kernel/debug/kmemleak output. By issuing a 'scan' after a 'clear' | |
108 | you can find new unreferenced objects; this should help with testing | |
109 | specific sections of code. | |
110 | ||
111 | To test a critical section on demand with a clean kmemleak do: | |
112 | ||
113 | # echo clear > /sys/kernel/debug/kmemleak | |
114 | ... test your kernel or modules ... | |
115 | # echo scan > /sys/kernel/debug/kmemleak | |
116 | ||
117 | Then as usual to get your report with: | |
118 | ||
119 | # cat /sys/kernel/debug/kmemleak | |
120 | ||
04f70336 CM |
121 | Kmemleak API |
122 | ------------ | |
123 | ||
124 | See the include/linux/kmemleak.h header for the functions prototype. | |
125 | ||
126 | kmemleak_init - initialize kmemleak | |
127 | kmemleak_alloc - notify of a memory block allocation | |
128 | kmemleak_free - notify of a memory block freeing | |
129 | kmemleak_not_leak - mark an object as not a leak | |
130 | kmemleak_ignore - do not scan or report an object as leak | |
131 | kmemleak_scan_area - add scan areas inside a memory block | |
132 | kmemleak_no_scan - do not scan a memory block | |
133 | kmemleak_erase - erase an old value in a pointer variable | |
134 | kmemleak_alloc_recursive - as kmemleak_alloc but checks the recursiveness | |
135 | kmemleak_free_recursive - as kmemleak_free but checks the recursiveness | |
136 | ||
137 | Dealing with false positives/negatives | |
138 | -------------------------------------- | |
139 | ||
140 | The false negatives are real memory leaks (orphan objects) but not | |
141 | reported by kmemleak because values found during the memory scanning | |
142 | point to such objects. To reduce the number of false negatives, kmemleak | |
143 | provides the kmemleak_ignore, kmemleak_scan_area, kmemleak_no_scan and | |
144 | kmemleak_erase functions (see above). The task stacks also increase the | |
145 | amount of false negatives and their scanning is not enabled by default. | |
146 | ||
147 | The false positives are objects wrongly reported as being memory leaks | |
148 | (orphan). For objects known not to be leaks, kmemleak provides the | |
149 | kmemleak_not_leak function. The kmemleak_ignore could also be used if | |
150 | the memory block is known not to contain other pointers and it will no | |
151 | longer be scanned. | |
152 | ||
153 | Some of the reported leaks are only transient, especially on SMP | |
154 | systems, because of pointers temporarily stored in CPU registers or | |
155 | stacks. Kmemleak defines MSECS_MIN_AGE (defaulting to 1000) representing | |
156 | the minimum age of an object to be reported as a memory leak. | |
157 | ||
158 | Limitations and Drawbacks | |
159 | ------------------------- | |
160 | ||
161 | The main drawback is the reduced performance of memory allocation and | |
162 | freeing. To avoid other penalties, the memory scanning is only performed | |
163 | when the /sys/kernel/debug/kmemleak file is read. Anyway, this tool is | |
164 | intended for debugging purposes where the performance might not be the | |
165 | most important requirement. | |
166 | ||
167 | To keep the algorithm simple, kmemleak scans for values pointing to any | |
168 | address inside a block's address range. This may lead to an increased | |
169 | number of false negatives. However, it is likely that a real memory leak | |
170 | will eventually become visible. | |
171 | ||
172 | Another source of false negatives is the data stored in non-pointer | |
173 | values. In a future version, kmemleak could only scan the pointer | |
174 | members in the allocated structures. This feature would solve many of | |
175 | the false negative cases described above. | |
176 | ||
177 | The tool can report false positives. These are cases where an allocated | |
178 | block doesn't need to be freed (some cases in the init_call functions), | |
179 | the pointer is calculated by other methods than the usual container_of | |
180 | macro or the pointer is stored in a location not scanned by kmemleak. | |
181 | ||
21b86bd5 | 182 | Page allocations and ioremap are not tracked. |