blob: 24979f691e3e88dd1ab82b3b00633e683445093f [file] [log] [blame]
Thomas Gleixner691cc542008-04-30 00:55:02 -07001<?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>
Christine Chanb84d4352011-11-07 19:48:27 -080099 <listitem><para>debug_object_assert_init</para></listitem>
Thomas Gleixner691cc542008-04-30 00:55:02 -0700100 </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>
GeunSik Lim156f5a72009-06-02 15:01:37 +0900110 The statistics are available via /sys/kernel/debug/debug_objects/stats.
Thomas Gleixner691cc542008-04-30 00:55:02 -0700111 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>
Christine Chanb84d4352011-11-07 19:48:27 -0800277
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>
Thomas Gleixner691cc542008-04-30 00:55:02 -0700297 </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>
Christine Chanb84d4352011-11-07 19:48:27 -0800405 <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>
Thomas Gleixner691cc542008-04-30 00:55:02 -0700434 </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>