]>
Commit | Line | Data |
---|---|---|
04f70336 CM |
1 | Kernel Memory Leak Detector |
2 | =========================== | |
3 | ||
04f70336 | 4 | Kmemleak provides a way of detecting possible kernel memory leaks in a |
b7c3613e AA |
5 | way similar to a `tracing garbage collector |
6 | <https://en.wikipedia.org/wiki/Tracing_garbage_collection>`_, | |
04f70336 CM |
7 | with the difference that the orphan objects are not freed but only |
8 | reported via /sys/kernel/debug/kmemleak. A similar method is used by the | |
ca90a7a3 | 9 | Valgrind tool (``memcheck --leak-check``) to detect the memory leaks in |
04f70336 | 10 | user-space applications. |
6480e449 JN |
11 | Kmemleak is supported on x86, arm, arm64, powerpc, sparc, sh, microblaze, mips, |
12 | s390, nds32, arc and xtensa. | |
04f70336 CM |
13 | |
14 | Usage | |
15 | ----- | |
16 | ||
17 | CONFIG_DEBUG_KMEMLEAK in "Kernel hacking" has to be enabled. A kernel | |
bab4a34a | 18 | thread scans the memory every 10 minutes (by default) and prints the |
b7c3613e AA |
19 | number of new unreferenced objects found. If the ``debugfs`` isn't already |
20 | mounted, mount with:: | |
04f70336 CM |
21 | |
22 | # mount -t debugfs nodev /sys/kernel/debug/ | |
b7c3613e AA |
23 | |
24 | To display the details of all the possible scanned memory leaks:: | |
25 | ||
04f70336 CM |
26 | # cat /sys/kernel/debug/kmemleak |
27 | ||
ca90a7a3 | 28 | To trigger an intermediate memory scan:: |
4698c1f2 CM |
29 | |
30 | # echo scan > /sys/kernel/debug/kmemleak | |
31 | ||
ca90a7a3 | 32 | To clear the list of all current possible memory leaks:: |
30b37101 LR |
33 | |
34 | # echo clear > /sys/kernel/debug/kmemleak | |
35 | ||
ca90a7a3 | 36 | New leaks will then come up upon reading ``/sys/kernel/debug/kmemleak`` |
30b37101 LR |
37 | again. |
38 | ||
04f70336 CM |
39 | Note that the orphan objects are listed in the order they were allocated |
40 | and one object at the beginning of the list may cause other subsequent | |
41 | objects to be reported as orphan. | |
42 | ||
43 | Memory scanning parameters can be modified at run-time by writing to the | |
ca90a7a3 JC |
44 | ``/sys/kernel/debug/kmemleak`` file. The following parameters are supported: |
45 | ||
46 | - off | |
47 | disable kmemleak (irreversible) | |
48 | - stack=on | |
49 | enable the task stacks scanning (default) | |
50 | - stack=off | |
51 | disable the tasks stacks scanning | |
52 | - scan=on | |
53 | start the automatic memory scanning thread (default) | |
54 | - scan=off | |
55 | stop the automatic memory scanning thread | |
56 | - scan=<secs> | |
57 | set the automatic memory scanning period in seconds | |
58 | (default 600, 0 to stop the automatic scanning) | |
59 | - scan | |
60 | trigger a memory scan | |
61 | - clear | |
62 | clear list of current memory leak suspects, done by | |
63 | marking all current reported unreferenced objects grey, | |
64 | or free all kmemleak objects if kmemleak has been disabled. | |
65 | - dump=<addr> | |
66 | dump information about the object found at <addr> | |
67 | ||
68 | Kmemleak can also be disabled at boot-time by passing ``kmemleak=off`` on | |
04f70336 CM |
69 | the kernel command line. |
70 | ||
a9d9058a CM |
71 | Memory may be allocated or freed before kmemleak is initialised and |
72 | these actions are stored in an early log buffer. The size of this buffer | |
2c861bf5 | 73 | is configured via the CONFIG_DEBUG_KMEMLEAK_MEM_POOL_SIZE option. |
a9d9058a | 74 | |
6808a40d | 75 | If CONFIG_DEBUG_KMEMLEAK_DEFAULT_OFF are enabled, the kmemleak is |
ca90a7a3 | 76 | disabled by default. Passing ``kmemleak=on`` on the kernel command |
6808a40d MI |
77 | line enables the function. |
78 | ||
b7c3613e AA |
79 | If you are getting errors like "Error while writing to stdout" or "write_loop: |
80 | Invalid argument", make sure kmemleak is properly enabled. | |
81 | ||
04f70336 CM |
82 | Basic Algorithm |
83 | --------------- | |
84 | ||
ca90a7a3 JC |
85 | The memory allocations via :c:func:`kmalloc`, :c:func:`vmalloc`, |
86 | :c:func:`kmem_cache_alloc` and | |
04f70336 | 87 | friends are traced and the pointers, together with additional |
4762c984 | 88 | information like size and stack trace, are stored in a rbtree. |
04f70336 CM |
89 | The corresponding freeing function calls are tracked and the pointers |
90 | removed from the kmemleak data structures. | |
91 | ||
92 | An allocated block of memory is considered orphan if no pointer to its | |
93 | start address or to any location inside the block can be found by | |
94 | scanning the memory (including saved registers). This means that there | |
95 | might be no way for the kernel to pass the address of the allocated | |
96 | block to a freeing function and therefore the block is considered a | |
97 | memory leak. | |
98 | ||
99 | The scanning algorithm steps: | |
100 | ||
101 | 1. mark all objects as white (remaining white objects will later be | |
102 | considered orphan) | |
103 | 2. scan the memory starting with the data section and stacks, checking | |
4762c984 | 104 | the values against the addresses stored in the rbtree. If |
04f70336 CM |
105 | a pointer to a white object is found, the object is added to the |
106 | gray list | |
107 | 3. scan the gray objects for matching addresses (some white objects | |
108 | can become gray and added at the end of the gray list) until the | |
109 | gray set is finished | |
110 | 4. the remaining white objects are considered orphan and reported via | |
111 | /sys/kernel/debug/kmemleak | |
112 | ||
113 | Some allocated memory blocks have pointers stored in the kernel's | |
114 | internal data structures and they cannot be detected as orphans. To | |
115 | avoid this, kmemleak can also store the number of values pointing to an | |
116 | address inside the block address range that need to be found so that the | |
117 | block is not considered a leak. One example is __vmalloc(). | |
118 | ||
30b37101 LR |
119 | Testing specific sections with kmemleak |
120 | --------------------------------------- | |
121 | ||
122 | Upon initial bootup your /sys/kernel/debug/kmemleak output page may be | |
123 | quite extensive. This can also be the case if you have very buggy code | |
124 | when doing development. To work around these situations you can use the | |
125 | 'clear' command to clear all reported unreferenced objects from the | |
126 | /sys/kernel/debug/kmemleak output. By issuing a 'scan' after a 'clear' | |
127 | you can find new unreferenced objects; this should help with testing | |
128 | specific sections of code. | |
129 | ||
ca90a7a3 | 130 | To test a critical section on demand with a clean kmemleak do:: |
30b37101 LR |
131 | |
132 | # echo clear > /sys/kernel/debug/kmemleak | |
133 | ... test your kernel or modules ... | |
134 | # echo scan > /sys/kernel/debug/kmemleak | |
135 | ||
ca90a7a3 | 136 | Then as usual to get your report with:: |
30b37101 LR |
137 | |
138 | # cat /sys/kernel/debug/kmemleak | |
139 | ||
c89da70c LZ |
140 | Freeing kmemleak internal objects |
141 | --------------------------------- | |
142 | ||
abb3b1f8 | 143 | To allow access to previously found memory leaks after kmemleak has been |
c89da70c LZ |
144 | disabled by the user or due to an fatal error, internal kmemleak objects |
145 | won't be freed when kmemleak is disabled, and those objects may occupy | |
146 | a large part of physical memory. | |
147 | ||
ca90a7a3 | 148 | In this situation, you may reclaim memory with:: |
c89da70c LZ |
149 | |
150 | # echo clear > /sys/kernel/debug/kmemleak | |
151 | ||
04f70336 CM |
152 | Kmemleak API |
153 | ------------ | |
154 | ||
155 | See the include/linux/kmemleak.h header for the functions prototype. | |
156 | ||
ca90a7a3 JC |
157 | - ``kmemleak_init`` - initialize kmemleak |
158 | - ``kmemleak_alloc`` - notify of a memory block allocation | |
159 | - ``kmemleak_alloc_percpu`` - notify of a percpu memory block allocation | |
94f4a161 | 160 | - ``kmemleak_vmalloc`` - notify of a vmalloc() memory allocation |
ca90a7a3 JC |
161 | - ``kmemleak_free`` - notify of a memory block freeing |
162 | - ``kmemleak_free_part`` - notify of a partial memory block freeing | |
163 | - ``kmemleak_free_percpu`` - notify of a percpu memory block freeing | |
164 | - ``kmemleak_update_trace`` - update object allocation stack trace | |
165 | - ``kmemleak_not_leak`` - mark an object as not a leak | |
166 | - ``kmemleak_ignore`` - do not scan or report an object as leak | |
167 | - ``kmemleak_scan_area`` - add scan areas inside a memory block | |
168 | - ``kmemleak_no_scan`` - do not scan a memory block | |
169 | - ``kmemleak_erase`` - erase an old value in a pointer variable | |
170 | - ``kmemleak_alloc_recursive`` - as kmemleak_alloc but checks the recursiveness | |
171 | - ``kmemleak_free_recursive`` - as kmemleak_free but checks the recursiveness | |
04f70336 | 172 | |
9099daed CM |
173 | The following functions take a physical address as the object pointer |
174 | and only perform the corresponding action if the address has a lowmem | |
175 | mapping: | |
176 | ||
177 | - ``kmemleak_alloc_phys`` | |
178 | - ``kmemleak_free_part_phys`` | |
179 | - ``kmemleak_not_leak_phys`` | |
180 | - ``kmemleak_ignore_phys`` | |
181 | ||
04f70336 CM |
182 | Dealing with false positives/negatives |
183 | -------------------------------------- | |
184 | ||
185 | The false negatives are real memory leaks (orphan objects) but not | |
186 | reported by kmemleak because values found during the memory scanning | |
187 | point to such objects. To reduce the number of false negatives, kmemleak | |
188 | provides the kmemleak_ignore, kmemleak_scan_area, kmemleak_no_scan and | |
189 | kmemleak_erase functions (see above). The task stacks also increase the | |
190 | amount of false negatives and their scanning is not enabled by default. | |
191 | ||
192 | The false positives are objects wrongly reported as being memory leaks | |
193 | (orphan). For objects known not to be leaks, kmemleak provides the | |
194 | kmemleak_not_leak function. The kmemleak_ignore could also be used if | |
195 | the memory block is known not to contain other pointers and it will no | |
196 | longer be scanned. | |
197 | ||
198 | Some of the reported leaks are only transient, especially on SMP | |
199 | systems, because of pointers temporarily stored in CPU registers or | |
200 | stacks. Kmemleak defines MSECS_MIN_AGE (defaulting to 1000) representing | |
201 | the minimum age of an object to be reported as a memory leak. | |
202 | ||
203 | Limitations and Drawbacks | |
204 | ------------------------- | |
205 | ||
206 | The main drawback is the reduced performance of memory allocation and | |
207 | freeing. To avoid other penalties, the memory scanning is only performed | |
208 | when the /sys/kernel/debug/kmemleak file is read. Anyway, this tool is | |
209 | intended for debugging purposes where the performance might not be the | |
210 | most important requirement. | |
211 | ||
212 | To keep the algorithm simple, kmemleak scans for values pointing to any | |
213 | address inside a block's address range. This may lead to an increased | |
214 | number of false negatives. However, it is likely that a real memory leak | |
215 | will eventually become visible. | |
216 | ||
217 | Another source of false negatives is the data stored in non-pointer | |
218 | values. In a future version, kmemleak could only scan the pointer | |
219 | members in the allocated structures. This feature would solve many of | |
220 | the false negative cases described above. | |
221 | ||
222 | The tool can report false positives. These are cases where an allocated | |
223 | block doesn't need to be freed (some cases in the init_call functions), | |
224 | the pointer is calculated by other methods than the usual container_of | |
225 | macro or the pointer is stored in a location not scanned by kmemleak. | |
226 | ||
21b86bd5 | 227 | Page allocations and ioremap are not tracked. |
b7c3613e AA |
228 | |
229 | Testing with kmemleak-test | |
230 | -------------------------- | |
231 | ||
232 | To check if you have all set up to use kmemleak, you can use the kmemleak-test | |
233 | module, a module that deliberately leaks memory. Set CONFIG_DEBUG_KMEMLEAK_TEST | |
234 | as module (it can't be used as bult-in) and boot the kernel with kmemleak | |
235 | enabled. Load the module and perform a scan with:: | |
236 | ||
237 | # modprobe kmemleak-test | |
238 | # echo scan > /sys/kernel/debug/kmemleak | |
239 | ||
240 | Note that the you may not get results instantly or on the first scanning. When | |
241 | kmemleak gets results, it'll log ``kmemleak: <count of leaks> new suspected | |
242 | memory leaks``. Then read the file to see then:: | |
243 | ||
244 | # cat /sys/kernel/debug/kmemleak | |
245 | unreferenced object 0xffff89862ca702e8 (size 32): | |
246 | comm "modprobe", pid 2088, jiffies 4294680594 (age 375.486s) | |
247 | hex dump (first 32 bytes): | |
248 | 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b kkkkkkkkkkkkkkkk | |
249 | 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b a5 kkkkkkkkkkkkkkk. | |
250 | backtrace: | |
251 | [<00000000e0a73ec7>] 0xffffffffc01d2036 | |
252 | [<000000000c5d2a46>] do_one_initcall+0x41/0x1df | |
253 | [<0000000046db7e0a>] do_init_module+0x55/0x200 | |
254 | [<00000000542b9814>] load_module+0x203c/0x2480 | |
255 | [<00000000c2850256>] __do_sys_finit_module+0xba/0xe0 | |
256 | [<000000006564e7ef>] do_syscall_64+0x43/0x110 | |
257 | [<000000007c873fa6>] entry_SYSCALL_64_after_hwframe+0x44/0xa9 | |
258 | ... | |
259 | ||
260 | Removing the module with ``rmmod kmemleak_test`` should also trigger some | |
261 | kmemleak results. |