aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/DocBook
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/DocBook')
-rw-r--r--Documentation/DocBook/Makefile2
-rw-r--r--Documentation/DocBook/debugobjects.tmpl391
2 files changed, 392 insertions, 1 deletions
diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
index 83966e94cc32..0eb0d027eb32 100644
--- a/Documentation/DocBook/Makefile
+++ b/Documentation/DocBook/Makefile
@@ -12,7 +12,7 @@ DOCBOOKS := wanbook.xml z8530book.xml mcabook.xml videobook.xml \
12 kernel-api.xml filesystems.xml lsm.xml usb.xml kgdb.xml \ 12 kernel-api.xml filesystems.xml lsm.xml usb.xml kgdb.xml \
13 gadget.xml libata.xml mtdnand.xml librs.xml rapidio.xml \ 13 gadget.xml libata.xml mtdnand.xml librs.xml rapidio.xml \
14 genericirq.xml s390-drivers.xml uio-howto.xml scsi.xml \ 14 genericirq.xml s390-drivers.xml uio-howto.xml scsi.xml \
15 mac80211.xml 15 mac80211.xml debugobjects.xml
16 16
17### 17###
18# The build process is as follows (targets): 18# The build process is as follows (targets):
diff --git a/Documentation/DocBook/debugobjects.tmpl b/Documentation/DocBook/debugobjects.tmpl
new file mode 100644
index 000000000000..7f5f218015fe
--- /dev/null
+++ b/Documentation/DocBook/debugobjects.tmpl
@@ -0,0 +1,391 @@
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 </itemizedlist>
100 Each of these functions takes the address of the real object and
101 a pointer to the object type specific debug description
102 structure.
103 </para>
104 <para>
105 Each detected error is reported in the statistics and a limited
106 number of errors are printk'ed including a full stack trace.
107 </para>
108 <para>
109 The statistics are available via debugfs/debug_objects/stats.
110 They provide information about the number of warnings and the
111 number of successful fixups along with information about the
112 usage of the internal tracking objects and the state of the
113 internal tracking objects pool.
114 </para>
115 </chapter>
116 <chapter id="debugfunctions">
117 <title>Debug functions</title>
118 <sect1 id="prototypes">
119 <title>Debug object function reference</title>
120!Elib/debugobjects.c
121 </sect1>
122 <sect1 id="debug_object_init">
123 <title>debug_object_init</title>
124 <para>
125 This function is called whenever the initialization function
126 of a real object is called.
127 </para>
128 <para>
129 When the real object is already tracked by debugobjects it is
130 checked, whether the object can be initialized. Initializing
131 is not allowed for active and destroyed objects. When
132 debugobjects detects an error, then it calls the fixup_init
133 function of the object type description structure if provided
134 by the caller. The fixup function can correct the problem
135 before the real initialization of the object happens. E.g. it
136 can deactivate an active object in order to prevent damage to
137 the subsystem.
138 </para>
139 <para>
140 When the real object is not yet tracked by debugobjects,
141 debugobjects allocates a tracker object for the real object
142 and sets the tracker object state to ODEBUG_STATE_INIT. It
143 verifies that the object is not on the callers stack. If it is
144 on the callers stack then a limited number of warnings
145 including a full stack trace is printk'ed. The calling code
146 must use debug_object_init_on_stack() and remove the object
147 before leaving the function which allocated it. See next
148 section.
149 </para>
150 </sect1>
151
152 <sect1 id="debug_object_init_on_stack">
153 <title>debug_object_init_on_stack</title>
154 <para>
155 This function is called whenever the initialization function
156 of a real object which resides on the stack is called.
157 </para>
158 <para>
159 When the real object is already tracked by debugobjects it is
160 checked, whether the object can be initialized. Initializing
161 is not allowed for active and destroyed objects. When
162 debugobjects detects an error, then it calls the fixup_init
163 function of the object type description structure if provided
164 by the caller. The fixup function can correct the problem
165 before the real initialization of the object happens. E.g. it
166 can deactivate an active object in order to prevent damage to
167 the subsystem.
168 </para>
169 <para>
170 When the real object is not yet tracked by debugobjects
171 debugobjects allocates a tracker object for the real object
172 and sets the tracker object state to ODEBUG_STATE_INIT. It
173 verifies that the object is on the callers stack.
174 </para>
175 <para>
176 An object which is on the stack must be removed from the
177 tracker by calling debug_object_free() before the function
178 which allocates the object returns. Otherwise we keep track of
179 stale objects.
180 </para>
181 </sect1>
182
183 <sect1 id="debug_object_activate">
184 <title>debug_object_activate</title>
185 <para>
186 This function is called whenever the activation function of a
187 real object is called.
188 </para>
189 <para>
190 When the real object is already tracked by debugobjects it is
191 checked, whether the object can be activated. Activating is
192 not allowed for active and destroyed objects. When
193 debugobjects detects an error, then it calls the
194 fixup_activate function of the object type description
195 structure if provided by the caller. The fixup function can
196 correct the problem before the real activation of the object
197 happens. E.g. it can deactivate an active object in order to
198 prevent damage to the subsystem.
199 </para>
200 <para>
201 When the real object is not yet tracked by debugobjects then
202 the fixup_activate function is called if available. This is
203 necessary to allow the legitimate activation of statically
204 allocated and initialized objects. The fixup function checks
205 whether the object is valid and calls the debug_objects_init()
206 function to initialize the tracking of this object.
207 </para>
208 <para>
209 When the activation is legitimate, then the state of the
210 associated tracker object is set to ODEBUG_STATE_ACTIVE.
211 </para>
212 </sect1>
213
214 <sect1 id="debug_object_deactivate">
215 <title>debug_object_deactivate</title>
216 <para>
217 This function is called whenever the deactivation function of
218 a real object is called.
219 </para>
220 <para>
221 When the real object is tracked by debugobjects it is checked,
222 whether the object can be deactivated. Deactivating is not
223 allowed for untracked or destroyed objects.
224 </para>
225 <para>
226 When the deactivation is legitimate, then the state of the
227 associated tracker object is set to ODEBUG_STATE_INACTIVE.
228 </para>
229 </sect1>
230
231 <sect1 id="debug_object_destroy">
232 <title>debug_object_destroy</title>
233 <para>
234 This function is called to mark an object destroyed. This is
235 useful to prevent the usage of invalid objects, which are
236 still available in memory: either statically allocated objects
237 or objects which are freed later.
238 </para>
239 <para>
240 When the real object is tracked by debugobjects it is checked,
241 whether the object can be destroyed. Destruction is not
242 allowed for active and destroyed objects. When debugobjects
243 detects an error, then it calls the fixup_destroy function of
244 the object type description structure if provided by the
245 caller. The fixup function can correct the problem before the
246 real destruction of the object happens. E.g. it can deactivate
247 an active object in order to prevent damage to the subsystem.
248 </para>
249 <para>
250 When the destruction is legitimate, then the state of the
251 associated tracker object is set to ODEBUG_STATE_DESTROYED.
252 </para>
253 </sect1>
254
255 <sect1 id="debug_object_free">
256 <title>debug_object_free</title>
257 <para>
258 This function is called before an object is freed.
259 </para>
260 <para>
261 When the real object is tracked by debugobjects it is checked,
262 whether the object can be freed. Free is not allowed for
263 active objects. When debugobjects detects an error, then it
264 calls the fixup_free function of the object type description
265 structure if provided by the caller. The fixup function can
266 correct the problem before the real free of the object
267 happens. E.g. it can deactivate an active object in order to
268 prevent damage to the subsystem.
269 </para>
270 <para>
271 Note that debug_object_free removes the object from the
272 tracker. Later usage of the object is detected by the other
273 debug checks.
274 </para>
275 </sect1>
276 </chapter>
277 <chapter id="fixupfunctions">
278 <title>Fixup functions</title>
279 <sect1 id="debug_obj_descr">
280 <title>Debug object type description structure</title>
281!Iinclude/linux/debugobjects.h
282 </sect1>
283 <sect1 id="fixup_init">
284 <title>fixup_init</title>
285 <para>
286 This function is called from the debug code whenever a problem
287 in debug_object_init is detected. The function takes the
288 address of the object and the state which is currently
289 recorded in the tracker.
290 </para>
291 <para>
292 Called from debug_object_init when the object state is:
293 <itemizedlist>
294 <listitem><para>ODEBUG_STATE_ACTIVE</para></listitem>
295 </itemizedlist>
296 </para>
297 <para>
298 The function returns 1 when the fixup was successful,
299 otherwise 0. The return value is used to update the
300 statistics.
301 </para>
302 <para>
303 Note, that the function needs to call the debug_object_init()
304 function again, after the damage has been repaired in order to
305 keep the state consistent.
306 </para>
307 </sect1>
308
309 <sect1 id="fixup_activate">
310 <title>fixup_activate</title>
311 <para>
312 This function is called from the debug code whenever a problem
313 in debug_object_activate is detected.
314 </para>
315 <para>
316 Called from debug_object_activate when the object state is:
317 <itemizedlist>
318 <listitem><para>ODEBUG_STATE_NOTAVAILABLE</para></listitem>
319 <listitem><para>ODEBUG_STATE_ACTIVE</para></listitem>
320 </itemizedlist>
321 </para>
322 <para>
323 The function returns 1 when the fixup was successful,
324 otherwise 0. The return value is used to update the
325 statistics.
326 </para>
327 <para>
328 Note that the function needs to call the debug_object_activate()
329 function again after the damage has been repaired in order to
330 keep the state consistent.
331 </para>
332 <para>
333 The activation of statically initialized objects is a special
334 case. When debug_object_activate() has no tracked object for
335 this object address then fixup_activate() is called with
336 object state ODEBUG_STATE_NOTAVAILABLE. The fixup function
337 needs to check whether this is a legitimate case of a
338 statically initialized object or not. In case it is it calls
339 debug_object_init() and debug_object_activate() to make the
340 object known to the tracker and marked active. In this case
341 the function should return 0 because this is not a real fixup.
342 </para>
343 </sect1>
344
345 <sect1 id="fixup_destroy">
346 <title>fixup_destroy</title>
347 <para>
348 This function is called from the debug code whenever a problem
349 in debug_object_destroy is detected.
350 </para>
351 <para>
352 Called from debug_object_destroy when the object state is:
353 <itemizedlist>
354 <listitem><para>ODEBUG_STATE_ACTIVE</para></listitem>
355 </itemizedlist>
356 </para>
357 <para>
358 The function returns 1 when the fixup was successful,
359 otherwise 0. The return value is used to update the
360 statistics.
361 </para>
362 </sect1>
363 <sect1 id="fixup_free">
364 <title>fixup_free</title>
365 <para>
366 This function is called from the debug code whenever a problem
367 in debug_object_free is detected. Further it can be called
368 from the debug checks in kfree/vfree, when an active object is
369 detected from the debug_check_no_obj_freed() sanity checks.
370 </para>
371 <para>
372 Called from debug_object_free() or debug_check_no_obj_freed()
373 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 </chapter>
385 <chapter id="bugs">
386 <title>Known Bugs And Assumptions</title>
387 <para>
388 None (knock on wood).
389 </para>
390 </chapter>
391</book>
generated by cgit v1.2.2 (git 2.25.0) at 2024-12-25 23:56:57 -0500