About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / DocBook / debugobjects.tmpl


Based on kernel version 4.9. Page generated on 2016-12-21 14:33 EST.

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 true when the fixup was successful,
320		otherwise false. 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 true when the fixup was successful,
345		otherwise false. 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 false because this is not a real
363		fixup.
364	      </para>
365	    </sect1>
366	
367	    <sect1 id="fixup_destroy">
368	      <title>fixup_destroy</title>
369	      <para>
370		This function is called from the debug code whenever a problem
371		in debug_object_destroy is detected.
372	      </para>
373	      <para>
374		Called from debug_object_destroy when the object state is:
375		<itemizedlist>
376		  <listitem><para>ODEBUG_STATE_ACTIVE</para></listitem>
377		</itemizedlist>
378	      </para>
379	      <para>
380		The function returns true when the fixup was successful,
381		otherwise false. The return value is used to update the
382		statistics.
383	      </para>
384	    </sect1>
385	    <sect1 id="fixup_free">
386	      <title>fixup_free</title>
387	      <para>
388		This function is called from the debug code whenever a problem
389		in debug_object_free is detected. Further it can be called
390		from the debug checks in kfree/vfree, when an active object is
391		detected from the debug_check_no_obj_freed() sanity checks.
392	      </para>
393	      <para>
394		Called from debug_object_free() or debug_check_no_obj_freed()
395		when the object state is:
396		<itemizedlist>
397		  <listitem><para>ODEBUG_STATE_ACTIVE</para></listitem>
398		</itemizedlist>
399	      </para>
400	      <para>
401		The function returns true when the fixup was successful,
402		otherwise false. The return value is used to update the
403		statistics.
404	      </para>
405	    </sect1>
406	    <sect1 id="fixup_assert_init">
407	      <title>fixup_assert_init</title>
408	      <para>
409		This function is called from the debug code whenever a problem
410		in debug_object_assert_init is detected.
411	      </para>
412	      <para>
413		Called from debug_object_assert_init() with a hardcoded state
414		ODEBUG_STATE_NOTAVAILABLE when the object is not found in the
415		debug bucket.
416	      </para>
417	      <para>
418		The function returns true when the fixup was successful,
419		otherwise false. The return value is used to update the
420		statistics.
421	      </para>
422	      <para>
423		Note, this function should make sure debug_object_init() is
424		called before returning.
425	      </para>
426	      <para>
427		The handling of statically initialized objects is a special
428		case. The fixup function should check if this is a legitimate
429		case of a statically initialized object or not. In this case only
430		debug_object_init() should be called to make the object known to
431		the tracker. Then the function should return false because this
432		is not
433		a real fixup.
434	      </para>
435	    </sect1>
436	  </chapter>
437	  <chapter id="bugs">
438	    <title>Known Bugs And Assumptions</title>
439	    <para>
440		None (knock on wood).
441	    </para>
442	  </chapter>
443	</book>
Hide Line Numbers


About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog