]>
Commit | Line | Data |
---|---|---|
691cc54c TG |
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> | |
156f5a78 | 109 | The statistics are available via /sys/kernel/debug/debug_objects/stats. |
691cc54c TG |
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> |