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>
99	<listitem><para>debug_object_assert_init</para></listitem>
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>
110      The statistics are available via /sys/kernel/debug/debug_objects/stats.
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>
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>
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>
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>
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>
442