1 Kernel Memory Leak Detector
2 ===========================
3
4 Kmemleak provides a way of detecting possible
5 way similar to a `tracing garbage collector
6 <https://en.wikipedia.org/wiki/Tracing_garbage
7 with the difference that the orphan objects ar
8 reported via /sys/kernel/debug/kmemleak. A sim
9 Valgrind tool (``memcheck --leak-check``) to d
10 user-space applications.
11
12 Usage
13 -----
14
15 CONFIG_DEBUG_KMEMLEAK in "Kernel hacking" has
16 thread scans the memory every 10 minutes (by d
17 number of new unreferenced objects found. If t
18 mounted, mount with::
19
20 # mount -t debugfs nodev /sys/kernel/debug/
21
22 To display the details of all the possible sca
23
24 # cat /sys/kernel/debug/kmemleak
25
26 To trigger an intermediate memory scan::
27
28 # echo scan > /sys/kernel/debug/kmemleak
29
30 To clear the list of all current possible memo
31
32 # echo clear > /sys/kernel/debug/kmemleak
33
34 New leaks will then come up upon reading ``/sy
35 again.
36
37 Note that the orphan objects are listed in the
38 and one object at the beginning of the list ma
39 objects to be reported as orphan.
40
41 Memory scanning parameters can be modified at
42 ``/sys/kernel/debug/kmemleak`` file. The follo
43
44 - off
45 disable kmemleak (irreversible)
46 - stack=on
47 enable the task stacks scanning (default)
48 - stack=off
49 disable the tasks stacks scanning
50 - scan=on
51 start the automatic memory scanning thread
52 - scan=off
53 stop the automatic memory scanning thread
54 - scan=<secs>
55 set the automatic memory scanning period i
56 (default 600, 0 to stop the automatic scan
57 - scan
58 trigger a memory scan
59 - clear
60 clear list of current memory leak suspects
61 marking all current reported unreferenced
62 or free all kmemleak objects if kmemleak h
63 - dump=<addr>
64 dump information about the object found at
65
66 Kmemleak can also be disabled at boot-time by
67 the kernel command line.
68
69 Memory may be allocated or freed before kmemle
70 these actions are stored in an early log buffe
71 is configured via the CONFIG_DEBUG_KMEMLEAK_ME
72
73 If CONFIG_DEBUG_KMEMLEAK_DEFAULT_OFF are enabl
74 disabled by default. Passing ``kmemleak=on`` o
75 line enables the function.
76
77 If you are getting errors like "Error while wr
78 Invalid argument", make sure kmemleak is prope
79
80 Basic Algorithm
81 ---------------
82
83 The memory allocations via :c:func:`kmalloc`,
84 :c:func:`kmem_cache_alloc` and
85 friends are traced and the pointers, together
86 information like size and stack trace, are sto
87 The corresponding freeing function calls are t
88 removed from the kmemleak data structures.
89
90 An allocated block of memory is considered orp
91 start address or to any location inside the bl
92 scanning the memory (including saved registers
93 might be no way for the kernel to pass the add
94 block to a freeing function and therefore the
95 memory leak.
96
97 The scanning algorithm steps:
98
99 1. mark all objects as white (remaining whit
100 considered orphan)
101 2. scan the memory starting with the data se
102 the values against the addresses stored i
103 a pointer to a white object is found, the
104 gray list
105 3. scan the gray objects for matching addres
106 can become gray and added at the end of t
107 gray set is finished
108 4. the remaining white objects are considere
109 /sys/kernel/debug/kmemleak
110
111 Some allocated memory blocks have pointers sto
112 internal data structures and they cannot be de
113 avoid this, kmemleak can also store the number
114 address inside the block address range that ne
115 block is not considered a leak. One example is
116
117 Testing specific sections with kmemleak
118 ---------------------------------------
119
120 Upon initial bootup your /sys/kernel/debug/kme
121 quite extensive. This can also be the case if
122 when doing development. To work around these s
123 'clear' command to clear all reported unrefere
124 /sys/kernel/debug/kmemleak output. By issuing
125 you can find new unreferenced objects; this sh
126 specific sections of code.
127
128 To test a critical section on demand with a cl
129
130 # echo clear > /sys/kernel/debug/kmemleak
131 ... test your kernel or modules ...
132 # echo scan > /sys/kernel/debug/kmemleak
133
134 Then as usual to get your report with::
135
136 # cat /sys/kernel/debug/kmemleak
137
138 Freeing kmemleak internal objects
139 ---------------------------------
140
141 To allow access to previously found memory lea
142 disabled by the user or due to an fatal error,
143 won't be freed when kmemleak is disabled, and
144 a large part of physical memory.
145
146 In this situation, you may reclaim memory with
147
148 # echo clear > /sys/kernel/debug/kmemleak
149
150 Kmemleak API
151 ------------
152
153 See the include/linux/kmemleak.h header for th
154
155 - ``kmemleak_init`` - initialize
156 - ``kmemleak_alloc`` - notify of a
157 - ``kmemleak_alloc_percpu`` - notify of a
158 - ``kmemleak_vmalloc`` - notify of a
159 - ``kmemleak_free`` - notify of a
160 - ``kmemleak_free_part`` - notify of a
161 - ``kmemleak_free_percpu`` - notify of a
162 - ``kmemleak_update_trace`` - update obje
163 - ``kmemleak_not_leak`` - mark an object as n
164 - ``kmemleak_ignore`` - do not scan
165 - ``kmemleak_scan_area`` - add scan ar
166 - ``kmemleak_no_scan`` - do not scan a memor
167 - ``kmemleak_erase`` - erase an ol
168 - ``kmemleak_alloc_recursive`` - as kmemleak_a
169 - ``kmemleak_free_recursive`` - as kmemleak
170
171 The following functions take a physical addres
172 and only perform the corresponding action if t
173 mapping:
174
175 - ``kmemleak_alloc_phys``
176 - ``kmemleak_free_part_phys``
177 - ``kmemleak_ignore_phys``
178
179 Dealing with false positives/negatives
180 --------------------------------------
181
182 The false negatives are real memory leaks (orp
183 reported by kmemleak because values found duri
184 point to such objects. To reduce the number of
185 provides the kmemleak_ignore, kmemleak_scan_ar
186 kmemleak_erase functions (see above). The task
187 amount of false negatives and their scanning i
188
189 The false positives are objects wrongly report
190 (orphan). For objects known not to be leaks, k
191 kmemleak_not_leak function. The kmemleak_ignor
192 the memory block is known not to contain other
193 longer be scanned.
194
195 Some of the reported leaks are only transient,
196 systems, because of pointers temporarily store
197 stacks. Kmemleak defines MSECS_MIN_AGE (defaul
198 the minimum age of an object to be reported as
199
200 Limitations and Drawbacks
201 -------------------------
202
203 The main drawback is the reduced performance o
204 freeing. To avoid other penalties, the memory
205 when the /sys/kernel/debug/kmemleak file is re
206 intended for debugging purposes where the perf
207 most important requirement.
208
209 To keep the algorithm simple, kmemleak scans f
210 address inside a block's address range. This m
211 number of false negatives. However, it is like
212 will eventually become visible.
213
214 Another source of false negatives is the data
215 values. In a future version, kmemleak could on
216 members in the allocated structures. This feat
217 the false negative cases described above.
218
219 The tool can report false positives. These are
220 block doesn't need to be freed (some cases in
221 the pointer is calculated by other methods tha
222 macro or the pointer is stored in a location n
223
224 Page allocations and ioremap are not tracked.
225
226 Testing with kmemleak-test
227 --------------------------
228
229 To check if you have all set up to use kmemlea
230 module, a module that deliberately leaks memor
231 as module (it can't be used as built-in) and b
232 enabled. Load the module and perform a scan wi
233
234 # modprobe kmemleak-test
235 # echo scan > /sys/kernel/debug/kmemle
236
237 Note that the you may not get results instantl
238 kmemleak gets results, it'll log ``kmemleak: <
239 memory leaks``. Then read the file to see then
240
241 # cat /sys/kernel/debug/kmemleak
242 unreferenced object 0xffff89862ca702e8
243 comm "modprobe", pid 2088, jiffies 4
244 hex dump (first 32 bytes):
245 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6
246 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6
247 backtrace:
248 [<00000000e0a73ec7>] 0xffffffffc01
249 [<000000000c5d2a46>] do_one_initca
250 [<0000000046db7e0a>] do_init_modul
251 [<00000000542b9814>] load_module+0
252 [<00000000c2850256>] __do_sys_fini
253 [<000000006564e7ef>] do_syscall_64
254 [<000000007c873fa6>] entry_SYSCALL
255 ...
256
257 Removing the module with ``rmmod kmemleak_test
258 kmemleak results.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.