tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
debugobjects: add documentation
Add a DocBook for debugobjects.
Signed-off-by: Thomas Gleixner <tglx@linutronix.de>
Acked-by: Ingo Molnar <mingo@elte.hu>
Cc: Greg KH <greg@kroah.com>
Cc: Randy Dunlap <randy.dunlap@oracle.com>
Cc: Kay Sievers <kay.sievers@vrfy.org>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
authored by
Thomas Gleixner
and committed by
Linus Torvalds
691cc54c
3ac7fe5a
+392
-1
+1
-1
Documentation/DocBook/Makefile
+1
-1
Documentation/DocBook/Makefile
···
12
12
kernel-api.xml filesystems.xml lsm.xml usb.xml kgdb.xml \
13
13
gadget.xml libata.xml mtdnand.xml librs.xml rapidio.xml \
14
14
genericirq.xml s390-drivers.xml uio-howto.xml scsi.xml \
15
-
mac80211.xml
15
+
mac80211.xml debugobjects.xml
16
16
17
17
###
18
18
# The build process is as follows (targets):
+391
Documentation/DocBook/debugobjects.tmpl
+391
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
+
</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>