Merge branch 'for-linus' of git://git.infradead.org/users/vkoul/slave-dma
[linux-3.10.git] / Documentation / DocBook / debugobjects.tmpl
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>