Commit | Line | Data |
---|---|---|
691cc54c TG |
1 | <?xml version="1.0" encoding="UTF-8"?> |
2 | <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" | |
3 | "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> | |
4 | ||
5 | <book id="debug-objects-guide"> | |
6 | <bookinfo> | |
7 | <title>Debug objects life time</title> | |
8 | ||
9 | <authorgroup> | |
10 | <author> | |
11 | <firstname>Thomas</firstname> | |
12 | <surname>Gleixner</surname> | |
13 | <affiliation> | |
14 | <address> | |
15 | <email>tglx@linutronix.de</email> | |
16 | </address> | |
17 | </affiliation> | |
18 | </author> | |
19 | </authorgroup> | |
20 | ||
21 | <copyright> | |
22 | <year>2008</year> | |
23 | <holder>Thomas Gleixner</holder> | |
24 | </copyright> | |
25 | ||
26 | <legalnotice> | |
27 | <para> | |
28 | This documentation is free software; you can redistribute | |
29 | it and/or modify it under the terms of the GNU General Public | |
30 | License version 2 as published by the Free Software Foundation. | |
31 | </para> | |
32 | ||
33 | <para> | |
34 | This program is distributed in the hope that it will be | |
35 | useful, but WITHOUT ANY WARRANTY; without even the implied | |
36 | warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. | |
37 | See the GNU General Public License for more details. | |
38 | </para> | |
39 | ||
40 | <para> | |
41 | You should have received a copy of the GNU General Public | |
42 | License along with this program; if not, write to the Free | |
43 | Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, | |
44 | MA 02111-1307 USA | |
45 | </para> | |
46 | ||
47 | <para> | |
48 | For more details see the file COPYING in the source | |
49 | distribution of Linux. | |
50 | </para> | |
51 | </legalnotice> | |
52 | </bookinfo> | |
53 | ||
54 | <toc></toc> | |
55 | ||
56 | <chapter id="intro"> | |
57 | <title>Introduction</title> | |
58 | <para> | |
59 | debugobjects is a generic infrastructure to track the life time | |
60 | of kernel objects and validate the operations on those. | |
61 | </para> | |
62 | <para> | |
63 | debugobjects is useful to check for the following error patterns: | |
64 | <itemizedlist> | |
65 | <listitem><para>Activation of uninitialized objects</para></listitem> | |
66 | <listitem><para>Initialization of active objects</para></listitem> | |
67 | <listitem><para>Usage of freed/destroyed objects</para></listitem> | |
68 | </itemizedlist> | |
69 | </para> | |
70 | <para> | |
71 | debugobjects is not changing the data structure of the real | |
72 | object so it can be compiled in with a minimal runtime impact | |
73 | and enabled on demand with a kernel command line option. | |
74 | </para> | |
75 | </chapter> | |
76 | ||
77 | <chapter id="howto"> | |
78 | <title>Howto use debugobjects</title> | |
79 | <para> | |
80 | A kernel subsystem needs to provide a data structure which | |
81 | describes the object type and add calls into the debug code at | |
82 | appropriate places. The data structure to describe the object | |
83 | type needs at minimum the name of the object type. Optional | |
84 | functions can and should be provided to fixup detected problems | |
85 | so the kernel can continue to work and the debug information can | |
86 | be retrieved from a live system instead of hard core debugging | |
87 | with serial consoles and stack trace transcripts from the | |
88 | monitor. | |
89 | </para> | |
90 | <para> | |
91 | The debug calls provided by debugobjects are: | |
92 | <itemizedlist> | |
93 | <listitem><para>debug_object_init</para></listitem> | |
94 | <listitem><para>debug_object_init_on_stack</para></listitem> | |
95 | <listitem><para>debug_object_activate</para></listitem> | |
96 | <listitem><para>debug_object_deactivate</para></listitem> | |
97 | <listitem><para>debug_object_destroy</para></listitem> | |
98 | <listitem><para>debug_object_free</para></listitem> | |
b84d435c | 99 | <listitem><para>debug_object_assert_init</para></listitem> |
691cc54c TG |
100 | </itemizedlist> |
101 | Each of these functions takes the address of the real object and | |
102 | a pointer to the object type specific debug description | |
103 | structure. | |
104 | </para> | |
105 | <para> | |
106 | Each detected error is reported in the statistics and a limited | |
107 | number of errors are printk'ed including a full stack trace. | |
108 | </para> | |
109 | <para> | |
156f5a78 | 110 | The statistics are available via /sys/kernel/debug/debug_objects/stats. |
691cc54c TG |
111 | They provide information about the number of warnings and the |
112 | number of successful fixups along with information about the | |
113 | usage of the internal tracking objects and the state of the | |
114 | internal tracking objects pool. | |
115 | </para> | |
116 | </chapter> | |
117 | <chapter id="debugfunctions"> | |
118 | <title>Debug functions</title> | |
119 | <sect1 id="prototypes"> | |
120 | <title>Debug object function reference</title> | |
121 | !Elib/debugobjects.c | |
122 | </sect1> | |
123 | <sect1 id="debug_object_init"> | |
124 | <title>debug_object_init</title> | |
125 | <para> | |
126 | This function is called whenever the initialization function | |
127 | of a real object is called. | |
128 | </para> | |
129 | <para> | |
130 | When the real object is already tracked by debugobjects it is | |
131 | checked, whether the object can be initialized. Initializing | |
132 | is not allowed for active and destroyed objects. When | |
133 | debugobjects detects an error, then it calls the fixup_init | |
134 | function of the object type description structure if provided | |
135 | by the caller. The fixup function can correct the problem | |
136 | before the real initialization of the object happens. E.g. it | |
137 | can deactivate an active object in order to prevent damage to | |
138 | the subsystem. | |
139 | </para> | |
140 | <para> | |
141 | When the real object is not yet tracked by debugobjects, | |
142 | debugobjects allocates a tracker object for the real object | |
143 | and sets the tracker object state to ODEBUG_STATE_INIT. It | |
144 | verifies that the object is not on the callers stack. If it is | |
145 | on the callers stack then a limited number of warnings | |
146 | including a full stack trace is printk'ed. The calling code | |
147 | must use debug_object_init_on_stack() and remove the object | |
148 | before leaving the function which allocated it. See next | |
149 | section. | |
150 | </para> | |
151 | </sect1> | |
152 | ||
153 | <sect1 id="debug_object_init_on_stack"> | |
154 | <title>debug_object_init_on_stack</title> | |
155 | <para> | |
156 | This function is called whenever the initialization function | |
157 | of a real object which resides on the stack is called. | |
158 | </para> | |
159 | <para> | |
160 | When the real object is already tracked by debugobjects it is | |
161 | checked, whether the object can be initialized. Initializing | |
162 | is not allowed for active and destroyed objects. When | |
163 | debugobjects detects an error, then it calls the fixup_init | |
164 | function of the object type description structure if provided | |
165 | by the caller. The fixup function can correct the problem | |
166 | before the real initialization of the object happens. E.g. it | |
167 | can deactivate an active object in order to prevent damage to | |
168 | the subsystem. | |
169 | </para> | |
170 | <para> | |
171 | When the real object is not yet tracked by debugobjects | |
172 | debugobjects allocates a tracker object for the real object | |
173 | and sets the tracker object state to ODEBUG_STATE_INIT. It | |
174 | verifies that the object is on the callers stack. | |
175 | </para> | |
176 | <para> | |
177 | An object which is on the stack must be removed from the | |
178 | tracker by calling debug_object_free() before the function | |
179 | which allocates the object returns. Otherwise we keep track of | |
180 | stale objects. | |
181 | </para> | |
182 | </sect1> | |
183 | ||
184 | <sect1 id="debug_object_activate"> | |
185 | <title>debug_object_activate</title> | |
186 | <para> | |
187 | This function is called whenever the activation function of a | |
188 | real object is called. | |
189 | </para> | |
190 | <para> | |
191 | When the real object is already tracked by debugobjects it is | |
192 | checked, whether the object can be activated. Activating is | |
193 | not allowed for active and destroyed objects. When | |
194 | debugobjects detects an error, then it calls the | |
195 | fixup_activate function of the object type description | |
196 | structure if provided by the caller. The fixup function can | |
197 | correct the problem before the real activation of the object | |
198 | happens. E.g. it can deactivate an active object in order to | |
199 | prevent damage to the subsystem. | |
200 | </para> | |
201 | <para> | |
202 | When the real object is not yet tracked by debugobjects then | |
203 | the fixup_activate function is called if available. This is | |
204 | necessary to allow the legitimate activation of statically | |
205 | allocated and initialized objects. The fixup function checks | |
206 | whether the object is valid and calls the debug_objects_init() | |
207 | function to initialize the tracking of this object. | |
208 | </para> | |
209 | <para> | |
210 | When the activation is legitimate, then the state of the | |
211 | associated tracker object is set to ODEBUG_STATE_ACTIVE. | |
212 | </para> | |
213 | </sect1> | |
214 | ||
215 | <sect1 id="debug_object_deactivate"> | |
216 | <title>debug_object_deactivate</title> | |
217 | <para> | |
218 | This function is called whenever the deactivation function of | |
219 | a real object is called. | |
220 | </para> | |
221 | <para> | |
222 | When the real object is tracked by debugobjects it is checked, | |
223 | whether the object can be deactivated. Deactivating is not | |
224 | allowed for untracked or destroyed objects. | |
225 | </para> | |
226 | <para> | |
227 | When the deactivation is legitimate, then the state of the | |
228 | associated tracker object is set to ODEBUG_STATE_INACTIVE. | |
229 | </para> | |
230 | </sect1> | |
231 | ||
232 | <sect1 id="debug_object_destroy"> | |
233 | <title>debug_object_destroy</title> | |
234 | <para> | |
235 | This function is called to mark an object destroyed. This is | |
236 | useful to prevent the usage of invalid objects, which are | |
237 | still available in memory: either statically allocated objects | |
238 | or objects which are freed later. | |
239 | </para> | |
240 | <para> | |
241 | When the real object is tracked by debugobjects it is checked, | |
242 | whether the object can be destroyed. Destruction is not | |
243 | allowed for active and destroyed objects. When debugobjects | |
244 | detects an error, then it calls the fixup_destroy function of | |
245 | the object type description structure if provided by the | |
246 | caller. The fixup function can correct the problem before the | |
247 | real destruction of the object happens. E.g. it can deactivate | |
248 | an active object in order to prevent damage to the subsystem. | |
249 | </para> | |
250 | <para> | |
251 | When the destruction is legitimate, then the state of the | |
252 | associated tracker object is set to ODEBUG_STATE_DESTROYED. | |
253 | </para> | |
254 | </sect1> | |
255 | ||
256 | <sect1 id="debug_object_free"> | |
257 | <title>debug_object_free</title> | |
258 | <para> | |
259 | This function is called before an object is freed. | |
260 | </para> | |
261 | <para> | |
262 | When the real object is tracked by debugobjects it is checked, | |
263 | whether the object can be freed. Free is not allowed for | |
264 | active objects. When debugobjects detects an error, then it | |
265 | calls the fixup_free function of the object type description | |
266 | structure if provided by the caller. The fixup function can | |
267 | correct the problem before the real free of the object | |
268 | happens. E.g. it can deactivate an active object in order to | |
269 | prevent damage to the subsystem. | |
270 | </para> | |
271 | <para> | |
272 | Note that debug_object_free removes the object from the | |
273 | tracker. Later usage of the object is detected by the other | |
274 | debug checks. | |
275 | </para> | |
276 | </sect1> | |
b84d435c CC |
277 | |
278 | <sect1 id="debug_object_assert_init"> | |
279 | <title>debug_object_assert_init</title> | |
280 | <para> | |
281 | This function is called to assert that an object has been | |
282 | initialized. | |
283 | </para> | |
284 | <para> | |
285 | When the real object is not tracked by debugobjects, it calls | |
286 | fixup_assert_init of the object type description structure | |
287 | provided by the caller, with the hardcoded object state | |
288 | ODEBUG_NOT_AVAILABLE. The fixup function can correct the problem | |
289 | by calling debug_object_init and other specific initializing | |
290 | functions. | |
291 | </para> | |
292 | <para> | |
293 | When the real object is already tracked by debugobjects it is | |
294 | ignored. | |
295 | </para> | |
296 | </sect1> | |
691cc54c TG |
297 | </chapter> |
298 | <chapter id="fixupfunctions"> | |
299 | <title>Fixup functions</title> | |
300 | <sect1 id="debug_obj_descr"> | |
301 | <title>Debug object type description structure</title> | |
302 | !Iinclude/linux/debugobjects.h | |
303 | </sect1> | |
304 | <sect1 id="fixup_init"> | |
305 | <title>fixup_init</title> | |
306 | <para> | |
307 | This function is called from the debug code whenever a problem | |
308 | in debug_object_init is detected. The function takes the | |
309 | address of the object and the state which is currently | |
310 | recorded in the tracker. | |
311 | </para> | |
312 | <para> | |
313 | Called from debug_object_init when the object state is: | |
314 | <itemizedlist> | |
315 | <listitem><para>ODEBUG_STATE_ACTIVE</para></listitem> | |
316 | </itemizedlist> | |
317 | </para> | |
318 | <para> | |
319 | The function returns 1 when the fixup was successful, | |
320 | otherwise 0. The return value is used to update the | |
321 | statistics. | |
322 | </para> | |
323 | <para> | |
324 | Note, that the function needs to call the debug_object_init() | |
325 | function again, after the damage has been repaired in order to | |
326 | keep the state consistent. | |
327 | </para> | |
328 | </sect1> | |
329 | ||
330 | <sect1 id="fixup_activate"> | |
331 | <title>fixup_activate</title> | |
332 | <para> | |
333 | This function is called from the debug code whenever a problem | |
334 | in debug_object_activate is detected. | |
335 | </para> | |
336 | <para> | |
337 | Called from debug_object_activate when the object state is: | |
338 | <itemizedlist> | |
339 | <listitem><para>ODEBUG_STATE_NOTAVAILABLE</para></listitem> | |
340 | <listitem><para>ODEBUG_STATE_ACTIVE</para></listitem> | |
341 | </itemizedlist> | |
342 | </para> | |
343 | <para> | |
344 | The function returns 1 when the fixup was successful, | |
345 | otherwise 0. The return value is used to update the | |
346 | statistics. | |
347 | </para> | |
348 | <para> | |
349 | Note that the function needs to call the debug_object_activate() | |
350 | function again after the damage has been repaired in order to | |
351 | keep the state consistent. | |
352 | </para> | |
353 | <para> | |
354 | The activation of statically initialized objects is a special | |
355 | case. When debug_object_activate() has no tracked object for | |
356 | this object address then fixup_activate() is called with | |
357 | object state ODEBUG_STATE_NOTAVAILABLE. The fixup function | |
358 | needs to check whether this is a legitimate case of a | |
359 | statically initialized object or not. In case it is it calls | |
360 | debug_object_init() and debug_object_activate() to make the | |
361 | object known to the tracker and marked active. In this case | |
362 | the function should return 0 because this is not a real fixup. | |
363 | </para> | |
364 | </sect1> | |
365 | ||
366 | <sect1 id="fixup_destroy"> | |
367 | <title>fixup_destroy</title> | |
368 | <para> | |
369 | This function is called from the debug code whenever a problem | |
370 | in debug_object_destroy is detected. | |
371 | </para> | |
372 | <para> | |
373 | Called from debug_object_destroy when the object state is: | |
374 | <itemizedlist> | |
375 | <listitem><para>ODEBUG_STATE_ACTIVE</para></listitem> | |
376 | </itemizedlist> | |
377 | </para> | |
378 | <para> | |
379 | The function returns 1 when the fixup was successful, | |
380 | otherwise 0. The return value is used to update the | |
381 | statistics. | |
382 | </para> | |
383 | </sect1> | |
384 | <sect1 id="fixup_free"> | |
385 | <title>fixup_free</title> | |
386 | <para> | |
387 | This function is called from the debug code whenever a problem | |
388 | in debug_object_free is detected. Further it can be called | |
389 | from the debug checks in kfree/vfree, when an active object is | |
390 | detected from the debug_check_no_obj_freed() sanity checks. | |
391 | </para> | |
392 | <para> | |
393 | Called from debug_object_free() or debug_check_no_obj_freed() | |
394 | when the object state is: | |
395 | <itemizedlist> | |
396 | <listitem><para>ODEBUG_STATE_ACTIVE</para></listitem> | |
397 | </itemizedlist> | |
398 | </para> | |
399 | <para> | |
400 | The function returns 1 when the fixup was successful, | |
401 | otherwise 0. The return value is used to update the | |
402 | statistics. | |
403 | </para> | |
404 | </sect1> | |
b84d435c CC |
405 | <sect1 id="fixup_assert_init"> |
406 | <title>fixup_assert_init</title> | |
407 | <para> | |
408 | This function is called from the debug code whenever a problem | |
409 | in debug_object_assert_init is detected. | |
410 | </para> | |
411 | <para> | |
412 | Called from debug_object_assert_init() with a hardcoded state | |
413 | ODEBUG_STATE_NOTAVAILABLE when the object is not found in the | |
414 | debug bucket. | |
415 | </para> | |
416 | <para> | |
417 | The function returns 1 when the fixup was successful, | |
418 | otherwise 0. The return value is used to update the | |
419 | statistics. | |
420 | </para> | |
421 | <para> | |
422 | Note, this function should make sure debug_object_init() is | |
423 | called before returning. | |
424 | </para> | |
425 | <para> | |
426 | The handling of statically initialized objects is a special | |
427 | case. The fixup function should check if this is a legitimate | |
428 | case of a statically initialized object or not. In this case only | |
429 | debug_object_init() should be called to make the object known to | |
430 | the tracker. Then the function should return 0 because this is not | |
431 | a real fixup. | |
432 | </para> | |
433 | </sect1> | |
691cc54c TG |
434 | </chapter> |
435 | <chapter id="bugs"> | |
436 | <title>Known Bugs And Assumptions</title> | |
437 | <para> | |
438 | None (knock on wood). | |
439 | </para> | |
440 | </chapter> | |
441 | </book> |